prmd 0.0.1 → 0.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YWJmODRjMTMyNjBmNGE5N2JmZTk4ZmI2MzZiZTM3NDBkZmEyNTI5Yw==
+    OTJiYjFkZjYwZTAxYWExOTJmYzAxMWZjYmJiNmQ1YzA3ZTdiMmY0Ng==
   data.tar.gz: !binary |-
-    MjJiNjE4ZjA0ODUzNjlhNGZkZmVhZmY3MmRhMzY1MDFkYTM0M2QxMw==
+    Y2RmMDI2NTIyNzQxZTk4NjcxZmZhYzU5NTM2NDdlNmM4YWZhMTE4Mg==
 SHA512:
   metadata.gz: !binary |-
-    MThmMTQ3ODhhNDMwNTliZjk4NWY0N2JiOWU3MDk4ZjI1YzE2NDJhNjQ3YjIy
-    ZGU3OGVjYzBiNjZhNmVhNzljMjY5ZWE0YTJlMjg4NmMyN2JiOWQ1ZDM4N2E0
-    M2FjNDdjMmNmYzBlZjBiZjk1ZWQ4NWM3MDhiYmVmYTQ3MTYwMDA=
+    MTE2N2FhODUzYjgxY2Y0YjJmOGUwYzRkYTQwYmY0Nzg2NDJhNDdjM2JhZGYy
+    ZjFjY2MxMGY5ZmNkYjM0OTVlMmUyNTYzMGJlYTdmYjk1MTczOTZiODI3ZjVh
+    MWZlYTQ2OTg2MWRlNjg3Yjc4ZmU2MThkMGVjNTc2Yjg5ZGZmMTA=
   data.tar.gz: !binary |-
-    ZDMzZWZjMzAyZDYxNjg5NTRmZjRjODJjMDNkOTZmNmNhM2QzNzRjN2M2OGVi
-    Yjg3NWE1ZWE2Njk5M2Y5ODg4NDQ1NzlmNjZmZTQxY2E4ZWY0YTJmMzI0NGUz
-    MjM5ZjljNDMxZGNjNGQ3MTI1MmQ3Mjk5MWYyMjM2OGRjMjJkMmI=
+    ZjIyMmNlZmI2NGJiMjY2OGE5NWM2ZTJmMzkxMzAyM2NjNTkyOWFmMDZiMTRk
+    MWEwOWUwYmY0YjM3Mzk1N2FhNDE1YTdkYWJiNTY1NmUxMTE0NmQ4YjBiOTVm
+    Mjk5NzNmODZiNTIwNWUzY2Q3MDIxMjM0ZTRmNTEyMDFjMWU0MWY=

data/.travis.yml

@@ -1,2 +1,4 @@
 language: ruby
 script: "bundle exec rake"
+notifications:
+  email: false

data/Gemfile.lock

@@ -2,13 +2,11 @@ PATH
   remote: .
   specs:
     prmd (0.0.1)
-      diff-lcs
       erubis
 
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.2.5)
     erubis (2.7.0)
     minitest (4.7.5)
     rake (10.1.0)

data/README.md

@@ -1,66 +1,86 @@
 # Prmd
 
-schema to rule them all
+JSON Schema tooling: scaffold, verify, and generate documentation
+against JSON Schema documents.
+
 
 ## Introduction
 
-JSON-Schema provides a great way to describe an API. prmd provides tools for bootstrapping a description like this, verifying it's completeness and generating documentation from the specification.
+[JSON Schema](http://json-schema.org/) provides a great way to describe
+an API. prmd provides tools for bootstrapping a description like this,
+verifying its completeness, and generating documentation from the
+specification.
 
-The expectations for json-schema usage that are expected by prmd are described in [/docs/schemata.md](/docs/schemata.md).
+The JSON Schema usage conventions expected by prmd are described in
+[/docs/schemata.md](/docs/schemata.md).
 
-To learn more about json-schema in general, start with [this excellent guide](http://spacetelescope.github.io/understanding-json-schema/) and supplement with the [specification](http://json-schema.org/documentation.html).
+To learn more about JSON Schema in general, start with
+[this excellent guide](http://spacetelescope.github.io/understanding-json-schema/)
+and supplement with the [specification](http://json-schema.org/documentation.html).
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'prmd'
+```ruby
+gem 'prmd'
+```
 
 And then execute:
 
-    $ bundle
+```console
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install prmd
+```console
+$ gem install prmd
+```
 
 ## Usage
 
-Combine takes the path to a directory of schemas and combines them onto stdout. If -m or --meta is supplied, it will override defaults/metadata.
+Combine takes the path to a schema file or directory of schema files and
+combines them on to stdout. If -m or --meta is supplied, it will override
+defaults/metadata:
 
-```
-prmd combine <directory>
+```console
+$ prmd combine <file or directory>
 ```
 
-Doc takes the path to a directory of schemas and outputs their documentation onto stdout. If -m or --meta is supplied, it will override defaults/metadata.
+Doc takes the path to a combined schema and outputs documentation to stdout.
+If -m or --meta is supplied, it will override defaults/metadata:
 
-```
-prmd doc <directory_or_schema>
+```console
+$ prmd doc <combined schema>
 ```
 
-Prepend file to the documentation output.
+You can also prepend files to the documention with -p or --prepend:
 
-```
-prmd doc -p header.md,overview.md <directory or schema>
+```console
+$ prmd doc -p header.md,overview.md <directory or schema>
 ```
 
-Init optionally takes a resource as it's first argument and generates a new schema file to stdout (generically or using the resource name provided). If -m or --meta is supplied, it will override defaults/metadata.
+Init optionally takes a resource as it's first argument and generates a
+new schema file to stdout (generically or using the resource name
+provided). If -m or --meta is supplied, it will override
+defaults/metadata:
 
-```
-prmd init
-prmd init <resource_name>
+```console
+$ prmd init
+$ prmd init <resource name>
 ```
 
-Verify takes a path to a directory of schemas or a particular schema file and checks to see if it matches expectations.
+Verify takes a path to a combined schema and warns about missing attributes.
 
-```
-prmd verify <directory_or_schema>
+```console
+$ prmd verify <combined schema>
 ```
 
-Combining commands works too.
+You can also chain commands as needed:
 
-```
-prmd combine <directory> | prmd verify | prmd doc > schema.md
+```console
+$ prmd combine <directory> | prmd verify | prmd doc > schema.md
 ```
 
 ## Contributing

data/bin/prmd

@@ -6,29 +6,25 @@ options = {}
 
 commands = {
   combine: OptionParser.new do |opts|
-    opts.banner = "prmd combine [options] <directory>"
+    opts.banner = "prmd combine [options] <file or directory>"
     opts.on("-m", "--meta meta.json", "Set defaults for schemata") do |m|
       options[:meta] = m
     end
   end,
   doc: OptionParser.new do |opts|
-    opts.banner = "prmd doc [options] <schema>"
-    opts.on("-m", "--meta meta.json", "Set defaults for schemata") do |m|
-      options[:meta] = m
-    end
+    opts.banner = "prmd doc [options] <combined schema>"
     opts.on("-p", "--prepend header,overview", Array, "Prepend files to output") do |p|
       options[:prepend] = p
     end
-    opts.banner = "prmd doc [options] <directory>"
   end,
   init: OptionParser.new do |opts|
-    opts.banner = "prmd init [options] <directory> <resource>"
+    opts.banner = "prmd init [options] <resource name>"
     opts.on("-m", "--meta meta.json", "Set defaults for schemata") do |m|
       options[:meta] = m
     end
   end,
   verify: OptionParser.new do |opts|
-    opts.banner = "prmd verify [options] <directory or schema>"
+    opts.banner = "prmd verify [options] <combined schema>"
   end
 }
 
@@ -68,37 +64,33 @@ option.order!
 
 case command
   when :combine
-    puts Prmd.combine(ARGV[0], options)
+    puts Prmd.combine(ARGV[0], options).to_s
   when :doc
-    if ARGV.empty?
+    unless $stdin.tty?
       data = JSON.parse($stdin.read)
-      schema = Prmd::Schema.new(data, options)
+      schema = Prmd::Schema.new(data)
       puts Prmd.doc(schema, options)
     else
-      schema = Prmd::Schema.load(ARGV[0])
+      data = JSON.parse(File.read(ARGV[0]))
+      schema = Prmd::Schema.new(data)
       puts Prmd.doc(schema, options)
     end
   when :init
     puts Prmd.init(ARGV[0], options)
   when :verify
-    errors = []
-    if ARGV.empty?
+    data, errors = '', []
+    unless $stdin.tty?
       data = $stdin.read
-      errors = Prmd.verify(JSON.parse(data))
-      puts data
-    elsif File.directory?(ARGV[0])
-      Dir.glob(File.join(ARGV[0], '**/*.json')).each do |path|
-        Prmd.verify(JSON.parse(File.read(path))).each do |error|
-          errors << "#{path}: #{error}"
-        end
-      end
+      errors.concat(Prmd.verify(JSON.parse(data)))
     else
-      Prmd.verify(JSON.parse(File.read(ARGV[0]))).each do |error|
+      data = JSON.parse(File.read(ARGV[0]))
+      Prmd.verify(data).each do |error|
         errors << "#{ARGV[0]}: #{error}"
       end
     end
     errors.each do |error|
-      $stderr.puts error
+      $stderr.puts(error)
     end
     exit(1) unless errors.empty?
+    puts(data) unless $stdout.tty?
 end

data/docs/schemata.md

@@ -42,7 +42,6 @@ Each attribute MUST include the following properties:
 Each attribute MAY include the following properties:
 
 * `pattern` - a regex encoded in a string that the valid values MUST match
-* `readOnly` - boolean value defining if the attribute can be modified, assumes `false` if omitted
 * `format` - format of the value. MUST be one of spec defined `["date-time", "email", "hostname", "ipv4", "ipv6", "uri"]` or defined by us `["uuid"]`
 
 Examples:
@@ -54,7 +53,6 @@ Examples:
       "description":  "unique identifier of resource",
       "example":      "01234567-89ab-cdef-0123-456789abcdef",
       "format":       "uuid",
-      "readOnly":     true,
       "type":         ["string"]
     },
     "url": {

data/lib/prmd/commands/combine.rb

@@ -1,5 +1,59 @@
 module Prmd
-  def self.combine(directory, options={})
-    Prmd::Schema.load(directory, options).to_s
+  def self.combine(path, options={})
+    files = if File.directory?(path)
+      Dir.glob(File.join(path, '**', '*.json')) - [options[:meta]]
+    else
+      [path]
+    end
+    schemas = files.map { |file| JSON.parse(File.read(file)) }
+
+    data = {
+      '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
+      'definitions' => {},
+      'properties'  => {},
+      'type'        => ['object']
+    }
+
+    if options[:meta] && File.exists?(options[:meta])
+      data.merge!(JSON.parse(File.read(options[:meta])))
+    end
+
+    schemas.each do |schema_data|
+      id = if schema_data['id']
+        schema_data['id'].split('/').last
+      end
+      next if id.nil? || id[0..0] == '_' # FIXME: remove this exception?
+
+      data['definitions'][id] = schema_data
+      reference_localizer = lambda do |datum|
+        case datum
+        when Array
+          datum.map {|element| reference_localizer.call(element)}
+        when Hash
+          if datum.has_key?('$ref')
+            if datum['$ref'].include?('/schema/')
+              $stderr.puts("`#{schema_data['id']}` `/schema/` prefixed refs are deprecated, use `/schemata/` prefixes")
+              datum['$ref'] = datum['$ref'].gsub(%r{/schema/([^#]*)#}, '#/definitions/\1')
+            end
+            datum['$ref'] = datum['$ref'].gsub(%r{/schemata/([^#]*)#}, '#/definitions/\1')
+          end
+          if datum.has_key?('href')
+            if datum['href'].include?('%2Fschema%2F')
+              $stderr.puts("`#{id}` `%2Fschema%2F` prefixed hrefs are deprecated, use `%2Fschemata%2F` prefixes")
+              datum['href'] = datum['href'].gsub(%r{%2Fschema%2F([^%]*)%23%2F}, '%23%2Fdefinitions%2F\1%2F')
+            end
+            datum['href'] = datum['href'].gsub(%r{%2Fschemata%2F([^%]*)%23%2F}, '%23%2Fdefinitions%2F\1%2F')
+          end
+          datum.each { |k,v| datum[k] = reference_localizer.call(v) }
+        else
+          datum
+        end
+      end
+      reference_localizer.call(data['definitions'][id])
+
+      data['properties'][id] = { '$ref' => "#/definitions/#{id}" }
+    end
+
+    Prmd::Schema.new(data)
   end
 end

data/lib/prmd/commands/doc.rb

@@ -2,7 +2,7 @@ def extract_attributes(schema, properties)
   attributes = []
   properties.each do |key, value|
     # found a reference to another element:
-    value = schema.dereference(value)
+    _, value = schema.dereference(value)
     if value.has_key?('anyOf')
       descriptions = []
       examples = []
@@ -13,7 +13,7 @@ def extract_attributes(schema, properties)
       end
 
       anyof.each do |ref|
-        nested_field = schema.dereference(ref)
+        _, nested_field = schema.dereference(ref)
         descriptions << nested_field['description']
         examples << nested_field['example']
       end
@@ -23,7 +23,10 @@ def extract_attributes(schema, properties)
         descriptions.first.gsub!(/ of (this )?.*/, "")
         descriptions[1..-1].map { |d| d.gsub!(/unique /, "") }
       end
-      description = descriptions.join(" or ")
+
+      last = descriptions.pop
+      description = [descriptions.join(", "), last].join(" or ")
+
       example = doc_example(*examples)
       attributes << [key, "string", description, example]
 
@@ -59,7 +62,7 @@ end
 
 module Prmd
   def self.doc(schema, options={})
-    root_url = schema['links'].find{|l| l['rel'] == 'root'}['href'] rescue schema['url']
+    root_url = schema['links'].find{|l| l['rel'] == 'self'}['href']
 
     doc = (options[:prepend] || []).map do |path|
       File.open(path, 'r').read + "\n"
@@ -73,20 +76,21 @@ module Prmd
         identifiers = if definition['definitions']['identity'].has_key?('anyOf')
           definition['definitions']['identity']['anyOf']
         else
-          [definitions['definitions']['identity']]
+          [definition['definitions']['identity']]
         end
 
         identifiers = identifiers.map {|ref| ref['$ref'].split('/').last }
       end
       if definition['properties']
         definition['properties'].each do |key, value|
-          unless value.has_key?('properties')
-            serialization[key] = schema.dereference(value)['example']
-          else
+          _, value = schema.dereference(value)
+          if value.has_key?('properties')
             serialization[key] = {}
             value['properties'].each do |k,v|
-              serialization[key][k] = schema.dereference(v)['example']
+              serialization[key][k] = schema.dereference(v).last['example']
             end
+          else
+            serialization[key] = value['example']
           end
         end
       else

data/lib/prmd/commands/expand.rb

@@ -39,25 +39,20 @@ if original['definitions']
     when 'uuid'
       {
         'example'   => '01234567-89ab-cdef-0123-456789abcdef',
-        'readOnly'  => true,
         'type'      => ['string']
       }
     when 'email'
       {
         'example'   => 'username@example.com',
-        'readOnly'  => false,
         'type'      => ['string']
       }
     when 'date-time'
       {
         'example'   => '2012-01-01T12:00:00Z',
-        'readOnly'  => true,
         'type'      => ['string']
       }
     else
-      {
-        'readOnly'  => false
-      }
+      {}
     end
     expanded['definitions'][key] = default.merge!(value)
   end

data/lib/prmd/commands/init.rb

@@ -3,10 +3,11 @@ module Prmd
     data = {
       '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
       'title'       => 'FIXME',
-      'type'        => ['object'],
       'definitions' => {},
+      'description' => 'FIXME',
       'links'       => [],
-      'properties'  => {}
+      'properties'  => {},
+      'type'        => ['object']
     }
 
     if options[:meta] && File.exists?(options[:meta])
@@ -16,83 +17,92 @@ module Prmd
     schema = Prmd::Schema.new(data)
 
     if resource
-      schema['id']    = "schema/#{resource}"
+      if resource.include?('/')
+        parent, resource = resource.split('/')
+      end
+      schema['id']    = "schemata/#{resource}"
       schema['title'] = "#{schema['title']} - #{resource[0...1].upcase}#{resource[1..-1]}"
       schema['definitions'] = {
         "created_at" => {
           "description" => "when #{resource} was created",
           "example"     => "2012-01-01T12:00:00Z",
           "format"      => "date-time",
-          "readOnly"    => true,
           "type"        => ["string"]
         },
         "id" => {
           "description" => "unique identifier of #{resource}",
           "example"     => "01234567-89ab-cdef-0123-456789abcdef",
           "format"      => "uuid",
-          "readOnly"    => true,
           "type"        => ["string"]
         },
         "identity" => {
-          "$ref" => "/schema/#{resource}#/definitions/id"
+          "$ref" => "/schemata/#{resource}#/definitions/id"
         },
         "updated_at" => {
           "description" => "when #{resource} was updated",
           "example"     => "2012-01-01T12:00:00Z",
           "format"      => "date-time",
-          "readOnly"    => true,
           "type"        => ["string"]
         }
       }
       schema['links'] = [
         {
-          "description" => "Create a new #{resource}.",
-          "href"        => "/#{resource}s",
-          "method"      => "POST",
-          "rel"         => "create",
-          "schema"      => {
+          "description"   => "Create a new #{resource}.",
+          "href"          => "/#{resource}s",
+          "method"        => "POST",
+          "rel"           => "create",
+          "schema"        => {
             "properties"  => {},
             "type"        => ["object"]
           },
-          "title"       => "Create"
+          "title"         => "Create"
         },
         {
-          "description" => "Delete an existing #{resource}.",
-          "href"        => "/#{resource}s/{(%2Fschema%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
-          "method"      => "DELETE",
-          "rel"         => "destroy",
-          "title"       => "Delete"
+          "description"   => "Delete an existing #{resource}.",
+          "href"          => "/#{resource}s/{(%2Fschemata%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
+          "method"        => "DELETE",
+          "rel"           => "destroy",
+          "title"         => "Delete"
         },
         {
-          "description"  => "Info for existing #{resource}.",
-          "href"        => "/#{resource}s/{(%2Fschema%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
-          "method"       => "GET",
-          "rel"          => "self",
-          "title"        => "Info"
+          "description"   => "Info for existing #{resource}.",
+          "href"          => "/#{resource}s/{(%2Fschemata%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
+          "method"        => "GET",
+          "rel"           => "self",
+          "title"         => "Info"
         },
         {
-          "description"  => "List existing #{resource}.",
-          "href"        => "/#{resource}s",
-          "method"       => "GET",
-          "rel"          => "instances",
-          "title"        => "List"
+          "description"   => "List existing #{resource}s.",
+          "href"          => "/#{resource}s",
+          "method"        => "GET",
+          "rel"           => "instances",
+          "title"         => "List"
         },
         {
-          "description"  => "Update an existing #{resource}.",
-          "href"        => "/#{resource}s/{(%2Fschema%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
-          "method"       => "PATCH",
-          "rel"          => "update",
-          "schema"      => {
+          "description"   => "Update an existing #{resource}.",
+          "href"          => "/#{resource}s/{(%2Fschemata%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
+          "method"        => "PATCH",
+          "rel"           => "update",
+          "schema"        => {
             "properties"  => {},
             "type"        => ["object"]
           },
-          "title"        => "Update"
+          "title"         => "Update"
         }
       ]
+      if parent
+        schema['links'] << {
+          "description"  => "List existing #{resource}s for existing #{parent}.",
+          "href"         => "/#{parent}s/{(%2Fschemata%2F#{parent}%23%2Fdefinitions%2Fidentity)}/#{resource}s",
+          "method"       => "GET",
+          "rel"          => "instances",
+          "title"        => "List"
+        }
+      end
       schema['properties'] = {
-        "created_at"  => { "$ref" => "/schema/#{resource}#/definitions/created_at" },
-        "id"          => { "$ref" => "/schema/#{resource}#/definitions/id" },
-        "updated_at"  => { "$ref" => "/schema/#{resource}#/definitions/updated_at" }
+        "created_at"  => { "$ref" => "/schemata/#{resource}#/definitions/created_at" },
+        "id"          => { "$ref" => "/schemata/#{resource}#/definitions/id" },
+        "updated_at"  => { "$ref" => "/schemata/#{resource}#/definitions/updated_at" }
       }
     end
 

data/lib/prmd/commands/verify.rb

@@ -1,11 +1,23 @@
 module Prmd
   def self.verify(schema)
     errors = []
+    errors << verify_schema(schema)
+    if schema['definitions']
+      schema['definitions'].each do |key, value|
+        errors << verify_schema(value)
+        errors << verify_definitions_and_links(value)
+      end
+    end
+    errors.flatten!
+  end
+
+  def self.verify_schema(schema)
+    errors = []
 
     id = schema['id']
 
     missing_requirements = []
-    %w{description id $schema title type definitions links properties}.each do |requirement|
+    %w{$schema definitions description id links properties title type}.each do |requirement|
       unless schema.has_key?(requirement)
         missing_requirements << requirement
       end
@@ -14,6 +26,14 @@ module Prmd
       errors << "Missing `#{id}#/#{missing_requirement}`"
     end
 
+    errors
+  end
+
+  def self.verify_definitions_and_links(schema)
+    errors = []
+
+    id = schema['id']
+
     if schema['definitions']
       unless schema['definitions'].has_key?('identity')
         errors << "Missing `#{id}#/definitions/identity`"
@@ -21,7 +41,7 @@ module Prmd
       schema['definitions'].each do |key, value|
         missing_requirements = []
         unless key == 'identity'
-          %w{description readOnly type}.each do |requirement|
+          %w{description type}.each do |requirement|
             unless schema['definitions'][key].has_key?(requirement)
               missing_requirements << requirement
             end
@@ -59,6 +79,8 @@ module Prmd
           errors << "Missing #{missing_requirement} in `#{link}` link for `#{id}`"
         end
       end
+    else
+      errors << "Missing `#{id}/links`"
     end
 
     errors

data/lib/prmd/schema.rb

@@ -9,61 +9,13 @@ module Prmd
       @data[key] = value
     end
 
-    def self.load(path, options={})
-      unless File.directory?(path)
-        data = JSON.parse(File.read(path))
-      else
-        data = {
-          '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
-          'definitions' => {},
-          'properties'  => {},
-          'type'        => ['object']
-        }
-
-        if options[:meta] && File.exists?(options[:meta])
-          data.merge!(JSON.parse(File.read(options[:meta])))
-        end
-
-        Dir.glob(File.join(path, '**', '*.json')).each do |schema|
-          schema_data = JSON.parse(File.read(schema))
-          id = if schema_data['id']
-            schema_data['id'].gsub('schema/', '')
-          end
-          next if id.nil? || id[0..0] == '_' # FIXME: remove this exception?
-
-          data['definitions'][id] = schema_data
-          reference_localizer = lambda do |datum|
-            case datum
-            when Array
-              datum.map {|element| reference_localizer.call(element)}
-            when Hash
-              if datum.has_key?('$ref')
-                datum['$ref'] = datum['$ref'].gsub(%r{/schema/([^#]*)#}, '#/definitions/\1')
-              end
-              if datum.has_key?('href')
-                datum['href'] = datum['href'].gsub(%r{%2Fschema%2F([^%]*)%23%2F}, '%23%2Fdefinitions%2F\1%2F')
-              end
-              datum.each { |k,v| datum[k] = reference_localizer.call(v) }
-            else
-              datum
-            end
-          end
-          reference_localizer.call(data['definitions'][id])
-
-          data['properties'][id] = { '$ref' => "#/definitions/#{id}" }
-        end
-      end
-
-      self.new(data)
-    end
-
     def initialize(new_data = {})
       convert_type_to_array = lambda do |datum|
         case datum
         when Array
           datum.map { |element| convert_type_to_array.call(element) }
         when Hash
-          if datum.has_key?('type')
+          if datum.has_key?('type') && datum['type'].is_a?(String)
             datum['type'] = [*datum['type']]
           end
           datum.each { |k,v| datum[k] = convert_type_to_array.call(v) }
@@ -77,19 +29,26 @@ module Prmd
     def dereference(reference)
       if reference.is_a?(Hash)
         if reference.has_key?('$ref')
-          key = reference['$ref']
+          value = reference.dup
+          key = value.delete('$ref')
         else
-          return reference # no dereference needed
+          return [nil, reference] # no dereference needed
         end
       else
-        key = reference
+        key, value = reference, {}
       end
       begin
         datum = @data
         key.gsub(%r{[^#]*#/}, '').split('/').each do |fragment|
           datum = datum[fragment]
         end
-        datum
+        # last dereference will have nil key, so compact it out
+        # [-2..-1] should be the final key reached before deref
+        dereferenced_key, dereferenced_value = dereference(datum)
+        [
+          [key, dereferenced_key].compact.last,
+          [dereferenced_value, value].inject({}) { |composite, element| composite.merge(element) }
+        ]
       rescue => error
         $stderr.puts("Failed to dereference `#{key}`")
         raise(error)

data/lib/prmd/version.rb

@@ -1,3 +1,3 @@
 module Prmd
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/prmd/views/endpoint.erb

@@ -24,8 +24,13 @@
 <%- definition['links'].each do |link, datum| %>
 <%- path = link['href'].gsub(%r|(\{\([^\)]+\)\})|) do |ref|
   ref = ref.gsub('%2F', '/').gsub('%23', '#').gsub(%r|[\{\(\)\}]|, '')
-  resource = ref.split('#/definitions/').last.split('/definitions/identity').first
-  '{' + resource + '_' + schema.dereference(ref)['anyOf'].map {|r| r['$ref'].split('/').last}.join('_or_') + '}'
+  resource = ref.match(%r{^#/definitions/([^/]*)}).captures.first
+  identity_key, identity_value = schema.dereference(ref)
+  if identity_value.has_key?('anyOf')
+    '{' + resource + '_' + identity_value['anyOf'].map {|r| r['$ref'].split('/').last}.join('_or_') + '}'
+  else
+    '{' + resource + '_' + identity_key.split('/').last + '}'
+  end
 end -%>
 ### <%= title %> <%= link['title'] %>
 <%= link['description'] %>
@@ -53,31 +58,52 @@ end -%>
 
 #### Curl Example
 ```term
-$ curl -n -X <%= link['method'] %> <%= root_url %><%= path.gsub(/{([^}]*)}/) {|match| '$' + match.gsub(/[{}]/, '').gsub('-', '_').upcase} %><%- if link.has_key?('schema') && (link['schema'].has_key?('properties') || link['schema'].has_key?('example')) %> \
--H "Content-Type: application/json" \
-<%-
-  data = {}
-  if link['schema']['properties']
-    link['schema']['properties'].each do |key, value|
-      if value.has_key?('anyOf')
-        id_ref = value['anyOf'].detect {|ref| ref['$ref'].split('/').last == 'id'}
-        data[key] = schema.dereference(id_ref)['example']
-      elsif value.has_key?('properties')
-        data[key] = {}
-        value['properties'].each do |k,v|
-          data[key][k] = v['example']
+<%- path = path.gsub(/{([^}]*)}/) {|match| '$' + match.gsub(/[{}]/, '')} %>
+<%- if link.has_key?('schema') && (link['schema'].has_key?('properties') || link['schema'].has_key?('example')) %>
+  <%-
+    data = {}
+    if link['schema']['properties']
+      link['schema']['properties'].each do |key, value|
+        if value.has_key?('anyOf')
+          id_ref = value['anyOf'].detect {|ref| ref['$ref'].split('/').last == 'id'}
+          data[key] = schema.dereference(id_ref).last['example']
+        elsif value.has_key?('properties')
+          data[key] = {}
+          value['properties'].each do |k,v|
+            data[key][k] = schema.dereference(v).last['example']
+          end
+        else
+          data[key] = schema.dereference(value).last['example']
         end
-      else
-        data[key] = value['example']
       end
+    else
+      data.merge!(link['schema']['example'])
     end
-  else
-    data.merge!(link['schema']['example'])
-  end
-%>
+  %>
+  <%- if link['method'].upcase == 'GET' %>
+    <%-
+      unless data.empty?
+        path << '?'
+        data.sort_by {|k,_| k.to_s }.each do |key, values|
+          if values.nil?
+            path << key.to_s << '&'
+          else
+            [values].flatten.each do |value|
+              path << key.to_s << '=' << CGI.escape(value.to_s) << '&'
+            end
+          end
+        end
+        path.chop! # remove trailing '&'
+      end
+    %>
+$ curl -n -X <%= link['method'] %> <%= root_url %><%= path %>
+  <%- else %>
+$ curl -n -X <%= link['method'] %> <%= root_url %><%= path %> \
+-H "Content-Type: application/json" \
 -d '<%= data.to_json %>'
+  <%- end %>
 <%- else %>
-
+$ curl -n -X <%= link['method'] %> <%= root_url %><%= path %>
 <%- end %>
 ```
 
@@ -89,12 +115,6 @@ when 'create'
 else
   '200 OK'
 end %>
-<%- if link['rel'] == 'instances' && identifiers %>
-Accept-Range: <%= identifiers.join(', ') %>
-Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
-<%- end %>
-ETag: "0123456789abcdef0123456789abcdef"
-RateLimit-Remaining: 1200
 ```
 ```javascript```
 <%- if link['rel'] == 'instances' %>

data/lib/prmd.rb

@@ -1,4 +1,4 @@
-require "diff-lcs"
+require "cgi"
 require "erubis"
 require "json"
 

data/prmd.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = Prmd::VERSION
   spec.authors       = ["geemus"]
   spec.email         = ["geemus@gmail.com"]
-  spec.description   = %q{schema to rule them all}
-  spec.summary       = %q{schema to rule them all}
-  spec.homepage      = ""
+  spec.description   = %q{scaffold, verify and generate docs from JSON Schema}
+  spec.summary       = %q{JSON Schema tooling}
+  spec.homepage      = "https://github.com/heroku/prmd"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)
@@ -18,10 +18,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "diff-lcs"
-  spec.add_dependency "erubis"
+  spec.add_dependency "erubis", "~> 2.7"
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "bundler",  "~> 1.3"
+  spec.add_development_dependency "rake",     "~> 10.2"
+  spec.add_development_dependency "minitest", "~> 5.3"
 end

data/test/helpers.rb

@@ -2,9 +2,9 @@ require "minitest/autorun"
 require "prmd"
 
 def input_schemas_path
-  @data_path ||= File.join(File.dirname(__FILE__), 'schemas', 'input')
+  @@data_path ||= File.join(File.dirname(__FILE__), 'schemas', 'input')
 end
 
 def user_input_schema
-  @user_input_schema ||= Prmd::Schema.load(File.join(input_schemas_path, 'user.json'))
+  @@user_input_schema ||= Prmd.combine(File.join(input_schemas_path, 'user.json'))
 end

data/test/schema_test.rb

@@ -1,13 +1,34 @@
-require File.join(File.dirname(__FILE__), 'helpers')
+require File.expand_path(File.join(File.dirname(__FILE__), 'helpers'))
 
 class SchemaTest < Minitest::Unit::TestCase
   def test_dereference_with_ref
-    ref = user_input_schema.dereference({ "$ref" => "/schema/user#/definitions/id" })
-    assert_equal ref, user_input_schema["definitions"]["id"]
+    key, value = user_input_schema.dereference({
+      '$ref' => '#/definitions/user/definitions/id'
+    })
+    assert_equal(key,   '#/definitions/user/definitions/id')
+    assert_equal(value, user_input_schema['definitions']['user']['definitions']['id'])
   end
 
   def test_dereference_without_ref
-    ref = user_input_schema.dereference("/schema/user#/definitions/id")
-    assert_equal ref, user_input_schema["definitions"]["id"]
+    key, value = user_input_schema.dereference('#/definitions/user/definitions/id')
+    assert_equal(key,   '#/definitions/user/definitions/id')
+    assert_equal(value, user_input_schema['definitions']['user']['definitions']['id'])
+  end
+
+  def test_dereference_with_nested_ref
+    key, value = user_input_schema.dereference({
+      '$ref' => '#/definitions/user/definitions/identity'
+    })
+    assert_equal(key,   '#/definitions/user/definitions/id')
+    assert_equal(value, user_input_schema['definitions']['user']['definitions']['id'])
+  end
+
+  def test_dereference_with_local_context
+    key, value = user_input_schema.dereference({
+      '$ref'     => '#/definitions/user/properties/id',
+      'override' => true
+    })
+    assert_equal(key,   '#/definitions/user/definitions/id')
+    assert_equal(value, {'override' => true}.merge(user_input_schema['definitions']['user']['definitions']['id']))
   end
 end

data/test/schemas/input/meta.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-04/hyper-schema",
+  "definitions": {},
+  "description": "API lets you interact with service",
+  "links": [{
+    "href": "https://api.example.com",
+    "rel": "self"
+  }],
+  "properties": {},
+  "title": "API",
+  "type": [
+    "object"
+  ]
+}

data/test/schemas/input/user.json

@@ -9,7 +9,6 @@
       "description": "when user was created",
       "example": "2012-01-01T12:00:00Z",
       "format": "date-time",
-      "readOnly": true,
       "type": [
         "string"
       ]
@@ -18,19 +17,17 @@
       "description": "unique identifier of user",
       "example": "01234567-89ab-cdef-0123-456789abcdef",
       "format": "uuid",
-      "readOnly": true,
       "type": [
         "string"
       ]
     },
     "identity": {
-      "$ref": "/schema/user#/definitions/id"
+      "$ref": "/schemata/user#/definitions/id"
     },
     "updated_at": {
       "description": "when user was updated",
       "example": "2012-01-01T12:00:00Z",
       "format": "date-time",
-      "readOnly": true,
       "type": [
         "string"
       ]
@@ -53,14 +50,14 @@
     },
     {
       "description": "Delete an existing user.",
-      "href": "/users/{(%2Fschema%2Fuser%23%2Fdefinitions%2Fidentity)}",
+      "href": "/users/{(%2Fschemata%2Fuser%23%2Fdefinitions%2Fidentity)}",
       "method": "DELETE",
       "rel": "destroy",
       "title": "Delete"
     },
     {
       "description": "Info for existing user.",
-      "href": "/users/{(%2Fschema%2Fuser%23%2Fdefinitions%2Fidentity)}",
+      "href": "/users/{(%2Fschemata%2Fuser%23%2Fdefinitions%2Fidentity)}",
       "method": "GET",
       "rel": "self",
       "title": "Info"
@@ -74,7 +71,7 @@
     },
     {
       "description": "Update an existing user.",
-      "href": "/users/{(%2Fschema%2Fuser%23%2Fdefinitions%2Fidentity)}",
+      "href": "/users/{(%2Fschemata%2Fuser%23%2Fdefinitions%2Fidentity)}",
       "method": "PATCH",
       "rel": "update",
       "schema": {
@@ -89,14 +86,14 @@
   ],
   "properties": {
     "created_at": {
-      "$ref": "/schema/user#/definitions/created_at"
+      "$ref": "/schemata/user#/definitions/created_at"
     },
     "id": {
-      "$ref": "/schema/user#/definitions/id"
+      "$ref": "/schemata/user#/definitions/id"
     },
     "updated_at": {
-      "$ref": "/schema/user#/definitions/updated_at"
+      "$ref": "/schemata/user#/definitions/updated_at"
     }
   },
-  "id": "schema/user"
+  "id": "schemata/user"
 }

metadata

@@ -1,43 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: prmd
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - geemus
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-07 00:00:00.000000000 Z
+date: 2014-04-10 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: diff-lcs
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: erubis
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -56,31 +42,31 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.2'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
-description: schema to rule them all
+        version: '5.3'
+description: scaffold, verify and generate docs from JSON Schema
 email:
 - geemus@gmail.com
 executables:
@@ -111,8 +97,9 @@ files:
 - prmd.gemspec
 - test/helpers.rb
 - test/schema_test.rb
+- test/schemas/input/meta.json
 - test/schemas/input/user.json
-homepage: ''
+homepage: https://github.com/heroku/prmd
 licenses:
 - MIT
 metadata: {}
@@ -135,9 +122,10 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: schema to rule them all
+summary: JSON Schema tooling
 test_files:
 - test/helpers.rb
 - test/schema_test.rb
+- test/schemas/input/meta.json
 - test/schemas/input/user.json
 has_rdoc: