respect 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 Nicolas Despres
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,289 @@
+# Welcome to Respect
+
+_Respect_ is a DSL to concisely describe the structure of common data such as Hash and Array using
+Ruby code. It comes with a validator, a sanitizer and dumpers to generate valid
+[json-schema.org](http://json-schema.org/) compliant specifications. Although it was designed to
+specify JSON schema, it can be used for any data represented as Hash and Array. It does not require
+any JSON parser since it works only on data.
+
+Respect is named after the contraction of _REST_ and _SPEC_. Indeed, it was first intended to be
+used to specify REST API in the context of a Web application.
+
+There is a plugin called [Respect for Rails](https://github.com/nicolasdespres/respect-rails) which
+integrate this gem in Rails.
+
+# Features
+
+Already available:
+
+* Compact Ruby DSL to specify your schema.
+* Standard [json-schema.org](http://json-schema.org/) specification generator.
+* Validator for JSON document or the like.
+* Contextual validation error.
+* Object sanitizer: turn plain string and integer values into real objects.
+* Extensible API to add your custom validator and sanitizer.
+* Extensible macro definition system to factor you schema definition code.
+
+See the RELEASE_NOTES file for detailed feature listing.
+
+# Take a Tour
+
+_Respect_ comes with a compact Ruby DSL to specify the structure of a hash and/or an array.
+Thus, it is ideal to specify JSON schema. I find it a way more concise than
+[json-schema.org](http://json-schema.org/). And it is plain Ruby so you can rely on all great Ruby features
+to factor your specification code.
+
+For instance, this ruby code specify how one could structure a very simple user profile:
+
+```ruby
+schema = Respect::HashSchema.define do |s|
+  s.string "name"
+  s.integer "age", greater_than: 18
+  s.string "homepage", format: :email
+end
+```
+
+But you can still convert this specification to
+[JSON Schema specification draft v3](http://tools.ietf.org/id/draft-zyp-json-schema-03.html)
+easily so that all your customers can read and understand it:
+
+```ruby
+require 'json'
+puts JSON.pretty_generate(schema.to_h)
+```
+
+prints
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "age": {
+      "type": "integer",
+      "required": true,
+      "minimum": 18,
+      "exclusiveMinimum": true
+    },
+    "email": {
+      "type": "string",
+      "required": true,
+      "format": "email"
+    }
+  }
+}
+```
+
+As you can see the Ruby specification is 4 times shorter than the JSON Schema specification...
+
+You can also use this specification to validate JSON documents:
+
+```ruby
+schema.validate?({ "name" => "My name", "age" => 20, "email" => "me@example.com" })          #=> true
+schema.validate?({ "name" => "My name", "age" => 15, "email" => "me@example.com" })          #=> false
+```
+
+When it fails to validate a document, you get descriptive error messages with contextual information:
+
+```ruby
+schema.last_error                #=> "15 is not greater than 18"
+schema.last_error.message        #=> "15 is not greater than 18"
+schema.last_error.context[0]     #=> "15 is not greater than 18"
+schema.last_error.context[1]     #=> "in hash property `age'"
+```
+
+_Respect_ does not parse JSON document by default but it is easy to do so using one of the JSON parser available in Ruby:
+
+```ruby
+schema.validate?(JSON.parse('{ "name": "My name", "age": 20, "email": "me@example.com" }'))   #=> true
+```
+
+Once a JSON document has been validated, we often want to turn its basic strings and integers into real object like `URI`.
+_Respect_ does that automatically for you for standard objects:
+
+```ruby
+schema = Respect::HashSchema.define do |s|
+  s.uri "homepage"
+end
+object = { "homepage" => "http://example.com" }
+schema.validate!(object)                            #=> true
+object["homepage"].class                            #=> URI::HTTP
+```
+
+You can easily extend the sanitizer with your own object type. Let's assume you have an object type define like this:
+
+```ruby
+class Place
+  def initialize(latitude, longitude)
+    @latitude, @longitude = latitude, longitude
+  end
+
+  attr_reader :latitude, :longitude
+
+  def ==(other)
+    @latitude == other.latitude && @longitude == other.longitude
+  end
+end
+```
+
+Then you must extend the Schema hierarchy with the new schema for your custom type.
+The `CompositeSchema` class assists you in this task so you just have to overwrite
+two methods.
+
+```ruby
+module Respect
+  class PlaceSchema < CompositeSchema
+    # This method returns the schema specification for your custom type.
+    def schema_definition
+      Respect::HashSchema.define do |s|
+        s.float "latitude"
+        s.float "longitude"
+      end
+    end
+
+    # The 'sanitize' method is called with the JSON document if the validation succeed.
+    # The returned value will be inserted into the JSON document.
+    def sanitize(object)
+      Place.new(object[:latitude], object[:longitude])
+    end
+  end
+end
+```
+
+Finally, you define the structure of your JSON document as usual. Note that you have
+access to your custom schema via the `place` method.
+
+```ruby
+schema = Respect::HashSchema.define do |s|
+  s.place "home"
+end
+
+object = {
+  "home" => {
+    "latitude" => "48.846559",
+    "longitude" => "2.344519",
+  }
+}
+
+schema.validate!(object)                              #=> true
+object["home"].class                                  #=> Place
+```
+
+Sometimes you just want to extend the DSL with a new statement providing higher level feature than
+the primitive `integer`, `string` or `float`, etc... For instance if you specify identifier
+in your schema like this:
+
+```ruby
+Respect::HashSchema.define do |s|
+  s.integer "article_id", greater_than: 0
+  s.string "title"
+  s.hash "author" do |s|
+    s.integer "author_id", greater_than: 0
+    s.string "name"
+  end
+end
+```
+
+In such case, you don't need a custom sanitizer. You just want to factor the definition of
+identifier property. You can easily to it like this:
+
+```ruby
+module MyMacros
+  def id(name, options = {})
+    unless name.nil? || name =~ /_id$/
+      name += "_id"
+    end
+    integer(name, { greater_than: 0 }.merge(options))
+  end
+end
+Respect.extend_dsl_with(MyMacros)
+```
+
+Now you can rewrite the original schema this way:
+
+```ruby
+Respect::HashSchema.define do |s|
+  s.id "article"
+  s.string "title"
+  s.hash "author" do |s|
+    s.id "author"
+    s.string "name"
+  end
+end
+```
+
+# Getting started
+
+The easiest way to install _Respect_ is to add it to your `Gemfile`:
+
+```ruby
+gem "respect"
+```
+
+Then, after running the `bundle install` command, you can start to validate JSON document in your program like this:
+
+```ruby
+require 'respect'
+
+schema = Respect::HashSchema.define do |s|
+  s.string "name"
+  s.integer "age", greater_than: 18
+end
+
+schema.validate?({ "name" => "John", "age" => 30 })
+```
+
+# JSON Schema implementation status
+
+_Respect_ currently implements most of the features included in the
+[JSON Schema specification draft v3](http://tools.ietf.org/id/draft-zyp-json-schema-03.html).
+
+See the `STATUS_MATRIX` file included in this package for detailed information.
+
+Although, the semantics of the schema definition DSL available in this library may change slightly from the
+_JSON schema standard_, we have tried to keep it as close as possible. For instance the `strict` option of
+hash schema is not presented in the standard. However, when a schema is dumped to its _JSON Schema_ version
+the syntax and semantic have been followed. You should note that there is no "loader" available yet in this
+library. In other word, you cannot instantiate a Schema class from a _JSON Schema_ string representation.
+
+# Getting help
+
+The easiest way to get help about how to use this library is to post your question on the
+[Respect discussion group](https://groups.google.com/forum/#!forum/ruby-respect-gem-talk).
+I will be glade to answer. I may have already answered the
+same question so before you post your question take a bit of time to search the group.
+
+You can also read these documents for further documentation:
+
+* [Repect API reference documentation](http://nicolasdespres.github.io/respect/)
+
+# Compatibility
+
+_Respect_ has been tested with:
+
+* Ruby 1.9.3-p392 (should be compatible with all 1.9.x family)
+* ActiveSupport 3.2.13
+
+Note that **it does not depend on any JSON parsing library**. It works only on primitive Ruby data type. So,
+any JSON parser returning normal basic types like `Hash`, `Array`, `String`, `Numeric`, `TrueClass`,
+`FalseClass`, `NilClass`, should work.
+
+# Feedback
+
+I would love to hear what you think about this library. Feel free to post any comments/remarks on the
+[Respect discussion group](https://groups.google.com/forum/#!forum/ruby-respect-gem-talk).
+
+# Contributing patches
+
+I spent quite a lot of time writing this gem but there is still a lot of work to do. Whether it
+is a bug-fix, a new feature, some code re-factoring, or documentation clarification, I will be
+glade to merge your pull request on GitHub. You just have to create a branch from `master` and
+send me a pull request.
+
+# License
+
+_Respect_ is released under the term of the [MIT License](http://opensource.org/licenses/MIT).
+Copyright (c) 2013 Nicolas Despres.

data/RELATED_WORK.md

@@ -0,0 +1,40 @@
+# Related works
+
+This section describes some projects sharing more or less the same purpose as _Respect_.
+The goal is to have an overview of the eco-system around this topic to borrow ideas and
+to drive implementation.
+
+This section is not meant to be accurate even if we try to stay objective here.
+
+## [json-schema](https://github.com/hoxworth/json-schema)
+
+* No DSL
+* No doc generation
+* No sanitizer.
+
+## [ruby-jsonschema](https://github.com/Constellation/ruby-jsonchema)
+
+* No DSL
+* No doc generation
+* No sanitizer.
+
+## [google/autoparse](https://github.com/google/autoparse)
+
+* No DSL
+* Seems no longer maintained.
+* No doc generation.
+* No sanitizer.
+
+## [json expression](https://github.com/chancancode/json_expressions)
+
+* Provide an easy way to test your JSON responses.
+* No documentation generator.
+* No DSL.
+* No sanitizer.
+
+## [Net HTTP API Spec](https://github.com/franckcuny/net-http-api-spec)
+
+* Seems not used (i.e. no fork and almost no star)
+* Seems no longer maintained.
+* Not compliant with json-schema.org spec.
+* No sanitizer.

data/RELEASE_NOTES.md

@@ -0,0 +1,23 @@
+# Release notes
+
+This document is a list of user visible feature changes made between
+releases except for bug fixes.
+
+Note that each entry is kept so brief that no reason behind or
+reference information is supplied with.  For a full list of changes
+with all sufficient information, see the git(1) log.
+
+A lot more is coming soon check out the issue tagged as `feature`
+in the tracker.
+
+## Part of the first release
+
+Feature: DSL to describe schema of Hash, Array, String, Numeric, Integer, Float, Boolean, etc...
+Feature: Dumper to pretty-print a schema using the same DSL syntax.
+Feature: Dumper to generate [JSON schema draft v3 standard](http://tools.ietf.org/id/draft-zyp-json-schema-03.html) representation of a schema.
+Feature: Validation system to check objects follow a schema.
+Feature: Sanitizer to promote validated value to a more specific type.
+Feature: CompositeSchema class to easily create your own schema.
+Feature: Facilities to extends the DSL with user-defined module.
+Feature: Contextual validation error.
+Feature: A JSON schema HTML formatter.

data/Rakefile

@@ -0,0 +1,31 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = [
+    'lib/**/*.rb',
+    '-',
+    'README.md',
+    'STATUS_MATRIX.html',
+    'RELEASE_NOTES.md',
+    'RELATED_WORK.md',
+  ]
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test

data/STATUS_MATRIX.html

@@ -0,0 +1,137 @@
+<h3>Core Schema definition</h3>
+<p>
+This document is a work in progress and is updated constantly. It may not reflect the exact state
+of implementation.
+</p>
+<table border="1">
+  <tr>
+    <td>Core Schema definition feature</td>
+    <td>Abailable in Respect ?</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor9">5.1. type</a></td>
+    <td style="color:green" align="center">With the various core DSL statements: 'integer', 'string', etc...</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#properties">5.2. properties</a></td>
+    <td style="color:green" align="center">Yes</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor10">5.3. patternProperties</a></td>
+    <td style="color:orangered" align="center">
+      With a regular expression instead of a string as property name<br>
+      (Ruby regexp instead of ECMA 262)
+    </td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#additionalProperties">5.4. additionalProperties</a></td>
+    <td style="color:green" align="center">With 'extra' statement or 'required' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor11">5.5. items</a></td>
+    <td style="color:green" align="center">With 'item' or 'items' statement</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#additionalItems">5.6. additionalItems</a></td>
+    <td style="color:green" align="center">With 'extra_items' statement</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor12">5.7. required</a></td>
+    <td style="color:green" align="center">Yes</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor13">5.8. dependencies</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor14">5.9. minimum</a></td>
+    <td style="color:green" align="center">With 'greater_than_or_equal_to' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor15">5.10. maximum</a></td>
+    <td style="color:green" align="center">With 'less_than_or_equal_to' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor16">5.11. exclusiveMinimum</a></td>
+    <td style="color:green" align="center">With 'greater_than' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor17">5.12. exclusiveMaximum</a></td>
+    <td style="color:green" align="center">With 'less_than' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor18">5.13. minItems</a></td>
+    <td style="color:green" align="center">With 'min_size' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor19">5.14. maxItems</a></td>
+    <td style="color:green" align="center">With 'max_size' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#uniqueItems">5.15. uniqueItems</a></td>
+    <td style="color:green" align="center">With 'uniq' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor20">5.16. pattern</a></td>
+    <td style="color:orangered" align="center">With 'match' option<br>(Ruby regexp instead of ECMA 262)</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor21">5.17. minLength</a></td>
+    <td style="color:green" align="center">With 'min_length' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor22">5.18. maxLength</a></td>
+    <td style="color:green" align="center">With 'max_length' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor23">5.19. enum</a></td>
+    <td style="color:green" align="center">With 'in' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor24">5.20. default</a></td>
+    <td style="color:green" align="center">Yes</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor25">5.21. title</a></td>
+    <td style="color:green" align="center">Yes</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor26">5.22. description</a></td>
+    <td style="color:green" align="center">Yes</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: date-time</a></td>
+    <td style="color:orangered" align="center">With 'datetime' parameter<br>(RFC 3399 instead of ISO 8601)</td></tr>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: regex</a></td>
+    <td style="color:orangered" align="center">With 'regexp' parameter<br>(Ruby regexp instead of ECMA 262)</td></tr>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: format</a></td>
+    <td style="color:green"  align="center">With 'phone_number' paramter</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: uri</a></td>
+    <td style="color:green"  align="center">With 'uri' parameter (RFC 2396)</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: email</a></td>
+    <td style="color:green"  align="center">With 'email' parameter</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: ip-address</a></td>
+    <td style="color:green"  align="center">With 'ipv4_addr' parameter</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: ipv6</a></td>
+    <td style="color:green"  align="center">With 'ipv6_addr' parameter</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: host-name</a></td>
+    <td style="color:green"  align="center">With 'hostname' parameter</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: date</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: time</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: utc-millisec</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: color</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor27">5.23. format: style</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor28">5.24. divisibleBy</a></td>
+    <td style="color:green" align="center">With 'divisible_by' or 'multiple_of' option</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor29">5.25. disallow</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor30">5.26. extends</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor31">5.27. id</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor32">5.28. $ref</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr><tr>
+    <td><a href="http://tools.ietf.org/id/draft-zyp-json-schema-03.html#anchor33">5.29. $schema</a></td>
+    <td style="color:red" align="center">No</td>
+  </tr>
+</table>