prmd 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YWJmODRjMTMyNjBmNGE5N2JmZTk4ZmI2MzZiZTM3NDBkZmEyNTI5Yw==
+  data.tar.gz: !binary |-
+    MjJiNjE4ZjA0ODUzNjlhNGZkZmVhZmY3MmRhMzY1MDFkYTM0M2QxMw==
+SHA512:
+  metadata.gz: !binary |-
+    MThmMTQ3ODhhNDMwNTliZjk4NWY0N2JiOWU3MDk4ZjI1YzE2NDJhNjQ3YjIy
+    ZGU3OGVjYzBiNjZhNmVhNzljMjY5ZWE0YTJlMjg4NmMyN2JiOWQ1ZDM4N2E0
+    M2FjNDdjMmNmYzBlZjBiZjk1ZWQ4NWM3MDhiYmVmYTQ3MTYwMDA=
+  data.tar.gz: !binary |-
+    ZDMzZWZjMzAyZDYxNjg5NTRmZjRjODJjMDNkOTZmNmNhM2QzNzRjN2M2OGVi
+    Yjg3NWE1ZWE2Njk5M2Y5ODg4NDQ1NzlmNjZmZTQxY2E4ZWY0YTJmMzI0NGUz
+    MjM5ZjljNDMxZGNjNGQ3MTI1MmQ3Mjk5MWYyMjM2OGRjMjJkMmI=

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.ruby-version
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/.travis.yml

@@ -0,0 +1,2 @@
+language: ruby
+script: "bundle exec rake"

data/CONTRIBUTORS.md

@@ -0,0 +1,6 @@
+* Brandur <brandur@mutelight.org>
+* Chris Continanza <christopher.continanza@gmail.com>
+* Mark McGranaghan <mmcgrana@gmail.com>
+* Timothée Peignier <timothee.peignier@tryphon.org>
+* Wesley Beary <geemus+github@gmail.com>
+* geemus <geemus@gmail.com>

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in prmd.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,23 @@
+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)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  minitest
+  prmd!
+  rake

data/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2014 [CONTRIBUTORS.md](https://github.com/heroku/prmd/blob/master/CONTRIBUTORS.md)
+
+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,72 @@
+# Prmd
+
+schema to rule them all
+
+## 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.
+
+The expectations for json-schema usage that are 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).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'prmd'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ 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.
+
+```
+prmd combine <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.
+
+```
+prmd doc <directory_or_schema>
+```
+
+Prepend file to the documentation output.
+
+```
+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.
+
+```
+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.
+
+```
+prmd verify <directory_or_schema>
+```
+
+Combining commands works too.
+
+```
+prmd combine <directory> | prmd verify | prmd doc > schema.md
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

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

data/bin/prmd

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'prmd')))
+
+options = {}
+
+commands = {
+  combine: OptionParser.new do |opts|
+    opts.banner = "prmd combine [options] <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.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.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>"
+  end
+}
+
+help_text = commands.values.map do |command|
+  "   #{command.banner}"
+end.join("\n")
+
+global = OptionParser.new do |opts|
+  opts.banner = "Usage: prmd [options] [command [options]]"
+  opts.separator "\nAvailable options:"
+  opts.on("--version", "Return version") do |opts|
+    puts "prmd #{Prmd::VERSION}"
+    exit(0)
+  end
+  opts.separator "\nAvailable commands:"
+  opts.separator help_text
+end
+
+if ARGV.empty?
+  puts global
+  exit(1)
+end
+global.order!
+
+command = ARGV.shift.to_sym
+option = commands[command]
+if option.nil?
+  puts global
+  exit(1)
+end
+
+if ARGV.empty? && $stdin.tty?
+  puts option
+  exit(1)
+end
+option.order!
+
+case command
+  when :combine
+    puts Prmd.combine(ARGV[0], options)
+  when :doc
+    if ARGV.empty?
+      data = JSON.parse($stdin.read)
+      schema = Prmd::Schema.new(data, options)
+      puts Prmd.doc(schema, options)
+    else
+      schema = Prmd::Schema.load(ARGV[0])
+      puts Prmd.doc(schema, options)
+    end
+  when :init
+    puts Prmd.init(ARGV[0], options)
+  when :verify
+    errors = []
+    if ARGV.empty?
+      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
+    else
+      Prmd.verify(JSON.parse(File.read(ARGV[0]))).each do |error|
+        errors << "#{ARGV[0]}: #{error}"
+      end
+    end
+    errors.each do |error|
+      $stderr.puts error
+    end
+    exit(1) unless errors.empty?
+end

data/docs/schemata.md

@@ -0,0 +1,162 @@
+# schemata
+This document seeks to explain JSON schema in practice as well as our usage and associated implications. Everything described must be followed unless otherwise noted (or it is a bug). Unless otherwise noted (as in meta-data) keys should be alphabetized for ease of modification/review/updating. A great example in-the-wild is available for the Heroku Platform API, see [Heroku Devcenter](https://devcenter.heroku.com/articles/platform-api-reference#schema) for details.
+
+## json-schema
+
+JSON Schema provides a way to describe the resources, attributes and links of an API using JSON. This document will contain many examples and explanation, but going to the source can also be useful. There are three relevant specs, which are additive. You can read through them, ideally in this order:
+
+1. [JSON Schema Core](http://tools.ietf.org/html/draft-zyp-json-schema-04) - defines the basic foundation of JSON Schema - you probably will not need this often
+2. [JSON Schema Validation](http://tools.ietf.org/html/draft-fge-json-schema-validation-00) - defines the validation keywords of JSON Schema - covers most attributes
+3. [JSON Hyper-Schema](http://tools.ietf.org/html/draft-luff-json-hyper-schema-00) - defines the hyper-media keywords of JSON Schema - covers remaining links-specific attributes
+
+## structure
+
+We have opted to split apart the schema into individual resource schema and a root schema which references all of them. These individual schema are named based on the singular form of the resource in question.
+
+### meta-data
+
+Each schema MUST include some meta-data, which we cluster at the top of the file, including:
+
+* `description` - a description of the resource described by the schema
+* `id` - an id for this schema, it MUST be in the form `"schema/#{lower_case_singular_resource}"`
+* `$schema` - defines what meta-schema is in use, it MUST be `http://json-schema.org/draft-04/hyper-schema`
+* `title` - title for this resource, it MUST be in the form `"Heroku Platform API - #{title_case_plural_resource}"`
+* `type` - the type(s) of this schema, it MUST be `["object"]`
+
+### `definitions`
+
+We make heavy usage of the `definitions` attribute in each resource to provide a centralized collection of attributes related to each resource. By doing so we are able to refer to the same attribute in links, properties and even as foreign keys.
+
+The definitions object MUST include every attribute related directly to this resource, including:
+
+* all properties that are present in the serialization of the object
+* an `identity` property to provide an easy way to find what unique identifier(s) can be used with this object as well as what to use for foreign keys
+* all transient properties which may be passed into links related to the object, even if they are not serialized
+
+Each attribute MUST include the following properties:
+
+* `description` - a description of the attribute and how it relates to the resource
+* `example` - an example of the attributes value, useful for documentation and tests
+* `type` - an array of type(s) for this attribute, values MUST be one of `["array", "boolean", "integer", "number", "null", "object", "string"]`
+
+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:
+
+```javascript
+{
+  "definitions": {
+    "id": {
+      "description":  "unique identifier of resource",
+      "example":      "01234567-89ab-cdef-0123-456789abcdef",
+      "format":       "uuid",
+      "readOnly":     true,
+      "type":         ["string"]
+    },
+    "url": {
+      "description":  "URL of resource",
+      "example":      "http://example.com",
+      "format":       "uri",
+      "pattern":      "^http://[a-z][a-z0-9-]{3,30}\\.com$",
+      "type":         ["null", "string"]
+    }
+  }
+}
+```
+
+### `links`
+
+Links define the actions available on a given resource. They are listed as an array, which should be alphabetized by title.
+
+The links array MUST include an object defining each action available. Each action MUST include the following attributes:
+
+* `description` - a description of the action to perform
+* `href` - the path associated with this action, use [URI templates](http://tools.ietf.org/html/rfc6570) as needed, CGI escaping any JSON pointer values used for identity
+* `method` - the http method to be used with this actio
+* `rel` - describes relation of link to resource, SHOULD be one of `["create", "destroy", "self", "instances", "update"]`
+* `title` - title for the link
+
+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.
+
+```javascript
+{
+  "links": [
+    {
+      "description":  "Create a new resource.",
+      "href":         "/resources",
+      "method":       "POST",
+      "rel":          "create",
+      "schema":       {
+        "properties": {
+          "owner":  { "$ref": "/schema/user#/definitions/identity" },
+          "url":    { "$ref": "/schema/resource/definitions/url" }
+        }
+      },
+      "title":        "Create"
+    },
+    {
+      "description":  "Delete an existing resource.",
+      "href":         "/resources/{(%2Fschema%2Fresources%23%2Fdefinitions%2Fidentity)}",
+      "method":       "DELETE",
+      "rel":          "destroy",
+      "title":        "Delete"
+    },
+    {
+      "description":  "Info for existing resource.",
+      "href":         "/resources/{(%2Fschema%2Fresources%23%2Fdefinitions%2Fidentity)}",
+      "method":       "GET",
+      "rel":          "self",
+      "title":        "Info"
+    },
+    {
+      "description":  "List existing resources.",
+      "href":         "/resources",
+      "method":       "GET",
+      "rel":          "instances",
+      "title":        "List"
+    },
+    {
+      "description":  "Update an existing resource.",
+      "href":         "/resources/{(%2Fschema%2Fresource%23%2Fdefinitions%2Fidentity)}",
+      "method":       "PATCH",
+      "rel":          "update",
+      "schema":       {
+        "properties": {
+          "url":    { "$ref": "/schema/resource/definitions/url" }
+        }
+      },
+      "title":        "Update"
+    }
+}
+```
+
+### `properties`
+
+Properties defines the attributes that exist in the serialization of the object.
+
+The properties object MUST contain all the serialized attributes for the object. Each attribute MUST provide a [JSON pointer](http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-07) to the attribute in appropriate `definitions`, we have opted to always use absolute pointers for consistency. Properties MUST also add any data which overrides the values in definitions and SHOULD add any additional, relevant data.
+
+```javascript
+{
+  "properties": {
+    "id":       { "$ref": "/schema/resource#/definitions/id" },
+    "owner": {
+      "description": "unique identifier of the user who owns this resource",
+      "properties": {
+        "id": { "$ref": "/schema/user#/definitions/id" }
+      },
+      "type": ["object"]
+    },
+    "url":      { "$ref": "/schema/resource#/definitions/url" }
+  }
+}
+```
+
+Note: this assumes that schema/user will also be available and will have id defined in the definitions. If/when you need to refer to a foreign key, you MUST add a new schema and/or add the appropriate attribute to the foreign resource definitions unless it already exists.