nicolasdespres/respect

Object schema definition using a Ruby DSL.

respect's Issues

CompositeSchema should allow to pass options to composed schema.

Consider the following CompositeSchema:

module Respect
  class PointSchema < CompositeSchema
    def schema_definition
      HashSchema.define do |s|
        s.float "x"
        s.float "y"
      end
    end
  end
end

when using it like that:

HashSchema.define do |s|
  s.point :center
end

The user should be able to pass options to the underlying x and y properties like that:

HashSchema.define do |s|
  s.point :center, x: { greater_than: 4 }, y: { in: 42.5..51.5 }
end

Recursive composite schema must work too. Consider:

HashSchema.define do |s|
  s.circle "area", radius: { greater_than: 10.0 }, center: { x: greater_than: 5.0 }
end

For array we could use the index for key (items and extra items) and :all (item).

Should we check schema definition validity before at definition time?

• Forbid zero for 'divisible_by' and 'multiple_of'?
  A ZeroDivisionError is raised at validation time instead of a InvalidSchemaError at
  description time.
• Valid format argument?
  For most of the argument it is not that important since it fails afterward
  at validation time. It will be safer for user to fail with an InvalidSchemaError
  at description time but we will probably loose in extensibility and flexibility.
  Ruby traditional approach would be not to check.
• Forbid unknown option?
  Same remarks as above.

Cleanup dumpers API.

Right now it is not easy to define how a new Schema sub-class should be dump using the various available dumpers. The ideal would be to only have to overwrite one method.

Main Example - Schema Validation doesn't match DSL

The DSL now looks like this:

schema = Respect::HashSchema.define do |s|
s.string "name"
s.integer "age", greater_than: 18
s.string "homepage", format: :uri
end

But the schema validation will always be false:
schema.validate?({ "name" => "My name", "age" => 20, "email" => "[email protected]" })
schema.validate?({ "name" => "My name", "age" => 15, "email" => "[email protected]" })

The last parameter/key is "email", and it should be "homepage" to match the DSL. Of course, you'll need an appropriate URI value to go with it.

Add a JSON schema loader.

Right now users can dump their schema in JSON Schema specification draft v3. It would be great to be able to create a schema object from such a representation.

Main example needs a require statement

Before using Respect, you need to require it. The first 2 lines should look like this:

require 'respect'

schema = Respect::HashSchema.define do |s|
...

That way, someone can just copy the code off the page, paste it directly into irb or rails console, and it just works out of the box.

Add :blank boolean option.

Should be used like that:

StringSchema.new(blank: false).validate?("")  #=> false
StringSchema.new(blank: true).validate?("")  #=> true

Must:

• Use ActiveSupport blank? method.
• How to we convert it in json-schema.org?

Factor the way we reset sanitized object on failed validation.

This chunk of code is duplicated in many places:

rescue ValidationError => e
  # Reset sanitized object.
  self.sanitized_object = nil
  raise e
end

Org3Dumper should warn if regexp uses features not available in ECMA 262.

We use Ruby regexp but json-schema.org uses ECMA 262 regexp. AFAIK, Ruby's regexps have more features.

Should we add support for custom constraints via a class/block?

Obviously, json-schema v3 and the draft do not provide such a constraint. They are very useful but we could not generate documentation for them. Would that be ok?

Add 'lenght' option for string.

The string must be exactly that long.

More sugar for `HashDef#[]` and `HashDef#[]=`

Users should be able to write something like that:

# Check "HTTP_VERSION" is "HTTP/1.1".
h["HTTP_VERSION"] = "HTTP/1.1"
# Check "rack.version" is an array equal to [ 1, 1 ].
h["rack.version"] = [ 1, 1 ]
# Check "HTTP_USER_AGENT" matches /^Mozilla/.
h["HTTP_USER_AGENT"] =~ /^Mozilla/
# Check "rack.run_once" is boolean equal to false.
h["rack.run_once"] = false
# Check "action_dispatch.parameter_filter" is an array including :password.
h["action_dispatch.parameter_filter"].include_item :password
# Check "rack.session" is a hash containing a "session_id" key with a string value of minimum length 16.
h["rack.session"].has_property("session_id").string(min_length: 16)
# Check "rack.session" is a hash containing a _csrf_token" key with a string value of minimum length 44.
h["rack.session"].has_property("_csrf_token").string(min_length: 44)
# Check "rack.session.options" is a hash with the given hash schema.
h["rack.session.options"].object strict: false do |s|
  # A "secret" key with a string value of minimum lenght 60.
  s.string "secret", min_length: 60
  # A "httponly" key with a boolean value equal to true
  s.boolean "httponly", equal_to: true
  # A "rack.request.cookie_hash" hash with the following schema.
  s.headers "rack.request.cookie_hash" do |h|
    h["_blog_session"].string min_length: 218
  end
end
# Check "action_controller.instance" value is a ActionController::Base instance.
# This check won't be documented.
h["action_controller.instance"].is_a ActionController::Base, doc: false
# Check "__internal__" is a string equal to "foo" and won't be documented.
h["__internal__"].must_be("foo", doc: false)
# Check "REQUEST_URI" is string formatted as a URI.
h.uri "REQUEST_URI"

This would be useful for headers specification.

Example DSL has a minor error

The example DSL reads as follows:
schema = Respect::HashSchema.define do |s|
s.string "name"
s.integer "age", greater_than: 18
s.string "homepage", format: :email
end

But there's a minor mistake that causes the schema validation to always return false.
The last value in the DSL should read:
s.string "email", format: :email

Then the schema validation examples lower down the page work as advertised.

Add a better loggin system in back-end.

Right now there is the poorest logging system in dumpers: Kernel.warn. We should use a regular logger API and let the user provide its own. We could also introduce a Logger module which add the logger API to an object/class implementing print.

`puts JSON.pretty_generate(schema.to_h)` doesn't actually work

In Ruby 2.1, I get:

lib/respect/schema.rb:252:in `to_json': unknown format '#<JSON::Ext::Generator::State:0x007fd32b89b5d8>' (ArgumentError)
    from /opt/rubies/2.1.4-github1/lib/ruby/2.1.0/json/common.rb:285:in `generate'
    from /opt/rubies/2.1.4-github1/lib/ruby/2.1.0/json/common.rb:285:in `pretty_generate'
    from scheme.rb:11:in `<main>'

I think the def to_json implementation assumes some other value for format.

Factor implementation of `allow_nil` option.

Should our validation exception be a sub-class of ArgumentError instead of StandardError?

• Pro:
  • More descriptive
• Cons:
  • Will be caught by ArgumentError rescue_from...

Split CoreStatement in several module to make API clearer and let end-users include only what they need.

I see four modules:

• one for the dynamic methods (called DynamicStatement?)
• one for the macros: email, phone_number, and hostname (called FormatHelperStatement?)
• one for doc (called DocStatement?)
• one for with_options ( called WithOptionsStatement?)