prmd 0.3.2 → 0.4.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MzFkN2NlODhjNzdiNjMyN2E1YTQwMTg0MWRjMTNhMDUwZWE5YTc3OA==
+    YTBiMDJmODY4NDAwMTE1ZTMzZTJiY2I2MzA1M2VkMzM2OWZkYmI5NA==
   data.tar.gz: !binary |-
-    OGQzODUzMzI3M2U5YjliZDNhNzQ0YjM2ZTUzNzA1MjI1ODQ3Y2NiZA==
+    MTc2MjY0MjgzMDEwYzhhYWVmYzZkY2VhNjI0YmM3ZmI4MThhYzFlZA==
 SHA512:
   metadata.gz: !binary |-
-    NzgxZjQyZGMxNDRhMDM3YjI0OGUyYTdiMDVjMzYzNjUzZGJkNDM4MTU0Mjg0
-    NzMyN2I0ODBiZDNmZTc0NDIzZjU4YWQwMWJkNWQ5NDNkOWYyYjY3MTRkODJm
-    NzU4OWFlM2NkMWY5NDY5MmYxYjVhN2I4NDk2OWM4NTYxNTliMTc=
+    ZDJkMzVkZTk4ZTI1YmU5M2Q2MGVmNzZhZjI0YzFmODYwNDE0YThlYjA1MTYw
+    NDI0ZDNhYmFjOTczNTllOTBjZDgyNDYwZGQyMzZhYmVlMzZlMTFjZTIzYWVm
+    MmNjOTA0MTIzMWRlNjNmMDU5YTQ3YjZkZjQyZGQ1MzY1YWNlNGI=
   data.tar.gz: !binary |-
-    NGVkMDAxMGUxMzk4ODY5NTM4N2VlNjJjMzBjMWEyOWFhY2JhMGIyOTkwMjU0
-    OWUwNTkyMTlkZWE2MjM4Yjk0NDI5MzRiZDhlOGI3MTU4OWMxZWY3ZWVlNjll
-    ZGUxYzE0N2QyZmJjZWNjOWM4N2Q3ZGFhMzg1YjdlZjc5ZmRkNzM=
+    NmI3N2ViOGIyZDE1NTljODExNDhkY2E2MDlmZThhZTFiZWE2YmFhNmQyNTg0
+    MTBjYzczMjg4NDI1OGVjODlkOTI5NzU5YjllYmMyZGJjYzQ2N2I1YWZlMGM2
+    MzY3YzIwM2RjYTlkNzk5MzExNjU0NjAxZDUzYTIzODlkZDQ2YjY=

data/Gemfile.lock

@@ -1,13 +1,15 @@
 PATH
   remote: .
   specs:
-    prmd (0.3.1)
+    prmd (0.4.0)
       erubis (~> 2.7)
+      json_schema (~> 0.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     erubis (2.7.0)
+    json_schema (0.1.4)
     minitest (5.3.2)
     rake (10.2.2)
 

data/Rakefile

@@ -2,7 +2,7 @@ require "bundler/gem_tasks"
 require "rake/testtask"
 
 Rake::TestTask.new do |t|
-  t.pattern = "test/*_test.rb"
+  t.pattern = "test/**/*_test.rb"
 end
 
 task :default => :test

data/bin/prmd

@@ -16,6 +16,9 @@ commands = {
     opts.on("-p", "--prepend header,overview", Array, "Prepend files to output") do |p|
       options[:prepend] = p
     end
+    opts.on("-c", "--content-type application/json", String, "Content-Type header") do |c|
+      options[:content_type] = c
+    end
   end,
   init: OptionParser.new do |opts|
     opts.banner = "prmd init [options] <resource name>"
@@ -24,11 +27,11 @@ commands = {
     end
   end,
   render: OptionParser.new do |opts|
-    opts.banner = "prmd doc [options] <combined schema>"
+    opts.banner = "prmd render [options] <combined schema>"
     opts.on("-p", "--prepend header,overview", Array, "Prepend files to output") do |p|
       options[:prepend] = p
     end
-    opts.on("-t", "--template schemata.erb", String, "Use alternate template") do |t|
+    opts.on("-t", "--template templates", String, "Use alternate template") do |t|
       options[:template] = t
     end
   end,
@@ -82,7 +85,7 @@ case command
     end
     schema = Prmd::Schema.new(JSON.parse(data))
 
-    options[:template] = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'prmd', 'templates', 'schema.erb'))
+    options[:template] = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'prmd', 'templates'))
 
     puts Prmd.render(schema, options)
   when :init

data/docs/schemata.md

@@ -81,7 +81,8 @@ The links array MUST include an object defining each action available. Each acti
 Links that expect a json-encoded body as input MUST also include the following attributes:
 * `schema` - an object with a `properties` object that MUST include JSON pointers to the definitions for each associated attribute
 
-Schema properties MAY also include a `required` boolean to indicate if an attribute must be present, which is assumed to be false when omitted.
+The `schema` object MAY also include a `required` array to define all attributes for this link, which can not be omitted.
+If this field is not present, all attributes in this link are considered as optional.
 
 ```javascript
 {
@@ -95,7 +96,8 @@ Schema properties MAY also include a `required` boolean to indicate if an attrib
         "properties": {
           "owner":  { "$ref": "/schema/user#/definitions/identity" },
           "url":    { "$ref": "/schema/resource/definitions/url" }
-        }
+        },
+        "required": [ "owner", "url" ]
       },
       "title":        "Create"
     },

data/lib/prmd.rb

@@ -11,6 +11,7 @@ require File.join(dir, 'prmd', 'commands', 'render')
 require File.join(dir, 'prmd', 'commands', 'verify')
 require File.join(dir, 'prmd', 'schema')
 require File.join(dir, 'prmd', 'version')
+require File.join(dir, 'prmd', 'template')
 
 module Prmd
 end

data/lib/prmd/commands/combine.rb

@@ -8,7 +8,17 @@ module Prmd
       [path]
     end
     # sort for stable loading on any platform
-    schemata = files.sort.map { |file| [file, YAML.load(File.read(file))] }
+    schemata = []
+    files.sort.each do |file|
+      begin
+        schemata << [file, YAML.load(File.read(file))]
+      rescue
+        $stderr.puts "unable to parse #{file}"
+      end
+    end
+    unless schemata.length == files.length
+      exit(1) # one or more files failed to parse
+    end
 
     data = {
       '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
@@ -45,7 +55,7 @@ module Prmd
           if datum.has_key?('$ref')
             datum['$ref'] = '#/definitions' + datum['$ref'].gsub('#', '').gsub('/schemata', '')
           end
-          if datum.has_key?('href')
+          if datum.has_key?('href') && datum['href'].is_a?(String)
             datum['href'] = datum['href'].gsub('%23', '').gsub(%r{%2Fschemata(%2F[^%]*%2F)}, '%23%2Fdefinitions\1')
           end
           datum.each { |k,v| datum[k] = reference_localizer.call(v) }

data/lib/prmd/commands/render.rb

@@ -2,11 +2,19 @@ module Prmd
   def self.render(schema, options={})
     doc = ''
 
+    options[:content_type] ||= 'application/json'
+
     if options[:prepend]
       doc << options[:prepend].map {|path| File.read(path)}.join("\n") << "\n"
     end
 
-    doc << Erubis::Eruby.new(File.read(options[:template])).result({
+    template_dir = File::expand_path(options[:template])
+    if not File.directory?(template_dir)  # to keep backward compatibility
+      template_dir = File.dirname(options[:template])
+    end
+    options[:template] = template_dir
+
+    doc << Prmd::Template::render('schema.erb', template_dir, {
       options:         options,
       schema:          schema
     })

data/lib/prmd/commands/verify.rb

@@ -1,87 +1,51 @@
-module Prmd
-  def self.verify(schema)
-    errors = []
-    errors << verify_schema(schema['id'], schema)
-    schema = Prmd::Schema.new(schema)
-    if schema['properties']
-      schema['properties'].each do |key, value|
-        id, schemata = schema.dereference(value)
+require "json"
+require "json_schema"
 
-        errors << verify_schema(id, schemata)
-        errors << verify_definitions_and_links(id, schemata)
-      end
+module Prmd
+  # These schemas are listed manually and in order because they reference each
+  # other.
+  SCHEMAS = [
+    "schema.json",
+    "hyper-schema.json",
+    "interagent-hyper-schema.json"
+  ]
+
+  def self.verify(schema_data)
+    store = init_document_store
+
+    if !(schema_uri = schema_data["$schema"])
+      return ["Missing $schema."]
     end
-    errors.flatten!
-  end
 
-  def self.verify_schema(id, schema)
-    errors = []
+    # for good measure, make sure that the schema parses and that its
+    # references can be expanded
+    schema, errors = JsonSchema.parse!(schema_data)
+    return JsonSchema::SchemaError.aggregate(errors) if !schema
 
-    missing_requirements = []
-    %w{$schema definitions description links properties title type}.each do |requirement|
-      unless schema.has_key?(requirement)
-        missing_requirements << requirement
-      end
-    end
-    missing_requirements.each do |missing_requirement|
-      errors << "Missing `#{id}#/#{missing_requirement}`"
+    valid, errors = schema.expand_references(store: store)
+    return JsonSchema::SchemaError.aggregate(errors) if !valid
+
+    if !(meta_schema = store.lookup_schema(schema_uri))
+      return ["Unknown $schema: #{schema_uri}."]
     end
 
-    errors
-  end
+    valid, errors = meta_schema.validate(schema_data)
+    return JsonSchema::SchemaError.aggregate(errors) if !valid
 
-  def self.verify_definitions_and_links(id, schema)
-    errors = []
+    []
+  end
 
-    if schema['definitions']
-      unless schema['definitions'].has_key?('identity')
-        errors << "Missing `#{id}#/definitions/identity`"
-      end
-      schema['definitions'].each do |key, value|
-        missing_requirements = []
-        unless key == 'identity'
-          %w{description type}.each do |requirement|
-            unless schema['definitions'][key].has_key?(requirement)
-              missing_requirements << requirement
-            end
-          end
-        end
-        # check for example, unless they are nested in array/object
-        type = schema['definitions'][key]['type']
-        unless type.nil? || type.include?('array') || type.include?('object')
-          unless schema['definitions'][key].has_key?('example')
-            missing_requirements << 'example'
-          end
-        end
-        missing_requirements.each do |missing_requirement|
-          errors << "Missing `#{id}#/definitions/#{key}/#{missing_requirement}`"
-        end
-      end
-    end
+  private
 
-    if schema['links']
-      schema['links'].each do |link|
-        missing_requirements = []
-        %w{description href method rel title}.each do |requirement|
-          unless link.has_key?(requirement)
-            missing_requirements << requirement
-          end
-        end
-        if link.has_key?('schema')
-          %w{properties type}.each do |requirement|
-            unless link['schema'].has_key?(requirement)
-              missing_requirements << "schema/#{requirement}"
-            end
-          end
-        end
-        missing_requirements.each do |missing_requirement|
-          errors << "Missing #{missing_requirement} in `#{link}` link for `#{id}`"
-        end
-      end
-    else
-      errors << "Missing `#{id}/links`"
+  def self.init_document_store
+    store = JsonSchema::DocumentStore.new
+    SCHEMAS.each do |file|
+      file = File.expand_path("../../../../schemas/#{file}", __FILE__)
+      data = JSON.parse(File.read(file))
+      schema = JsonSchema::Parser.new.parse!(data)
+      schema.expand_references!(store: store)
+      store.add_schema(schema)
     end
-
-    errors
+    store
   end
 end

data/lib/prmd/schema.rb

@@ -72,15 +72,19 @@ module Prmd
     end
 
     def schema_example(schema)
-      if schema.has_key?('example')
-        schema['example']
-      elsif schema.has_key?('properties')
+      _, _schema = dereference(schema)
+
+      if _schema.has_key?('example')
+        _schema['example']
+      elsif _schema.has_key?('properties')
         example = {}
-        schema['properties'].each do |key, value|
+        _schema['properties'].each do |key, value|
           _, value = dereference(value)
           example[key] = schema_value_example(value)
         end
         example
+      elsif _schema.has_key?('items')
+        schema_value_example(_schema)
       end
     end
 

data/lib/prmd/template.rb

@@ -0,0 +1,19 @@
+module Prmd
+  class Template
+    def self.load(path, base)
+      fallback = File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
+
+      resolved = File.join(base, path)
+      if not File.exist?(resolved)
+        resolved = File.join(fallback, path)
+      end
+
+      return File.read(resolved)
+    end
+
+    def self.render(path, base, *args)
+      template = self.load(path, base)
+      Erubis::Eruby.new(template).result(*args)
+    end
+  end
+end

data/lib/prmd/templates/schema.erb

@@ -1,13 +1,18 @@
 <%=
-  schemata_template = File.read(File.join(File.dirname(options[:template]), 'schemata.erb'))
+  schemata_template = Prmd::Template::load('schemata.erb', options[:template])
 
   schema['properties'].map do |resource, property|
-    _, schemata = schema.dereference(property)
-    Erubis::Eruby.new(schemata_template).result({
-      options:         options,
-      resource:        resource,
-      schema:          schema,
-      schemata:        schemata
-    })
+    begin
+      _, schemata = schema.dereference(property)
+      Erubis::Eruby.new(schemata_template).result({
+        options:         options,
+        resource:        resource,
+        schema:          schema,
+        schemata:        schemata
+      })
+    rescue => e 
+      $stdout.puts("Error in resource: #{resource}")
+      raise e
+    end
   end.join("\n") << "\n"
 %>

data/lib/prmd/templates/schemata.erb

@@ -1,74 +1,14 @@
 <%-
   return unless schemata.has_key?('links') && !schemata['links'].empty?
 
-  link_schema_properties_template = File.read(File.join(File.dirname(options[:template]), 'link_schema_properties.erb'))
-  title = schemata['title'].split(' - ', 2).last
-
-  def extract_attributes(schema, properties)
-    attributes = []
-    properties = properties.sort_by {|k,v| k} # ensure consistent ordering
-
-    properties.each do |key, value|
-      # found a reference to another element:
-      _, value = schema.dereference(value)
-      if value.has_key?('anyOf')
-        descriptions = []
-        examples = []
-
-        # sort anyOf! always show unique identifier first
-        anyof = value['anyOf'].sort_by do |property|
-          property['$ref'].split('/').last.gsub('id', 'a')
-        end
-
-        anyof.each do |ref|
-          _, nested_field = schema.dereference(ref)
-          descriptions << nested_field['description']
-          examples << nested_field['example']
-        end
-
-        # avoid repetition :}
-        description = if descriptions.size > 1
-          descriptions.first.gsub!(/ of (this )?.*/, "")
-          descriptions[1..-1].map { |d| d.gsub!(/unique /, "") }
-          [descriptions[0...-1].join(", "), descriptions.last].join(" or ")
-        else
-          description = descriptions.last
-        end
+  Prmd::Template::render(File.join('schemata', 'helper.erb'), options[:template], {
+    options:         options,
+    resource:        resource,
+    schema:          schema,
+    schemata:        schemata
+  })
 
-        example = [*examples].map { |e| "<code>#{e.to_json}</code>" }.join(" or ")
-        attributes << [key, "string", description, example]
-
-      # found a nested object
-      elsif value['type'] == ['object'] && value['properties']
-        nested = extract_attributes(schema, value['properties'])
-        nested.each do |attribute|
-          attribute[0] = "#{key}:#{attribute[0]}"
-        end
-        attributes.concat(nested)
-      # just a regular attribute
-      else
-        description = value['description']
-        if value['enum']
-          description += '<br/><b>one of:</b>' + [*value['enum']].map { |e| "<code>#{e.to_json}</code>" }.join(" or ")
-        end
-
-        if value.has_key?('example')
-          example = [*value['example']].map { |e| "<code>#{e.to_json}</code>" }.join(" or ")
-        elsif value['type'] == ['array'] && value.has_key?('items')
-          example = "<code>#{schema.schema_value_example(value)}</code>"
-        end
-
-        type = if value['type'].include?('null')
-          'nullable '
-        else
-          ''
-        end
-        type += (value['format'] || (value['type'] - ['null']).first)
-        attributes << [key, type, description, example]
-      end
-    end
-    return attributes
-  end
+  title = schemata['title'].split(' - ', 2).last
 %>
 ## <%= title %>
 <%= schemata['description'] %>
@@ -94,83 +34,14 @@
 
 <%- end %>
 <%- schemata['links'].each do |link, datum| %>
-  <%-
-    path = link['href'].gsub(%r|(\{\([^\)]+\)\})|) do |ref|
-      ref = ref.gsub('%2F', '/').gsub('%23', '#').gsub(%r|[\{\(\)\}]|, '')
-      ref_resource = ref.split('#/definitions/').last.split('/').first.gsub('-','_')
-      identity_key, identity_value = schema.dereference(ref)
-      if identity_value.has_key?('anyOf')
-        '{' + ref_resource + '_' + identity_value['anyOf'].map {|r| r['$ref'].split('/').last}.join('_or_') + '}'
-      else
-        '{' + ref_resource + '_' + identity_key.split('/').last + '}'
-      end
-    end
-  -%>
-### <%= title %> <%= link['title'] %>
-<%= link['description'] %>
-
-```
-<%= link['method'] %> <%= path %>
-```
-
-  <%- if link.has_key?('schema') && link['schema'].has_key?('properties') %>
-    <%-
-      required, optional = link['schema']['properties'].partition do |k, v|
-        (link['schema']['required'] || []).include?(k)
-      end.map { |partition| Hash[partition] }
-    %>
-    <%- unless required.empty? %>
-#### Required Parameters
-<%= Erubis::Eruby.new(link_schema_properties_template).result(params: required, schema: schema) %>
-
-    <%- end %>
-      <%- unless optional.empty? %>
-#### Optional Parameters
-<%= Erubis::Eruby.new(link_schema_properties_template).result(params: optional, schema: schema) %>
-    <%- end %>
-  <%- end %>
-
-#### Curl Example
-```term
-  <%-
-    data = {}
-    path = path.gsub(/{([^}]*)}/) {|match| '$' + match.gsub(/[{}]/, '').upcase}
-
-    if link.has_key?('schema')
-      data.merge!(schema.schema_example(link['schema']))
-
-      if link['method'].upcase == 'GET' && !data.empty?
-        path << '?'
-        data.sort_by {|k,_| k.to_s }.each do |key, values|
-          [values].flatten.each do |value|
-            path << [key.to_s, CGI.escape(value.to_s)].join('=') << '&'
-          end
-        end
-        path.chop! # remove trailing '&'
-      end
-    end
-  %>
-$ curl -n -X <%= link['method'] %> <%= schema.href %><%= path %>
-  <%- unless data.empty? || link['method'].upcase == 'GET' %>
--H "Content-Type: application/json" \
--d '<%= data.to_json %>'
-  <%- end %>
-```
-
-#### Response Example
-```
-HTTP/1.1 <%= case link['rel']
-  when 'create'
-    '201 Created'
-  else
-    '200 OK'
-  end %>
-```
-```javascript```
-  <%- if link['rel'] == 'instances' %>
-<%= JSON.pretty_generate([schema.schemata_example(resource)]) %>
-  <%- else %>
-<%= JSON.pretty_generate(schema.schemata_example(resource)) %>
-  <%- end %>
-```
+<%=
+  Prmd::Template::render(File.join('schemata', 'link.erb'), options[:template], {
+    options:         options,
+    resource:        resource,
+    schema:          schema,
+    schemata:        schemata,
+    link:            link,
+    title:           title
+  })
+%>
 <%- end -%>