diff --git a/.github/.DS_Store b/.github/.DS_Store new file mode 100644 index 0000000..1f2c43e Binary files /dev/null and b/.github/.DS_Store differ diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 0000000..884f397 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,36 @@ +# This is a basic workflow to help you get started with Actions + +name: JSONSCheme + +# Controls when the workflow will run +on: + # Triggers the workflow on push or pull request events but only for the master branch + push: + branches: [ master ] + pull_request: + branches: [ master ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: macos-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $jsonSChemeQ, so your job can access it + - uses: actions/checkout@v2 + + # Runs a single command using the runners shell + - name: Run a one-line script + run: echo Hello, world! + + # Runs a set of commands using the runners shell + - name: Run a multi-line script + run: | + echo Add other actions to build, + echo test, and deploy your project. diff --git a/address b/address new file mode 100644 index 0000000..c553848 --- /dev/null +++ b/address @@ -0,0 +1,12 @@ +{"description":"An Address following the convention of http://microformats.org/wiki/hcard", + "type":"object", + "properties":{ + "post-office-box":{"type":"string","requires":"street-address"}, + "extended-address":{"type":"string","requires":"street-address"}, + "street-address":{"type":"string","requires":"region"}, + "locality":{"type":"string","requires":"region", "required":true}, + "region":{"type":"string","requires":"country-name", "required":true}, + "postal-code":{"type":"string"}, + "country-name":{"type":"string", "required":true} + } +} \ No newline at end of file diff --git a/address-v2 b/address-v2 new file mode 100644 index 0000000..437da9e --- /dev/null +++ b/address-v2 @@ -0,0 +1,12 @@ +{"description":"An Address following the convention of http://microformats.org/wiki/hcard", + "type":"object", + "properties":{ + "post-office-box":{"type":"string","specifity":5,"optional":true}, + "extended-address":{"type":"string","specifity":5,"optional":true}, + "street-address":{"type":"string","specifity":4,"optional":true}, + "locality":{"type":"string","specifity":3}, + "region":{"type":"string","specifity":2}, + "postal-code":{"type":"string","optional":true}, + "country-name":{"type":"string","specifity":1} + } +} \ No newline at end of file diff --git a/address.properties b/address.properties new file mode 100644 index 0000000..fc61ac2 --- /dev/null +++ b/address.properties @@ -0,0 +1,9 @@ +{ +"post-office-box":{"type":"string","specifity":5,"optional":true}, +"extended-address":{"type":"string","specifity":5,"optional":true}, +"street-address":{"type":"string","specifity":4,"optional":true}, +"locality":{"type":"string","specifity":3}, +"region":{"type":"string","specifity":2}, +"postal-code":{"type":"string","optional":true}, +"country-name":{"type":"string","specifity":1} +} diff --git a/calendar b/calendar new file mode 100644 index 0000000..9b02c4d --- /dev/null +++ b/calendar @@ -0,0 +1,20 @@ +{"description":"A representation of an event", + "type":"object", + "properties":{ + "dtstart":{"format":"date-time","type":"string","description":"Event starting time","required":true}, + "summary":{"type":"string","required":true}, + "location":{"type":"string"}, + "url":{"type":"string","format":"url"}, + "dtend":{"format":"date-time","type":"string","description":"Event ending time"}, + "duration":{"format":"date","type":"string","description":"Event duration"}, + "rdate":{"format":"date-time","type":"string","description":"Recurrence date"}, + "rrule":{"type":"string","description":"Recurrence rule"}, + "category":{"type":"string"}, + "description":{"type":"string"}, + "geo":"http://json-schema.org/geo" + } +} + + + + diff --git a/calendar-v2 b/calendar-v2 new file mode 100644 index 0000000..d250369 --- /dev/null +++ b/calendar-v2 @@ -0,0 +1,20 @@ +{"description":"A representation of an event", + "type":"object", + "properties":{ + "dtstart":{"format":"date-time","type":"string","description":"Event starting time"}, + "summary":{"type":"string"}, + "location":{"type":"string","optional":true}, + "url":{"type":"string","format":"url","optional":true}, + "dtend":{"format":"date-time","type":"string","description":"Event ending time","optional":true}, + "duration":{"format":"date","type":"string","description":"Event duration","optional":true}, + "rdate":{"format":"date-time","type":"string","description":"Recurrence date","optional":true}, + "rrule":{"type":"string","description":"Recurrence rule","optional":true}, + "category":{"type":"string","optional":true}, + "description":{"type":"string","optional":true}, + "geo":{"type":"object","properties":{"$ref":"http://json-schema.org/geo#properties"},"optional":true} + } +} + + + + diff --git a/calendar.properties b/calendar.properties new file mode 100644 index 0000000..a71520d --- /dev/null +++ b/calendar.properties @@ -0,0 +1,13 @@ +{ + "dtstart":{"format":"date-time","type":"string","description":"Event starting time"}, + "summary":{"type":"string"}, + "location":{"type":"string","optional":true}, + "url":{"type":"string","format":"url","optional":true}, + "dtend":{"format":"date-time","type":"string","description":"Event ending time","optional":true}, + "duration":{"format":"date","type":"string","description":"Event duration","optional":true}, + "rdate":{"format":"date-time","type":"string","description":"Recurrence date","optional":true}, + "rrule":{"type":"string","description":"Recurrence rule","optional":true}, + "category":{"type":"string","optional":true}, + "description":{"type":"string","optional":true}, + "geo":{"type":"object","properties":{"$ref":"http://json-schema.org/geo.properties"},"optional":true} + } diff --git a/card b/card new file mode 100644 index 0000000..ba47d78 --- /dev/null +++ b/card @@ -0,0 +1,43 @@ +{"description":"A representation of a person, company, organization, or place", + "type":"object", + "properties":{ + "fn":{"description":"Formatted Name","type":"string"}, + "familyName":{"type":"string", "required":true}, + "givenName":{"type":"string", "required":true}, + "additionalName":{"type":"array","items":{"type":"string"}}, + "honorificPrefix":{"type":"array","items":{"type":"string"}}, + "honorificSuffix":{"type":"array","items":{"type":"string"}}, + "nickname":{"type":"string"}, + "url":{"type":"string","format":"url"}, + "email":{ + "type":"object", + "properties":{ + "type":{"type":"string"}, + "value":{"type":"string","format":"email"}}, + }, + "tel":{ + "type":"object", + "properties":{ + "type":{"type":"string"}, + "value":{"type":"string","format":"phone"}}, + }, + "adr":"http://json-schema.org/address", + "geo":"http://json-schema.org/geo", + "tz":{"type":"string"}, + "photo":{"format":"image","type":"string"}, + "logo":{"format":"image","type":"string"}, + "sound":{"format":"attachment","type":"string"}, + "bday":{"type":"string","format":"date"}, + "title":{"type":"string"}, + "role":{"type":"string"}, + "org":{"type":"object", + "properties":{ + "organizationName":{"type":"string"}, + "organizationUnit":{"type":"string"}}, + } + } +} + + + + diff --git a/card-v2 b/card-v2 new file mode 100644 index 0000000..520dfbb --- /dev/null +++ b/card-v2 @@ -0,0 +1,47 @@ +{"description":"A representation of a person, company, organization, or place", + "type":"object", + "properties":{ + "fn":{"description":"Formatted Name","type":"string","optional":true}, + "familyName":{"type":"string"}, + "givenName":{"type":"string"}, + "additionalName":{"type":"array","items":{"type":"string"},"optional":true}, + "honorificPrefix":{"type":"array","items":{"type":"string"},"optional":true}, + "honorificSuffix":{"type":"array","items":{"type":"string"},"optional":true}, + "nickname":{"type":"string","optional":true}, + "url":{"type":"string","format":"url","optional":true}, + "email":{ + "type":"object", + "properties":{ + "type":{"type":"string"}, + "value":{"type":"string","format":"email"}}, + "optional":true}, + "tel":{ + "type":"object", + "properties":{ + "type":{"type":"string"}, + "value":{"type":"string","format":"phone"}}, + "optional":true}, + "adr":{ "type":"object", + "properties":{"$ref":"http://json-schema.org/address#properties"}, + "optional":true}, + "geo":{ "type":"object", + "properties":{"$ref":"http://json-schema.org/geo#properties"}, + "optional":true}, + "tz":{"type":"string","optional":true}, + "photo":{"format":"image","type":"string","optional":true}, + "logo":{"format":"image","type":"string","optional":true}, + "sound":{"format":"attachment","type":"string","optional":true}, + "bday":{"type":"string","format":"date","optional":true}, + "title":{"type":"string","optional":true}, + "role":{"type":"string","optional":true}, + "org":{"type":"object", + "properties":{ + "organizationName":{"type":"string"}, + "organizationUnit":{"type":"string"}}, + "optional":true} + } +} + + + + diff --git a/card.properties b/card.properties new file mode 100644 index 0000000..8704f79 --- /dev/null +++ b/card.properties @@ -0,0 +1,40 @@ +{ + "fn":{"description":"Formatted Name","type":"string","optional":true}, + "familyName":{"type":"string"}, + "givenName":{"type":"string"}, + "additionalName":{"type":"array","items":{"type":"string"},"optional":true}, + "honorificPrefix":{"type":"array","items":{"type":"string"},"optional":true}, + "honorificSuffix":{"type":"array","items":{"type":"string"},"optional":true}, + "nickname":{"type":"string","optional":true}, + "url":{"type":"string","format":"url","optional":true}, + "email":{ + "type":"object", + "properties":{ + "type":{"type":"string"}, + "value":{"type":"string","format":"email"}}, + "optional":true}, + "tel":{ + "type":"object", + "properties":{ + "type":{"type":"string"}, + "value":{"type":"string","format":"phone"}}, + "optional":true}, + "adr":{ "type":"object", + "properties":{"$ref":"http://json-schema.org/address.properties"}, + "optional":true}, + "geo":{ "type":"object", + "properties":{"$ref":"http://json-schema.org/geo.properties"}, + "optional":true}, + "tz":{"type":"string","optional":true}, + "photo":{"format":"image","type":"string","optional":true}, + "logo":{"format":"image","type":"string","optional":true}, + "sound":{"format":"attachment","type":"string","optional":true}, + "bday":{"type":"string","format":"date","optional":true}, + "title":{"type":"string","optional":true}, + "role":{"type":"string","optional":true}, + "org":{"type":"object", + "properties":{ + "organizationName":{"type":"string"}, + "organizationUnit":{"type":"string"}}, + "optional":true} + } \ No newline at end of file diff --git a/draft-zyp-json-schema-00.txt b/draft-zyp-json-schema-00.txt new file mode 100644 index 0000000..2cdabe2 --- /dev/null +++ b/draft-zyp-json-schema-00.txt @@ -0,0 +1,1289 @@ + + + +Internet Engineering Task Force K. Zyp, Ed. +Internet-Draft SitePen (USA) +Updates: 4120 (if approved) December 5, 2009 +Intended status: Standards Track +Expires: June 8, 2010 + + + A JSON Media Type for Describing the Structure and Meaning of JSON + Documents + draft-zyp-json-schema-00 + +Abstract + + JSON (JavaScript Object Notation) Schema defines the media type + application/schema+json, a JSON based format for defining the + structure of JSON data. JSON Schema provides a contract for what + JSON data is required for a given application and how to interact + with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +Status of This Memo + + This Internet-Draft is submitted to IETF in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on June 8, 2010. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + + +Zyp Expires June 8, 2010 [Page 1] + +Internet-Draft JSON Schema Media Type December 2009 + + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Design Considerations . . . . . . . . . . . . . . . . . . 6 + 4. Schema/Instance Association . . . . . . . . . . . . . . . . . 6 + 4.1. Self-Descriptive Schema . . . . . . . . . . . . . . . . . 7 + 5. Core Schema Definition . . . . . . . . . . . . . . . . . . . . 7 + 5.1. type . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 5.2. properties . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.3. items . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.4. optional . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.5. additionalProperties . . . . . . . . . . . . . . . . . . . 9 + 5.6. requires . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.7. minimum . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.8. maximum . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.9. minimumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 + 5.10. maximumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 + 5.11. minItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.12. maxItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.13. pattern . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.14. maxLength . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.15. minLength . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.16. enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.17. title . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.18. description . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.19. format . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.20. contentEncoding . . . . . . . . . . . . . . . . . . . . . 12 + 5.21. default . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.22. maxDecimal . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.23. disallow . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.24. extends . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6. Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6.1. links . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6.1.1. Link Description Object . . . . . . . . . . . . . . . 13 + 6.2. fragmentResolution . . . . . . . . . . . . . . . . . . . . 17 + + + +Zyp Expires June 8, 2010 [Page 2] + +Internet-Draft JSON Schema Media Type December 2009 + + + 6.2.1. dot-delimited fragment resolution . . . . . . . . . . 18 + 6.3. root . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.4. readonly . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.5. pathStart . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.6. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.7. alternate . . . . . . . . . . . . . . . . . . . . . . . . 20 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 + 8.1. Registry of Link Relations . . . . . . . . . . . . . . . . 21 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23 + Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 23 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 3] + +Internet-Draft JSON Schema Media Type December 2009 + + +1. Introduction + + JSON (JavaScript Object Notation) Schema is a JSON media type for + defining the structure of JSON data. JSON Schema provides a contract + for what JSON data is required for a given application and how to + interact with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +2. Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119. + +3. Overview + + JSON Schema defines the media type application/schema+json for + describing the structure of other JSON documents. JSON Schema is + JSON-based and includes facilities for describing the structure of + JSON documents in terms of allowable values, descriptions, and + interpreting relations with other resources. + + JSON Schema format is organized into several separate definitions. + The first definition is the core schema specification. This + definition is primary concerned with describing a JSON structure and + specifying valid elements in the structure. The second definition is + the Hyper Schema specification which is intended define elements in a + structure that can be interpreted as hyperlinks. Hyper Schema builds + on JSON Schema to describe the hyperlink structure of other JSON + documents. This allows user agents to be able to successfully + navigate JSON documents based on their schemas. + + Cumulatively JSON Schema acts as a meta-document that can be used to + define the required type and constraints on property values, as well + as define the meaning of the property values for the purpose of + describing a resource and determining hyperlinks within the + representation. + + An example JSON Schema that describes products might look like: + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 4] + +Internet-Draft JSON Schema Media Type December 2009 + + + { + "name":"Product", + "properties":{ + "id":{ + "type":"number", + "description":"Product identifier" + }, + "name":{ + "description":"Name of the product", + "type":"string" + }, + "price":{ + "type": "number", + "minimum":0 + }, + "tags":{ + "optional":true, + "type":"array", + "items":{ + "type":"string" + } + } + }, + "links":[ + { + "rel":"full", + "href":"{id}" + }, + { + "rel":"comments", + "href":"comments/?id={id}" + } + ] + } + + This schema defines the properties of the instance JSON documents and + their required properties (id, name, and price) as well as an + optional property (tags). This also defines the link relations of + the instance JSON documents. + +3.1. Terminology + + For this specification, a schema will be used to denote a JSON Schema + definition, and an instance refers to the JSON object or array that + the schema will be describing and validating + + + + + + +Zyp Expires June 8, 2010 [Page 5] + +Internet-Draft JSON Schema Media Type December 2009 + + +3.2. Design Considerations + + The JSON Schema media type does not attempt to dictate the structure + of JSON representations that contain data, but rather provides a + separate format for flexibly communicating how a JSON representation + should be interpreted and validated, such that user agents can + properly understand acceptable structures and extrapolate hyperlink + information with the JSON document. This specification does not + define a protocol. The underlying protocol (such as HTTP) should + sufficiently define the semantics of the client-server interface, the + retrieval of resource representations linked to by JSON + representations, and modification of those resources. The goal of + this format is to sufficiently describe JSON structures such that one + can utilize existing information available in existing JSON + representations from a large variety of services that leverage a REST + architecture using existing protocols. + +4. Schema/Instance Association + + JSON Schema instances are correlated to their schema by the + "describedby" relation, where the schema is defined to be the target + of the relation. Instance representations may be of the application/ + json media type or any other subtype. Consequently, dictating how an + instance representation should specify the relation to the schema is + beyond the normative scope of this document (since this document + specifically defines the JSON Schema media type, and no other), but + it is recommended that instances specify their schema so that user + agents can interpret the instance representation and messages may + retain the self-descriptive characteristic, avoiding the need for + out-of-band information about instance data. Two approaches are + recommended for declaring the relation to the schema that describes + the meaning of a JSON instance's (or collection of instances) + structure. A MIME type parameter named "describedby" or a Link + header with a relation of "describedby" SHOULD be used: + + + Content-Type: application/json; + describedby=http://json.com/my-hyper-schema + + or if the content is being transferred by a protocol (such as HTTP) + that provides headers, a Link header can be used: + + + Link: ; rel="describedby" + + Instances MAY specify multiple schemas, to indicate all the schemas + that are applicable to the data. The instance data may have multiple + schemas that it is defined by (the instance data should be valid for + + + +Zyp Expires June 8, 2010 [Page 6] + +Internet-Draft JSON Schema Media Type December 2009 + + + those schemas). Or if the document is a collection of instances, the + collection may contain instances from different schemas. When + collections contain heterogeneous instances, the pathStart attribute + MAY be specified in the schema to disambiguate which schema should be + applied for each item in the collection. + +4.1. Self-Descriptive Schema + + JSON Schemas are themselves instances for the schema schemas. A + self-describing JSON Schema for the core JSON Schema can be found at + http://json-schema.org/schema and the hyper schema self-description + can be found at: http://json-schema.org/hyper-schema. All schemas + used within a protocol with media type definitions SHOULD include a + MIME parameter that refers to the self-descriptive hyper schema or + another schema that extends this hyper schema: + + + Content-Type: application/json; + describedby=http://www.json-schema.org/hyper-schema + +5. Core Schema Definition + + A JSON Schema is a JSON Object that defines various attributes of the + instance and defines it's usage and valid values. A JSON Schema is a + JSON Object with schema attribute properties. The following is the + grammar of a JSON Schema: + + And an example JSON Schema definition could look like: + + + {"description":"A person", + "type":"object", + + "properties": + {"name": {"type":"string"}, + "age" : {"type":"integer", + "maximum":125}} + } + + A JSON Schema object may have any of the following properties, called + schema attributes (all attributes are optional): + +5.1. type + + Union type definition - An array with two or more items which + indicates a union of type definitions. Each item in the array may + be a simple type definition or a schema. The instance value is + valid if it is of the same type as one the type definitions in the + + + +Zyp Expires June 8, 2010 [Page 7] + +Internet-Draft JSON Schema Media Type December 2009 + + + array or if it is valid by one of the schemas in the array. For + example to indicate that a string or number is a valid: {"type": + ["string","number"]} + + Simple type definition - A string indicating a primitive or simple + type. The following are acceptable strings: + + string - Value must be a string. + + number - Value must be a number, floating point numbers are + allowed. + + integer - Value must be an integer, no floating point numbers + are allowed. This is a subset of the number type. + + boolean - Value must be a boolean. + + object - Value must be an object. + + array - Value must be an array. + + null - Value must be null. Note this is mainly for purpose of + being able use union types to define nullability. + + any - Value may be of any type including null. If the property + is not defined or is not in this list, than any type of value + is acceptable. Other type values may be used for custom + purposes, but minimal validators of the specification + implementation can allow any instance value on unknown type + values. + +5.2. properties + + This should be an object type definition, which is an object with + property definitions that correspond to instance object properties. + When the instance value is an object, the property values of the + instance object must conform to the property definitions in this + object. In this object, each property definition's value should be a + schema, and the property's name should be the name of the instance + property that it defines. + +5.3. items + + This should be a schema or an array of schemas. When this is an + object/schema and the instance value is an array, all the items in + the array must conform to this schema. When this is an array of + schemas and the instance value is an array, each position in the + instance array must conform to the schema in the corresponding + + + +Zyp Expires June 8, 2010 [Page 8] + +Internet-Draft JSON Schema Media Type December 2009 + + + position for this array. This called tuple typing. When tuple + typing is used, additional items are allowed, disallowed, or + constrained by the additionalProperties attribute using the same + rules as extra properties for objects.. + +5.4. optional + + This indicates that the instance property in the instance object is + optional. This is false by default. + +5.5. additionalProperties + + This provides a default property definition for all properties that + are not explicitly defined in an object type definition. The value + must be a schema. If false is provided, no additional properties are + allowed, and the schema can not be extended. The default value is an + empty schema which allows any value for additional properties. + +5.6. requires + + This indicates that if this property is present in the containing + instance object, the property given by requires attribute must also + be present in the containing instance object. The value of this + property may be a string, indicating the require property name. Or + the value may be a schema, in which case the containing instance must + be valid by the schema if the property is present. For example if a + object type definition is defined: + + + { + "state": + { + "optional":true + }, + "town": + { + "requires":"state", + "optional":true + } + } + + An instance must include a state property if a town property is + included. If a town property is not included, the state property is + optional. + + + + + + + +Zyp Expires June 8, 2010 [Page 9] + +Internet-Draft JSON Schema Media Type December 2009 + + +5.7. minimum + + This indicates the minimum value for the instance property when the + type of the instance value is a number. + +5.8. maximum + + This indicates the minimum value for the instance property when the + type of the instance value is a number. + +5.9. minimumCanEqual + + If the minimum is defined, this indicates whether or not the instance + property value can equal the minimum. + +5.10. maximumCanEqual + + If the maximum is defined, this indicates whether or not the instance + property value can equal the maximum. + +5.11. minItems + + This indicates the minimum number of values in an array when an array + is the instance value. + +5.12. maxItems + + This indicates the maximum number of values in an array when an array + is the instance value. + +5.13. pattern + + When the instance value is a string, this provides a regular + expression that a instance string value should match in order to be + valid. Regular expressions should follow the regular expression + specification from ECMA 262/Perl 5 + +5.14. maxLength + + When the instance value is a string, this indicates maximum length of + the string. + +5.15. minLength + + When the instance value is a string, this indicates minimum length of + the string. + + + + + +Zyp Expires June 8, 2010 [Page 10] + +Internet-Draft JSON Schema Media Type December 2009 + + +5.16. enum + + This provides an enumeration of possible values that are valid for + the instance property. This should be an array, and each item in the + array represents a possible value for the instance value. If "enum" + is included, the instance value must be one of the values in enum + array in order for the schema to be valid. + +5.17. title + + This provides a short description of the instance property. The + value must be a string. + +5.18. description + + This provides a full description of the of purpose the instance + property. The value must be a string. + +5.19. format + + This property indicates the type of data, content type, or + microformat to be expected in the instance property values. A format + attribute may be one of the values listed below, and if so, should + adhere to the semantics describing for the format. A format should + only be used give meaning to primitive types (string, integer, + number, or boolean). Validators are not required to validate that + the instance values conform to a format. The following formats are + defined: + + Any valid MIME media type may be used as a format value, in which + case the instance property value must be a string, representing + the contents of the MIME file. + + date-time - This should be a date in ISO 8601 format of YYYY-MM- + DDThh:mm:ssZ in UTC time. This is the recommended form of date/ + timestamp. + + date - This should be a date in the format of YYYY-MM-DD. It is + recommended that you use the "date-time" format instead of "date" + unless you need to transfer only the date part. + + time - This should be a time in the format of hh:mm:ss. It is + recommended that you use the "date-time" format instead of "time" + unless you need to transfer only the time part. + + utc-millisec - This should be the difference, measured in + milliseconds, between the specified time and midnight, January 1, + 1970 UTC. The value should be a number (integer or float). + + + +Zyp Expires June 8, 2010 [Page 11] + +Internet-Draft JSON Schema Media Type December 2009 + + + regex - A regular expression. + + color - This is a CSS color (like "#FF0000" or "red"). + + style - This is a CSS style definition (like "color: red; + background-color:#FFF"). + + phone - This should be a phone number (format may follow E.123). + + uri - This value should be a URI.. + + email - This should be an email address. + + ip-address - This should be an ip version 4 address. + + ipv6 - This should be an ip version 6 address. + + street-address - This should be a street address. + + locality - This should be a city or town. + + region - This should be a region (a state in the US, province in + Canada, etc.) + + postal-code - This should be a postal code (AKA zip code). + + country - This should be the name of a country. + + Additional custom formats may be defined with a URL to a + definition of the format. + +5.20. contentEncoding + + If the instance property value is a string, this indicates that the + string should be interpreted as binary data and decoded using the + encoding named by this schema property. RFC 2045, Sec 6.1 lists + possible values. + +5.21. default + + This indicates the default for the instance property. + +5.22. maxDecimal + + This indicates the maximum number of decimal places in a floating + point number. By default there is no maximum. + + + + + +Zyp Expires June 8, 2010 [Page 12] + +Internet-Draft JSON Schema Media Type December 2009 + + +5.23. disallow + + This attribute may take the same values as the "type" attribute, + however if the instance matches the type or if this value is an array + and the instance matches any type or schema in the array, than this + instance is not valid. + +5.24. extends + + The value of this property should be another schema which will + provide a base schema which the current schema will inherit from. + The inheritance rules are such that any instance that is valid + according to the current schema must be valid according to the + referenced schema. This may also be an array, in which case, the + instance must be valid for all the schemas in the array. + +6. Hyper Schema + + This section defines hypermedia definitions of JSON schema. The + following attributes are specified in addition to those attributes + that already provided by JSON schema with the specific purpose of + informing user agents of relations between resources based on JSON + data. Just as with JSON schema attributes, all the attributes in + hyper-schema are optional. Therefore an empty object is a valid + (non-informative) schema, and essentially describes plain JSON (no + constraints on the structures). Addition of attributes provides + additive information for user agents. + +6.1. links + + The value of the links property should be an array, where each item + in the array is a link description object which describes the link + relations of the instances. + +6.1.1. Link Description Object + + A link description object is used to describe the link relations of + instances of a schema. + +6.1.1.1. href + + The value of the "href" link description property indicates the + target URI of the related resource. The value of the instance + property should be resolved as a URI-Reference per [RFC3986] and may + be a relative URI. The base URI to be used for relative resolution + should be the URI used to retrieve the instance object (not the + schema). Also, the URI may be parametrized by the property values of + the instance object. + + + +Zyp Expires June 8, 2010 [Page 13] + +Internet-Draft JSON Schema Media Type December 2009 + + + Instance property values should be substituted into the URIs where + matching braces ('{', '}') are found surrounding zero or more + characters, creating an expanded URI. Instance property value + substitutions are resolved by using the text between the braces to + denote the property name from the instance to get the value to + substitute. For example, if an href value is defined: + + + http://somesite.com/{id} + + Then it would be resolved by replace the value of the "id" property + value from the instance object. If the value of the "id" property + was "45", the expanded URI would be: + + + http://somesite.com/45 + + If matching braces are found with the string "-this" (no quotes) + between the braces, than the actual instance value should be used to + replace the braces, rather than a property value. This should only + be used in situations where the instance is a scalar (string, + boolean, or number), and not for objects or arrays. + +6.1.1.2. rel + + The value of the "rel" property indicates the name of the relation to + the target resource. The relation to the target should be + interpreted as specifically from the instance object that the schema + (or sub-schema) applies to, not just the top level resource that + contains the object within its hierarchy. If a resource JSON + representation contains a sub object with a property interpreted as a + link, that sub-object holds the relation with the target. A relation + to target from the top level resource must be indicated with the + schema describing the top level JSON representation. + + Relationship definitions SHOULD NOT be media type dependent, and + users are encouraged to utilize existing accepted relation + definitions, including those in existing relation registries (see + &rfc4287). However, we define these relation here for clarity of + normative interpretation within the context of JSON hyper schema + defined relations: + + self - If the relation value is "self", when this property is + encountered in the instance object, the object represents a + resource and the instance object is treated as a full + representation of the target resource identified by the specified + URI. + + + + +Zyp Expires June 8, 2010 [Page 14] + +Internet-Draft JSON Schema Media Type December 2009 + + + full - This indicates that the target of the link is the full + representation for the instance object. The object that contains + this link may not be the full representation. + + describedby - This indicates the target of the link is the schema + for the instance object. This may be used to specifically denote + the schemas of objects within a JSON object hierarchy, + facilitating polymorphic type data structures. + + The following relations are applicable for schemas (the schema as + the "from" resource in the relation). + + instances - This indicates the target resource that represents + collection of instances of a schema. + + create - This indicates a target to use for creating new instances + of a schema. This link definition SHOULD be a submission link + with a non-safe method (like POST). + + For example, if a schema is defined: + + + { + "links": [ + { + "rel": "self" + "href": "{id}" + }, + { + "rel": "up" + "href": "{upId}" + }, + { + "rel": "children" + "href": "?upId={id}" + } + ] + } + + And if a collection of instance resource's JSON representation was + retrieved: + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 15] + +Internet-Draft JSON Schema Media Type December 2009 + + + GET /Resource/ + + [ + { + "id": "thing", + "upId": "parent" + }, + { + "id": "thing2", + "upId": "parent" + } + ] + + This would indicate that for the first item in the collection, it's + own (self) URI would resolve to "/Resource/thing" and the first + item's "up" relation should be resolved to the resource at + "/Resource/parent". The "children" collection would be located at + "/Resource/?upId=thing". + +6.1.1.3. Submission Link Properties + + The following properties also apply to link definition objects, and + provide functionality analogous to HTML forms, in providing a means + for submitting extra (often user supplied) information to send to a + server. + +6.1.1.3.1. method + + This indicates which method should be used to access the target + resource. In an HTTP environment, this would be "GET" or "POST" + (other HTTP methods such as "PUT" and "DELETE" have semantics that + are clearly implied by accessed resources, and do not need to be + defined here). This defaults to "GET". + +6.1.1.3.2. enctype + + If present, this property indicates a query media type format that + the server supports for querying or posting to the collection of + instances at the target resource. The query can be suffixed to the + target URI to query the collection with property-based constraints on + the resources that SHOULD be returned from the server or used to post + data to the resource (depending on the method). For example, with + the following schema: + + + + + + + + +Zyp Expires June 8, 2010 [Page 16] + +Internet-Draft JSON Schema Media Type December 2009 + + + { + "links":[ + { + "enctype": "application/x-www-form-urlencoded", + "method": "GET", + "href": "/Product/", + "properties":{ + "name":{"description":"name of the product"} + } + } + ] + } + + This indicates that the client can query the server for instances + that have a specific name: + + + /Product/?name=Slinky + + If no enctype or method is specified, only the single URI specified + by the href property is defined. If the method is POST, application/ + json is the default media type. + +6.1.1.3.3. properties + + This is inherited from the base JSON schema definition, and can + follow the same structure, but its meaning should be used to define + the acceptable property names and values for the action (whether it + be for the GET query or POST body). If properties are omitted, and + this form is the child of a schema, the properties from the parent + schema should be used as the basis for the form action. + +6.2. fragmentResolution + + This property indicates the fragment resolution protocol to use for + resolving fragment identifiers in URIs within the instance + representations. This applies to the instance object URIs and all + children of the instance object's URIs. The default fragment + resolution protocol is "dot-delimited", which is defined below. + Other fragment resolution protocols may be used, but are not defined + in this document. + + The fragment identifier is based on RFC 2396 Sec 5, and defines the + mechanism for resolving references to entities within a document. + + + + + + + +Zyp Expires June 8, 2010 [Page 17] + +Internet-Draft JSON Schema Media Type December 2009 + + +6.2.1. dot-delimited fragment resolution + + With the dot-delimited fragment resolution protocol, the fragment + identifier is interpreted as a series of property reference tokens + that are delimited by the "." character (\x2E). Each property + reference token is a series of any legal URI component characters + except the "." character. Each property reference token should be + interpreted, starting from the beginning of the fragment identifier, + as a path reference in the target JSON structure. The final target + value of the fragment can be determined by starting with the root of + the JSON structure from the representation of the resource identified + by the pre-fragment URI. If the target is a JSON object, than the + new target is the value of the property with the name identified by + the next property reference token in the fragment. If the target is + a JSON array, than the target is determined by finding the item in + array the array with the index defined by the next property reference + token (which MUST be a number). The target is successively updated + for each property reference token, until the entire fragment has been + traversed. + + Property names SHOULD be URI-encoded. In particular, any "." in a + property name MUST be encoded to avoid being interpreted as a + property delimiter. + + For example, for the following JSON representation: + + + { + "foo":{ + "anArray":[ + {"prop":44} + ], + "another prop":{ + "baz":"A string" + } + } + } + + The following fragment identifiers would be resolved: + + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 18] + +Internet-Draft JSON Schema Media Type December 2009 + + + fragment identifier resolution + ------------------- ---------- + # self, the root of the resource itself + #foo the object referred to by the foo property + #foo.another prop the object referred to by the "another prop" + property of the object referred to by the + "foo" property + #foo.another prop.baz the string referred to by the value of "baz" + property of the "another prop" property of + the object referred to by the "foo" property + #foo.anArray.0 the first object in the "anArray" array + +6.3. root + + This attribute indicates that the value of the instance property + value SHOULD be treated as the root or the body of the representation + for the purposes of user agent interaction and fragment resolution + (all other properties of the instance objects are can be regarded as + meta-data descriptions for the data). + +6.4. readonly + + This indicates that the instance property should not be changed. + Attempts by a user agent to modify the value of this property are + expected to be rejected by a server. + +6.5. pathStart + + This property value is a URI-Reference that indicates the URI that + all the URIs for the instances of the schema should start with. When + multiple schemas have been referenced for an instance, the user agent + can determine if this schema is applicable for a particular instance + by determining if URI of the instance begins with the pathStart's + referenced URI. pathStart MUST be resolved as per [RFC3986] section + 5. If the URI of the instance does not start with URI indicated by + pathStart, or if another schema specifies a starting URI that is + longer and also matches the instance, this schema should not be + applied to the instance. Any schema that does not have a pathStart + attribute should be considered applicable to all the instances for + which it is referenced. + +6.6. mediaType + + This indicates the media type of the instance representations that + this schema is defining. + + + + + + +Zyp Expires June 8, 2010 [Page 19] + +Internet-Draft JSON Schema Media Type December 2009 + + +6.7. alternate + + This is an array of JSON schema definitions that define any other + schemas for alternate JSON-based representations of the instance + resources. + +7. Security Considerations + + This specification is a sub-type of the JSON format, and consequently + the security considerations are generally the same as RFC 4627. + However, an additional issue is that when link relation of "self" is + used to denote a full representation of an object, the user agent + SHOULD NOT consider the representation to be the authoritative + representation of the resource denoted by the target URI if the + target URI is not equivalent to or a sub-path of the the URI used to + request the resource representation which contains the target URI + with the "self" link. For example, if a hyper schema was defined: + + + { + "links":[ + { + "rel":"self", + "href":"{id}" + } + ] + } + + And a resource was requested from somesite.com: + + + GET /foo/ + + With a response of: + + +Content-Type: application/json; describedby=/schema-for-this-data +[ + {"id":"bar", "name":"This representation can be safely treated \ + as authoritative "}, + {"id":"/baz", "name":"This representation should not be treated as \ + authoritative the user agent should make request the resource\ + from "/baz" to ensure it has the authoritative representation"}, + {"id":"http://othersite.com/something", "name":"This representation\ + should also not be treated as authoritative and the target\ + resource representation should be retrieved for the\ + authoritative representation"} +] + + + +Zyp Expires June 8, 2010 [Page 20] + +Internet-Draft JSON Schema Media Type December 2009 + + +8. IANA Considerations + + The proposed MIME media type for JSON Schema is application/ + schema+json + + Type name: application + + Subtype name: schema+json + + Required parameters: describedby + + The value of the describedby parameter should be a URI (relative or + absolute) that refers to the schema used to define the structure of + this structure (the meta-schema). Normally the value would be + http://json-schema.org/hyper-schema, but it is allowable to use other + schemas that extend the hyper schema's meta- schema. + + Optional parameters: pretty + + The value of the pretty parameter may be true or false to indicate if + additional whitespace has been included to make the JSON + representation easier to read. + +8.1. Registry of Link Relations + + This registry is maintained by IANA per RFC 4287 and this + specification adds three values: "full", "create", "instances". New + assignments are subject to IESG Approval, as outlined in [RFC5226]. + Requests should be made by email to IANA, which will then forward the + request to the IESG, requesting approval. + +9. References + +9.1. Normative References + + [RFC3986] Berners-Lee, T., Fielding, R., and + L. Masinter, "Uniform Resource + Identifier (URI): Generic Syntax", + STD 66, RFC 3986, January 2005. + + [RFC2119] Bradner, S., "Key words for use in + RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, + March 1997. + + [RFC4287] Nottingham, M., Ed. and R. Sayre, + Ed., "The Atom Syndication + Format", RFC 4287, December 2005. + + + +Zyp Expires June 8, 2010 [Page 21] + +Internet-Draft JSON Schema Media Type December 2009 + + + [RFC3339] Klyne, G., Ed. and C. Newman, + "Date and Time on the Internet: + Timestamps", RFC 3339, July 2002. + + [RFC2045] Freed, N. and N. Borenstein, + "Multipurpose Internet Mail + Extensions (MIME) Part One: Format + of Internet Message Bodies", + RFC 2045, November 1996. + +9.2. Informative References + + [RFC4627] Crockford, D., "The application/ + json Media Type for JavaScript + Object Notation (JSON)", RFC 4627, + July 2006. + + [RFC2616] Fielding, R., Gettys, J., Mogul, + J., Frystyk, H., Masinter, L., + Leach, P., and T. Berners-Lee, + "Hypertext Transfer Protocol -- + HTTP/1.1", RFC 2616, June 1999. + + [RFC5226] Narten, T. and H. Alvestrand, + "Guidelines for Writing an IANA + Considerations Section in RFCs", + BCP 26, RFC 5226, May 2008. + + [I-D.hammer-discovery] Hammer-Lahav, E., "Link-based + Resource Descriptor Discovery", + draft-hammer-discovery-03 (work in + progress), March 2009. + + [I-D.gregorio-uritemplate] Gregorio, J., "URI Template", + draft-gregorio-uritemplate-03 + (work in progress), April 2008. + + [I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", dra + ft-nottingham-http-link-header-06 + (work in progress), July 2009. + + [W3C.REC-html401-19991224] Hors, A., Jacobs, I., and D. + Raggett, "HTML 4.01 + Specification", World Wide Web + Consortium Recommendation REC- + html401-19991224, December 1999, < + http://www.w3.org/TR/1999/ + REC-html401-19991224>. + + + +Zyp Expires June 8, 2010 [Page 22] + +Internet-Draft JSON Schema Media Type December 2009 + + +Appendix A. Change Log + +Appendix B. Open Issues + + Should we give a preference to MIME headers over Link headers (or + only use one)? + + Should we use "profile" as the media type parameter instead? + + Should "root" be a MIME parameter instead of a schema attribute? + + Should "format" be renamed to "mediaType" or "contentType" to reflect + the usage MIME media types that are allowed. + + I still do not like how dates are handled. + +Author's Address + + Kris Zyp (editor) + SitePen (USA) + 530 Lytton Avenue + Palo Alto, CA 94301 + USA + + Phone: +1 650 968 8787 + EMail: kris@sitepen.com + + + + + + + + + + + + + + + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 23] + + diff --git a/draft-zyp-json-schema-00.xml b/draft-zyp-json-schema-00.xml new file mode 100644 index 0000000..9f722c9 --- /dev/null +++ b/draft-zyp-json-schema-00.xml @@ -0,0 +1,897 @@ + + + + + + + + + + + + + +]> + + + + + + + + + + + + A JSON Media Type for Describing the Structure and Meaning of JSON Documents + + + + SitePen (USA) + +
+ + 530 Lytton Avenue + + Palo Alto, CA 94301 + + USA + + + +1 650 968 8787 + + kris@sitepen.com +
+ + + + + Internet Engineering Task Force + + JSON + + Schema + + Hyper Schema + + Hypermedia + + + + + JSON (JavaScript Object Notation) Schema defines the media type application/schema+json, + a JSON based format for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. + + + + + + +
+ JSON (JavaScript Object Notation) Schema is a JSON media type for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. +
+ + +
+ The key words "MUST", "MUST + NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", + "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be + interpreted as described in RFC 2119. +
+ + + +
+ JSON Schema defines the media type application/schema+json for + describing the structure of other + JSON documents. JSON Schema is JSON-based and includes facilities + for describing the structure of JSON documents in terms of + allowable values, descriptions, and interpreting relations with other resources. + + JSON Schema format is organized into several separate definitions. The first + definition is the core schema specification. This definition is primary + concerned with describing a JSON structure and specifying valid elements + in the structure. The second definition is the Hyper Schema specification + which is intended define elements in a structure that can be interpreted as + hyperlinks. + Hyper Schema builds on JSON Schema to describe the hyperlink structure of + other JSON documents. This allows user agents to be able to successfully navigate + JSON documents based on their schemas. + + + Cumulatively JSON Schema acts as a meta-document that can be used to define the required type and constraints on + property values, as well as define the meaning of the property values + for the purpose of describing a resource and determining hyperlinks + within the representation. + + + An example JSON Schema that describes products might look like: +
+ +
+This schema defines the properties of the instance JSON documents and +their required properties (id, name, and price) as well as an optional +property (tags). This also defines the link relations of the instance +JSON documents. + +
+ For this specification, a schema will be used to denote a JSON Schema + definition, and an instance refers to the JSON object or array that the schema + will be describing and validating + +
+
+ + The JSON Schema media type does not attempt to dictate the structure of JSON + representations that contain data, but rather provides a separate format + for flexibly communicating how a JSON representation should be + interpreted and validated, such that user agents can properly understand + acceptable structures and extrapolate hyperlink information + with the JSON document. This specification does not define a protocol. + The underlying protocol (such as HTTP) should sufficiently define the + semantics of the client-server interface, the retrieval of resource + representations linked to by JSON representations, and modification of + those resources. The goal of this + format is to sufficiently describe JSON structures such that one can + utilize existing information available in existing JSON + representations from a large variety of services that leverage a REST + architecture using existing protocols. + +
+
+ +
+ + JSON Schema instances are correlated to their schema by the "describedby" + relation, where the schema is defined to be the target of the relation. + Instance representations may be of the application/json media type or + any other subtype. Consequently, dictating how an instance + representation should specify the relation to the schema is beyond the normative scope + of this document (since this document specifically defines the JSON + Schema media type, and no other), but it is recommended that instances + specify their schema so that user agents can interpret the instance + representation and messages may retain the self-descriptive + characteristic, avoiding the need for out-of-band information about + instance data. Two approaches are recommended for declaring the + relation to the schema that describes the meaning of a JSON instance's (or collection + of instances) structure. A MIME type parameter named + "describedby" or a Link header with a relation of "describedby" SHOULD be used: +
+ +
+ or if the content is being transferred by a protocol (such as HTTP) that + provides headers, a Link header can be used: +
+ + ; rel="describedby" +]]>
+ Instances MAY specify multiple schemas, to indicate all the schemas that + are applicable to the data. The instance data may have multiple schemas + that it is defined by (the instance data should be valid for those schemas). + Or if the document is a collection of instances, the collection may contain + instances from different schemas. When collections contain heterogeneous + instances, the pathStart attribute MAY be specified in the + schema to disambiguate which schema should be applied for each item in the +collection. + +
+ + JSON Schemas are themselves instances for the schema + schemas. A self-describing JSON Schema for the core JSON Schema can + be found at http://json-schema.org/schema and the hyper schema + self-description can be found at: http://json-schema.org/hyper-schema. All schemas + used within a protocol with media type definitions + SHOULD include a MIME parameter that refers to the self-descriptive + hyper schema or another schema that extends this hyper schema: +
+ +
+ +
+
+ +
+ A JSON Schema is a JSON Object that defines various attributes + of the instance and defines it's usage and valid values. A JSON + Schema is a JSON Object with schema attribute properties. + The following is the grammar of a JSON Schema: + + + + And an example JSON Schema definition could look like: +
+ + +
+ + A JSON Schema object may have any of the following properties, called schema + attributes (all attributes are optional): + + +
+ +Union type definition - An array with two or more items which indicates a union of type definitions. Each item in the array may be a simple type definition or a schema. The instance value is valid if it is of the same type as one the type definitions in the array or if it is valid by one of the schemas in the array. For example to indicate that a string or number is a valid: +{"type":["string","number"]} +Simple type definition - A string indicating a primitive or simple type. The following are acceptable strings: + + + +string - Value must be a string. + +number - Value must be a number, floating point numbers are allowed. +integer - Value must be an integer, no floating point numbers are allowed. This is a subset of the number type. +boolean - Value must be a boolean. +object - Value must be an object. +array - Value must be an array. + +null - Value must be null. Note this is mainly for purpose of being able use union types to define nullability. +any - Value may be of any type including null. +If the property is not defined or is not in this list, than any type of value is acceptable. Other type values may be used for custom purposes, but minimal validators of the specification implementation can allow any instance value on unknown type values. + + + + +
+
+This should be an object type definition, which is an object with property definitions that correspond to instance object properties. When the instance value is an object, the property values of the instance object must conform to the property definitions in this object. In this object, each property definition's value should be a schema, and the property's name should be the name of the instance property that it defines. +
+
+This should be a schema or an array of schemas. When this is an object/schema and the instance value is an array, all the items in the array must conform to this schema. When this is an array of schemas and the instance value is an array, each position in the instance array must conform to the schema in the corresponding position for this array. This called tuple typing. When tuple typing is used, additional items are allowed, disallowed, or constrained by the additionalProperties attribute using the same rules as extra properties for objects.. +
+
+This indicates that the instance property in the instance object is optional. This is false by default. +
+
+This provides a default property definition for all properties that are not explicitly defined in an object type definition. The value must be a schema. If false is provided, no additional properties are allowed, and the schema can not be extended. The default value is an empty schema which allows any value for additional properties. +
+
+This indicates that if this property is present in the containing instance object, the property given by requires attribute must also be present in the containing instance object. The value +of this property may be a string, indicating the require property name. Or the value may be a schema, in which case the containing instance must be valid by the schema if the property is present. For example if a object type definition is defined: +
+ + +
+An instance must include a state property if a town property is included. If a town property is not included, the state property is optional. +
+
+This indicates the minimum value for the instance property when the type of the instance value is a number. +
+
+This indicates the minimum value for the instance property when the type of the instance value is a number. +
+
+If the minimum is defined, this indicates whether or not the instance property value can equal the minimum. +
+
+If the maximum is defined, this indicates whether or not the instance property value can equal the maximum. +
+
+This indicates the minimum number of values in an array when an array is the instance value. +
+
+This indicates the maximum number of values in an array when an array is the instance value. +
+
+When the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid. Regular expressions should follow the regular expression specification from ECMA 262/Perl 5
+
+When the instance value is a string, this indicates maximum length of the string. +
+
+When the instance value is a string, this indicates minimum length of the string. +
+
+This provides an enumeration of possible values that are valid for the instance property. This should be an array, and each item in the array represents a possible value for the instance value. If "enum" is included, the instance value must be one of the values in enum array in order for the schema to be valid. +
+
+This provides a short description of the instance property. The value must be a string. +
+
+This provides a full description of the of purpose the instance property. The value must be a string. +
+
This property indicates the type of data, content type, or microformat to be expected in the instance property values. A format attribute may be one of the values listed below, and if so, should adhere to the semantics describing for the format. A format should only be used give meaning to primitive types (string, integer, number, or boolean). Validators are not required to validate that the instance values conform to a format. The following formats are defined: + +Any valid MIME media type may be used as a format value, in which case the instance property value must be a string, representing the contents of the MIME file. +date-time - This should be a date in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. This is the recommended form of date/timestamp. +date - This should be a date in the format of YYYY-MM-DD. It is recommended that you use the "date-time" format instead of "date" unless you need to transfer only the date part. +time - This should be a time in the format of hh:mm:ss. It is recommended that you use the "date-time" format instead of "time" unless you need to transfer only the time part. +utc-millisec - This should be the difference, measured in milliseconds, between the specified time and midnight, January 1, 1970 UTC. The value should be a number (integer or float). +regex - A regular expression. +color - This is a CSS color (like "#FF0000" or "red"). +style - This is a CSS style definition (like "color: red; background-color:#FFF"). +phone - This should be a phone number (format may follow E.123). +uri - This value should be a URI.. +email - This should be an email address. +ip-address - This should be an ip version 4 address. +ipv6 - This should be an ip version 6 address. +street-address - This should be a street address. +locality - This should be a city or town. +region - This should be a region (a state in the US, province in Canada, etc.) +postal-code - This should be a postal code (AKA zip code). +country - This should be the name of a country. +Additional custom formats may be defined with a URL to a definition of the format. + +
+
+If the instance property value is a string, this indicates that the string should be interpreted as binary data and decoded using the encoding named by this schema property. RFC 2045, Sec 6.1 lists possible values. + +
+
+This indicates the default for the instance property. +
+
+This indicates the maximum number of decimal places in a floating point number. By default there is no maximum. +
+
+This attribute may take the same values as the "type" attribute, however if the instance matches the type or if this value is an array and the instance matches any type or schema in the array, than this instance is not valid. +
+
+The value of this property should be another schema which will provide a base schema which the current schema will inherit from. The inheritance rules are such that any instance that is valid according to the current schema must be valid according to the referenced schema. This may also be an array, in which case, the instance must be valid for all the schemas in the array. +
+
+
+ This section defines hypermedia definitions of JSON schema. + The following attributes are specified in addition to those +attributes that already provided by JSON schema with the specific +purpose of informing user agents of relations between resources based +on JSON data. Just as with JSON +schema attributes, all the attributes in hyper-schema are optional. +Therefore an empty object is a valid (non-informative) schema, and +essentially describes plain JSON (no constraints on the structures). +Addition of attributes provides additive information for user agents. +
+ +The value of the links property should be an array, where each item +in the array is a link description object which describes the link +relations of the instances. + +
+ +A link description object is used to describe the link relations +of instances of a schema. + +
+ + The value of the "href" link description property +indicates the target URI of the related resource. The value +of the instance property should be resolved as a URI-Reference per [RFC3986] +and may be a relative URI. The base URI to be used for relative resolution +should be the URI used to retrieve the instance object (not the schema). +Also, the URI may be parametrized by the property values of the instance +object. + + +Instance property values should be substituted into the URIs where +matching braces ('{', '}') are found surrounding zero or more characters, +creating an expanded URI. Instance property value substitutions are resolved +by using the text between the braces to denote the property name +from the instance to get the value to substitute. For example, +if an href value is defined: +
+ + +
+Then it would be resolved by replace the value of the "id" property value from +the instance object. If the value of the "id" property was "45", the expanded +URI would be: +
+ + +
+If matching braces are found with the string "-this" (no quotes) between the braces, than the +actual instance value should be used to replace the braces, rather than a property value. +This should only be used in situations where the instance is a scalar (string, +boolean, or number), and not for objects or arrays. + +
+
+ +The value of the "rel" property indicates the name of the +relation to the target resource. The relation to the target should be interpreted as specifically from the instance object that the schema (or sub-schema) applies to, not just the top level resource that contains the object within its hierarchy. If a resource JSON representation contains a sub object with a property interpreted as a link, that sub-object holds the relation with the target. A relation to target from the top level resource must be indicated with the schema describing the top level JSON representation. + + +Relationship definitions SHOULD NOT be media type dependent, and users are encouraged to utilize existing accepted relation definitions, including those in existing relation registries (see &rfc4287). However, we define these relation here for clarity of normative interpretation within the context of JSON hyper schema defined relations: + + +self - If the relation value is "self", when this property is encountered in +the instance object, the object represents a resource and the instance object is +treated as a full representation of the target resource identified by +the specified URI. + + +full - This indicates that the target of the link is the full representation for the instance object. The object that contains this link may not be the full representation. + + +describedby - This indicates the target of the link is the schema for the instance object. This may be used to specifically denote the schemas of objects within a JSON object hierarchy, facilitating polymorphic type data structures. + + +The following relations are applicable for schemas (the schema as the "from" resource in the relation). + + +instances - This indicates the target resource that represents collection of instances of a schema. + + +create - This indicates a target to use for creating new instances of a schema. This link definition SHOULD be a submission link with a non-safe method (like POST). + + +For example, if a schema is defined: +
+ + +
+And if a collection of instance resource's JSON representation was +retrieved: +
+ + +
+ +This would indicate that for the first item in the collection, it's own +(self) URI would resolve to "/Resource/thing" and the first item's "up" +relation should be resolved to the resource at "/Resource/parent". +The "children" collection would be located at "/Resource/?upId=thing". + +
+
+ +The following properties also apply to link definition objects, and +provide functionality analogous to HTML forms, in providing a +means for submitting extra (often user supplied) information to send to a server. + +
+ + +This indicates which method should be used to access the target resource. +In an HTTP environment, this would be "GET" or "POST" (other HTTP methods +such as "PUT" and "DELETE" have semantics that are clearly implied by +accessed resources, and do not need to be defined here). +This defaults to "GET". + +
+ +
+ +If present, this property indicates a query media type format that the server +supports for querying or posting to the collection of instances at the target +resource. The query can be +suffixed to the target URI to query the collection with +property-based constraints on the resources that SHOULD be returned from +the server or used to post data to the resource (depending on the method). +For example, with the following schema: +
+ + +
+This indicates that the client can query the server for instances that +have a specific name: +
+ + +
+ +If no enctype or method is specified, only the single URI specified by +the href property is defined. If the method is POST, application/json is +the default media type. + +
+
+ +This is inherited from the base JSON schema definition, and can follow the +same structure, but its meaning should be used to define the acceptable +property names and values for the action (whether it be for the GET query +or POST body). If properties are omitted, and this form is the child of a +schema, the properties from the parent schema should be used as the basis +for the form action. + +
+
+
+
+
+ This property indicates the fragment resolution protocol to use for +resolving fragment identifiers in URIs within the instance +representations. This applies to the instance object URIs and all +children of the instance object's URIs. The default fragment resolution +protocol is "dot-delimited", which is defined below. Other fragment +resolution protocols may be used, but are not defined in this +document. + + + +The fragment identifier is based on RFC 2396 Sec 5, and defines the +mechanism for resolving references to entities within a document. + +
+With the dot-delimited fragment resolution protocol, the fragment +identifier is interpreted as a series of property reference tokens that +are delimited by the "." character (\x2E). Each property reference token +is a series of any legal URI component characters except the "." character. Each property +reference token should be interpreted, starting from the beginning of +the fragment identifier, as a path reference in the target JSON +structure. The final target value of the fragment can be determined by +starting with the root of the JSON structure from the representation of +the resource identified by the pre-fragment URI. If the target is a JSON +object, than the new target is the value of the property with the name +identified by the next property reference token in the fragment. If the +target is a JSON array, than the target is determined by finding the +item in array the array with the index defined by the next property +reference token (which MUST be a number). The target is successively +updated for each property reference token, until the entire fragment has +been traversed. + + +Property names SHOULD be URI-encoded. In particular, any "." in a +property name MUST be encoded to avoid being interpreted as a property +delimiter. + + +For example, for the following JSON representation: +
+ + +
+The following fragment identifiers would be resolved: +
+ + +
+ +
+ + +
+ +
+ This attribute indicates that the value of the instance property value +SHOULD be treated as the root or the body of the representation for the +purposes of user agent interaction and fragment resolution (all other +properties of the instance objects are can be regarded as meta-data +descriptions for the data). + + + +
+
+This indicates that the instance property should not be changed. Attempts by a user agent to modify the value of this property are expected to be rejected by a server. +
+ +
+ This property value is a URI-Reference that indicates the URI that all +the URIs for the instances of the schema should start with. When +multiple schemas have been referenced for an instance, the user agent +can determine if this schema is applicable for a particular instance by +determining if URI of the instance begins with the pathStart's referenced +URI. pathStart MUST be resolved as per [RFC3986] section 5. If the URI of +the instance does not start with URI indicated by pathStart, or if another +schema specifies a starting URI that is longer and also matches the +instance, this schema should not be applied to the instance. Any schema +that does not have a pathStart attribute should be considered applicable +to all the instances for which it is referenced. + + + + + +
+
+ This indicates the media type of the instance representations that this schema is defining. + + +
+ +
+ This is an array of JSON schema definitions that define any + other schemas for alternate JSON-based representations + of the instance resources. + + +
+ + +
+ +
+ +This specification is a sub-type of the JSON format, and +consequently the security considerations are generally the same as RFC +4627. However, an additional issue is that when link relation of "self" +is used to denote a full representation of an object, the user agent +SHOULD NOT consider the representation to be the authoritative representation +of the resource denoted by the target URI if the target URI is not +equivalent to or a sub-path of the the URI used to request the resource +representation which contains the target URI with the "self" link. +For example, if a hyper schema was defined: +
+ + +
+And a resource was requested from somesite.com: +
+ + +
+ +With a response of: +
+ + +
+ +
+
+ + The proposed MIME media type for JSON Schema is application/schema+json + + + Type name: application + + + Subtype name: schema+json + + + Required parameters: describedby + + + The value of the describedby parameter should be a URI (relative or absolute) that + refers to the schema used to define the structure of this structure (the + meta-schema). Normally the value would be http://json-schema.org/hyper-schema, + but it is allowable to use other schemas that extend the hyper schema's meta- + schema. + + + Optional parameters: pretty + + + The value of the pretty parameter may be true or false to indicate if additional + whitespace has been included to make the JSON representation easier to read. + + +
+ +This registry is maintained by IANA per RFC 4287 and this specification adds +three values: "full", "create", "instances". New + assignments are subject to IESG Approval, as outlined in [RFC5226]. + Requests should be made by email to IANA, which will then forward the + request to the IESG, requesting approval. + + +
+ +
+ + + + + + + + &rfc3986; + &rfc2119; + &rfc4287; + &rfc3339; + &rfc2045; + + + + &rfc4627; + &rfc2616; + &rfc5226; + &iddiscovery; + &uritemplate; + &linkheader; + &html401; + + + + +
+ -01 + + + Fixed category and updates from template + + + -00 + + + Initial draft + + + +
+ +
+ Should we give a preference to MIME headers over Link headers (or only use one)? + Should we use "profile" as the media type parameter instead? + Should "root" be a MIME parameter instead of a schema attribute? + Should "format" be renamed to "mediaType" or "contentType" to reflect the usage MIME media types that are allowed. + I still do not like how dates are handled. + +
+ + + + diff --git a/draft-zyp-json-schema-01.html b/draft-zyp-json-schema-01.html new file mode 100644 index 0000000..7ce12a8 --- /dev/null +++ b/draft-zyp-json-schema-01.html @@ -0,0 +1,1400 @@ + +A JSON Media Type for Describing the Structure and Meaning of JSON Documents + + + + + + + +
 TOC 
+
+ + + + +
Internet Engineering Task ForceK. Zyp, Ed.
Internet-DraftSitePen (USA)
Intended status: InformationalDecember 5, 2009
Expires: June 8, 2010 
+


A JSON Media Type for Describing the Structure and Meaning of JSON Documents
draft-zyp-json-schema-01

+ +

Abstract

+ +

JSON (JavaScript Object Notation) Schema defines the media type application/schema+json, + a JSON based format for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. +

+

Status of This Memo

+

+This Internet-Draft is submitted to IETF in full +conformance with the provisions of BCP 78 and BCP 79.

+

+Internet-Drafts are working documents of the Internet Engineering +Task Force (IETF), its areas, and its working groups. +Note that other groups may also distribute working documents as +Internet-Drafts.

+

+Internet-Drafts are draft documents valid for a maximum of six months +and may be updated, replaced, or obsoleted by other documents at any time. +It is inappropriate to use Internet-Drafts as reference material or to cite +them other than as “work in progress.”

+

+The list of current Internet-Drafts can be accessed at +http://www.ietf.org/ietf/1id-abstracts.txt.

+

+The list of Internet-Draft Shadow Directories can be accessed at +http://www.ietf.org/shadow.html.

+

+This Internet-Draft will expire on June 8, 2010.

+ +

Copyright Notice

+

+Copyright (c) 2009 IETF Trust and the persons identified as the +document authors. All rights reserved.

+

+This document is subject to BCP 78 and the IETF Trust's Legal +Provisions Relating to IETF Documents +(http://trustee.ietf.org/license-info) in effect on the date of +publication of this document. Please review these documents +carefully, as they describe your rights and restrictions with respect +to this document. Code Components extracted from this document must +include Simplified BSD License text as described in Section 4.e of +the Trust Legal Provisions and are provided without warranty as +described in the BSD License.

+
+

Table of Contents

+

+1.  +Introduction
+2.  +Conventions
+3.  +Overview
+    3.1.  +Terminology
+    3.2.  +Design Considerations
+4.  +Schema/Instance Association
+    4.1.  +Self-Descriptive Schema
+5.  +Core Schema Definition
+    5.1.  +type
+    5.2.  +properties
+    5.3.  +items
+    5.4.  +optional
+    5.5.  +additionalProperties
+    5.6.  +requires
+    5.7.  +minimum
+    5.8.  +maximum
+    5.9.  +minimumCanEqual
+    5.10.  +maximumCanEqual
+    5.11.  +minItems
+    5.12.  +maxItems
+    5.13.  +pattern
+    5.14.  +maxLength
+    5.15.  +minLength
+    5.16.  +enum
+    5.17.  +title
+    5.18.  +description
+    5.19.  +format
+    5.20.  +contentEncoding
+    5.21.  +default
+    5.22.  +maxDecimal
+    5.23.  +disallow
+    5.24.  +extends
+6.  +Hyper Schema
+    6.1.  +links
+        6.1.1.  +Link Description Object
+    6.2.  +fragmentResolution
+        6.2.1.  +dot-delimited fragment resolution
+    6.3.  +root
+    6.4.  +readonly
+    6.5.  +pathStart
+    6.6.  +mediaType
+    6.7.  +alternate
+7.  +Security Considerations
+8.  +IANA Considerations
+    8.1.  +Registry of Link Relations
+9.  +References
+    9.1.  +Normative References
+    9.2.  +Informative References
+Appendix A.  +Change Log
+Appendix B.  +Open Issues
+

+
+ +
+
 TOC 
+

1.  +Introduction

+ +

JSON (JavaScript Object Notation) Schema is a JSON media type for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. +

+
+
 TOC 
+

2.  +Conventions

+ +

The key words "MUST", "MUST + NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", + "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be + interpreted as described in RFC 2119. +

+
+
 TOC 
+

3.  +Overview

+ +

JSON Schema defines the media type application/schema+json for + describing the structure of other + JSON documents. JSON Schema is JSON-based and includes facilities + for describing the structure of JSON documents in terms of + allowable values, descriptions, and interpreting relations with other resources. +

+

JSON Schema format is organized into several separate definitions. The first + definition is the core schema specification. This definition is primary + concerned with describing a JSON structure and specifying valid elements + in the structure. The second definition is the Hyper Schema specification + which is intended define elements in a structure that can be interpreted as + hyperlinks. + Hyper Schema builds on JSON Schema to describe the hyperlink structure of + other JSON documents. This allows user agents to be able to successfully navigate + JSON documents based on their schemas. +

+

+ Cumulatively JSON Schema acts as a meta-document that can be used to define the required type and constraints on + property values, as well as define the meaning of the property values + for the purpose of describing a resource and determining hyperlinks + within the representation. +

+

+ An example JSON Schema that describes products might look like: +

+
+
+{
+  "name":"Product",
+  "properties":{
+    "id":{
+      "type":"number",
+      "description":"Product identifier"
+    },
+    "name":{
+      "description":"Name of the product",
+      "type":"string"
+    },
+    "price":{
+      "type": "number",
+      "minimum":0
+    },
+    "tags":{
+      "optional":true,
+      "type":"array",
+      "items":{
+         "type":"string"
+      }
+    }
+  },
+  "links":[
+    {
+      "rel":"full",
+      "href":"{id}"
+    },
+    {
+      "rel":"comments",
+      "href":"comments/?id={id}"
+    }
+  ]
+}
+

+ +This schema defines the properties of the instance JSON documents and +their required properties (id, name, and price) as well as an optional +property (tags). This also defines the link relations of the instance +JSON documents. + +

+
+
 TOC 
+

3.1.  +Terminology

+ +

For this specification, a schema will be used to denote a JSON Schema + definition, and an instance refers to the JSON object or array that the schema + will be describing and validating +

+
+
 TOC 
+

3.2.  +Design Considerations

+ +

+ The JSON Schema media type does not attempt to dictate the structure of JSON + representations that contain data, but rather provides a separate format + for flexibly communicating how a JSON representation should be + interpreted and validated, such that user agents can properly understand + acceptable structures and extrapolate hyperlink information + with the JSON document. This specification does not define a protocol. + The underlying protocol (such as HTTP) should sufficiently define the + semantics of the client-server interface, the retrieval of resource + representations linked to by JSON representations, and modification of + those resources. The goal of this + format is to sufficiently describe JSON structures such that one can + utilize existing information available in existing JSON + representations from a large variety of services that leverage a REST + architecture using existing protocols. + +

+
+
 TOC 
+

4.  +Schema/Instance Association

+ +

+ JSON Schema instances are correlated to their schema by the "describedby" + relation, where the schema is defined to be the target of the relation. + Instance representations may be of the application/json media type or + any other subtype. Consequently, dictating how an instance + representation should specify the relation to the schema is beyond the normative scope + of this document (since this document specifically defines the JSON + Schema media type, and no other), but it is recommended that instances + specify their schema so that user agents can interpret the instance + representation and messages may retain the self-descriptive + characteristic, avoiding the need for out-of-band information about + instance data. Two approaches are recommended for declaring the + relation to the schema that describes the meaning of a JSON instance's (or collection + of instances) structure. A MIME type parameter named + "describedby" or a Link header with a relation of "describedby" SHOULD be used: +

+
+
+Content-Type: application/json;
+              describedby=http://json.com/my-hyper-schema
+

+ + or if the content is being transferred by a protocol (such as HTTP) that + provides headers, a Link header can be used: +

+
+
+Link: <http://json.com/my-hyper-schema>; rel="describedby"
+

+ + Instances MAY specify multiple schemas, to indicate all the schemas that + are applicable to the data. The instance data may have multiple schemas + that it is defined by (the instance data should be valid for those schemas). + Or if the document is a collection of instances, the collection may contain + instances from different schemas. When collections contain heterogeneous + instances, the pathStart attribute MAY be specified in the + schema to disambiguate which schema should be applied for each item in the +collection. + +

+
+
 TOC 
+

4.1.  +Self-Descriptive Schema

+ +

+ JSON Schemas are themselves instances for the schema + schemas. A self-describing JSON Schema for the core JSON Schema can + be found at http://json-schema.org/schema and the hyper schema + self-description can be found at: http://json-schema.org/hyper-schema. All schemas + used within a protocol with media type definitions + SHOULD include a MIME parameter that refers to the self-descriptive + hyper schema or another schema that extends this hyper schema: +

+
+
+Content-Type: application/json;
+              describedby=http://www.json-schema.org/hyper-schema
+

+ + +

+
+
 TOC 
+

5.  +Core Schema Definition

+ +

A JSON Schema is a JSON Object that defines various attributes + of the instance and defines it's usage and valid values. A JSON + Schema is a JSON Object with schema attribute properties. + The following is the grammar of a JSON Schema: + +

+

And an example JSON Schema definition could look like: +

+
+{"description":"A person",
+ "type":"object",
+
+ "properties":
+  {"name": {"type":"string"},
+   "age" : {"type":"integer",
+     "maximum":125}}
+}
+
+

A JSON Schema object may have any of the following properties, called schema + attributes (all attributes are optional): + +

+
+
 TOC 
+

5.1.  +type

+ +

+

+
+

Union type definition - An array with two or more items which indicates a union of type definitions. Each item in the array may be a simple type definition or a schema. The instance value is valid if it is of the same type as one the type definitions in the array or if it is valid by one of the schemas in the array. For example to indicate that a string or number is a valid: +{"type":["string","number"]} +

+

Simple type definition - A string indicating a primitive or simple type. The following are acceptable strings: + + +

+
+

string - Value must be a string. + +

+

number - Value must be a number, floating point numbers are allowed. +

+

integer - Value must be an integer, no floating point numbers are allowed. This is a subset of the number type. +

+

boolean - Value must be a boolean. +

+

object - Value must be an object. +

+

array - Value must be an array. + +

+

null - Value must be null. Note this is mainly for purpose of being able use union types to define nullability. +

+

any - Value may be of any type including null. +If the property is not defined or is not in this list, than any type of value is acceptable. Other type values may be used for custom purposes, but minimal validators of the specification implementation can allow any instance value on unknown type values. +

+
+ + +

+ +

+
+
 TOC 
+

5.2.  +properties

+ +

This should be an object type definition, which is an object with property definitions that correspond to instance object properties. When the instance value is an object, the property values of the instance object must conform to the property definitions in this object. In this object, each property definition's value should be a schema, and the property's name should be the name of the instance property that it defines. +

+
+
 TOC 
+

5.3.  +items

+ +

This should be a schema or an array of schemas. When this is an object/schema and the instance value is an array, all the items in the array must conform to this schema. When this is an array of schemas and the instance value is an array, each position in the instance array must conform to the schema in the corresponding position for this array. This called tuple typing. When tuple typing is used, additional items are allowed, disallowed, or constrained by the additionalProperties attribute using the same rules as extra properties for objects.. +

+
+
 TOC 
+

5.4.  +optional

+ +

This indicates that the instance property in the instance object is optional. This is false by default. +

+
+
 TOC 
+

5.5.  +additionalProperties

+ +

This provides a default property definition for all properties that are not explicitly defined in an object type definition. The value must be a schema. If false is provided, no additional properties are allowed, and the schema can not be extended. The default value is an empty schema which allows any value for additional properties. +

+
+
 TOC 
+

5.6.  +requires

+ +

This indicates that if this property is present in the containing instance object, the property given by requires attribute must also be present in the containing instance object. The value +of this property may be a string, indicating the require property name. Or the value may be a schema, in which case the containing instance must be valid by the schema if the property is present. For example if a object type definition is defined: +

+
+{
+  "state":
+  {
+    "optional":true
+  },
+  "town":
+  {
+    "requires":"state",
+    "optional":true
+  }
+}
+
+

An instance must include a state property if a town property is included. If a town property is not included, the state property is optional. +

+
+
 TOC 
+

5.7.  +minimum

+ +

This indicates the minimum value for the instance property when the type of the instance value is a number. +

+
+
 TOC 
+

5.8.  +maximum

+ +

This indicates the minimum value for the instance property when the type of the instance value is a number. +

+
+
 TOC 
+

5.9.  +minimumCanEqual

+ +

If the minimum is defined, this indicates whether or not the instance property value can equal the minimum. +

+
+
 TOC 
+

5.10.  +maximumCanEqual

+ +

If the maximum is defined, this indicates whether or not the instance property value can equal the maximum. +

+
+
 TOC 
+

5.11.  +minItems

+ +

This indicates the minimum number of values in an array when an array is the instance value. +

+
+
 TOC 
+

5.12.  +maxItems

+ +

This indicates the maximum number of values in an array when an array is the instance value. +

+
+
 TOC 
+

5.13.  +pattern

+ +

When the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid. Regular expressions should follow the regular expression specification from ECMA 262/Perl 5 +

+
+
 TOC 
+

5.14.  +maxLength

+ +

When the instance value is a string, this indicates maximum length of the string. +

+
+
 TOC 
+

5.15.  +minLength

+ +

When the instance value is a string, this indicates minimum length of the string. +

+
+
 TOC 
+

5.16.  +enum

+ +

This provides an enumeration of possible values that are valid for the instance property. This should be an array, and each item in the array represents a possible value for the instance value. If "enum" is included, the instance value must be one of the values in enum array in order for the schema to be valid. +

+
+
 TOC 
+

5.17.  +title

+ +

This provides a short description of the instance property. The value must be a string. +

+
+
 TOC 
+

5.18.  +description

+ +

This provides a full description of the of purpose the instance property. The value must be a string. +

+
+
 TOC 
+

5.19.  +format

+ +

This property indicates the type of data, content type, or microformat to be expected in the instance property values. A format attribute may be one of the values listed below, and if so, should adhere to the semantics describing for the format. A format should only be used give meaning to primitive types (string, integer, number, or boolean). Validators are not required to validate that the instance values conform to a format. The following formats are defined: +

+
+

Any valid MIME media type may be used as a format value, in which case the instance property value must be a string, representing the contents of the MIME file. + +

+

date-time - This should be a date in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. This is the recommended form of date/timestamp. + +

+

date - This should be a date in the format of YYYY-MM-DD. It is recommended that you use the "date-time" format instead of "date" unless you need to transfer only the date part. + +

+

time - This should be a time in the format of hh:mm:ss. It is recommended that you use the "date-time" format instead of "time" unless you need to transfer only the time part. + +

+

utc-millisec - This should be the difference, measured in milliseconds, between the specified time and midnight, January 1, 1970 UTC. The value should be a number (integer or float). + +

+

regex - A regular expression. + +

+

color - This is a CSS color (like "#FF0000" or "red"). + +

+

style - This is a CSS style definition (like "color: red; background-color:#FFF"). + +

+

phone - This should be a phone number (format may follow E.123). + +

+

uri - This value should be a URI.. + +

+

email - This should be an email address. + +

+

ip-address - This should be an ip version 4 address. + +

+

ipv6 - This should be an ip version 6 address. +

+

street-address - This should be a street address. +

+

locality - This should be a city or town. +

+

region - This should be a region (a state in the US, province in Canada, etc.) +

+

postal-code - This should be a postal code (AKA zip code). +

+

country - This should be the name of a country. +

+

Additional custom formats may be defined with a URL to a definition of the format. +

+
+
+
 TOC 
+

5.20.  +contentEncoding

+ +

+If the instance property value is a string, this indicates that the string should be interpreted as binary data and decoded using the encoding named by this schema property. RFC 2045, Sec 6.1 lists possible values. + +

+
+
 TOC 
+

5.21.  +default

+ +

This indicates the default for the instance property. +

+
+
 TOC 
+

5.22.  +maxDecimal

+ +

This indicates the maximum number of decimal places in a floating point number. By default there is no maximum. +

+
+
 TOC 
+

5.23.  +disallow

+ +

This attribute may take the same values as the "type" attribute, however if the instance matches the type or if this value is an array and the instance matches any type or schema in the array, than this instance is not valid. +

+
+
 TOC 
+

5.24.  +extends

+ +

The value of this property should be another schema which will provide a base schema which the current schema will inherit from. The inheritance rules are such that any instance that is valid according to the current schema must be valid according to the referenced schema. This may also be an array, in which case, the instance must be valid for all the schemas in the array. +

+
+
 TOC 
+

6.  +Hyper Schema

+ +

This section defines hypermedia definitions of JSON schema. + The following attributes are specified in addition to those +attributes that already provided by JSON schema with the specific +purpose of informing user agents of relations between resources based +on JSON data. Just as with JSON +schema attributes, all the attributes in hyper-schema are optional. +Therefore an empty object is a valid (non-informative) schema, and +essentially describes plain JSON (no constraints on the structures). +Addition of attributes provides additive information for user agents. +

+
+
 TOC 
+

6.1.  +links

+ +

+The value of the links property should be an array, where each item +in the array is a link description object which describes the link +relations of the instances. + +

+
+
 TOC 
+

6.1.1.  +Link Description Object

+ +

+A link description object is used to describe the link relations +of instances of a schema. + +

+
+
 TOC 
+

6.1.1.1.  +href

+ +

+ The value of the "href" link description property +indicates the target URI of the related resource. The value +of the instance property should be resolved as a URI-Reference per [RFC3986] +and may be a relative URI. The base URI to be used for relative resolution +should be the URI used to retrieve the instance object (not the schema). +Also, the URI may be parametrized by the property values of the instance +object. + +

+

+Instance property values should be substituted into the URIs where +matching braces ('{', '}') are found surrounding zero or more characters, +creating an expanded URI. Instance property value substitutions are resolved +by using the text between the braces to denote the property name +from the instance to get the value to substitute. For example, +if an href value is defined: +

+
+
+http://somesite.com/{id}
+

+ +Then it would be resolved by replace the value of the "id" property value from +the instance object. If the value of the "id" property was "45", the expanded +URI would be: +

+
+
+http://somesite.com/45
+

+ +If matching braces are found with the string "-this" (no quotes) between the braces, than the +actual instance value should be used to replace the braces, rather than a property value. +This should only be used in situations where the instance is a scalar (string, +boolean, or number), and not for objects or arrays. + +

+
+
 TOC 
+

6.1.1.2.  +rel

+ +

+The value of the "rel" property indicates the name of the +relation to the target resource. The relation to the target should be interpreted as specifically from the instance object that the schema (or sub-schema) applies to, not just the top level resource that contains the object within its hierarchy. If a resource JSON representation contains a sub object with a property interpreted as a link, that sub-object holds the relation with the target. A relation to target from the top level resource must be indicated with the schema describing the top level JSON representation. + +

+

+Relationship definitions SHOULD NOT be media type dependent, and users are encouraged to utilize existing accepted relation definitions, including those in existing relation registries (see &rfc4287). However, we define these relation here for clarity of normative interpretation within the context of JSON hyper schema defined relations: +

+
+

+self - If the relation value is "self", when this property is encountered in +the instance object, the object represents a resource and the instance object is +treated as a full representation of the target resource identified by +the specified URI. + +

+

+full - This indicates that the target of the link is the full representation for the instance object. The object that contains this link may not be the full representation. + +

+

+describedby - This indicates the target of the link is the schema for the instance object. This may be used to specifically denote the schemas of objects within a JSON object hierarchy, facilitating polymorphic type data structures. + +

+

+The following relations are applicable for schemas (the schema as the "from" resource in the relation). + +

+

+instances - This indicates the target resource that represents collection of instances of a schema. + +

+

+create - This indicates a target to use for creating new instances of a schema. This link definition SHOULD be a submission link with a non-safe method (like POST). + +

+

+For example, if a schema is defined: +

+
+
+{
+    "links": [
+    	{
+    		"rel": "self"
+    		"href": "{id}"
+    	},
+    	{
+    		"rel": "up"
+    		"href": "{upId}"
+    	},
+    	{
+    		"rel": "children"
+    		"href": "?upId={id}"
+    	}
+    ]
+}
+

+ +And if a collection of instance resource's JSON representation was +retrieved: +

+
+
+GET /Resource/
+
+[
+    {
+        "id": "thing",
+        "upId": "parent"
+    },
+    {
+        "id": "thing2",
+        "upId": "parent"
+    }
+]
+

+ + +This would indicate that for the first item in the collection, it's own +(self) URI would resolve to "/Resource/thing" and the first item's "up" +relation should be resolved to the resource at "/Resource/parent". +The "children" collection would be located at "/Resource/?upId=thing". + +

+
+
 TOC 
+

6.1.1.3.  +Submission Link Properties

+ +

+The following properties also apply to link definition objects, and +provide functionality analogous to HTML forms, in providing a +means for submitting extra (often user supplied) information to send to a server. + +

+
+
 TOC 
+

6.1.1.3.1.  +method

+ +

+ +This indicates which method should be used to access the target resource. +In an HTTP environment, this would be "GET" or "POST" (other HTTP methods +such as "PUT" and "DELETE" have semantics that are clearly implied by +accessed resources, and do not need to be defined here). +This defaults to "GET". + +

+
+
 TOC 
+

6.1.1.3.2.  +enctype

+ +

+If present, this property indicates a query media type format that the server +supports for querying or posting to the collection of instances at the target +resource. The query can be +suffixed to the target URI to query the collection with +property-based constraints on the resources that SHOULD be returned from +the server or used to post data to the resource (depending on the method). +For example, with the following schema: +

+
+
+{
+ "links":[
+    {
+      "enctype": "application/x-www-form-urlencoded",
+      "method": "GET",
+      "href": "/Product/",
+      "properties":{
+         "name":{"description":"name of the product"}
+      }
+    }
+  ]
+}
+

+ +This indicates that the client can query the server for instances that +have a specific name: +

+
+
+/Product/?name=Slinky
+

+ + +If no enctype or method is specified, only the single URI specified by +the href property is defined. If the method is POST, application/json is +the default media type. + +

+
+
 TOC 
+

6.1.1.3.3.  +properties

+ +

+This is inherited from the base JSON schema definition, and can follow the +same structure, but its meaning should be used to define the acceptable +property names and values for the action (whether it be for the GET query +or POST body). If properties are omitted, and this form is the child of a +schema, the properties from the parent schema should be used as the basis +for the form action. + +

+
+
 TOC 
+

6.2.  +fragmentResolution

+ +

This property indicates the fragment resolution protocol to use for +resolving fragment identifiers in URIs within the instance +representations. This applies to the instance object URIs and all +children of the instance object's URIs. The default fragment resolution +protocol is "dot-delimited", which is defined below. Other fragment +resolution protocols may be used, but are not defined in this +document. + + +

+

+The fragment identifier is based on RFC 2396 Sec 5, and defines the +mechanism for resolving references to entities within a document. + +

+
+
 TOC 
+

6.2.1.  +dot-delimited fragment resolution

+ +

With the dot-delimited fragment resolution protocol, the fragment +identifier is interpreted as a series of property reference tokens that +are delimited by the "." character (\x2E). Each property reference token +is a series of any legal URI component characters except the "." character. Each property +reference token should be interpreted, starting from the beginning of +the fragment identifier, as a path reference in the target JSON +structure. The final target value of the fragment can be determined by +starting with the root of the JSON structure from the representation of +the resource identified by the pre-fragment URI. If the target is a JSON +object, than the new target is the value of the property with the name +identified by the next property reference token in the fragment. If the +target is a JSON array, than the target is determined by finding the +item in array the array with the index defined by the next property +reference token (which MUST be a number). The target is successively +updated for each property reference token, until the entire fragment has +been traversed. + +

+

+Property names SHOULD be URI-encoded. In particular, any "." in a +property name MUST be encoded to avoid being interpreted as a property +delimiter. + +

+

+For example, for the following JSON representation: +

+
+
+{
+   "foo":{
+      "anArray":[
+        {"prop":44}
+      ],
+      "another prop":{
+          "baz":"A string"
+      }
+   }
+}
+

+ +The following fragment identifiers would be resolved: +

+
+
+fragment identifier    resolution
+-------------------    ----------
+#                      self, the root of the resource itself
+#foo                   the object referred to by the foo property
+#foo.another prop      the object referred to by the "another prop"
+                       property of the object referred to by the
+                       "foo" property
+#foo.another prop.baz  the string referred to by the value of "baz"
+                       property of the "another prop" property of
+                       the object referred to by the "foo" property
+#foo.anArray.0         the first object in the "anArray" array
+

+ + +

+
+
 TOC 
+

6.3.  +root

+ +

This attribute indicates that the value of the instance property value +SHOULD be treated as the root or the body of the representation for the +purposes of user agent interaction and fragment resolution (all other +properties of the instance objects are can be regarded as meta-data +descriptions for the data). + + +

+
+
 TOC 
+

6.4.  +readonly

+ +

This indicates that the instance property should not be changed. Attempts by a user agent to modify the value of this property are expected to be rejected by a server. +

+
+
 TOC 
+

6.5.  +pathStart

+ +

This property value is a URI-Reference that indicates the URI that all +the URIs for the instances of the schema should start with. When +multiple schemas have been referenced for an instance, the user agent +can determine if this schema is applicable for a particular instance by +determining if URI of the instance begins with the pathStart's referenced +URI. pathStart MUST be resolved as per [RFC3986] section 5. If the URI of +the instance does not start with URI indicated by pathStart, or if another +schema specifies a starting URI that is longer and also matches the +instance, this schema should not be applied to the instance. Any schema +that does not have a pathStart attribute should be considered applicable +to all the instances for which it is referenced. + + + +

+
+
 TOC 
+

6.6.  +mediaType

+ +

This indicates the media type of the instance representations that this schema is defining. + +

+
+
 TOC 
+

6.7.  +alternate

+ +

This is an array of JSON schema definitions that define any + other schemas for alternate JSON-based representations + of the instance resources. + +

+
+
 TOC 
+

7.  +Security Considerations

+ +

+This specification is a sub-type of the JSON format, and +consequently the security considerations are generally the same as RFC +4627. However, an additional issue is that when link relation of "self" +is used to denote a full representation of an object, the user agent +SHOULD NOT consider the representation to be the authoritative representation +of the resource denoted by the target URI if the target URI is not +equivalent to or a sub-path of the the URI used to request the resource +representation which contains the target URI with the "self" link. +For example, if a hyper schema was defined: +

+
+
+{
+  "links":[
+  	{
+  		"rel":"self",
+  		"href":"{id}"
+  	}
+  ]
+}
+

+ +And a resource was requested from somesite.com: +

+
+
+GET /foo/
+

+ + +With a response of: +

+
+
+Content-Type: application/json; describedby=/schema-for-this-data
+[
+  {"id":"bar", "name":"This representation can be safely treated \
+        as authoritative "},
+  {"id":"/baz", "name":"This representation should not be treated as \
+        authoritative the user agent should make request the resource\
+        from "/baz" to ensure it has the authoritative representation"},
+  {"id":"http://othersite.com/something", "name":"This representation\
+        should also not be treated as authoritative and the target\
+        resource representation should be retrieved for the\
+        authoritative representation"}
+]
+

+ + +

+
+
 TOC 
+

8.  +IANA Considerations

+ +

+ The proposed MIME media type for JSON Schema is application/schema+json + +

+

+ Type name: application + +

+

+ Subtype name: schema+json + +

+

+ Required parameters: describedby + +

+

+ The value of the describedby parameter should be a URI (relative or absolute) that + refers to the schema used to define the structure of this structure (the + meta-schema). Normally the value would be http://json-schema.org/hyper-schema, + but it is allowable to use other schemas that extend the hyper schema's meta- + schema. + +

+

+ Optional parameters: pretty + +

+

+ The value of the pretty parameter may be true or false to indicate if additional + whitespace has been included to make the JSON representation easier to read. + +

+
+
 TOC 
+

8.1.  +Registry of Link Relations

+ +

+This registry is maintained by IANA per RFC 4287 and this specification adds +three values: "full", "create", "instances". New + assignments are subject to IESG Approval, as outlined in [RFC5226]. + Requests should be made by email to IANA, which will then forward the + request to the IESG, requesting approval. + + +

+
+
 TOC 
+

9.  +References

+ +
+
 TOC 
+

9.1. Normative References

+ + + + + + + + + + + +
[RFC3986]Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, January 2005 (TXT, HTML, XML).
[RFC2119]Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC4287]Nottingham, M., Ed. and R. Sayre, Ed., “The Atom Syndication Format,” RFC 4287, December 2005 (TXT, HTML, XML).
[RFC3339]Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” RFC 3339, July 2002 (TXT, HTML, XML).
[RFC2045]Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” RFC 2045, November 1996 (TXT).
+ +
+
 TOC 
+

9.2. Informative References

+ + + + + + + + + + + + + + + +
[RFC4627]Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[RFC2616]Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC5226]Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” BCP 26, RFC 5226, May 2008 (TXT).
[I-D.hammer-discovery]Hammer-Lahav, E., “Link-based Resource Descriptor Discovery,” draft-hammer-discovery-03 (work in progress), March 2009 (TXT).
[I-D.gregorio-uritemplate]Gregorio, J., “URI Template,” draft-gregorio-uritemplate-03 (work in progress), April 2008 (TXT).
[I-D.nottingham-http-link-header]Nottingham, M., “Web Linking,” draft-nottingham-http-link-header-06 (work in progress), July 2009 (TXT).
[W3C.REC-html401-19991224]Hors, A., Jacobs, I., and D. Raggett, “HTML 4.01 Specification,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (HTML).
+ +
+
 TOC 
+

Appendix A.  +Change Log

+ +

-01 +

+

+

+

+ +

+

-00 +

+

+

+

+ +

+
+
 TOC 
+

Appendix B.  +Open Issues

+ +

Should we give a preference to MIME headers over Link headers (or only use one)? +

+

Should we use "profile" as the media type parameter instead? +

+

Should "root" be a MIME parameter instead of a schema attribute? +

+

Should "format" be renamed to "mediaType" or "contentType" to reflect the usage MIME media types that are allowed. +

+

I still do not like how dates are handled. +

+
+
 TOC 
+

Author's Address

+ + + + + + + + + + + + + + + +
 Kris Zyp (editor)
 SitePen (USA)
 530 Lytton Avenue
 Palo Alto, CA 94301
 USA
Phone: +1 650 968 8787
EMail: kris@sitepen.com
+ + diff --git a/draft-zyp-json-schema-01.txt b/draft-zyp-json-schema-01.txt new file mode 100644 index 0000000..e154671 --- /dev/null +++ b/draft-zyp-json-schema-01.txt @@ -0,0 +1,1289 @@ + + + +Internet Engineering Task Force K. Zyp, Ed. +Internet-Draft SitePen (USA) +Intended status: Informational December 5, 2009 +Expires: June 8, 2010 + + + A JSON Media Type for Describing the Structure and Meaning of JSON + Documents + draft-zyp-json-schema-01 + +Abstract + + JSON (JavaScript Object Notation) Schema defines the media type + application/schema+json, a JSON based format for defining the + structure of JSON data. JSON Schema provides a contract for what + JSON data is required for a given application and how to interact + with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +Status of This Memo + + This Internet-Draft is submitted to IETF in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on June 8, 2010. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + + + +Zyp Expires June 8, 2010 [Page 1] + +Internet-Draft JSON Schema Media Type December 2009 + + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Design Considerations . . . . . . . . . . . . . . . . . . 6 + 4. Schema/Instance Association . . . . . . . . . . . . . . . . . 6 + 4.1. Self-Descriptive Schema . . . . . . . . . . . . . . . . . 7 + 5. Core Schema Definition . . . . . . . . . . . . . . . . . . . . 7 + 5.1. type . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 5.2. properties . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.3. items . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.4. optional . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.5. additionalProperties . . . . . . . . . . . . . . . . . . . 9 + 5.6. requires . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.7. minimum . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.8. maximum . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.9. minimumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 + 5.10. maximumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 + 5.11. minItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.12. maxItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.13. pattern . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.14. maxLength . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.15. minLength . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.16. enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.17. title . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.18. description . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.19. format . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.20. contentEncoding . . . . . . . . . . . . . . . . . . . . . 12 + 5.21. default . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.22. maxDecimal . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.23. disallow . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.24. extends . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6. Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6.1. links . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6.1.1. Link Description Object . . . . . . . . . . . . . . . 13 + 6.2. fragmentResolution . . . . . . . . . . . . . . . . . . . . 17 + + + +Zyp Expires June 8, 2010 [Page 2] + +Internet-Draft JSON Schema Media Type December 2009 + + + 6.2.1. dot-delimited fragment resolution . . . . . . . . . . 18 + 6.3. root . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.4. readonly . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.5. pathStart . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.6. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.7. alternate . . . . . . . . . . . . . . . . . . . . . . . . 20 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 + 8.1. Registry of Link Relations . . . . . . . . . . . . . . . . 21 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23 + Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 23 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 3] + +Internet-Draft JSON Schema Media Type December 2009 + + +1. Introduction + + JSON (JavaScript Object Notation) Schema is a JSON media type for + defining the structure of JSON data. JSON Schema provides a contract + for what JSON data is required for a given application and how to + interact with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +2. Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119. + +3. Overview + + JSON Schema defines the media type application/schema+json for + describing the structure of other JSON documents. JSON Schema is + JSON-based and includes facilities for describing the structure of + JSON documents in terms of allowable values, descriptions, and + interpreting relations with other resources. + + JSON Schema format is organized into several separate definitions. + The first definition is the core schema specification. This + definition is primary concerned with describing a JSON structure and + specifying valid elements in the structure. The second definition is + the Hyper Schema specification which is intended define elements in a + structure that can be interpreted as hyperlinks. Hyper Schema builds + on JSON Schema to describe the hyperlink structure of other JSON + documents. This allows user agents to be able to successfully + navigate JSON documents based on their schemas. + + Cumulatively JSON Schema acts as a meta-document that can be used to + define the required type and constraints on property values, as well + as define the meaning of the property values for the purpose of + describing a resource and determining hyperlinks within the + representation. + + An example JSON Schema that describes products might look like: + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 4] + +Internet-Draft JSON Schema Media Type December 2009 + + + { + "name":"Product", + "properties":{ + "id":{ + "type":"number", + "description":"Product identifier" + }, + "name":{ + "description":"Name of the product", + "type":"string" + }, + "price":{ + "type": "number", + "minimum":0 + }, + "tags":{ + "optional":true, + "type":"array", + "items":{ + "type":"string" + } + } + }, + "links":[ + { + "rel":"full", + "href":"{id}" + }, + { + "rel":"comments", + "href":"comments/?id={id}" + } + ] + } + + This schema defines the properties of the instance JSON documents and + their required properties (id, name, and price) as well as an + optional property (tags). This also defines the link relations of + the instance JSON documents. + +3.1. Terminology + + For this specification, a schema will be used to denote a JSON Schema + definition, and an instance refers to the JSON object or array that + the schema will be describing and validating + + + + + + +Zyp Expires June 8, 2010 [Page 5] + +Internet-Draft JSON Schema Media Type December 2009 + + +3.2. Design Considerations + + The JSON Schema media type does not attempt to dictate the structure + of JSON representations that contain data, but rather provides a + separate format for flexibly communicating how a JSON representation + should be interpreted and validated, such that user agents can + properly understand acceptable structures and extrapolate hyperlink + information with the JSON document. This specification does not + define a protocol. The underlying protocol (such as HTTP) should + sufficiently define the semantics of the client-server interface, the + retrieval of resource representations linked to by JSON + representations, and modification of those resources. The goal of + this format is to sufficiently describe JSON structures such that one + can utilize existing information available in existing JSON + representations from a large variety of services that leverage a REST + architecture using existing protocols. + +4. Schema/Instance Association + + JSON Schema instances are correlated to their schema by the + "describedby" relation, where the schema is defined to be the target + of the relation. Instance representations may be of the application/ + json media type or any other subtype. Consequently, dictating how an + instance representation should specify the relation to the schema is + beyond the normative scope of this document (since this document + specifically defines the JSON Schema media type, and no other), but + it is recommended that instances specify their schema so that user + agents can interpret the instance representation and messages may + retain the self-descriptive characteristic, avoiding the need for + out-of-band information about instance data. Two approaches are + recommended for declaring the relation to the schema that describes + the meaning of a JSON instance's (or collection of instances) + structure. A MIME type parameter named "describedby" or a Link + header with a relation of "describedby" SHOULD be used: + + + Content-Type: application/json; + describedby=http://json.com/my-hyper-schema + + or if the content is being transferred by a protocol (such as HTTP) + that provides headers, a Link header can be used: + + + Link: ; rel="describedby" + + Instances MAY specify multiple schemas, to indicate all the schemas + that are applicable to the data. The instance data may have multiple + schemas that it is defined by (the instance data should be valid for + + + +Zyp Expires June 8, 2010 [Page 6] + +Internet-Draft JSON Schema Media Type December 2009 + + + those schemas). Or if the document is a collection of instances, the + collection may contain instances from different schemas. When + collections contain heterogeneous instances, the pathStart attribute + MAY be specified in the schema to disambiguate which schema should be + applied for each item in the collection. + +4.1. Self-Descriptive Schema + + JSON Schemas are themselves instances for the schema schemas. A + self-describing JSON Schema for the core JSON Schema can be found at + http://json-schema.org/schema and the hyper schema self-description + can be found at: http://json-schema.org/hyper-schema. All schemas + used within a protocol with media type definitions SHOULD include a + MIME parameter that refers to the self-descriptive hyper schema or + another schema that extends this hyper schema: + + + Content-Type: application/json; + describedby=http://www.json-schema.org/hyper-schema + +5. Core Schema Definition + + A JSON Schema is a JSON Object that defines various attributes of the + instance and defines it's usage and valid values. A JSON Schema is a + JSON Object with schema attribute properties. The following is the + grammar of a JSON Schema: + + And an example JSON Schema definition could look like: + + + {"description":"A person", + "type":"object", + + "properties": + {"name": {"type":"string"}, + "age" : {"type":"integer", + "maximum":125}} + } + + A JSON Schema object may have any of the following properties, called + schema attributes (all attributes are optional): + +5.1. type + + Union type definition - An array with two or more items which + indicates a union of type definitions. Each item in the array may + be a simple type definition or a schema. The instance value is + valid if it is of the same type as one the type definitions in the + + + +Zyp Expires June 8, 2010 [Page 7] + +Internet-Draft JSON Schema Media Type December 2009 + + + array or if it is valid by one of the schemas in the array. For + example to indicate that a string or number is a valid: {"type": + ["string","number"]} + + Simple type definition - A string indicating a primitive or simple + type. The following are acceptable strings: + + string - Value must be a string. + + number - Value must be a number, floating point numbers are + allowed. + + integer - Value must be an integer, no floating point numbers + are allowed. This is a subset of the number type. + + boolean - Value must be a boolean. + + object - Value must be an object. + + array - Value must be an array. + + null - Value must be null. Note this is mainly for purpose of + being able use union types to define nullability. + + any - Value may be of any type including null. If the property + is not defined or is not in this list, than any type of value + is acceptable. Other type values may be used for custom + purposes, but minimal validators of the specification + implementation can allow any instance value on unknown type + values. + +5.2. properties + + This should be an object type definition, which is an object with + property definitions that correspond to instance object properties. + When the instance value is an object, the property values of the + instance object must conform to the property definitions in this + object. In this object, each property definition's value should be a + schema, and the property's name should be the name of the instance + property that it defines. + +5.3. items + + This should be a schema or an array of schemas. When this is an + object/schema and the instance value is an array, all the items in + the array must conform to this schema. When this is an array of + schemas and the instance value is an array, each position in the + instance array must conform to the schema in the corresponding + + + +Zyp Expires June 8, 2010 [Page 8] + +Internet-Draft JSON Schema Media Type December 2009 + + + position for this array. This called tuple typing. When tuple + typing is used, additional items are allowed, disallowed, or + constrained by the additionalProperties attribute using the same + rules as extra properties for objects.. + +5.4. optional + + This indicates that the instance property in the instance object is + optional. This is false by default. + +5.5. additionalProperties + + This provides a default property definition for all properties that + are not explicitly defined in an object type definition. The value + must be a schema. If false is provided, no additional properties are + allowed, and the schema can not be extended. The default value is an + empty schema which allows any value for additional properties. + +5.6. requires + + This indicates that if this property is present in the containing + instance object, the property given by requires attribute must also + be present in the containing instance object. The value of this + property may be a string, indicating the require property name. Or + the value may be a schema, in which case the containing instance must + be valid by the schema if the property is present. For example if a + object type definition is defined: + + + { + "state": + { + "optional":true + }, + "town": + { + "requires":"state", + "optional":true + } + } + + An instance must include a state property if a town property is + included. If a town property is not included, the state property is + optional. + + + + + + + +Zyp Expires June 8, 2010 [Page 9] + +Internet-Draft JSON Schema Media Type December 2009 + + +5.7. minimum + + This indicates the minimum value for the instance property when the + type of the instance value is a number. + +5.8. maximum + + This indicates the minimum value for the instance property when the + type of the instance value is a number. + +5.9. minimumCanEqual + + If the minimum is defined, this indicates whether or not the instance + property value can equal the minimum. + +5.10. maximumCanEqual + + If the maximum is defined, this indicates whether or not the instance + property value can equal the maximum. + +5.11. minItems + + This indicates the minimum number of values in an array when an array + is the instance value. + +5.12. maxItems + + This indicates the maximum number of values in an array when an array + is the instance value. + +5.13. pattern + + When the instance value is a string, this provides a regular + expression that a instance string value should match in order to be + valid. Regular expressions should follow the regular expression + specification from ECMA 262/Perl 5 + +5.14. maxLength + + When the instance value is a string, this indicates maximum length of + the string. + +5.15. minLength + + When the instance value is a string, this indicates minimum length of + the string. + + + + + +Zyp Expires June 8, 2010 [Page 10] + +Internet-Draft JSON Schema Media Type December 2009 + + +5.16. enum + + This provides an enumeration of possible values that are valid for + the instance property. This should be an array, and each item in the + array represents a possible value for the instance value. If "enum" + is included, the instance value must be one of the values in enum + array in order for the schema to be valid. + +5.17. title + + This provides a short description of the instance property. The + value must be a string. + +5.18. description + + This provides a full description of the of purpose the instance + property. The value must be a string. + +5.19. format + + This property indicates the type of data, content type, or + microformat to be expected in the instance property values. A format + attribute may be one of the values listed below, and if so, should + adhere to the semantics describing for the format. A format should + only be used give meaning to primitive types (string, integer, + number, or boolean). Validators are not required to validate that + the instance values conform to a format. The following formats are + defined: + + Any valid MIME media type may be used as a format value, in which + case the instance property value must be a string, representing + the contents of the MIME file. + + date-time - This should be a date in ISO 8601 format of YYYY-MM- + DDThh:mm:ssZ in UTC time. This is the recommended form of date/ + timestamp. + + date - This should be a date in the format of YYYY-MM-DD. It is + recommended that you use the "date-time" format instead of "date" + unless you need to transfer only the date part. + + time - This should be a time in the format of hh:mm:ss. It is + recommended that you use the "date-time" format instead of "time" + unless you need to transfer only the time part. + + utc-millisec - This should be the difference, measured in + milliseconds, between the specified time and midnight, January 1, + 1970 UTC. The value should be a number (integer or float). + + + +Zyp Expires June 8, 2010 [Page 11] + +Internet-Draft JSON Schema Media Type December 2009 + + + regex - A regular expression. + + color - This is a CSS color (like "#FF0000" or "red"). + + style - This is a CSS style definition (like "color: red; + background-color:#FFF"). + + phone - This should be a phone number (format may follow E.123). + + uri - This value should be a URI.. + + email - This should be an email address. + + ip-address - This should be an ip version 4 address. + + ipv6 - This should be an ip version 6 address. + + street-address - This should be a street address. + + locality - This should be a city or town. + + region - This should be a region (a state in the US, province in + Canada, etc.) + + postal-code - This should be a postal code (AKA zip code). + + country - This should be the name of a country. + + Additional custom formats may be defined with a URL to a + definition of the format. + +5.20. contentEncoding + + If the instance property value is a string, this indicates that the + string should be interpreted as binary data and decoded using the + encoding named by this schema property. RFC 2045, Sec 6.1 lists + possible values. + +5.21. default + + This indicates the default for the instance property. + +5.22. maxDecimal + + This indicates the maximum number of decimal places in a floating + point number. By default there is no maximum. + + + + + +Zyp Expires June 8, 2010 [Page 12] + +Internet-Draft JSON Schema Media Type December 2009 + + +5.23. disallow + + This attribute may take the same values as the "type" attribute, + however if the instance matches the type or if this value is an array + and the instance matches any type or schema in the array, than this + instance is not valid. + +5.24. extends + + The value of this property should be another schema which will + provide a base schema which the current schema will inherit from. + The inheritance rules are such that any instance that is valid + according to the current schema must be valid according to the + referenced schema. This may also be an array, in which case, the + instance must be valid for all the schemas in the array. + +6. Hyper Schema + + This section defines hypermedia definitions of JSON schema. The + following attributes are specified in addition to those attributes + that already provided by JSON schema with the specific purpose of + informing user agents of relations between resources based on JSON + data. Just as with JSON schema attributes, all the attributes in + hyper-schema are optional. Therefore an empty object is a valid + (non-informative) schema, and essentially describes plain JSON (no + constraints on the structures). Addition of attributes provides + additive information for user agents. + +6.1. links + + The value of the links property should be an array, where each item + in the array is a link description object which describes the link + relations of the instances. + +6.1.1. Link Description Object + + A link description object is used to describe the link relations of + instances of a schema. + +6.1.1.1. href + + The value of the "href" link description property indicates the + target URI of the related resource. The value of the instance + property should be resolved as a URI-Reference per [RFC3986] and may + be a relative URI. The base URI to be used for relative resolution + should be the URI used to retrieve the instance object (not the + schema). Also, the URI may be parametrized by the property values of + the instance object. + + + +Zyp Expires June 8, 2010 [Page 13] + +Internet-Draft JSON Schema Media Type December 2009 + + + Instance property values should be substituted into the URIs where + matching braces ('{', '}') are found surrounding zero or more + characters, creating an expanded URI. Instance property value + substitutions are resolved by using the text between the braces to + denote the property name from the instance to get the value to + substitute. For example, if an href value is defined: + + + http://somesite.com/{id} + + Then it would be resolved by replace the value of the "id" property + value from the instance object. If the value of the "id" property + was "45", the expanded URI would be: + + + http://somesite.com/45 + + If matching braces are found with the string "-this" (no quotes) + between the braces, than the actual instance value should be used to + replace the braces, rather than a property value. This should only + be used in situations where the instance is a scalar (string, + boolean, or number), and not for objects or arrays. + +6.1.1.2. rel + + The value of the "rel" property indicates the name of the relation to + the target resource. The relation to the target should be + interpreted as specifically from the instance object that the schema + (or sub-schema) applies to, not just the top level resource that + contains the object within its hierarchy. If a resource JSON + representation contains a sub object with a property interpreted as a + link, that sub-object holds the relation with the target. A relation + to target from the top level resource must be indicated with the + schema describing the top level JSON representation. + + Relationship definitions SHOULD NOT be media type dependent, and + users are encouraged to utilize existing accepted relation + definitions, including those in existing relation registries (see + &rfc4287). However, we define these relation here for clarity of + normative interpretation within the context of JSON hyper schema + defined relations: + + self - If the relation value is "self", when this property is + encountered in the instance object, the object represents a + resource and the instance object is treated as a full + representation of the target resource identified by the specified + URI. + + + + +Zyp Expires June 8, 2010 [Page 14] + +Internet-Draft JSON Schema Media Type December 2009 + + + full - This indicates that the target of the link is the full + representation for the instance object. The object that contains + this link may not be the full representation. + + describedby - This indicates the target of the link is the schema + for the instance object. This may be used to specifically denote + the schemas of objects within a JSON object hierarchy, + facilitating polymorphic type data structures. + + The following relations are applicable for schemas (the schema as + the "from" resource in the relation). + + instances - This indicates the target resource that represents + collection of instances of a schema. + + create - This indicates a target to use for creating new instances + of a schema. This link definition SHOULD be a submission link + with a non-safe method (like POST). + + For example, if a schema is defined: + + + { + "links": [ + { + "rel": "self" + "href": "{id}" + }, + { + "rel": "up" + "href": "{upId}" + }, + { + "rel": "children" + "href": "?upId={id}" + } + ] + } + + And if a collection of instance resource's JSON representation was + retrieved: + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 15] + +Internet-Draft JSON Schema Media Type December 2009 + + + GET /Resource/ + + [ + { + "id": "thing", + "upId": "parent" + }, + { + "id": "thing2", + "upId": "parent" + } + ] + + This would indicate that for the first item in the collection, it's + own (self) URI would resolve to "/Resource/thing" and the first + item's "up" relation should be resolved to the resource at + "/Resource/parent". The "children" collection would be located at + "/Resource/?upId=thing". + +6.1.1.3. Submission Link Properties + + The following properties also apply to link definition objects, and + provide functionality analogous to HTML forms, in providing a means + for submitting extra (often user supplied) information to send to a + server. + +6.1.1.3.1. method + + This indicates which method should be used to access the target + resource. In an HTTP environment, this would be "GET" or "POST" + (other HTTP methods such as "PUT" and "DELETE" have semantics that + are clearly implied by accessed resources, and do not need to be + defined here). This defaults to "GET". + +6.1.1.3.2. enctype + + If present, this property indicates a query media type format that + the server supports for querying or posting to the collection of + instances at the target resource. The query can be suffixed to the + target URI to query the collection with property-based constraints on + the resources that SHOULD be returned from the server or used to post + data to the resource (depending on the method). For example, with + the following schema: + + + + + + + + +Zyp Expires June 8, 2010 [Page 16] + +Internet-Draft JSON Schema Media Type December 2009 + + + { + "links":[ + { + "enctype": "application/x-www-form-urlencoded", + "method": "GET", + "href": "/Product/", + "properties":{ + "name":{"description":"name of the product"} + } + } + ] + } + + This indicates that the client can query the server for instances + that have a specific name: + + + /Product/?name=Slinky + + If no enctype or method is specified, only the single URI specified + by the href property is defined. If the method is POST, application/ + json is the default media type. + +6.1.1.3.3. properties + + This is inherited from the base JSON schema definition, and can + follow the same structure, but its meaning should be used to define + the acceptable property names and values for the action (whether it + be for the GET query or POST body). If properties are omitted, and + this form is the child of a schema, the properties from the parent + schema should be used as the basis for the form action. + +6.2. fragmentResolution + + This property indicates the fragment resolution protocol to use for + resolving fragment identifiers in URIs within the instance + representations. This applies to the instance object URIs and all + children of the instance object's URIs. The default fragment + resolution protocol is "dot-delimited", which is defined below. + Other fragment resolution protocols may be used, but are not defined + in this document. + + The fragment identifier is based on RFC 2396 Sec 5, and defines the + mechanism for resolving references to entities within a document. + + + + + + + +Zyp Expires June 8, 2010 [Page 17] + +Internet-Draft JSON Schema Media Type December 2009 + + +6.2.1. dot-delimited fragment resolution + + With the dot-delimited fragment resolution protocol, the fragment + identifier is interpreted as a series of property reference tokens + that are delimited by the "." character (\x2E). Each property + reference token is a series of any legal URI component characters + except the "." character. Each property reference token should be + interpreted, starting from the beginning of the fragment identifier, + as a path reference in the target JSON structure. The final target + value of the fragment can be determined by starting with the root of + the JSON structure from the representation of the resource identified + by the pre-fragment URI. If the target is a JSON object, than the + new target is the value of the property with the name identified by + the next property reference token in the fragment. If the target is + a JSON array, than the target is determined by finding the item in + array the array with the index defined by the next property reference + token (which MUST be a number). The target is successively updated + for each property reference token, until the entire fragment has been + traversed. + + Property names SHOULD be URI-encoded. In particular, any "." in a + property name MUST be encoded to avoid being interpreted as a + property delimiter. + + For example, for the following JSON representation: + + + { + "foo":{ + "anArray":[ + {"prop":44} + ], + "another prop":{ + "baz":"A string" + } + } + } + + The following fragment identifiers would be resolved: + + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 18] + +Internet-Draft JSON Schema Media Type December 2009 + + + fragment identifier resolution + ------------------- ---------- + # self, the root of the resource itself + #foo the object referred to by the foo property + #foo.another prop the object referred to by the "another prop" + property of the object referred to by the + "foo" property + #foo.another prop.baz the string referred to by the value of "baz" + property of the "another prop" property of + the object referred to by the "foo" property + #foo.anArray.0 the first object in the "anArray" array + +6.3. root + + This attribute indicates that the value of the instance property + value SHOULD be treated as the root or the body of the representation + for the purposes of user agent interaction and fragment resolution + (all other properties of the instance objects are can be regarded as + meta-data descriptions for the data). + +6.4. readonly + + This indicates that the instance property should not be changed. + Attempts by a user agent to modify the value of this property are + expected to be rejected by a server. + +6.5. pathStart + + This property value is a URI-Reference that indicates the URI that + all the URIs for the instances of the schema should start with. When + multiple schemas have been referenced for an instance, the user agent + can determine if this schema is applicable for a particular instance + by determining if URI of the instance begins with the pathStart's + referenced URI. pathStart MUST be resolved as per [RFC3986] section + 5. If the URI of the instance does not start with URI indicated by + pathStart, or if another schema specifies a starting URI that is + longer and also matches the instance, this schema should not be + applied to the instance. Any schema that does not have a pathStart + attribute should be considered applicable to all the instances for + which it is referenced. + +6.6. mediaType + + This indicates the media type of the instance representations that + this schema is defining. + + + + + + +Zyp Expires June 8, 2010 [Page 19] + +Internet-Draft JSON Schema Media Type December 2009 + + +6.7. alternate + + This is an array of JSON schema definitions that define any other + schemas for alternate JSON-based representations of the instance + resources. + +7. Security Considerations + + This specification is a sub-type of the JSON format, and consequently + the security considerations are generally the same as RFC 4627. + However, an additional issue is that when link relation of "self" is + used to denote a full representation of an object, the user agent + SHOULD NOT consider the representation to be the authoritative + representation of the resource denoted by the target URI if the + target URI is not equivalent to or a sub-path of the the URI used to + request the resource representation which contains the target URI + with the "self" link. For example, if a hyper schema was defined: + + + { + "links":[ + { + "rel":"self", + "href":"{id}" + } + ] + } + + And a resource was requested from somesite.com: + + + GET /foo/ + + With a response of: + + +Content-Type: application/json; describedby=/schema-for-this-data +[ + {"id":"bar", "name":"This representation can be safely treated \ + as authoritative "}, + {"id":"/baz", "name":"This representation should not be treated as \ + authoritative the user agent should make request the resource\ + from "/baz" to ensure it has the authoritative representation"}, + {"id":"http://othersite.com/something", "name":"This representation\ + should also not be treated as authoritative and the target\ + resource representation should be retrieved for the\ + authoritative representation"} +] + + + +Zyp Expires June 8, 2010 [Page 20] + +Internet-Draft JSON Schema Media Type December 2009 + + +8. IANA Considerations + + The proposed MIME media type for JSON Schema is application/ + schema+json + + Type name: application + + Subtype name: schema+json + + Required parameters: describedby + + The value of the describedby parameter should be a URI (relative or + absolute) that refers to the schema used to define the structure of + this structure (the meta-schema). Normally the value would be + http://json-schema.org/hyper-schema, but it is allowable to use other + schemas that extend the hyper schema's meta- schema. + + Optional parameters: pretty + + The value of the pretty parameter may be true or false to indicate if + additional whitespace has been included to make the JSON + representation easier to read. + +8.1. Registry of Link Relations + + This registry is maintained by IANA per RFC 4287 and this + specification adds three values: "full", "create", "instances". New + assignments are subject to IESG Approval, as outlined in [RFC5226]. + Requests should be made by email to IANA, which will then forward the + request to the IESG, requesting approval. + +9. References + +9.1. Normative References + + [RFC3986] Berners-Lee, T., Fielding, R., and + L. Masinter, "Uniform Resource + Identifier (URI): Generic Syntax", + STD 66, RFC 3986, January 2005. + + [RFC2119] Bradner, S., "Key words for use in + RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, + March 1997. + + [RFC4287] Nottingham, M., Ed. and R. Sayre, + Ed., "The Atom Syndication + Format", RFC 4287, December 2005. + + + +Zyp Expires June 8, 2010 [Page 21] + +Internet-Draft JSON Schema Media Type December 2009 + + + [RFC3339] Klyne, G., Ed. and C. Newman, + "Date and Time on the Internet: + Timestamps", RFC 3339, July 2002. + + [RFC2045] Freed, N. and N. Borenstein, + "Multipurpose Internet Mail + Extensions (MIME) Part One: Format + of Internet Message Bodies", + RFC 2045, November 1996. + +9.2. Informative References + + [RFC4627] Crockford, D., "The application/ + json Media Type for JavaScript + Object Notation (JSON)", RFC 4627, + July 2006. + + [RFC2616] Fielding, R., Gettys, J., Mogul, + J., Frystyk, H., Masinter, L., + Leach, P., and T. Berners-Lee, + "Hypertext Transfer Protocol -- + HTTP/1.1", RFC 2616, June 1999. + + [RFC5226] Narten, T. and H. Alvestrand, + "Guidelines for Writing an IANA + Considerations Section in RFCs", + BCP 26, RFC 5226, May 2008. + + [I-D.hammer-discovery] Hammer-Lahav, E., "Link-based + Resource Descriptor Discovery", + draft-hammer-discovery-03 (work in + progress), March 2009. + + [I-D.gregorio-uritemplate] Gregorio, J., "URI Template", + draft-gregorio-uritemplate-03 + (work in progress), April 2008. + + [I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", dra + ft-nottingham-http-link-header-06 + (work in progress), July 2009. + + [W3C.REC-html401-19991224] Hors, A., Jacobs, I., and D. + Raggett, "HTML 4.01 + Specification", World Wide Web + Consortium Recommendation REC- + html401-19991224, December 1999, < + http://www.w3.org/TR/1999/ + REC-html401-19991224>. + + + +Zyp Expires June 8, 2010 [Page 22] + +Internet-Draft JSON Schema Media Type December 2009 + + +Appendix A. Change Log + + -01 + + o Fixed category and updates from template + + -00 + + o Initial draft + +Appendix B. Open Issues + + Should we give a preference to MIME headers over Link headers (or + only use one)? + + Should we use "profile" as the media type parameter instead? + + Should "root" be a MIME parameter instead of a schema attribute? + + Should "format" be renamed to "mediaType" or "contentType" to reflect + the usage MIME media types that are allowed. + + I still do not like how dates are handled. + +Author's Address + + Kris Zyp (editor) + SitePen (USA) + 530 Lytton Avenue + Palo Alto, CA 94301 + USA + + Phone: +1 650 968 8787 + EMail: kris@sitepen.com + + + + + + + + + + + + + + + + + +Zyp Expires June 8, 2010 [Page 23] + + diff --git a/draft-zyp-json-schema-01.xml b/draft-zyp-json-schema-01.xml new file mode 100644 index 0000000..215d927 --- /dev/null +++ b/draft-zyp-json-schema-01.xml @@ -0,0 +1,897 @@ + + + + + + + + + + + + + +]> + + + + + + + + + + + + A JSON Media Type for Describing the Structure and Meaning of JSON Documents + + + + SitePen (USA) + +
+ + 530 Lytton Avenue + + Palo Alto, CA 94301 + + USA + + + +1 650 968 8787 + + kris@sitepen.com +
+ + + + + Internet Engineering Task Force + + JSON + + Schema + + Hyper Schema + + Hypermedia + + + + + JSON (JavaScript Object Notation) Schema defines the media type application/schema+json, + a JSON based format for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. + + + + + + +
+ JSON (JavaScript Object Notation) Schema is a JSON media type for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. +
+ + +
+ The key words "MUST", "MUST + NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", + "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be + interpreted as described in RFC 2119. +
+ + + +
+ JSON Schema defines the media type application/schema+json for + describing the structure of other + JSON documents. JSON Schema is JSON-based and includes facilities + for describing the structure of JSON documents in terms of + allowable values, descriptions, and interpreting relations with other resources. + + JSON Schema format is organized into several separate definitions. The first + definition is the core schema specification. This definition is primary + concerned with describing a JSON structure and specifying valid elements + in the structure. The second definition is the Hyper Schema specification + which is intended define elements in a structure that can be interpreted as + hyperlinks. + Hyper Schema builds on JSON Schema to describe the hyperlink structure of + other JSON documents. This allows user agents to be able to successfully navigate + JSON documents based on their schemas. + + + Cumulatively JSON Schema acts as a meta-document that can be used to define the required type and constraints on + property values, as well as define the meaning of the property values + for the purpose of describing a resource and determining hyperlinks + within the representation. + + + An example JSON Schema that describes products might look like: +
+ +
+This schema defines the properties of the instance JSON documents and +their required properties (id, name, and price) as well as an optional +property (tags). This also defines the link relations of the instance +JSON documents. + +
+ For this specification, a schema will be used to denote a JSON Schema + definition, and an instance refers to the JSON object or array that the schema + will be describing and validating + +
+
+ + The JSON Schema media type does not attempt to dictate the structure of JSON + representations that contain data, but rather provides a separate format + for flexibly communicating how a JSON representation should be + interpreted and validated, such that user agents can properly understand + acceptable structures and extrapolate hyperlink information + with the JSON document. This specification does not define a protocol. + The underlying protocol (such as HTTP) should sufficiently define the + semantics of the client-server interface, the retrieval of resource + representations linked to by JSON representations, and modification of + those resources. The goal of this + format is to sufficiently describe JSON structures such that one can + utilize existing information available in existing JSON + representations from a large variety of services that leverage a REST + architecture using existing protocols. + +
+
+ +
+ + JSON Schema instances are correlated to their schema by the "describedby" + relation, where the schema is defined to be the target of the relation. + Instance representations may be of the application/json media type or + any other subtype. Consequently, dictating how an instance + representation should specify the relation to the schema is beyond the normative scope + of this document (since this document specifically defines the JSON + Schema media type, and no other), but it is recommended that instances + specify their schema so that user agents can interpret the instance + representation and messages may retain the self-descriptive + characteristic, avoiding the need for out-of-band information about + instance data. Two approaches are recommended for declaring the + relation to the schema that describes the meaning of a JSON instance's (or collection + of instances) structure. A MIME type parameter named + "describedby" or a Link header with a relation of "describedby" SHOULD be used: +
+ +
+ or if the content is being transferred by a protocol (such as HTTP) that + provides headers, a Link header can be used: +
+ + ; rel="describedby" +]]>
+ Instances MAY specify multiple schemas, to indicate all the schemas that + are applicable to the data. The instance data may have multiple schemas + that it is defined by (the instance data should be valid for those schemas). + Or if the document is a collection of instances, the collection may contain + instances from different schemas. When collections contain heterogeneous + instances, the pathStart attribute MAY be specified in the + schema to disambiguate which schema should be applied for each item in the +collection. + +
+ + JSON Schemas are themselves instances for the schema + schemas. A self-describing JSON Schema for the core JSON Schema can + be found at http://json-schema.org/schema and the hyper schema + self-description can be found at: http://json-schema.org/hyper-schema. All schemas + used within a protocol with media type definitions + SHOULD include a MIME parameter that refers to the self-descriptive + hyper schema or another schema that extends this hyper schema: +
+ +
+ +
+
+ +
+ A JSON Schema is a JSON Object that defines various attributes + of the instance and defines it's usage and valid values. A JSON + Schema is a JSON Object with schema attribute properties. + The following is the grammar of a JSON Schema: + + + + And an example JSON Schema definition could look like: +
+ + +
+ + A JSON Schema object may have any of the following properties, called schema + attributes (all attributes are optional): + + +
+ +Union type definition - An array with two or more items which indicates a union of type definitions. Each item in the array may be a simple type definition or a schema. The instance value is valid if it is of the same type as one the type definitions in the array or if it is valid by one of the schemas in the array. For example to indicate that a string or number is a valid: +{"type":["string","number"]} +Simple type definition - A string indicating a primitive or simple type. The following are acceptable strings: + + + +string - Value must be a string. + +number - Value must be a number, floating point numbers are allowed. +integer - Value must be an integer, no floating point numbers are allowed. This is a subset of the number type. +boolean - Value must be a boolean. +object - Value must be an object. +array - Value must be an array. + +null - Value must be null. Note this is mainly for purpose of being able use union types to define nullability. +any - Value may be of any type including null. +If the property is not defined or is not in this list, than any type of value is acceptable. Other type values may be used for custom purposes, but minimal validators of the specification implementation can allow any instance value on unknown type values. + + + + +
+
+This should be an object type definition, which is an object with property definitions that correspond to instance object properties. When the instance value is an object, the property values of the instance object must conform to the property definitions in this object. In this object, each property definition's value should be a schema, and the property's name should be the name of the instance property that it defines. +
+
+This should be a schema or an array of schemas. When this is an object/schema and the instance value is an array, all the items in the array must conform to this schema. When this is an array of schemas and the instance value is an array, each position in the instance array must conform to the schema in the corresponding position for this array. This called tuple typing. When tuple typing is used, additional items are allowed, disallowed, or constrained by the additionalProperties attribute using the same rules as extra properties for objects.. +
+
+This indicates that the instance property in the instance object is optional. This is false by default. +
+
+This provides a default property definition for all properties that are not explicitly defined in an object type definition. The value must be a schema. If false is provided, no additional properties are allowed, and the schema can not be extended. The default value is an empty schema which allows any value for additional properties. +
+
+This indicates that if this property is present in the containing instance object, the property given by requires attribute must also be present in the containing instance object. The value +of this property may be a string, indicating the require property name. Or the value may be a schema, in which case the containing instance must be valid by the schema if the property is present. For example if a object type definition is defined: +
+ + +
+An instance must include a state property if a town property is included. If a town property is not included, the state property is optional. +
+
+This indicates the minimum value for the instance property when the type of the instance value is a number. +
+
+This indicates the minimum value for the instance property when the type of the instance value is a number. +
+
+If the minimum is defined, this indicates whether or not the instance property value can equal the minimum. +
+
+If the maximum is defined, this indicates whether or not the instance property value can equal the maximum. +
+
+This indicates the minimum number of values in an array when an array is the instance value. +
+
+This indicates the maximum number of values in an array when an array is the instance value. +
+
+When the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid. Regular expressions should follow the regular expression specification from ECMA 262/Perl 5
+
+When the instance value is a string, this indicates maximum length of the string. +
+
+When the instance value is a string, this indicates minimum length of the string. +
+
+This provides an enumeration of possible values that are valid for the instance property. This should be an array, and each item in the array represents a possible value for the instance value. If "enum" is included, the instance value must be one of the values in enum array in order for the schema to be valid. +
+
+This provides a short description of the instance property. The value must be a string. +
+
+This provides a full description of the of purpose the instance property. The value must be a string. +
+
This property indicates the type of data, content type, or microformat to be expected in the instance property values. A format attribute may be one of the values listed below, and if so, should adhere to the semantics describing for the format. A format should only be used give meaning to primitive types (string, integer, number, or boolean). Validators are not required to validate that the instance values conform to a format. The following formats are defined: + +Any valid MIME media type may be used as a format value, in which case the instance property value must be a string, representing the contents of the MIME file. +date-time - This should be a date in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. This is the recommended form of date/timestamp. +date - This should be a date in the format of YYYY-MM-DD. It is recommended that you use the "date-time" format instead of "date" unless you need to transfer only the date part. +time - This should be a time in the format of hh:mm:ss. It is recommended that you use the "date-time" format instead of "time" unless you need to transfer only the time part. +utc-millisec - This should be the difference, measured in milliseconds, between the specified time and midnight, January 1, 1970 UTC. The value should be a number (integer or float). +regex - A regular expression. +color - This is a CSS color (like "#FF0000" or "red"). +style - This is a CSS style definition (like "color: red; background-color:#FFF"). +phone - This should be a phone number (format may follow E.123). +uri - This value should be a URI.. +email - This should be an email address. +ip-address - This should be an ip version 4 address. +ipv6 - This should be an ip version 6 address. +street-address - This should be a street address. +locality - This should be a city or town. +region - This should be a region (a state in the US, province in Canada, etc.) +postal-code - This should be a postal code (AKA zip code). +country - This should be the name of a country. +Additional custom formats may be defined with a URL to a definition of the format. + +
+
+If the instance property value is a string, this indicates that the string should be interpreted as binary data and decoded using the encoding named by this schema property. RFC 2045, Sec 6.1 lists possible values. + +
+
+This indicates the default for the instance property. +
+
+This indicates the maximum number of decimal places in a floating point number. By default there is no maximum. +
+
+This attribute may take the same values as the "type" attribute, however if the instance matches the type or if this value is an array and the instance matches any type or schema in the array, than this instance is not valid. +
+
+The value of this property should be another schema which will provide a base schema which the current schema will inherit from. The inheritance rules are such that any instance that is valid according to the current schema must be valid according to the referenced schema. This may also be an array, in which case, the instance must be valid for all the schemas in the array. +
+
+
+ This section defines hypermedia definitions of JSON schema. + The following attributes are specified in addition to those +attributes that already provided by JSON schema with the specific +purpose of informing user agents of relations between resources based +on JSON data. Just as with JSON +schema attributes, all the attributes in hyper-schema are optional. +Therefore an empty object is a valid (non-informative) schema, and +essentially describes plain JSON (no constraints on the structures). +Addition of attributes provides additive information for user agents. +
+ +The value of the links property should be an array, where each item +in the array is a link description object which describes the link +relations of the instances. + +
+ +A link description object is used to describe the link relations +of instances of a schema. + +
+ + The value of the "href" link description property +indicates the target URI of the related resource. The value +of the instance property should be resolved as a URI-Reference per [RFC3986] +and may be a relative URI. The base URI to be used for relative resolution +should be the URI used to retrieve the instance object (not the schema). +Also, the URI may be parametrized by the property values of the instance +object. + + +Instance property values should be substituted into the URIs where +matching braces ('{', '}') are found surrounding zero or more characters, +creating an expanded URI. Instance property value substitutions are resolved +by using the text between the braces to denote the property name +from the instance to get the value to substitute. For example, +if an href value is defined: +
+ + +
+Then it would be resolved by replace the value of the "id" property value from +the instance object. If the value of the "id" property was "45", the expanded +URI would be: +
+ + +
+If matching braces are found with the string "-this" (no quotes) between the braces, than the +actual instance value should be used to replace the braces, rather than a property value. +This should only be used in situations where the instance is a scalar (string, +boolean, or number), and not for objects or arrays. + +
+
+ +The value of the "rel" property indicates the name of the +relation to the target resource. The relation to the target should be interpreted as specifically from the instance object that the schema (or sub-schema) applies to, not just the top level resource that contains the object within its hierarchy. If a resource JSON representation contains a sub object with a property interpreted as a link, that sub-object holds the relation with the target. A relation to target from the top level resource must be indicated with the schema describing the top level JSON representation. + + +Relationship definitions SHOULD NOT be media type dependent, and users are encouraged to utilize existing accepted relation definitions, including those in existing relation registries (see &rfc4287). However, we define these relation here for clarity of normative interpretation within the context of JSON hyper schema defined relations: + + +self - If the relation value is "self", when this property is encountered in +the instance object, the object represents a resource and the instance object is +treated as a full representation of the target resource identified by +the specified URI. + + +full - This indicates that the target of the link is the full representation for the instance object. The object that contains this link may not be the full representation. + + +describedby - This indicates the target of the link is the schema for the instance object. This may be used to specifically denote the schemas of objects within a JSON object hierarchy, facilitating polymorphic type data structures. + + +The following relations are applicable for schemas (the schema as the "from" resource in the relation). + + +instances - This indicates the target resource that represents collection of instances of a schema. + + +create - This indicates a target to use for creating new instances of a schema. This link definition SHOULD be a submission link with a non-safe method (like POST). + + +For example, if a schema is defined: +
+ + +
+And if a collection of instance resource's JSON representation was +retrieved: +
+ + +
+ +This would indicate that for the first item in the collection, it's own +(self) URI would resolve to "/Resource/thing" and the first item's "up" +relation should be resolved to the resource at "/Resource/parent". +The "children" collection would be located at "/Resource/?upId=thing". + +
+
+ +The following properties also apply to link definition objects, and +provide functionality analogous to HTML forms, in providing a +means for submitting extra (often user supplied) information to send to a server. + +
+ + +This indicates which method should be used to access the target resource. +In an HTTP environment, this would be "GET" or "POST" (other HTTP methods +such as "PUT" and "DELETE" have semantics that are clearly implied by +accessed resources, and do not need to be defined here). +This defaults to "GET". + +
+ +
+ +If present, this property indicates a query media type format that the server +supports for querying or posting to the collection of instances at the target +resource. The query can be +suffixed to the target URI to query the collection with +property-based constraints on the resources that SHOULD be returned from +the server or used to post data to the resource (depending on the method). +For example, with the following schema: +
+ + +
+This indicates that the client can query the server for instances that +have a specific name: +
+ + +
+ +If no enctype or method is specified, only the single URI specified by +the href property is defined. If the method is POST, application/json is +the default media type. + +
+
+ +This is inherited from the base JSON schema definition, and can follow the +same structure, but its meaning should be used to define the acceptable +property names and values for the action (whether it be for the GET query +or POST body). If properties are omitted, and this form is the child of a +schema, the properties from the parent schema should be used as the basis +for the form action. + +
+
+
+
+
+ This property indicates the fragment resolution protocol to use for +resolving fragment identifiers in URIs within the instance +representations. This applies to the instance object URIs and all +children of the instance object's URIs. The default fragment resolution +protocol is "dot-delimited", which is defined below. Other fragment +resolution protocols may be used, but are not defined in this +document. + + + +The fragment identifier is based on RFC 2396 Sec 5, and defines the +mechanism for resolving references to entities within a document. + +
+With the dot-delimited fragment resolution protocol, the fragment +identifier is interpreted as a series of property reference tokens that +are delimited by the "." character (\x2E). Each property reference token +is a series of any legal URI component characters except the "." character. Each property +reference token should be interpreted, starting from the beginning of +the fragment identifier, as a path reference in the target JSON +structure. The final target value of the fragment can be determined by +starting with the root of the JSON structure from the representation of +the resource identified by the pre-fragment URI. If the target is a JSON +object, than the new target is the value of the property with the name +identified by the next property reference token in the fragment. If the +target is a JSON array, than the target is determined by finding the +item in array the array with the index defined by the next property +reference token (which MUST be a number). The target is successively +updated for each property reference token, until the entire fragment has +been traversed. + + +Property names SHOULD be URI-encoded. In particular, any "." in a +property name MUST be encoded to avoid being interpreted as a property +delimiter. + + +For example, for the following JSON representation: +
+ + +
+The following fragment identifiers would be resolved: +
+ + +
+ +
+ + +
+ +
+ This attribute indicates that the value of the instance property value +SHOULD be treated as the root or the body of the representation for the +purposes of user agent interaction and fragment resolution (all other +properties of the instance objects are can be regarded as meta-data +descriptions for the data). + + + +
+
+This indicates that the instance property should not be changed. Attempts by a user agent to modify the value of this property are expected to be rejected by a server. +
+ +
+ This property value is a URI-Reference that indicates the URI that all +the URIs for the instances of the schema should start with. When +multiple schemas have been referenced for an instance, the user agent +can determine if this schema is applicable for a particular instance by +determining if URI of the instance begins with the pathStart's referenced +URI. pathStart MUST be resolved as per [RFC3986] section 5. If the URI of +the instance does not start with URI indicated by pathStart, or if another +schema specifies a starting URI that is longer and also matches the +instance, this schema should not be applied to the instance. Any schema +that does not have a pathStart attribute should be considered applicable +to all the instances for which it is referenced. + + + + + +
+
+ This indicates the media type of the instance representations that this schema is defining. + + +
+ +
+ This is an array of JSON schema definitions that define any + other schemas for alternate JSON-based representations + of the instance resources. + + +
+ + +
+ +
+ +This specification is a sub-type of the JSON format, and +consequently the security considerations are generally the same as RFC +4627. However, an additional issue is that when link relation of "self" +is used to denote a full representation of an object, the user agent +SHOULD NOT consider the representation to be the authoritative representation +of the resource denoted by the target URI if the target URI is not +equivalent to or a sub-path of the the URI used to request the resource +representation which contains the target URI with the "self" link. +For example, if a hyper schema was defined: +
+ + +
+And a resource was requested from somesite.com: +
+ + +
+ +With a response of: +
+ + +
+ +
+
+ + The proposed MIME media type for JSON Schema is application/schema+json + + + Type name: application + + + Subtype name: schema+json + + + Required parameters: describedby + + + The value of the describedby parameter should be a URI (relative or absolute) that + refers to the schema used to define the structure of this structure (the + meta-schema). Normally the value would be http://json-schema.org/hyper-schema, + but it is allowable to use other schemas that extend the hyper schema's meta- + schema. + + + Optional parameters: pretty + + + The value of the pretty parameter may be true or false to indicate if additional + whitespace has been included to make the JSON representation easier to read. + + +
+ +This registry is maintained by IANA per RFC 4287 and this specification adds +three values: "full", "create", "instances". New + assignments are subject to IESG Approval, as outlined in [RFC5226]. + Requests should be made by email to IANA, which will then forward the + request to the IESG, requesting approval. + + +
+ +
+ + + + + + + + &rfc3986; + &rfc2119; + &rfc4287; + &rfc3339; + &rfc2045; + + + + &rfc4627; + &rfc2616; + &rfc5226; + &iddiscovery; + &uritemplate; + &linkheader; + &html401; + + + + +
+ -01 + + + Fixed category and updates from template + + + -00 + + + Initial draft + + + +
+ +
+ Should we give a preference to MIME headers over Link headers (or only use one)? + Should we use "profile" as the media type parameter instead? + Should "root" be a MIME parameter instead of a schema attribute? + Should "format" be renamed to "mediaType" or "contentType" to reflect the usage MIME media types that are allowed. + I still do not like how dates are handled. + +
+ + + + diff --git a/draft-zyp-json-schema-02.txt b/draft-zyp-json-schema-02.txt new file mode 100644 index 0000000..5e72fee --- /dev/null +++ b/draft-zyp-json-schema-02.txt @@ -0,0 +1,1345 @@ + + + +Internet Engineering Task Force K. Zyp, Ed. +Internet-Draft SitePen (USA) +Intended status: Informational March 23, 2010 +Expires: September 24, 2010 + + + A JSON Media Type for Describing the Structure and Meaning of JSON + Documents + draft-zyp-json-schema-02 + +Abstract + + JSON (JavaScript Object Notation) Schema defines the media type + application/schema+json, a JSON based format for defining the + structure of JSON data. JSON Schema provides a contract for what + JSON data is required for a given application and how to interact + with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +Status of This Memo + + This Internet-Draft is submitted to IETF in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on September 24, 2010. + +Copyright Notice + + Copyright (c) 2010 IETF Trust and the persons identified as the + document authors. All rights reserved. + + + + +Zyp Expires September 24, 2010 [Page 1] + +Internet-Draft JSON Schema Media Type March 2010 + + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Design Considerations . . . . . . . . . . . . . . . . . . 6 + 4. Schema/Instance Association . . . . . . . . . . . . . . . . . 6 + 4.1. Self-Descriptive Schema . . . . . . . . . . . . . . . . . 7 + 5. Core Schema Definition . . . . . . . . . . . . . . . . . . . . 7 + 5.1. type . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.2. properties . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.3. items . . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.4. optional . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.5. additionalProperties . . . . . . . . . . . . . . . . . . . 9 + 5.6. requires . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.7. minimum . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.8. maximum . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.9. minimumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 + 5.10. maximumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 + 5.11. minItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.12. maxItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.13. uniqueItems . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.14. pattern . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.15. maxLength . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.16. minLength . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.17. enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.18. title . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.19. description . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.20. format . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.21. contentEncoding . . . . . . . . . . . . . . . . . . . . . 12 + 5.22. default . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.23. divisibleBy . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.24. disallow . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.25. extends . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6. Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6.1. links . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6.1.1. Link Description Object . . . . . . . . . . . . . . . 14 + + + +Zyp Expires September 24, 2010 [Page 2] + +Internet-Draft JSON Schema Media Type March 2010 + + + 6.2. fragmentResolution . . . . . . . . . . . . . . . . . . . . 18 + 6.2.1. dot-delimited fragment resolution . . . . . . . . . . 18 + 6.2.2. slash-delimited fragment resolution . . . . . . . . . 19 + 6.3. root . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.4. readonly . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.5. pathStart . . . . . . . . . . . . . . . . . . . . . . . . 20 + 6.6. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 20 + 6.7. alternate . . . . . . . . . . . . . . . . . . . . . . . . 20 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 + 8.1. Registry of Link Relations . . . . . . . . . . . . . . . . 21 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 22 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23 + Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 24 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zyp Expires September 24, 2010 [Page 3] + +Internet-Draft JSON Schema Media Type March 2010 + + +1. Introduction + + JSON (JavaScript Object Notation) Schema is a JSON media type for + defining the structure of JSON data. JSON Schema provides a contract + for what JSON data is required for a given application and how to + interact with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +2. Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119. + +3. Overview + + JSON Schema defines the media type application/schema+json for + describing the structure of other JSON documents. JSON Schema is + JSON-based and includes facilities for describing the structure of + JSON documents in terms of allowable values, descriptions, and + interpreting relations with other resources. + + JSON Schema format is organized into several separate definitions. + The first definition is the core schema specification. This + definition is primary concerned with describing a JSON structure and + specifying valid elements in the structure. The second definition is + the Hyper Schema specification which is intended define elements in a + structure that can be interpreted as hyperlinks. Hyper Schema builds + on JSON Schema to describe the hyperlink structure of other JSON + documents. This allows user agents to be able to successfully + navigate JSON documents based on their schemas. + + Cumulatively JSON Schema acts as a meta-document that can be used to + define the required type and constraints on property values, as well + as define the meaning of the property values for the purpose of + describing a resource and determining hyperlinks within the + representation. + + An example JSON Schema that describes products might look like: + + + + + + + + + + + +Zyp Expires September 24, 2010 [Page 4] + +Internet-Draft JSON Schema Media Type March 2010 + + + { + "name":"Product", + "properties":{ + "id":{ + "type":"number", + "description":"Product identifier" + }, + "name":{ + "description":"Name of the product", + "type":"string" + }, + "price":{ + "type": "number", + "minimum":0 + }, + "tags":{ + "optional":true, + "type":"array", + "items":{ + "type":"string" + } + } + }, + "links":[ + { + "rel":"full", + "href":"{id}" + }, + { + "rel":"comments", + "href":"comments/?id={id}" + } + ] + } + + This schema defines the properties of the instance JSON documents and + their required properties (id, name, and price) as well as an + optional property (tags). This also defines the link relations of + the instance JSON documents. + +3.1. Terminology + + For this specification, a schema will be used to denote a JSON Schema + definition, and an instance refers to the JSON object or array that + the schema will be describing and validating + + + + + + +Zyp Expires September 24, 2010 [Page 5] + +Internet-Draft JSON Schema Media Type March 2010 + + +3.2. Design Considerations + + The JSON Schema media type does not attempt to dictate the structure + of JSON representations that contain data, but rather provides a + separate format for flexibly communicating how a JSON representation + should be interpreted and validated, such that user agents can + properly understand acceptable structures and extrapolate hyperlink + information with the JSON document. It is acknowledged that JSON + documents come in a variety of structures, and JSON is unique in that + the structure of stored data structures often prescribes a non- + ambiguous definite JSON representation. Attempting to force a + specific structure is generally not viable, and therefore JSON Schema + allows for great flexibility in the structure of JSON data that it + describes. + + This specification is protocol agnostic. The underlying protocol + (such as HTTP) should sufficiently define the semantics of the + client-server interface, the retrieval of resource representations + linked to by JSON representations, and modification of those + resources. The goal of this format is to sufficiently describe JSON + structures such that one can utilize existing information available + in existing JSON representations from a large variety of services + that leverage a representational state transfer architecture using + existing protocols. + +4. Schema/Instance Association + + JSON Schema instances are correlated to their schema by the + "describedby" relation, where the schema is defined to be the target + of the relation. Instance representations may be of the application/ + json media type or any other subtype. Consequently, dictating how an + instance representation should specify the relation to the schema is + beyond the normative scope of this document (since this document + specifically defines the JSON Schema media type, and no other), but + it is recommended that instances specify their schema so that user + agents can interpret the instance representation and messages may + retain the self-descriptive characteristic, avoiding the need for + out-of-band information about instance data. Two approaches are + recommended for declaring the relation to the schema that describes + the meaning of a JSON instance's (or collection of instances) + structure. A MIME type parameter named "profile" or a Link header + with a relation of "describedby" SHOULD be used: + + + Content-Type: application/json; + profile=http://json.com/my-hyper-schema + + or if the content is being transferred by a protocol (such as HTTP) + + + +Zyp Expires September 24, 2010 [Page 6] + +Internet-Draft JSON Schema Media Type March 2010 + + + that provides headers, a Link header can be used: + + + Link: ; rel="describedby" + + Instances MAY specify multiple schemas, to indicate all the schemas + that are applicable to the data. The instance data may have multiple + schemas that it is defined by (the instance data should be valid for + those schemas). Or if the document is a collection of instances, the + collection may contain instances from different schemas. When + collections contain heterogeneous instances, the pathStart attribute + MAY be specified in the schema to disambiguate which schema should be + applied for each item in the collection. + +4.1. Self-Descriptive Schema + + JSON Schemas are themselves instances for the schema schemas. A + self-describing JSON Schema for the core JSON Schema can be found at + http://json-schema.org/schema and the hyper schema self-description + can be found at: http://json-schema.org/hyper-schema. All schemas + used within a protocol with media type definitions SHOULD include a + MIME parameter that refers to the self-descriptive hyper schema or + another schema that extends this hyper schema: + + + Content-Type: application/json; + profile=http://www.json-schema.org/hyper-schema + +5. Core Schema Definition + + A JSON Schema is a JSON Object that defines various attributes of the + instance and defines it's usage and valid values. A JSON Schema is a + JSON Object with schema attribute properties. The following is the + grammar of a JSON Schema: + + And an example JSON Schema definition could look like: + + + {"description":"A person", + "type":"object", + + "properties": + {"name": {"type":"string"}, + "age" : {"type":"integer", + "maximum":125}} + } + + A JSON Schema object may have any of the following properties, called + + + +Zyp Expires September 24, 2010 [Page 7] + +Internet-Draft JSON Schema Media Type March 2010 + + + schema attributes (all attributes are optional): + +5.1. type + + Union type definition - An array with two or more items which + indicates a union of type definitions. Each item in the array may + be a simple type definition or a schema. The instance value is + valid if it is of the same type as one the type definitions in the + array or if it is valid by one of the schemas in the array. For + example to indicate that a string or number is a valid: {"type": + ["string","number"]} + + Simple type definition - A string indicating a primitive or simple + type. The following are acceptable strings: + + string - Value must be a string. + + number - Value must be a number, floating point numbers are + allowed. + + integer - Value must be an integer, no floating point numbers + are allowed. This is a subset of the number type. + + boolean - Value must be a boolean. + + object - Value must be an object. + + array - Value must be an array. + + null - Value must be null. Note this is mainly for purpose of + being able use union types to define nullability. + + any - Value may be of any type including null. If the property + is not defined or is not in this list, than any type of value + is acceptable. Other type values may be used for custom + purposes, but minimal validators of the specification + implementation can allow any instance value on unknown type + values. + +5.2. properties + + This should be an object type definition, which is an object with + property definitions that correspond to instance object properties. + When the instance value is an object, the property values of the + instance object must conform to the property definitions in this + object. In this object, each property definition's value should be a + schema, and the property's name should be the name of the instance + property that it defines. + + + +Zyp Expires September 24, 2010 [Page 8] + +Internet-Draft JSON Schema Media Type March 2010 + + +5.3. items + + This should be a schema or an array of schemas. When this is an + object/schema and the instance value is an array, all the items in + the array must conform to this schema. When this is an array of + schemas and the instance value is an array, each position in the + instance array must conform to the schema in the corresponding + position for this array. This called tuple typing. When tuple + typing is used, additional items are allowed, disallowed, or + constrained by the additionalProperties attribute using the same + rules as extra properties for objects. The default value is an empty + schema which allows any value for items in the instance array. + +5.4. optional + + This indicates that the instance property in the instance object is + optional. This is false by default. + +5.5. additionalProperties + + This provides a default property definition for all properties that + are not explicitly defined in an object type definition. The value + must be a schema. If false is provided, no additional properties are + allowed, and the schema can not be extended. The default value is an + empty schema which allows any value for additional properties. + +5.6. requires + + This indicates that if this property is present in the containing + instance object, the property given by requires attribute must also + be present in the containing instance object. The value of this + property may be a string, indicating the require property name. Or + the value may be a schema, in which case the containing instance must + be valid by the schema if the property is present. For example if a + object type definition is defined: + + + { + "state": + { + "optional":true + }, + "town": + { + "requires":"state", + "optional":true + } + } + + + +Zyp Expires September 24, 2010 [Page 9] + +Internet-Draft JSON Schema Media Type March 2010 + + + An instance must include a state property if a town property is + included. If a town property is not included, the state property is + optional. + +5.7. minimum + + This indicates the minimum value for the instance property when the + type of the instance value is a number. + +5.8. maximum + + This indicates the minimum value for the instance property when the + type of the instance value is a number. + +5.9. minimumCanEqual + + If the minimum is defined, this indicates whether or not the instance + property value can equal the minimum. + +5.10. maximumCanEqual + + If the maximum is defined, this indicates whether or not the instance + property value can equal the maximum. + +5.11. minItems + + This indicates the minimum number of values in an array when an array + is the instance value. + +5.12. maxItems + + This indicates the maximum number of values in an array when an array + is the instance value. + +5.13. uniqueItems + + This indicates that all the items in an array must be unique (no two + identical values) within that array when an array is the instance + value. + +5.14. pattern + + When the instance value is a string, this provides a regular + expression that a instance string value should match in order to be + valid. Regular expressions should follow the regular expression + specification from ECMA 262/Perl 5 + + + + + +Zyp Expires September 24, 2010 [Page 10] + +Internet-Draft JSON Schema Media Type March 2010 + + +5.15. maxLength + + When the instance value is a string, this indicates maximum length of + the string. + +5.16. minLength + + When the instance value is a string, this indicates minimum length of + the string. + +5.17. enum + + This provides an enumeration of possible values that are valid for + the instance property. This should be an array, and each item in the + array represents a possible value for the instance value. If "enum" + is included, the instance value must be one of the values in enum + array in order for the schema to be valid. + +5.18. title + + This provides a short description of the instance property. The + value must be a string. + +5.19. description + + This provides a full description of the of purpose the instance + property. The value must be a string. + +5.20. format + + This property indicates the type of data, content type, or + microformat to be expected in the instance property values. A format + attribute may be one of the values listed below, and if so, should + adhere to the semantics describing for the format. A format should + only be used give meaning to primitive types (string, integer, + number, or boolean). Validators are not required to validate that + the instance values conform to a format. The following formats are + defined: + + Any valid MIME media type may be used as a format value, in which + case the instance property value must be a string, representing + the contents of the MIME file. + + date-time - This should be a date in ISO 8601 format of YYYY-MM- + DDThh:mm:ssZ in UTC time. This is the recommended form of date/ + timestamp. + + + + + +Zyp Expires September 24, 2010 [Page 11] + +Internet-Draft JSON Schema Media Type March 2010 + + + date - This should be a date in the format of YYYY-MM-DD. It is + recommended that you use the "date-time" format instead of "date" + unless you need to transfer only the date part. + + time - This should be a time in the format of hh:mm:ss. It is + recommended that you use the "date-time" format instead of "time" + unless you need to transfer only the time part. + + utc-millisec - This should be the difference, measured in + milliseconds, between the specified time and midnight, January 1, + 1970 UTC. The value should be a number (integer or float). + + regex - A regular expression. + + color - This is a CSS color (like "#FF0000" or "red"). + + style - This is a CSS style definition (like "color: red; + background-color:#FFF"). + + phone - This should be a phone number (format may follow E.123). + + uri - This value should be a URI.. + + email - This should be an email address. + + ip-address - This should be an ip version 4 address. + + ipv6 - This should be an ip version 6 address. + + street-address - This should be a street address. + + locality - This should be a city or town. + + region - This should be a region (a state in the US, province in + Canada, etc.) + + postal-code - This should be a postal code (AKA zip code). + + country - This should be the name of a country. + + Additional custom formats may be defined with a URL to a + definition of the format. + +5.21. contentEncoding + + If the instance property value is a string, this indicates that the + string should be interpreted as binary data and decoded using the + encoding named by this schema property. RFC 2045, Sec 6.1 lists + + + +Zyp Expires September 24, 2010 [Page 12] + +Internet-Draft JSON Schema Media Type March 2010 + + + possible values. + +5.22. default + + This indicates the default for the instance property. + +5.23. divisibleBy + + This indicates that the instance property value must be divisible by + the given schema value when the instance property value is a number. + +5.24. disallow + + This attribute may take the same values as the "type" attribute, + however if the instance matches the type or if this value is an array + and the instance matches any type or schema in the array, than this + instance is not valid. + +5.25. extends + + The value of this property should be another schema which will + provide a base schema which the current schema will inherit from. + The inheritance rules are such that any instance that is valid + according to the current schema must be valid according to the + referenced schema. This may also be an array, in which case, the + instance must be valid for all the schemas in the array. + +6. Hyper Schema + + This section defines hypermedia definitions of JSON schema. The + following attributes are specified in addition to those attributes + that already provided by JSON schema with the specific purpose of + informing user agents of relations between resources based on JSON + data. Just as with JSON schema attributes, all the attributes in + hyper-schema are optional. Therefore an empty object is a valid + (non-informative) schema, and essentially describes plain JSON (no + constraints on the structures). Addition of attributes provides + additive information for user agents. + +6.1. links + + The value of the links property should be an array, where each item + in the array is a link description object which describes the link + relations of the instances. + + + + + + + +Zyp Expires September 24, 2010 [Page 13] + +Internet-Draft JSON Schema Media Type March 2010 + + +6.1.1. Link Description Object + + A link description object is used to describe the link relations. In + the context of a schema, it defines the link relations of the + instances of the schema, and can be parameterized by the instance + values. The link description format can be used on its own in + regular (non-schema documents), and use of this format can be + declared by referencing the normative link description schema as the + the schema for the data structure that uses the links. The URI of + the normative link description schema is: + http://json-schema.org/links. + +6.1.1.1. href + + The value of the "href" link description property indicates the + target URI of the related resource. The value of the instance + property should be resolved as a URI-Reference per [RFC3986] and may + be a relative URI. The base URI to be used for relative resolution + should be the URI used to retrieve the instance object (not the + schema) when used in the context of a schema. Also, the URI may be + parametrized by the property values of the instance object. + + Instance property values should be substituted into the URIs where + matching braces ('{', '}') are found surrounding zero or more + characters, creating an expanded URI. Instance property value + substitutions are resolved by using the text between the braces to + denote the property name from the instance to get the value to + substitute. For example, if an href value is defined: + + + http://somesite.com/{id} + + Then it would be resolved by replace the value of the "id" property + value from the instance object. If the value of the "id" property + was "45", the expanded URI would be: + + + http://somesite.com/45 + + If matching braces are found with the string "-this" (no quotes) + between the braces, than the actual instance value should be used to + replace the braces, rather than a property value. This should only + be used in situations where the instance is a scalar (string, + boolean, or number), and not for objects or arrays. + + + + + + + +Zyp Expires September 24, 2010 [Page 14] + +Internet-Draft JSON Schema Media Type March 2010 + + +6.1.1.2. rel + + The value of the "rel" property indicates the name of the relation to + the target resource. The relation to the target should be + interpreted as specifically from the instance object that the schema + (or sub-schema) applies to, not just the top level resource that + contains the object within its hierarchy. If a resource JSON + representation contains a sub object with a property interpreted as a + link, that sub-object holds the relation with the target. A relation + to target from the top level resource must be indicated with the + schema describing the top level JSON representation. + + Relationship definitions SHOULD NOT be media type dependent, and + users are encouraged to utilize existing accepted relation + definitions, including those in existing relation registries (see + &rfc4287). However, we define these relation here for clarity of + normative interpretation within the context of JSON hyper schema + defined relations: + + self - If the relation value is "self", when this property is + encountered in the instance object, the object represents a + resource and the instance object is treated as a full + representation of the target resource identified by the specified + URI. + + full - This indicates that the target of the link is the full + representation for the instance object. The object that contains + this link may not be the full representation. + + describedby - This indicates the target of the link is the schema + for the instance object. This may be used to specifically denote + the schemas of objects within a JSON object hierarchy, + facilitating polymorphic type data structures. + + The following relations are applicable for schemas (the schema as + the "from" resource in the relation). + + instances - This indicates the target resource that represents + collection of instances of a schema. + + create - This indicates a target to use for creating new instances + of a schema. This link definition SHOULD be a submission link + with a non-safe method (like POST). + + For example, if a schema is defined: + + + + + + +Zyp Expires September 24, 2010 [Page 15] + +Internet-Draft JSON Schema Media Type March 2010 + + + { + "links": [ + { + "rel": "self" + "href": "{id}" + }, + { + "rel": "up" + "href": "{upId}" + }, + { + "rel": "children" + "href": "?upId={id}" + } + ] + } + + And if a collection of instance resource's JSON representation was + retrieved: + + + GET /Resource/ + + [ + { + "id": "thing", + "upId": "parent" + }, + { + "id": "thing2", + "upId": "parent" + } + ] + + This would indicate that for the first item in the collection, it's + own (self) URI would resolve to "/Resource/thing" and the first + item's "up" relation should be resolved to the resource at + "/Resource/parent". The "children" collection would be located at + "/Resource/?upId=thing". + +6.1.1.2.1. targetSchema + + This property value can be a schema that defines the expected + structure of the JSON representation of the target of the link. + + + + + + + +Zyp Expires September 24, 2010 [Page 16] + +Internet-Draft JSON Schema Media Type March 2010 + + +6.1.1.3. Submission Link Properties + + The following properties also apply to link definition objects, and + provide functionality analogous to HTML forms, in providing a means + for submitting extra (often user supplied) information to send to a + server. + +6.1.1.3.1. method + + This indicates which method should be used to access the target + resource. In an HTTP environment, this would be "GET" or "POST" + (other HTTP methods such as "PUT" and "DELETE" have semantics that + are clearly implied by accessed resources, and do not need to be + defined here). This defaults to "GET". + +6.1.1.3.2. enctype + + If present, this property indicates a query media type format that + the server supports for querying or posting to the collection of + instances at the target resource. The query can be suffixed to the + target URI to query the collection with property-based constraints on + the resources that SHOULD be returned from the server or used to post + data to the resource (depending on the method). For example, with + the following schema: + + + { + "links":[ + { + "enctype": "application/x-www-form-urlencoded", + "method": "GET", + "href": "/Product/", + "properties":{ + "name":{"description":"name of the product"} + } + } + ] + } + + This indicates that the client can query the server for instances + that have a specific name: + + + /Product/?name=Slinky + + If no enctype or method is specified, only the single URI specified + by the href property is defined. If the method is POST, application/ + json is the default media type. + + + +Zyp Expires September 24, 2010 [Page 17] + +Internet-Draft JSON Schema Media Type March 2010 + + +6.1.1.3.3. properties + + This is inherited from the base JSON schema definition, and can + follow the same structure, but its meaning should be used to define + the acceptable property names and values for the action (whether it + be for the GET query or POST body). If properties are omitted, and + this form is the child of a schema, the properties from the parent + schema should be used as the basis for the form action. + +6.2. fragmentResolution + + This property indicates the fragment resolution protocol to use for + resolving fragment identifiers in URIs within the instance + representations. This applies to the instance object URIs and all + children of the instance object's URIs. The default fragment + resolution protocol is "slash-delimited", which is defined below. + Other fragment resolution protocols may be used, but are not defined + in this document. + + The fragment identifier is based on RFC 2396 Sec 5, and defines the + mechanism for resolving references to entities within a document. + +6.2.1. dot-delimited fragment resolution + + With the dot-delimited fragment resolution protocol, the fragment + identifier is interpreted as a series of property reference tokens + that are delimited by the "." character (\x2E). Each property + reference token is a series of any legal URI component characters + except the "." character. Each property reference token should be + interpreted, starting from the beginning of the fragment identifier, + as a path reference in the target JSON structure. The final target + value of the fragment can be determined by starting with the root of + the JSON structure from the representation of the resource identified + by the pre-fragment URI. If the target is a JSON object, than the + new target is the value of the property with the name identified by + the next property reference token in the fragment. If the target is + a JSON array, than the target is determined by finding the item in + array the array with the index defined by the next property reference + token (which MUST be a number). The target is successively updated + for each property reference token, until the entire fragment has been + traversed. + + Property names SHOULD be URI-encoded. In particular, any "." in a + property name MUST be encoded to avoid being interpreted as a + property delimiter. + + For example, for the following JSON representation: + + + + +Zyp Expires September 24, 2010 [Page 18] + +Internet-Draft JSON Schema Media Type March 2010 + + + { + "foo":{ + "anArray":[ + {"prop":44} + ], + "another prop":{ + "baz":"A string" + } + } + } + + The following fragment identifiers would be resolved: + + + fragment identifier resolution + ------------------- ---------- + # self, the root of the resource itself + #foo the object referred to by the foo property + #foo.another prop the object referred to by the "another prop" + property of the object referred to by the + "foo" property + #foo.another prop.baz the string referred to by the value of "baz" + property of the "another prop" property of + the object referred to by the "foo" property + #foo.anArray.0 the first object in the "anArray" array + +6.2.2. slash-delimited fragment resolution + + The slash-delimited fragment resolution protocol is exactly the same + as dot-delimited fragment resolution protocol except that the "/" + character (\x2F) is used as the delimiter between property names + (instead of "."). + +6.3. root + + This attribute indicates that the value of the instance property + value SHOULD be treated as the root or the body of the representation + for the purposes of user agent interaction and fragment resolution + (all other properties of the instance objects are can be regarded as + meta-data descriptions for the data). + +6.4. readonly + + This indicates that the instance property should not be changed. + Attempts by a user agent to modify the value of this property are + expected to be rejected by a server. + + + + + +Zyp Expires September 24, 2010 [Page 19] + +Internet-Draft JSON Schema Media Type March 2010 + + +6.5. pathStart + + This property value is a URI-Reference that indicates the URI that + all the URIs for the instances of the schema should start with. When + multiple schemas have been referenced for an instance, the user agent + can determine if this schema is applicable for a particular instance + by determining if URI of the instance begins with the pathStart's + referenced URI. pathStart MUST be resolved as per [RFC3986] section + 5. If the URI of the instance does not start with URI indicated by + pathStart, or if another schema specifies a starting URI that is + longer and also matches the instance, this schema should not be + applied to the instance. Any schema that does not have a pathStart + attribute should be considered applicable to all the instances for + which it is referenced. + +6.6. mediaType + + This indicates the media type of the instance representations that + this schema is defining. + +6.7. alternate + + This is an array of JSON schema definitions that define any other + schemas for alternate JSON-based representations of the instance + resources. + +7. Security Considerations + + This specification is a sub-type of the JSON format, and consequently + the security considerations are generally the same as RFC 4627. + However, an additional issue is that when link relation of "self" is + used to denote a full representation of an object, the user agent + SHOULD NOT consider the representation to be the authoritative + representation of the resource denoted by the target URI if the + target URI is not equivalent to or a sub-path of the the URI used to + request the resource representation which contains the target URI + with the "self" link. For example, if a hyper schema was defined: + + + { + "links":[ + { + "rel":"self", + "href":"{id}" + } + ] + } + + + + +Zyp Expires September 24, 2010 [Page 20] + +Internet-Draft JSON Schema Media Type March 2010 + + + And a resource was requested from somesite.com: + + + GET /foo/ + + With a response of: + + +Content-Type: application/json; profile=/schema-for-this-data +[ + {"id":"bar", "name":"This representation can be safely treated \ + as authoritative "}, + {"id":"/baz", "name":"This representation should not be treated as \ + authoritative the user agent should make request the resource\ + from "/baz" to ensure it has the authoritative representation"}, + {"id":"http://othersite.com/something", "name":"This representation\ + should also not be treated as authoritative and the target\ + resource representation should be retrieved for the\ + authoritative representation"} +] + +8. IANA Considerations + + The proposed MIME media type for JSON Schema is application/ + schema+json + + Type name: application + + Subtype name: schema+json + + Required parameters: profile + + The value of the profile parameter should be a URI (relative or + absolute) that refers to the schema used to define the structure of + this structure (the meta-schema). Normally the value would be + http://json-schema.org/hyper-schema, but it is allowable to use other + schemas that extend the hyper schema's meta- schema. + + Optional parameters: pretty + + The value of the pretty parameter may be true or false to indicate if + additional whitespace has been included to make the JSON + representation easier to read. + +8.1. Registry of Link Relations + + This registry is maintained by IANA per RFC 4287 and this + specification adds three values: "full", "create", "instances". New + + + +Zyp Expires September 24, 2010 [Page 21] + +Internet-Draft JSON Schema Media Type March 2010 + + + assignments are subject to IESG Approval, as outlined in [RFC5226]. + Requests should be made by email to IANA, which will then forward the + request to the IESG, requesting approval. + +9. References + +9.1. Normative References + + [RFC3986] Berners-Lee, T., Fielding, R., and + L. Masinter, "Uniform Resource + Identifier (URI): Generic Syntax", + STD 66, RFC 3986, January 2005. + + [RFC2119] Bradner, S., "Key words for use in + RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, + March 1997. + + [RFC4287] Nottingham, M., Ed. and R. Sayre, + Ed., "The Atom Syndication + Format", RFC 4287, December 2005. + + [RFC3339] Klyne, G., Ed. and C. Newman, + "Date and Time on the Internet: + Timestamps", RFC 3339, July 2002. + + [RFC2045] Freed, N. and N. Borenstein, + "Multipurpose Internet Mail + Extensions (MIME) Part One: Format + of Internet Message Bodies", + RFC 2045, November 1996. + +9.2. Informative References + + [RFC4627] Crockford, D., "The application/ + json Media Type for JavaScript + Object Notation (JSON)", RFC 4627, + July 2006. + + [RFC2616] Fielding, R., Gettys, J., Mogul, + J., Frystyk, H., Masinter, L., + Leach, P., and T. Berners-Lee, + "Hypertext Transfer Protocol -- + HTTP/1.1", RFC 2616, June 1999. + + [RFC5226] Narten, T. and H. Alvestrand, + "Guidelines for Writing an IANA + Considerations Section in RFCs", + + + +Zyp Expires September 24, 2010 [Page 22] + +Internet-Draft JSON Schema Media Type March 2010 + + + BCP 26, RFC 5226, May 2008. + + [I-D.hammer-discovery] Hammer-Lahav, E., "LRDD: Link- + based Resource Descriptor + Discovery", + draft-hammer-discovery-04 (work in + progress), March 2010. + + [I-D.gregorio-uritemplate] Gregorio, J., Fielding, R., + Hadley, M., and M. Nottingham, + "URI Template", + draft-gregorio-uritemplate-04 + (work in progress), March 2010. + + [I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", dra + ft-nottingham-http-link-header-08 + (work in progress), March 2010. + + [W3C.REC-html401-19991224] Hors, A., Jacobs, I., and D. + Raggett, "HTML 4.01 + Specification", World Wide Web + Consortium Recommendation REC- + html401-19991224, December 1999, < + http://www.w3.org/TR/1999/ + REC-html401-19991224>. + +Appendix A. Change Log + + -02 + + o Replaced maxDecimal attribute with divisibleBy attribute + + o Added slash-delimited fragment resolution protocol and made it the + default. + + o Added language about using links outside of schemas by referencing + it's normative URI. + + o Added uniqueItems attribute + + o Added targetSchema attribute to link description object + + -01 + + o Fixed category and updates from template + + -00 + + + + +Zyp Expires September 24, 2010 [Page 23] + +Internet-Draft JSON Schema Media Type March 2010 + + + o Initial draft + +Appendix B. Open Issues + + Should we give a preference to MIME headers over Link headers (or + only use one)? + + Should we use "profile" as the media type parameter instead? + + Should "root" be a MIME parameter instead of a schema attribute? + + Should "format" be renamed to "mediaType" or "contentType" to reflect + the usage MIME media types that are allowed. + + I still do not like how dates are handled. + + Should "slash-delimited" or "dot-delimited" be the default fragment + resolution protocol? + +Author's Address + + Kris Zyp (editor) + SitePen (USA) + 530 Lytton Avenue + Palo Alto, CA 94301 + USA + + Phone: +1 650 968 8787 + EMail: kris@sitepen.com + + + + + + + + + + + + + + + + + + + + + + +Zyp Expires September 24, 2010 [Page 24] + + diff --git a/draft-zyp-json-schema-02.xml b/draft-zyp-json-schema-02.xml new file mode 100644 index 0000000..0e36d7b --- /dev/null +++ b/draft-zyp-json-schema-02.xml @@ -0,0 +1,931 @@ + + + + + + + + + + + + + +]> + + + + + + + + + + + A JSON Media Type for Describing the Structure and Meaning of JSON Documents + + + + SitePen (USA) + +
+ + 530 Lytton Avenue + + Palo Alto, CA 94301 + + USA + + + +1 650 968 8787 + + kris@sitepen.com +
+ + + + + Internet Engineering Task Force + + JSON + + Schema + + Hyper Schema + + Hypermedia + + + + + JSON (JavaScript Object Notation) Schema defines the media type application/schema+json, + a JSON based format for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. + + + + + + +
+ JSON (JavaScript Object Notation) Schema is a JSON media type for defining + the structure of JSON data. JSON Schema provides a contract for what JSON + data is required for a given application and how to interact with it. JSON + Schema is intended to define validation, documentation, hyperlink + navigation, and interaction control of JSON data. +
+ + +
+ The key words "MUST", "MUST + NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", + "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be + interpreted as described in RFC 2119. +
+ + + +
+ JSON Schema defines the media type application/schema+json for + describing the structure of other + JSON documents. JSON Schema is JSON-based and includes facilities + for describing the structure of JSON documents in terms of + allowable values, descriptions, and interpreting relations with other resources. + + JSON Schema format is organized into several separate definitions. The first + definition is the core schema specification. This definition is primary + concerned with describing a JSON structure and specifying valid elements + in the structure. The second definition is the Hyper Schema specification + which is intended define elements in a structure that can be interpreted as + hyperlinks. + Hyper Schema builds on JSON Schema to describe the hyperlink structure of + other JSON documents. This allows user agents to be able to successfully navigate + JSON documents based on their schemas. + + + Cumulatively JSON Schema acts as a meta-document that can be used to define the required type and constraints on + property values, as well as define the meaning of the property values + for the purpose of describing a resource and determining hyperlinks + within the representation. + + + An example JSON Schema that describes products might look like: +
+ +
+This schema defines the properties of the instance JSON documents and +their required properties (id, name, and price) as well as an optional +property (tags). This also defines the link relations of the instance +JSON documents. + +
+ For this specification, a schema will be used to denote a JSON Schema + definition, and an instance refers to the JSON object or array that the schema + will be describing and validating + +
+
+ + The JSON Schema media type does not attempt to dictate the structure of JSON + representations that contain data, but rather provides a separate format + for flexibly communicating how a JSON representation should be + interpreted and validated, such that user agents can properly understand + acceptable structures and extrapolate hyperlink information + with the JSON document. It is acknowledged that JSON documents come + in a variety of structures, and JSON is unique in that the structure + of stored data structures often prescribes a non-ambiguous definite + JSON representation. Attempting to force a specific structure is generally + not viable, and therefore JSON Schema allows for great flexibility + in the structure of JSON data that it describes. + + This specification is protocol agnostic. + The underlying protocol (such as HTTP) should sufficiently define the + semantics of the client-server interface, the retrieval of resource + representations linked to by JSON representations, and modification of + those resources. The goal of this + format is to sufficiently describe JSON structures such that one can + utilize existing information available in existing JSON + representations from a large variety of services that leverage a representational state transfer + architecture using existing protocols. + +
+
+ +
+ + JSON Schema instances are correlated to their schema by the "describedby" + relation, where the schema is defined to be the target of the relation. + Instance representations may be of the application/json media type or + any other subtype. Consequently, dictating how an instance + representation should specify the relation to the schema is beyond the normative scope + of this document (since this document specifically defines the JSON + Schema media type, and no other), but it is recommended that instances + specify their schema so that user agents can interpret the instance + representation and messages may retain the self-descriptive + characteristic, avoiding the need for out-of-band information about + instance data. Two approaches are recommended for declaring the + relation to the schema that describes the meaning of a JSON instance's (or collection + of instances) structure. A MIME type parameter named + "profile" or a Link header with a relation of "describedby" SHOULD be used: +
+ +
+ or if the content is being transferred by a protocol (such as HTTP) that + provides headers, a Link header can be used: +
+ + ; rel="describedby" +]]>
+ Instances MAY specify multiple schemas, to indicate all the schemas that + are applicable to the data. The instance data may have multiple schemas + that it is defined by (the instance data should be valid for those schemas). + Or if the document is a collection of instances, the collection may contain + instances from different schemas. When collections contain heterogeneous + instances, the pathStart attribute MAY be specified in the + schema to disambiguate which schema should be applied for each item in the +collection. + +
+ + JSON Schemas are themselves instances for the schema + schemas. A self-describing JSON Schema for the core JSON Schema can + be found at http://json-schema.org/schema and the hyper schema + self-description can be found at: http://json-schema.org/hyper-schema. All schemas + used within a protocol with media type definitions + SHOULD include a MIME parameter that refers to the self-descriptive + hyper schema or another schema that extends this hyper schema: +
+ +
+ +
+
+ +
+ A JSON Schema is a JSON Object that defines various attributes + of the instance and defines it's usage and valid values. A JSON + Schema is a JSON Object with schema attribute properties. + The following is the grammar of a JSON Schema: + + + + And an example JSON Schema definition could look like: +
+ + +
+ + A JSON Schema object may have any of the following properties, called schema + attributes (all attributes are optional): + + +
+ +Union type definition - An array with two or more items which indicates a union of type definitions. Each item in the array may be a simple type definition or a schema. The instance value is valid if it is of the same type as one the type definitions in the array or if it is valid by one of the schemas in the array. For example to indicate that a string or number is a valid: +{"type":["string","number"]} +Simple type definition - A string indicating a primitive or simple type. The following are acceptable strings: + + + +string - Value must be a string. + +number - Value must be a number, floating point numbers are allowed. +integer - Value must be an integer, no floating point numbers are allowed. This is a subset of the number type. +boolean - Value must be a boolean. +object - Value must be an object. +array - Value must be an array. + +null - Value must be null. Note this is mainly for purpose of being able use union types to define nullability. +any - Value may be of any type including null. +If the property is not defined or is not in this list, than any type of value is acceptable. Other type values may be used for custom purposes, but minimal validators of the specification implementation can allow any instance value on unknown type values. + + + + +
+
+This should be an object type definition, which is an object with property definitions that correspond to instance object properties. When the instance value is an object, the property values of the instance object must conform to the property definitions in this object. In this object, each property definition's value should be a schema, and the property's name should be the name of the instance property that it defines. +
+
+This should be a schema or an array of schemas. When this is an object/schema and the instance value is an array, all the items in the array must conform to this schema. When this is an array of schemas and the instance value is an array, each position in the instance array must conform to the schema in the corresponding position for this array. This called tuple typing. When tuple typing is used, additional items are allowed, disallowed, or constrained by the additionalProperties attribute using the same rules as extra properties for objects. The default value is an empty schema which allows any value for items in the instance array. +
+
+This indicates that the instance property in the instance object is optional. This is false by default. +
+
+This provides a default property definition for all properties that are not explicitly defined in an object type definition. The value must be a schema. If false is provided, no additional properties are allowed, and the schema can not be extended. The default value is an empty schema which allows any value for additional properties. +
+
+This indicates that if this property is present in the containing instance object, the property given by requires attribute must also be present in the containing instance object. The value +of this property may be a string, indicating the require property name. Or the value may be a schema, in which case the containing instance must be valid by the schema if the property is present. For example if a object type definition is defined: +
+ + +
+An instance must include a state property if a town property is included. If a town property is not included, the state property is optional. +
+
+This indicates the minimum value for the instance property when the type of the instance value is a number. +
+
+This indicates the minimum value for the instance property when the type of the instance value is a number. +
+
+If the minimum is defined, this indicates whether or not the instance property value can equal the minimum. +
+
+If the maximum is defined, this indicates whether or not the instance property value can equal the maximum. +
+
+This indicates the minimum number of values in an array when an array is the instance value. +
+
+This indicates the maximum number of values in an array when an array is the instance value. +
+
+This indicates that all the items in an array must be unique (no two identical values) within that array when an array is the instance value. +
+
+When the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid. Regular expressions should follow the regular expression specification from ECMA 262/Perl 5
+
+When the instance value is a string, this indicates maximum length of the string. +
+
+When the instance value is a string, this indicates minimum length of the string. +
+
+This provides an enumeration of possible values that are valid for the instance property. This should be an array, and each item in the array represents a possible value for the instance value. If "enum" is included, the instance value must be one of the values in enum array in order for the schema to be valid. +
+
+This provides a short description of the instance property. The value must be a string. +
+
+This provides a full description of the of purpose the instance property. The value must be a string. +
+
This property indicates the type of data, content type, or microformat to be expected in the instance property values. A format attribute may be one of the values listed below, and if so, should adhere to the semantics describing for the format. A format should only be used give meaning to primitive types (string, integer, number, or boolean). Validators are not required to validate that the instance values conform to a format. The following formats are defined: + +Any valid MIME media type may be used as a format value, in which case the instance property value must be a string, representing the contents of the MIME file. +date-time - This should be a date in ISO 8601 format of YYYY-MM-DDThh:mm:ssZ in UTC time. This is the recommended form of date/timestamp. +date - This should be a date in the format of YYYY-MM-DD. It is recommended that you use the "date-time" format instead of "date" unless you need to transfer only the date part. +time - This should be a time in the format of hh:mm:ss. It is recommended that you use the "date-time" format instead of "time" unless you need to transfer only the time part. +utc-millisec - This should be the difference, measured in milliseconds, between the specified time and midnight, January 1, 1970 UTC. The value should be a number (integer or float). +regex - A regular expression. +color - This is a CSS color (like "#FF0000" or "red"). +style - This is a CSS style definition (like "color: red; background-color:#FFF"). +phone - This should be a phone number (format may follow E.123). +uri - This value should be a URI.. +email - This should be an email address. +ip-address - This should be an ip version 4 address. +ipv6 - This should be an ip version 6 address. +street-address - This should be a street address. +locality - This should be a city or town. +region - This should be a region (a state in the US, province in Canada, etc.) +postal-code - This should be a postal code (AKA zip code). +country - This should be the name of a country. +Additional custom formats may be defined with a URL to a definition of the format. + +
+
+If the instance property value is a string, this indicates that the string should be interpreted as binary data and decoded using the encoding named by this schema property. RFC 2045, Sec 6.1 lists possible values. + +
+
+This indicates the default for the instance property. +
+
+This indicates that the instance property value must be divisible by the given schema value when the instance property value is a number. +
+
+This attribute may take the same values as the "type" attribute, however if the instance matches the type or if this value is an array and the instance matches any type or schema in the array, than this instance is not valid. +
+
+The value of this property should be another schema which will provide a base schema which the current schema will inherit from. The inheritance rules are such that any instance that is valid according to the current schema must be valid according to the referenced schema. This may also be an array, in which case, the instance must be valid for all the schemas in the array. +
+
+
+ This section defines hypermedia definitions of JSON schema. + The following attributes are specified in addition to those +attributes that already provided by JSON schema with the specific +purpose of informing user agents of relations between resources based +on JSON data. Just as with JSON +schema attributes, all the attributes in hyper-schema are optional. +Therefore an empty object is a valid (non-informative) schema, and +essentially describes plain JSON (no constraints on the structures). +Addition of attributes provides additive information for user agents. +
+ +The value of the links property should be an array, where each item +in the array is a link description object which describes the link +relations of the instances. + +
+ +A link description object is used to describe the link relations. In +the context of a schema, it defines the link relations of the +instances of the schema, and can be parameterized by the instance +values. The link description format can be used on its own in +regular (non-schema documents), and use of this format can +be declared by referencing the normative link description +schema as the the schema for the data structure that uses the +links. The URI of the normative link description schema is: http://json-schema.org/links. + +
+ + The value of the "href" link description property +indicates the target URI of the related resource. The value +of the instance property should be resolved as a URI-Reference per [RFC3986] +and may be a relative URI. The base URI to be used for relative resolution +should be the URI used to retrieve the instance object (not the schema) +when used in the context of a schema. +Also, the URI may be parametrized by the property values of the instance +object. + + +Instance property values should be substituted into the URIs where +matching braces ('{', '}') are found surrounding zero or more characters, +creating an expanded URI. Instance property value substitutions are resolved +by using the text between the braces to denote the property name +from the instance to get the value to substitute. For example, +if an href value is defined: +
+ + +
+Then it would be resolved by replace the value of the "id" property value from +the instance object. If the value of the "id" property was "45", the expanded +URI would be: +
+ + +
+If matching braces are found with the string "-this" (no quotes) between the braces, than the +actual instance value should be used to replace the braces, rather than a property value. +This should only be used in situations where the instance is a scalar (string, +boolean, or number), and not for objects or arrays. + +
+
+ +The value of the "rel" property indicates the name of the +relation to the target resource. The relation to the target should be interpreted as specifically from the instance object that the schema (or sub-schema) applies to, not just the top level resource that contains the object within its hierarchy. If a resource JSON representation contains a sub object with a property interpreted as a link, that sub-object holds the relation with the target. A relation to target from the top level resource must be indicated with the schema describing the top level JSON representation. + + +Relationship definitions SHOULD NOT be media type dependent, and users are encouraged to utilize existing accepted relation definitions, including those in existing relation registries (see &rfc4287). However, we define these relation here for clarity of normative interpretation within the context of JSON hyper schema defined relations: + + +self - If the relation value is "self", when this property is encountered in +the instance object, the object represents a resource and the instance object is +treated as a full representation of the target resource identified by +the specified URI. + + +full - This indicates that the target of the link is the full representation for the instance object. The object that contains this link may not be the full representation. + + +describedby - This indicates the target of the link is the schema for the instance object. This may be used to specifically denote the schemas of objects within a JSON object hierarchy, facilitating polymorphic type data structures. + + +The following relations are applicable for schemas (the schema as the "from" resource in the relation). + + +instances - This indicates the target resource that represents collection of instances of a schema. + + +create - This indicates a target to use for creating new instances of a schema. This link definition SHOULD be a submission link with a non-safe method (like POST). + + +For example, if a schema is defined: +
+ + +
+And if a collection of instance resource's JSON representation was +retrieved: +
+ + +
+ +This would indicate that for the first item in the collection, it's own +(self) URI would resolve to "/Resource/thing" and the first item's "up" +relation should be resolved to the resource at "/Resource/parent". +The "children" collection would be located at "/Resource/?upId=thing". + +
+This property value can be a schema that defines the expected +structure of the JSON representation of the target of the link. +
+
+
+ +The following properties also apply to link definition objects, and +provide functionality analogous to HTML forms, in providing a +means for submitting extra (often user supplied) information to send to a server. + +
+ + +This indicates which method should be used to access the target resource. +In an HTTP environment, this would be "GET" or "POST" (other HTTP methods +such as "PUT" and "DELETE" have semantics that are clearly implied by +accessed resources, and do not need to be defined here). +This defaults to "GET". + +
+ +
+ +If present, this property indicates a query media type format that the server +supports for querying or posting to the collection of instances at the target +resource. The query can be +suffixed to the target URI to query the collection with +property-based constraints on the resources that SHOULD be returned from +the server or used to post data to the resource (depending on the method). +For example, with the following schema: +
+ + +
+This indicates that the client can query the server for instances that +have a specific name: +
+ + +
+ +If no enctype or method is specified, only the single URI specified by +the href property is defined. If the method is POST, application/json is +the default media type. + +
+
+ +This is inherited from the base JSON schema definition, and can follow the +same structure, but its meaning should be used to define the acceptable +property names and values for the action (whether it be for the GET query +or POST body). If properties are omitted, and this form is the child of a +schema, the properties from the parent schema should be used as the basis +for the form action. + +
+
+
+
+
+ This property indicates the fragment resolution protocol to use for +resolving fragment identifiers in URIs within the instance +representations. This applies to the instance object URIs and all +children of the instance object's URIs. The default fragment resolution +protocol is "slash-delimited", which is defined below. Other fragment +resolution protocols may be used, but are not defined in this +document. + + + +The fragment identifier is based on RFC 2396 Sec 5, and defines the +mechanism for resolving references to entities within a document. + +
+With the dot-delimited fragment resolution protocol, the fragment +identifier is interpreted as a series of property reference tokens that +are delimited by the "." character (\x2E). Each property reference token +is a series of any legal URI component characters except the "." character. Each property +reference token should be interpreted, starting from the beginning of +the fragment identifier, as a path reference in the target JSON +structure. The final target value of the fragment can be determined by +starting with the root of the JSON structure from the representation of +the resource identified by the pre-fragment URI. If the target is a JSON +object, than the new target is the value of the property with the name +identified by the next property reference token in the fragment. If the +target is a JSON array, than the target is determined by finding the +item in array the array with the index defined by the next property +reference token (which MUST be a number). The target is successively +updated for each property reference token, until the entire fragment has +been traversed. + + +Property names SHOULD be URI-encoded. In particular, any "." in a +property name MUST be encoded to avoid being interpreted as a property +delimiter. + + +For example, for the following JSON representation: +
+ + +
+The following fragment identifiers would be resolved: +
+ + +
+ +
+
+The slash-delimited fragment resolution protocol is exactly the same as +dot-delimited fragment resolution protocol except that the "/" character +(\x2F) is used as the delimiter between property names (instead of "."). +
+ + +
+ +
+ This attribute indicates that the value of the instance property value +SHOULD be treated as the root or the body of the representation for the +purposes of user agent interaction and fragment resolution (all other +properties of the instance objects are can be regarded as meta-data +descriptions for the data). + + + +
+
+This indicates that the instance property should not be changed. Attempts by a user agent to modify the value of this property are expected to be rejected by a server. +
+ +
+ This property value is a URI-Reference that indicates the URI that all +the URIs for the instances of the schema should start with. When +multiple schemas have been referenced for an instance, the user agent +can determine if this schema is applicable for a particular instance by +determining if URI of the instance begins with the pathStart's referenced +URI. pathStart MUST be resolved as per [RFC3986] section 5. If the URI of +the instance does not start with URI indicated by pathStart, or if another +schema specifies a starting URI that is longer and also matches the +instance, this schema should not be applied to the instance. Any schema +that does not have a pathStart attribute should be considered applicable +to all the instances for which it is referenced. + + + + + +
+
+ This indicates the media type of the instance representations that this schema is defining. + + +
+ +
+ This is an array of JSON schema definitions that define any + other schemas for alternate JSON-based representations + of the instance resources. + + +
+ + +
+ +
+ +This specification is a sub-type of the JSON format, and +consequently the security considerations are generally the same as RFC +4627. However, an additional issue is that when link relation of "self" +is used to denote a full representation of an object, the user agent +SHOULD NOT consider the representation to be the authoritative representation +of the resource denoted by the target URI if the target URI is not +equivalent to or a sub-path of the the URI used to request the resource +representation which contains the target URI with the "self" link. +For example, if a hyper schema was defined: +
+ + +
+And a resource was requested from somesite.com: +
+ + +
+ +With a response of: +
+ + +
+ +
+
+ + The proposed MIME media type for JSON Schema is application/schema+json + + + Type name: application + + + Subtype name: schema+json + + + Required parameters: profile + + + The value of the profile parameter should be a URI (relative or absolute) that + refers to the schema used to define the structure of this structure (the + meta-schema). Normally the value would be http://json-schema.org/hyper-schema, + but it is allowable to use other schemas that extend the hyper schema's meta- + schema. + + + Optional parameters: pretty + + + The value of the pretty parameter may be true or false to indicate if additional + whitespace has been included to make the JSON representation easier to read. + + +
+ +This registry is maintained by IANA per RFC 4287 and this specification adds +three values: "full", "create", "instances". New + assignments are subject to IESG Approval, as outlined in [RFC5226]. + Requests should be made by email to IANA, which will then forward the + request to the IESG, requesting approval. + + +
+ +
+ + + + + + + + &rfc3986; + &rfc2119; + &rfc4287; + &rfc3339; + &rfc2045; + + + + &rfc4627; + &rfc2616; + &rfc5226; + &iddiscovery; + &uritemplate; + &linkheader; + &html401; + + + + +
+ -02 + + + Replaced maxDecimal attribute with divisibleBy attribute + Added slash-delimited fragment resolution protocol and made it the default. + Added language about using links outside of schemas by referencing it's normative URI. + Added uniqueItems attribute + Added targetSchema attribute to link description object + + + + -01 + + + Fixed category and updates from template + + + -00 + + + Initial draft + + + +
+ +
+ Should we give a preference to MIME headers over Link headers (or only use one)? + Should we use "profile" as the media type parameter instead? + Should "root" be a MIME parameter instead of a schema attribute? + Should "format" be renamed to "mediaType" or "contentType" to reflect the usage MIME media types that are allowed. + I still do not like how dates are handled. + Should "slash-delimited" or "dot-delimited" be the default fragment resolution protocol? + +
+ + + + diff --git a/draft-zyp-json-schema-03.txt b/draft-zyp-json-schema-03.txt new file mode 100644 index 0000000..e41724b --- /dev/null +++ b/draft-zyp-json-schema-03.txt @@ -0,0 +1,1569 @@ + + + +Internet Engineering Task Force K. Zyp, Ed. +Internet-Draft SitePen (USA) +Intended status: Informational G. Court +Expires: May 26, 2011 November 22, 2010 + + + A JSON Media Type for Describing the Structure and Meaning of JSON + Documents + draft-zyp-json-schema-03 + +Abstract + + JSON (JavaScript Object Notation) Schema defines the media type + "application/schema+json", a JSON based format for defining the + structure of JSON data. JSON Schema provides a contract for what + JSON data is required for a given application and how to interact + with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on May 26, 2011. + +Copyright Notice + + Copyright (c) 2010 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + + + +Zyp & Court Expires May 26, 2011 [Page 1] + +Internet-Draft JSON Schema Media Type November 2010 + + + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.2. Design Considerations . . . . . . . . . . . . . . . . . . 6 + 4. Schema/Instance Association . . . . . . . . . . . . . . . . . 6 + 4.1. Self-Descriptive Schema . . . . . . . . . . . . . . . . . 7 + 5. Core Schema Definition . . . . . . . . . . . . . . . . . . . . 7 + 5.1. type . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 5.2. properties . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.3. patternProperties . . . . . . . . . . . . . . . . . . . . 9 + 5.4. additionalProperties . . . . . . . . . . . . . . . . . . . 9 + 5.5. items . . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.6. additionalItems . . . . . . . . . . . . . . . . . . . . . 10 + 5.7. required . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.8. dependencies . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.9. minimum . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.10. maximum . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.11. exclusiveMinimum . . . . . . . . . . . . . . . . . . . . . 11 + 5.12. exclusiveMaximum . . . . . . . . . . . . . . . . . . . . . 11 + 5.13. minItems . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.14. maxItems . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.15. uniqueItems . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.16. pattern . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.17. minLength . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.18. maxLength . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.19. enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.20. default . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.21. title . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.22. description . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.23. format . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.24. divisibleBy . . . . . . . . . . . . . . . . . . . . . . . 14 + 5.25. disallow . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 5.26. extends . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 5.27. id . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 5.28. $ref . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 5.29. $schema . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 6. Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 6.1. links . . . . . . . . . . . . . . . . . . . . . . . . . . 16 + 6.1.1. Link Description Object . . . . . . . . . . . . . . . 16 + 6.2. fragmentResolution . . . . . . . . . . . . . . . . . . . . 20 + 6.2.1. slash-delimited fragment resolution . . . . . . . . . 20 + + + +Zyp & Court Expires May 26, 2011 [Page 2] + +Internet-Draft JSON Schema Media Type November 2010 + + + 6.2.2. dot-delimited fragment resolution . . . . . . . . . . 21 + 6.3. readonly . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 6.4. contentEncoding . . . . . . . . . . . . . . . . . . . . . 22 + 6.5. pathStart . . . . . . . . . . . . . . . . . . . . . . . . 22 + 6.6. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 22 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 + 8.1. Registry of Link Relations . . . . . . . . . . . . . . . . 24 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 24 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 24 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 26 + Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 27 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zyp & Court Expires May 26, 2011 [Page 3] + +Internet-Draft JSON Schema Media Type November 2010 + + +1. Introduction + + JSON (JavaScript Object Notation) Schema is a JSON media type for + defining the structure of JSON data. JSON Schema provides a contract + for what JSON data is required for a given application and how to + interact with it. JSON Schema is intended to define validation, + documentation, hyperlink navigation, and interaction control of JSON + data. + +2. Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +3. Overview + + JSON Schema defines the media type "application/schema+json" for + describing the structure of other JSON documents. JSON Schema is + JSON-based and includes facilities for describing the structure of + JSON documents in terms of allowable values, descriptions, and + interpreting relations with other resources. + + JSON Schema format is organized into several separate definitions. + The first definition is the core schema specification. This + definition is primary concerned with describing a JSON structure and + specifying valid elements in the structure. The second definition is + the Hyper Schema specification which is intended define elements in a + structure that can be interpreted as hyperlinks. Hyper Schema builds + on JSON Schema to describe the hyperlink structure of other JSON + documents and elements of interaction. This allows user agents to be + able to successfully navigate JSON documents based on their schemas. + + Cumulatively JSON Schema acts as a meta-document that can be used to + define the required type and constraints on property values, as well + as define the meaning of the property values for the purpose of + describing a resource and determining hyperlinks within the + representation. + + + + + + + + + + + + + +Zyp & Court Expires May 26, 2011 [Page 4] + +Internet-Draft JSON Schema Media Type November 2010 + + + An example JSON Schema that describes products might look like: + + { + "name":"Product", + "properties":{ + "id":{ + "type":"number", + "description":"Product identifier", + "required":true + }, + "name":{ + "description":"Name of the product", + "type":"string", + "required":true + }, + "price":{ + "required":true, + "type": "number", + "minimum":0, + "required":true + }, + "tags":{ + "type":"array", + "items":{ + "type":"string" + } + } + }, + "links":[ + { + "rel":"full", + "href":"{id}" + }, + { + "rel":"comments", + "href":"comments/?id={id}" + } + ] + } + + This schema defines the properties of the instance JSON documents, + the required properties (id, name, and price), as well as an optional + property (tags). This also defines the link relations of the + instance JSON documents. + + + + + + + +Zyp & Court Expires May 26, 2011 [Page 5] + +Internet-Draft JSON Schema Media Type November 2010 + + +3.1. Terminology + + For this specification, *schema* will be used to denote a JSON Schema + definition, and an *instance* refers to a JSON value that the schema + will be describing and validating. + +3.2. Design Considerations + + The JSON Schema media type does not attempt to dictate the structure + of JSON representations that contain data, but rather provides a + separate format for flexibly communicating how a JSON representation + should be interpreted and validated, such that user agents can + properly understand acceptable structures and extrapolate hyperlink + information with the JSON document. It is acknowledged that JSON + documents come in a variety of structures, and JSON is unique in that + the structure of stored data structures often prescribes a non- + ambiguous definite JSON representation. Attempting to force a + specific structure is generally not viable, and therefore JSON Schema + allows for a great flexibility in the structure of the JSON data that + it describes. + + This specification is protocol agnostic. The underlying protocol + (such as HTTP) should sufficiently define the semantics of the + client-server interface, the retrieval of resource representations + linked to by JSON representations, and modification of those + resources. The goal of this format is to sufficiently describe JSON + structures such that one can utilize existing information available + in existing JSON representations from a large variety of services + that leverage a representational state transfer architecture using + existing protocols. + +4. Schema/Instance Association + + JSON Schema instances are correlated to their schema by the + "describedby" relation, where the schema is defined to be the target + of the relation. Instance representations may be of the + "application/json" media type or any other subtype. Consequently, + dictating how an instance representation should specify the relation + to the schema is beyond the normative scope of this document (since + this document specifically defines the JSON Schema media type, and no + other), but it is recommended that instances specify their schema so + that user agents can interpret the instance representation and + messages may retain the self-descriptive characteristic, avoiding the + need for out-of-band information about instance data. Two approaches + are recommended for declaring the relation to the schema that + describes the meaning of a JSON instance's (or collection of + instances) structure. A MIME type parameter named "profile" or a + relation of "describedby" (which could be defined by a Link header) + + + +Zyp & Court Expires May 26, 2011 [Page 6] + +Internet-Draft JSON Schema Media Type November 2010 + + + may be used: + + Content-Type: application/my-media-type+json; + profile=http://json.com/my-hyper-schema + + or if the content is being transferred by a protocol (such as HTTP) + that provides headers, a Link header can be used: + + Link: ; rel="describedby" + + Instances MAY specify multiple schemas, to indicate all the schemas + that are applicable to the data, and the data SHOULD be valid by all + the schemas. The instance data MAY have multiple schemas that it is + defined by (the instance data SHOULD be valid for those schemas). Or + if the document is a collection of instances, the collection MAY + contain instances from different schemas. When collections contain + heterogeneous instances, the "pathStart" attribute MAY be specified + in the schema to disambiguate which schema should be applied for each + item in the collection. However, ultimately, the mechanism for + referencing a schema is up to the media type of the instance + documents (if they choose to specify that schemas can be referenced). + +4.1. Self-Descriptive Schema + + JSON Schemas can themselves be described using JSON Schemas. A self- + describing JSON Schema for the core JSON Schema can be found at + http://json-schema.org/schema for the latest version or + http://json-schema.org/draft-03/schema for the draft-03 version. The + hyper schema self-description can be found at + http://json-schema.org/hyper-schema or + http://json-schema.org/draft-03/hyper-schema. All schemas used + within a protocol with media type definitions SHOULD include a MIME + parameter that refers to the self-descriptive hyper schema or another + schema that extends this hyper schema: + + Content-Type: application/json; + profile=http://json-schema.org/draft-03/hyper-schema + +5. Core Schema Definition + + A JSON Schema is a JSON Object that defines various attributes + (including usage and valid values) of a JSON value. JSON Schema has + recursive capabilities; there are a number of elements in the + structure that allow for nested JSON Schemas. + + An example JSON Schema definition could look like: + + + + + +Zyp & Court Expires May 26, 2011 [Page 7] + +Internet-Draft JSON Schema Media Type November 2010 + + + { + "description":"A person", + "type":"object", + + "properties":{ + "name":{"type":"string"}, + "age" :{ + "type":"integer", + "maximum":125 + } + } + } + + A JSON Schema object may have any of the following properties, called + schema attributes (all attributes are optional): + +5.1. type + + This attribute defines what the primitive type or the schema of the + instance MUST be in order to validate. This attribute can take one + of two forms: + + Simple Types A string indicating a primitive or simple type. The + following are acceptable string values: + + string Value MUST be a string. + + number Value MUST be a number, floating point numbers are + allowed. + + integer Value MUST be an integer, no floating point numbers are + allowed. This is a subset of the number type. + + boolean Value MUST be a boolean. + + object Value MUST be an object. + + array Value MUST be an array. + + null Value MUST be null. Note this is mainly for purpose of + being able use union types to define nullability. If this type + is not included in a union, null values are not allowed (the + primitives listed above do not allow nulls on their own). + + any Value MAY be of any type including null. + + If the property is not defined or is not in this list, then any + type of value is acceptable. Other type values MAY be used for + + + +Zyp & Court Expires May 26, 2011 [Page 8] + +Internet-Draft JSON Schema Media Type November 2010 + + + custom purposes, but minimal validators of the specification + implementation can allow any instance value on unknown type + values. + + Union Types An array of two or more simple type definitions. Each + item in the array MUST be a simple type definition or a schema. + The instance value is valid if it is of the same type as one of + the simple type definitions, or valid by one of the schemas, in + the array. + + For example, a schema that defines if an instance can be a string or + a number would be: + + {"type":["string","number"]} + +5.2. properties + + This attribute is an object with property definitions that define the + valid values of instance object property values. When the instance + value is an object, the property values of the instance object MUST + conform to the property definitions in this object. In this object, + each property definition's value MUST be a schema, and the property's + name MUST be the name of the instance property that it defines. The + instance property value MUST be valid according to the schema from + the property definition. Properties are considered unordered, the + order of the instance properties MAY be in any order. + +5.3. patternProperties + + This attribute is an object that defines the schema for a set of + property names of an object instance. The name of each property of + this attribute's object is a regular expression pattern in the ECMA + 262/Perl 5 format, while the value is a schema. If the pattern + matches the name of a property on the instance object, the value of + the instance's property MUST be valid against the pattern name's + schema value. + +5.4. additionalProperties + + This attribute defines a schema for all properties that are not + explicitly defined in an object type definition. If specified, the + value MUST be a schema or a boolean. If false is provided, no + additional properties are allowed beyond the properties defined in + the schema. The default value is an empty schema which allows any + value for additional properties. + + + + + + +Zyp & Court Expires May 26, 2011 [Page 9] + +Internet-Draft JSON Schema Media Type November 2010 + + +5.5. items + + This attribute defines the allowed items in an instance array, and + MUST be a schema or an array of schemas. The default value is an + empty schema which allows any value for items in the instance array. + + When this attribute value is a schema and the instance value is an + array, then all the items in the array MUST be valid according to the + schema. + + When this attribute value is an array of schemas and the instance + value is an array, each position in the instance array MUST conform + to the schema in the corresponding position for this array. This + called tuple typing. When tuple typing is used, additional items are + allowed, disallowed, or constrained by the "additionalItems" + (Section 5.6) attribute using the same rules as + "additionalProperties" (Section 5.4) for objects. + +5.6. additionalItems + + This provides a definition for additional items in an array instance + when tuple definitions of the items is provided. This can be false + to indicate additional items in the array are not allowed, or it can + be a schema that defines the schema of the additional items. + +5.7. required + + This attribute indicates if the instance must have a value, and not + be undefined. This is false by default, making the instance + optional. + +5.8. dependencies + + This attribute is an object that defines the requirements of a + property on an instance object. If an object instance has a property + with the same name as a property in this attribute's object, then the + instance must be valid against the attribute's property value + (hereafter referred to as the "dependency value"). + + The dependency value can take one of two forms: + + Simple Dependency If the dependency value is a string, then the + instance object MUST have a property with the same name as the + dependency value. If the dependency value is an array of strings, + then the instance object MUST have a property with the same name + as each string in the dependency value's array. + + + + + +Zyp & Court Expires May 26, 2011 [Page 10] + +Internet-Draft JSON Schema Media Type November 2010 + + + Schema Dependency If the dependency value is a schema, then the + instance object MUST be valid against the schema. + +5.9. minimum + + This attribute defines the minimum value of the instance property + when the type of the instance value is a number. + +5.10. maximum + + This attribute defines the maximum value of the instance property + when the type of the instance value is a number. + +5.11. exclusiveMinimum + + This attribute indicates if the value of the instance (if the + instance is a number) can not equal the number defined by the + "minimum" attribute. This is false by default, meaning the instance + value can be greater then or equal to the minimum value. + +5.12. exclusiveMaximum + + This attribute indicates if the value of the instance (if the + instance is a number) can not equal the number defined by the + "maximum" attribute. This is false by default, meaning the instance + value can be less then or equal to the maximum value. + +5.13. minItems + + This attribute defines the minimum number of values in an array when + the array is the instance value. + +5.14. maxItems + + This attribute defines the maximum number of values in an array when + the array is the instance value. + +5.15. uniqueItems + + This attribute indicates that all items in an array instance MUST be + unique (contains no two identical values). + + Two instance are consider equal if they are both of the same type + and: + + are null; or + + + + + +Zyp & Court Expires May 26, 2011 [Page 11] + +Internet-Draft JSON Schema Media Type November 2010 + + + are booleans/numbers/strings and have the same value; or + + are arrays, contains the same number of items, and each item in + the array is equal to the corresponding item in the other array; + or + + are objects, contains the same property names, and each property + in the object is equal to the corresponding property in the other + object. + +5.16. pattern + + When the instance value is a string, this provides a regular + expression that a string instance MUST match in order to be valid. + Regular expressions SHOULD follow the regular expression + specification from ECMA 262/Perl 5 + +5.17. minLength + + When the instance value is a string, this defines the minimum length + of the string. + +5.18. maxLength + + When the instance value is a string, this defines the maximum length + of the string. + +5.19. enum + + This provides an enumeration of all possible values that are valid + for the instance property. This MUST be an array, and each item in + the array represents a possible value for the instance value. If + this attribute is defined, the instance value MUST be one of the + values in the array in order for the schema to be valid. Comparison + of enum values uses the same algorithm as defined in "uniqueItems" + (Section 5.15). + +5.20. default + + This attribute defines the default value of the instance when the + instance is undefined. + +5.21. title + + This attribute is a string that provides a short description of the + instance property. + + + + + +Zyp & Court Expires May 26, 2011 [Page 12] + +Internet-Draft JSON Schema Media Type November 2010 + + +5.22. description + + This attribute is a string that provides a full description of the of + purpose the instance property. + +5.23. format + + This property defines the type of data, content type, or microformat + to be expected in the instance property values. A format attribute + MAY be one of the values listed below, and if so, SHOULD adhere to + the semantics describing for the format. A format SHOULD only be + used to give meaning to primitive types (string, integer, number, or + boolean). Validators MAY (but are not required to) validate that the + instance values conform to a format. The following formats are + predefined: + + date-time This SHOULD be a date in ISO 8601 format of YYYY-MM- + DDThh:mm:ssZ in UTC time. This is the recommended form of date/ + timestamp. + + date This SHOULD be a date in the format of YYYY-MM-DD. It is + recommended that you use the "date-time" format instead of "date" + unless you need to transfer only the date part. + + time This SHOULD be a time in the format of hh:mm:ss. It is + recommended that you use the "date-time" format instead of "time" + unless you need to transfer only the time part. + + utc-millisec This SHOULD be the difference, measured in + milliseconds, between the specified time and midnight, 00:00 of + January 1, 1970 UTC. The value SHOULD be a number (integer or + float). + + regex A regular expression, following the regular expression + specification from ECMA 262/Perl 5. + + color This is a CSS color (like "#FF0000" or "red"), based on CSS + 2.1 [W3C.CR-CSS21-20070719]. + + style This is a CSS style definition (like "color: red; background- + color:#FFF"), based on CSS 2.1 [W3C.CR-CSS21-20070719]. + + phone This SHOULD be a phone number (format MAY follow E.123). + + uri This value SHOULD be a URI.. + + + + + + +Zyp & Court Expires May 26, 2011 [Page 13] + +Internet-Draft JSON Schema Media Type November 2010 + + + email This SHOULD be an email address. + + ip-address This SHOULD be an ip version 4 address. + + ipv6 This SHOULD be an ip version 6 address. + + host-name This SHOULD be a host-name. + + Additional custom formats MAY be created. These custom formats MAY + be expressed as an URI, and this URI MAY reference a schema of that + format. + +5.24. divisibleBy + + This attribute defines what value the number instance must be + divisible by with no remainder (the result of the division must be an + integer.) The value of this attribute SHOULD NOT be 0. + +5.25. disallow + + This attribute takes the same values as the "type" attribute, however + if the instance matches the type or if this value is an array and the + instance matches any type or schema in the array, then this instance + is not valid. + +5.26. extends + + The value of this property MUST be another schema which will provide + a base schema which the current schema will inherit from. The + inheritance rules are such that any instance that is valid according + to the current schema MUST be valid according to the referenced + schema. This MAY also be an array, in which case, the instance MUST + be valid for all the schemas in the array. A schema that extends + another schema MAY define additional attributes, constrain existing + attributes, or add other constraints. + + Conceptually, the behavior of extends can be seen as validating an + instance against all constraints in the extending schema as well as + the extended schema(s). More optimized implementations that merge + schemas are possible, but are not required. An example of using + "extends": + + { + "description":"An adult", + "properties":{"age":{"minimum": 21}}, + "extends":"person" + } + + + + +Zyp & Court Expires May 26, 2011 [Page 14] + +Internet-Draft JSON Schema Media Type November 2010 + + + { + "description":"Extended schema", + "properties":{"deprecated":{"type": "boolean"}}, + "extends":"http://json-schema.org/draft-03/schema" + } + +5.27. id + + This attribute defines the current URI of this schema (this attribute + is effectively a "self" link). This URI MAY be relative or absolute. + If the URI is relative it is resolved against the current URI of the + parent schema it is contained in. If this schema is not contained in + any parent schema, the current URI of the parent schema is held to be + the URI under which this schema was addressed. If id is missing, the + current URI of a schema is defined to be that of the parent schema. + The current URI of the schema is also used to construct relative + references such as for $ref. + +5.28. $ref + + This attribute defines a URI of a schema that contains the full + representation of this schema. When a validator encounters this + attribute, it SHOULD replace the current schema with the schema + referenced by the value's URI (if known and available) and re- + validate the instance. This URI MAY be relative or absolute, and + relative URIs SHOULD be resolved against the URI of the current + schema. + +5.29. $schema + + This attribute defines a URI of a JSON Schema that is the schema of + the current schema. When this attribute is defined, a validator + SHOULD use the schema referenced by the value's URI (if known and + available) when resolving Hyper Schema (Section 6) links + (Section 6.1). + + A validator MAY use this attribute's value to determine which version + of JSON Schema the current schema is written in, and provide the + appropriate validation features and behavior. Therefore, it is + RECOMMENDED that all schema authors include this attribute in their + schemas to prevent conflicts with future JSON Schema specification + changes. + +6. Hyper Schema + + The following attributes are specified in addition to those + attributes that already provided by the core schema with the specific + purpose of informing user agents of relations between resources based + + + +Zyp & Court Expires May 26, 2011 [Page 15] + +Internet-Draft JSON Schema Media Type November 2010 + + + on JSON data. Just as with JSON schema attributes, all the + attributes in hyper schemas are optional. Therefore, an empty object + is a valid (non-informative) schema, and essentially describes plain + JSON (no constraints on the structures). Addition of attributes + provides additive information for user agents. + +6.1. links + + The value of the links property MUST be an array, where each item in + the array is a link description object which describes the link + relations of the instances. + +6.1.1. Link Description Object + + A link description object is used to describe link relations. In the + context of a schema, it defines the link relations of the instances + of the schema, and can be parameterized by the instance values. The + link description format can be used on its own in regular (non-schema + documents), and use of this format can be declared by referencing the + normative link description schema as the the schema for the data + structure that uses the links. The URI of the normative link + description schema is: http://json-schema.org/links (latest version) + or http://json-schema.org/draft-03/links (draft-03 version). + +6.1.1.1. href + + The value of the "href" link description property indicates the + target URI of the related resource. The value of the instance + property SHOULD be resolved as a URI-Reference per RFC 3986 [RFC3986] + and MAY be a relative URI. The base URI to be used for relative + resolution SHOULD be the URI used to retrieve the instance object + (not the schema) when used within a schema. Also, when links are + used within a schema, the URI SHOULD be parametrized by the property + values of the instance object, if property values exist for the + corresponding variables in the template (otherwise they MAY be + provided from alternate sources, like user input). + + Instance property values SHOULD be substituted into the URIs where + matching braces ('{', '}') are found surrounding zero or more + characters, creating an expanded URI. Instance property value + substitutions are resolved by using the text between the braces to + denote the property name from the instance to get the value to + substitute. For example, if an href value is defined: + + http://somesite.com/{id} + + Then it would be resolved by replace the value of the "id" property + value from the instance object. If the value of the "id" property + + + +Zyp & Court Expires May 26, 2011 [Page 16] + +Internet-Draft JSON Schema Media Type November 2010 + + + was "45", the expanded URI would be: + + http://somesite.com/45 + + If matching braces are found with the string "@" (no quotes) between + the braces, then the actual instance value SHOULD be used to replace + the braces, rather than a property value. This should only be used + in situations where the instance is a scalar (string, boolean, or + number), and not for objects or arrays. + +6.1.1.2. rel + + The value of the "rel" property indicates the name of the relation to + the target resource. The relation to the target SHOULD be + interpreted as specifically from the instance object that the schema + (or sub-schema) applies to, not just the top level resource that + contains the object within its hierarchy. If a resource JSON + representation contains a sub object with a property interpreted as a + link, that sub-object holds the relation with the target. A relation + to target from the top level resource MUST be indicated with the + schema describing the top level JSON representation. + + Relationship definitions SHOULD NOT be media type dependent, and + users are encouraged to utilize existing accepted relation + definitions, including those in existing relation registries (see RFC + 4287 [RFC4287]). However, we define these relations here for clarity + of normative interpretation within the context of JSON hyper schema + defined relations: + + self If the relation value is "self", when this property is + encountered in the instance object, the object represents a + resource and the instance object is treated as a full + representation of the target resource identified by the specified + URI. + + full This indicates that the target of the link is the full + representation for the instance object. The object that contains + this link possibly may not be the full representation. + + describedby This indicates the target of the link is the schema for + the instance object. This MAY be used to specifically denote the + schemas of objects within a JSON object hierarchy, facilitating + polymorphic type data structures. + + root This relation indicates that the target of the link SHOULD be + treated as the root or the body of the representation for the + purposes of user agent interaction or fragment resolution. All + other properties of the instance objects can be regarded as meta- + + + +Zyp & Court Expires May 26, 2011 [Page 17] + +Internet-Draft JSON Schema Media Type November 2010 + + + data descriptions for the data. + + The following relations are applicable for schemas (the schema as the + "from" resource in the relation): + + instances This indicates the target resource that represents + collection of instances of a schema. + + create This indicates a target to use for creating new instances of + a schema. This link definition SHOULD be a submission link with a + non-safe method (like POST). + + For example, if a schema is defined: + + { + "links": [ + { + "rel": "self" + "href": "{id}" + }, + { + "rel": "up" + "href": "{upId}" + }, + { + "rel": "children" + "href": "?upId={id}" + } + ] + } + + And if a collection of instance resource's JSON representation was + retrieved: + + GET /Resource/ + + [ + { + "id": "thing", + "upId": "parent" + }, + { + "id": "thing2", + "upId": "parent" + } + ] + + This would indicate that for the first item in the collection, its + + + +Zyp & Court Expires May 26, 2011 [Page 18] + +Internet-Draft JSON Schema Media Type November 2010 + + + own (self) URI would resolve to "/Resource/thing" and the first + item's "up" relation SHOULD be resolved to the resource at + "/Resource/parent". The "children" collection would be located at + "/Resource/?upId=thing". + +6.1.1.3. targetSchema + + This property value is a schema that defines the expected structure + of the JSON representation of the target of the link. + +6.1.1.4. Submission Link Properties + + The following properties also apply to link definition objects, and + provide functionality analogous to HTML forms, in providing a means + for submitting extra (often user supplied) information to send to a + server. + +6.1.1.4.1. method + + This attribute defines which method can be used to access the target + resource. In an HTTP environment, this would be "GET" or "POST" + (other HTTP methods such as "PUT" and "DELETE" have semantics that + are clearly implied by accessed resources, and do not need to be + defined here). This defaults to "GET". + +6.1.1.4.2. enctype + + If present, this property indicates a query media type format that + the server supports for querying or posting to the collection of + instances at the target resource. The query can be suffixed to the + target URI to query the collection with property-based constraints on + the resources that SHOULD be returned from the server or used to post + data to the resource (depending on the method). For example, with + the following schema: + + { + "links":[ + { + "enctype":"application/x-www-form-urlencoded", + "method":"GET", + "href":"/Product/", + "properties":{ + "name":{"description":"name of the product"} + } + } + ] + } + + + + +Zyp & Court Expires May 26, 2011 [Page 19] + +Internet-Draft JSON Schema Media Type November 2010 + + + This indicates that the client can query the server for instances + that have a specific name: + + /Product/?name=Slinky + + If no enctype or method is specified, only the single URI specified + by the href property is defined. If the method is POST, + "application/json" is the default media type. + +6.1.1.4.3. schema + + This attribute contains a schema which defines the acceptable + structure of the submitted request (for a GET request, this schema + would define the properties for the query string and for a POST + request, this would define the body). + +6.2. fragmentResolution + + This property indicates the fragment resolution protocol to use for + resolving fragment identifiers in URIs within the instance + representations. This applies to the instance object URIs and all + children of the instance object's URIs. The default fragment + resolution protocol is "slash-delimited", which is defined below. + Other fragment resolution protocols MAY be used, but are not defined + in this document. + + The fragment identifier is based on RFC 2396, Sec 5 [RFC2396], and + defines the mechanism for resolving references to entities within a + document. + +6.2.1. slash-delimited fragment resolution + + With the slash-delimited fragment resolution protocol, the fragment + identifier is interpreted as a series of property reference tokens + that start with and are delimited by the "/" character (\x2F). Each + property reference token is a series of unreserved or escaped URI + characters. Each property reference token SHOULD be interpreted, + starting from the beginning of the fragment identifier, as a path + reference in the target JSON structure. The final target value of + the fragment can be determined by starting with the root of the JSON + structure from the representation of the resource identified by the + pre-fragment URI. If the target is a JSON object, then the new + target is the value of the property with the name identified by the + next property reference token in the fragment. If the target is a + JSON array, then the target is determined by finding the item in + array the array with the index defined by the next property reference + token (which MUST be a number). The target is successively updated + for each property reference token, until the entire fragment has been + + + +Zyp & Court Expires May 26, 2011 [Page 20] + +Internet-Draft JSON Schema Media Type November 2010 + + + traversed. + + Property names SHOULD be URI-encoded. In particular, any "/" in a + property name MUST be encoded to avoid being interpreted as a + property delimiter. + + For example, for the following JSON representation: + + { + "foo":{ + "anArray":[ + {"prop":44} + ], + "another prop":{ + "baz":"A string" + } + } + } + + The following fragment identifiers would be resolved: + + fragment identifier resolution + ------------------- ---------- + # self, the root of the resource itself + #/foo the object referred to by the foo property + #/foo/another%20prop the object referred to by the "another prop" + property of the object referred to by the + "foo" property + #/foo/another%20prop/baz the string referred to by the value of "baz" + property of the "another prop" property of + the object referred to by the "foo" property + #/foo/anArray/0 the first object in the "anArray" array + +6.2.2. dot-delimited fragment resolution + + The dot-delimited fragment resolution protocol is the same as slash- + delimited fragment resolution protocol except that the "." character + (\x2E) is used as the delimiter between property names (instead of + "/") and the path does not need to start with a ".". For example, + #.foo and #foo are a valid fragment identifiers for referencing the + value of the foo propery. + +6.3. readonly + + This attribute indicates that the instance property SHOULD NOT be + changed. Attempts by a user agent to modify the value of this + property are expected to be rejected by a server. + + + + +Zyp & Court Expires May 26, 2011 [Page 21] + +Internet-Draft JSON Schema Media Type November 2010 + + +6.4. contentEncoding + + If the instance property value is a string, this attribute defines + that the string SHOULD be interpreted as binary data and decoded + using the encoding named by this schema property. RFC 2045, Sec 6.1 + [RFC2045] lists the possible values for this property. + +6.5. pathStart + + This attribute is a URI that defines what the instance's URI MUST + start with in order to validate. The value of the "pathStart" + attribute MUST be resolved as per RFC 3986, Sec 5 [RFC3986], and is + relative to the instance's URI. + + When multiple schemas have been referenced for an instance, the user + agent can determine if this schema is applicable for a particular + instance by determining if the URI of the instance begins with the + the value of the "pathStart" attribute. If the URI of the instance + does not start with this URI, or if another schema specifies a + starting URI that is longer and also matches the instance, this + schema SHOULD NOT be applied to the instance. Any schema that does + not have a pathStart attribute SHOULD be considered applicable to all + the instances for which it is referenced. + +6.6. mediaType + + This attribute defines the media type of the instance representations + that this schema is defining. + +7. Security Considerations + + This specification is a sub-type of the JSON format, and consequently + the security considerations are generally the same as RFC 4627 + [RFC4627]. However, an additional issue is that when link relation + of "self" is used to denote a full representation of an object, the + user agent SHOULD NOT consider the representation to be the + authoritative representation of the resource denoted by the target + URI if the target URI is not equivalent to or a sub-path of the the + URI used to request the resource representation which contains the + target URI with the "self" link. For example, if a hyper schema was + defined: + + + + + + + + + + +Zyp & Court Expires May 26, 2011 [Page 22] + +Internet-Draft JSON Schema Media Type November 2010 + + + { + "links":[ + { + "rel":"self", + "href":"{id}" + } + ] + } + + And a resource was requested from somesite.com: + + GET /foo/ + + With a response of: + +Content-Type: application/json; profile=/schema-for-this-data +[ + {"id":"bar", "name":"This representation can be safely treated \ + as authoritative "}, + {"id":"/baz", "name":"This representation should not be treated as \ + authoritative the user agent should make request the resource\ + from "/baz" to ensure it has the authoritative representation"}, + {"id":"http://othersite.com/something", "name":"This representation\ + should also not be treated as authoritative and the target\ + resource representation should be retrieved for the\ + authoritative representation"} +] + +8. IANA Considerations + + The proposed MIME media type for JSON Schema is "application/ + schema+json". + + Type name: application + + Subtype name: schema+json + + Required parameters: profile + + The value of the profile parameter SHOULD be a URI (relative or + absolute) that refers to the schema used to define the structure of + this structure (the meta-schema). Normally the value would be + http://json-schema.org/draft-03/hyper-schema, but it is allowable to + use other schemas that extend the hyper schema's meta- schema. + + Optional parameters: pretty + + The value of the pretty parameter MAY be true or false to indicate if + + + +Zyp & Court Expires May 26, 2011 [Page 23] + +Internet-Draft JSON Schema Media Type November 2010 + + + additional whitespace has been included to make the JSON + representation easier to read. + +8.1. Registry of Link Relations + + This registry is maintained by IANA per RFC 4287 [RFC4287] and this + specification adds four values: "full", "create", "instances", + "root". New assignments are subject to IESG Approval, as outlined in + RFC 5226 [RFC5226]. Requests should be made by email to IANA, which + will then forward the request to the IESG, requesting approval. + +9. References + +9.1. Normative References + + [RFC2045] Freed, N. and N. Borenstein, + "Multipurpose Internet Mail + Extensions (MIME) Part One: Format + of Internet Message Bodies", + RFC 2045, November 1996. + + [RFC2119] Bradner, S., "Key words for use in + RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, + March 1997. + + [RFC2396] Berners-Lee, T., Fielding, R., and + L. Masinter, "Uniform Resource + Identifiers (URI): Generic + Syntax", RFC 2396, August 1998. + + [RFC3339] Klyne, G., Ed. and C. Newman, + "Date and Time on the Internet: + Timestamps", RFC 3339, July 2002. + + [RFC3986] Berners-Lee, T., Fielding, R., and + L. Masinter, "Uniform Resource + Identifier (URI): Generic Syntax", + STD 66, RFC 3986, January 2005. + + [RFC4287] Nottingham, M., Ed. and R. Sayre, + Ed., "The Atom Syndication + Format", RFC 4287, December 2005. + +9.2. Informative References + + [RFC2616] Fielding, R., Gettys, J., Mogul, + J., Frystyk, H., Masinter, L., + + + +Zyp & Court Expires May 26, 2011 [Page 24] + +Internet-Draft JSON Schema Media Type November 2010 + + + Leach, P., and T. Berners-Lee, + "Hypertext Transfer Protocol -- + HTTP/1.1", RFC 2616, June 1999. + + [RFC4627] Crockford, D., "The application/ + json Media Type for JavaScript + Object Notation (JSON)", RFC 4627, + July 2006. + + [RFC5226] Narten, T. and H. Alvestrand, + "Guidelines for Writing an IANA + Considerations Section in RFCs", + BCP 26, RFC 5226, May 2008. + + [I-D.hammer-discovery] Hammer-Lahav, E., "LRDD: Link- + based Resource Descriptor + Discovery", + draft-hammer-discovery-06 (work in + progress), May 2010. + + [I-D.gregorio-uritemplate] Gregorio, J., Fielding, R., + Hadley, M., and M. Nottingham, + "URI Template", + draft-gregorio-uritemplate-04 + (work in progress), March 2010. + + [I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", dra + ft-nottingham-http-link-header-10 + (work in progress), May 2010. + + [W3C.REC-html401-19991224] Raggett, D., Hors, A., and I. + Jacobs, "HTML 4.01 Specification", + World Wide Web Consortium Recommen + dation REC-html401-19991224, + December 1999, . + + [W3C.CR-CSS21-20070719] Hickson, I., Lie, H., Celik, T., + and B. Bos, "Cascading Style + Sheets Level 2 Revision 1 (CSS + 2.1) Specification", World Wide + Web Consortium CR CR-CSS21- + 20070719, July 2007, . + + + + + + +Zyp & Court Expires May 26, 2011 [Page 25] + +Internet-Draft JSON Schema Media Type November 2010 + + +Appendix A. Change Log + + draft-03 + + * Added example and verbiage to "extends" attribute. + + * Defined slash-delimited to use a leading slash. + + * Made "root" a relation instead of an attribute. + + * Removed address values, and MIME media type from format to + reduce confusion (mediaType already exists, so it can be used + for MIME types). + + * Added more explanation of nullability. + + * Removed "alternate" attribute. + + * Upper cased many normative usages of must, may, and should. + + * Replaced the link submission "properties" attribute to "schema" + attribute. + + * Replaced "optional" attribute with "required" attribute. + + * Replaced "maximumCanEqual" attribute with "exclusiveMaximum" + attribute. + + * Replaced "minimumCanEqual" attribute with "exclusiveMinimum" + attribute. + + * Replaced "requires" attribute with "dependencies" attribute. + + * Moved "contentEncoding" attribute to hyper schema. + + * Added "additionalItems" attribute. + + * Added "id" attribute. + + * Switched self-referencing variable substitution from "-this" to + "@" to align with reserved characters in URI template. + + * Added "patternProperties" attribute. + + * Schema URIs are now namespace versioned. + + * Added "$ref" and "$schema" attributes. + + + + +Zyp & Court Expires May 26, 2011 [Page 26] + +Internet-Draft JSON Schema Media Type November 2010 + + + draft-02 + + * Replaced "maxDecimal" attribute with "divisibleBy" attribute. + + * Added slash-delimited fragment resolution protocol and made it + the default. + + * Added language about using links outside of schemas by + referencing its normative URI. + + * Added "uniqueItems" attribute. + + * Added "targetSchema" attribute to link description object. + + draft-01 + + * Fixed category and updates from template. + + draft-00 + + * Initial draft. + +Appendix B. Open Issues + + Should we give a preference to MIME headers over Link headers (or + only use one)? + + Should "root" be a MIME parameter? + + Should "format" be renamed to "mediaType" or "contentType" to + reflect the usage MIME media types that are allowed? + + How should dates be handled? + +Authors' Addresses + + Kris Zyp (editor) + SitePen (USA) + 530 Lytton Avenue + Palo Alto, CA 94301 + USA + + Phone: +1 650 968 8787 + EMail: kris@sitepen.com + + + + + + + +Zyp & Court Expires May 26, 2011 [Page 27] + +Internet-Draft JSON Schema Media Type November 2010 + + + Gary Court + Calgary, AB + Canada + + EMail: gary.court@gmail.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zyp & Court Expires May 26, 2011 [Page 28] + + diff --git a/geo b/geo new file mode 100644 index 0000000..73a9851 --- /dev/null +++ b/geo @@ -0,0 +1,7 @@ +{"description":"A geographical coordinate", + "type":"object", + "properties":{ + "latitude":{"type":"number"}, + "longitude":{"type":"number"} + } +} \ No newline at end of file diff --git a/geo-v2 b/geo-v2 new file mode 100644 index 0000000..73a9851 --- /dev/null +++ b/geo-v2 @@ -0,0 +1,7 @@ +{"description":"A geographical coordinate", + "type":"object", + "properties":{ + "latitude":{"type":"number"}, + "longitude":{"type":"number"} + } +} \ No newline at end of file diff --git a/geo.properties b/geo.properties new file mode 100644 index 0000000..3449cd0 --- /dev/null +++ b/geo.properties @@ -0,0 +1,4 @@ +{ +"latitude":{"type":"number"}, +"longitude":{"type":"number"} +} diff --git a/hyper-schema b/hyper-schema new file mode 100644 index 0000000..3fedec1 --- /dev/null +++ b/hyper-schema @@ -0,0 +1,107 @@ +{ + "id" : "http://json-schema.org/hyper-schema", + + "properties" : { + "links" : { + "type" : "array", + "items" : "http://json-schema.org/links" + }, + + "fragmentResolution" : { + "type" : "string", + "default" : "slash-delimited" + }, + + "root" : { + "type" : "boolean", + "default" : false + }, + + "readonly" : { + "type" : "boolean", + "default" : false + }, + + "pathStart" : { + "type" : "string", + "format" : "uri" + }, + + "mediaType" : { + "type" : "string", + "format" : "media-type" + }, + + "alternate" : { + "type" : "array", + "items" : "http://json-schema.org/hyper-schema-or-uri" + }, + + "type" : { + "type" : ["string", "array"], + "items" : { + "type" : ["string", "http://json-schema.org/hyper-schema-or-uri"] + }, + "uniqueItems" : true, + "default" : "any" + }, + + "properties" : { + "type" : "object", + "additionalProperties" : "http://json-schema.org/hyper-schema-or-uri", + "default" : {} + }, + + "items" : { + "type" : ["http://json-schema.org/hyper-schema-or-uri", "array"], + "items" : "http://json-schema.org/hyper-schema-or-uri", + "default" : {} + }, + "additionalProperties" : { + "type" : ["http://json-schema.org/hyper-schema-or-uri", "boolean"], + "default" : {} + }, + "additionalItems" : { + "type" : ["http://json-schema.org/hyper-schema-or-uri", "boolean"], + "default" : {} + }, + "contentEncoding" : { + "type" : "string" + }, + + "default" : { + }, + + "requires" : { + "type" : ["string", "http://json-schema.org/hyper-schema-or-uri"] + }, + "disallow" : { + "type" : ["string", "array", "http://json-schema.org/hyper-schema-or-uri"], + "items" : { + "type" : ["string", "http://json-schema.org/hyper-schema-or-uri"] + }, + "uniqueItems" : true + }, + "extends" : { + "type" : ["http://json-schema.org/hyper-schema-or-uri", "array"], + "items" : "http://json-schema.org/hyper-schema-or-uri", + "default" : {} + } + + }, + + "links" : [ + { + "href" : "{$schema}", + "rel" : "describedby" + }, + + { + "href" : "{$ref}", + "rel" : "full" + } + ], + + "fragmentResolution" : "dot-delimited", + "extends" : "http://json-schema.org/schema" +} \ No newline at end of file diff --git a/hyper-schema-or-uri b/hyper-schema-or-uri new file mode 100644 index 0000000..8d2a3c1 --- /dev/null +++ b/hyper-schema-or-uri @@ -0,0 +1,10 @@ +{ + "id" : "http://json-schema.org/hyper-schema-or-uri", + "type" : [{ + "type": "string", + "links": [{ + "rel": "full", + "href": "{@}" + }]}, + "http://json-schema.org/hyper-schema"] +} \ No newline at end of file diff --git a/hyper-schema-v2 b/hyper-schema-v2 new file mode 100644 index 0000000..b995b83 --- /dev/null +++ b/hyper-schema-v2 @@ -0,0 +1,68 @@ +{ + "$schema" : "http://json-schema.org/hyper-schema#", + "id" : "http://json-schema.org/hyper-schema#", + + "properties" : { + "links" : { + "type" : "array", + "items" : {"$ref" : "http://json-schema.org/links#"}, + "optional" : true + }, + + "fragmentResolution" : { + "type" : "string", + "optional" : true, + "default" : "slash-delimited" + }, + + "root" : { + "type" : "boolean", + "optional" : true, + "default" : false + }, + + "readonly" : { + "type" : "boolean", + "optional" : true, + "default" : false + }, + + "pathStart" : { + "type" : "string", + "optional" : true, + "format" : "uri" + }, + + "mediaType" : { + "type" : "string", + "optional" : true, + "format" : "media-type" + }, + + "alternate" : { + "type" : "array", + "items" : {"$ref" : "#"}, + "optional" : true + } + }, + + "links" : [ + { + "href" : "{$ref}", + "rel" : "full" + }, + + { + "href" : "{$schema}", + "rel" : "describedby" + }, + + { + "href" : "{id}", + "rel" : "self" + } + ], + + "fragmentResolution" : "dot-delimited", + "extends" : {"$ref" : "http://json-schema.org/schema#"} +} \ No newline at end of file diff --git a/hypertextSchema b/hypertextSchema new file mode 100644 index 0000000..e4767e5 --- /dev/null +++ b/hypertextSchema @@ -0,0 +1,254 @@ +Content-Type: application/json; schema="#" +{ + "extends": {"href":"http://json-schema.org/schema"}, + "description": "A schema for schemas that define how hypertext information is interpreted from instance objects", + "schema": {"href":"#"}, + "hrefProperty":"href", + "properties":{ + "hrefProperty":{ + "type":"string", + "description":"This defines the name of the property that indicates a hyperlink. When this property is encountered in the instance object or any of it's child objects, the value of the property indicates target URI of the hyperlink and is resolved per RFC 1808. The object may include other properties providing a partial/summary representation of the target resource", + "optional":true, + "default":"href" + } + "locatorProperty":{ + "type":"string", + "description":"This defines the name of the property that indicates the location of the object. When this property is encountered in the instance object or any of it's child objects, the object represents a resource, whose URI is indicated by the value of the property and is resolved per RFC 1808. The object is treated as a full representation of the target resource", + "optional":true, + "default":"id" + }, + "data":{ + "type":"array", + "description":"This should refer to the collection of instances of this defined schema" + }, + "baseUrl":{ + "type":"string", + "description":"This defines the base URL to be used for resolving hyperlinks and locator property values. When this property is not present, the URL that was used to retrieve the representation of resource is used", + "optional":true + }, + "envelopeFor":{ + "type":"string", + "description":"This presence of this property indicates that the instance object is an envelope for the real representation of the resource. This defines the name of property that refers to the actual data of the real representation. All other properties of the instance object are considered metadata" + "optional": true, + "default": "data" + }, + "queryEncoding":{ + "type":"string", + "description":"This property indicates the query encoding format that should be used for querying the collection of instances", + "options":[ + {"name":"Form URL Encoded", "value": "application/x-www-form-urlencoded"}, + {"name":"JSONQuery URL Encoded", "value": "application/x-jsonquery-urlencoded"} + ], + "optional": true, + "default": "application/x-www-form-urlencoded" + }, + "versionProperty": + "type":"string", + "description":"This property indicates the version of the instance. Any modification to the instance must cause a change in the version value", + "optional": true + } + } +} + +restSchema +Content-Type: application/json; schema="http://json-schema.org/hyper-schema" +{ + "description": "A schema for providing RESTful metadata of resources", + "schema": {"href":"http://json-schema.org/hyper-schema"}, + "hrefProperty": "href", + "envelopeFor": "members", + "properties":{ + "version":{ + "description":"identifies this version of the collection" + }, + "type":{ + "description":"the media type of the members of this collection" + } + }, + "items":{ + "envelopeFor": "value", + "properties":{ + "precis":{ + "description":"A summary of the item" + } + } + } +} + + + +Kris Zyp wrote: +> Another thought, one could also approach the data-schema relationship +> from the other direction. That is, a user could access a schema first, +> and then access the data (instances of that schema) as a link from the +> schema, where the link relationship is "data" or "collection" . That is +> a schema could have: +> +> { +> "data":{"href":"/Project/"} # points to the collection of instances of this schema +> "metadata": { +> ... +> }, +> "properties":{ +> ... +> }, +> +> } +> This could easily be added to the schema since it is well-defined +> structure. One could even define the forward and reverse relationship in +> the schema: +> +> { +> "data":{"href":"/Project/", "schema":{"href":"#"}}, +> ... +> +> The advantage of this you wouldn't need to rely MIME-type parameters. However, referencing data instances from the schema and schemas from the data don't necessarily need to be mutually exclusive, and if data relies on a schema, not having a link may be an REST anti-pattern since it would prevent intelligible bookmarkability of data resources. +> +> From a hypertext navigation perspective, starting with a list of schemas as an entry point to JSON-based site makes a lot of sense, it allows users to see the structure and descriptions of the available data and then drill down into the actual data instances from there. +> Kris +> +> Kris Zyp wrote: +>> I wanted to propose another possible approach for defining a JSON +>> structure for RESTful interaction. I have previously suggested the +>> importance of unobtrusively allowing JSON to preserve to it's natural +>> structure within a RESTful architecture; alternate JSON media sub-types +>> and structures should certainly be usable within a JSON-base REST +>> architecture, as alternate media-types are a core aspect of REST. At the +>> same time, others have expressed the desire to be able to include +>> resource metadata within JSON data structures. Perhaps the best approach +>> would be rather than enforcing a certain structure for resource +>> metadata, allow JSON representations to define their own structure or +>> schema and ascribe their own meaning for the hierarchy of their +>> structure. A JSON Schema [1] definition of data could be used (which +>> also provides definitions of allowable data types, very useful for +>> modifying data) and augmented with resource metadata types that could be +>> assigned to different properties. Additionally, this would permit +>> servers to define their own properties to use for hyperlinks and +>> resource identification. I believe it is one of our goals that we should +>> make it easy as possible for existing implementations to become +>> interoperable without forcing them to create their own backwards +>> incompatibility issues. Essentially this approach would mean they we +>> would be creating a meta-specification for defining how to specify +>> RESTful JSON. +>> +>> There are several advantages to this approach: +>> 1. Maintain unobtrusive natural JSON representations. Servers can +>> describe the structure and meaning of their JSON in terms of how it maps +>> to REST concepts (URLs, content types, etc.), rather than being forced +>> to follow a certain structure. Virtually any JSON structure that +>> contains RESTful information can be understood by clients with modifying +>> the structure. Existing implementations can conform by providing a +>> schema (and pointing to it in the MIME parameter) without any +>> modification of their outputted data. +>> 2. We can include metadata within JSON representations without needing +>> separate content types +>> 3. JSON Schemas on their own are an invaluable resource for user agents +>> that may be modifying resources based on JSON representations. Schemas +>> can be used to user agents to understand what are valid values for +>> different properties and properly constrain and guide the user in +>> updating data. A schema can be central resource for guiding the user +>> agent in both property constraints as well understanding the REST +>> mappings of the properties. +>> +>> The main disadvantage is that it increases the complexity of user +>> agents, and what they must understand (they can't hardcode the property +>> names for references/links for example). +>> +>> There are a number of ways that one could specify the applicable schema +>> for a JSON representation, but like I had suggested with the "locator" +>> property, I believe a MIME type parameter is most appropriate since it +>> does not impose on the representation format. For example, an object +>> representation could look like: +>> +>> GET /Project/proposal +>> +>> Content-Type: application/project+json; schema="/projectSchema" +>> { +>> // metadata: +>> "type": "application/project+json", +>> "href": "proposal", +>> "id": "proposal", +>> // data: +>> "data": { +>> "projectOwner": { +>> // metadata: +>> "href": "/Person/kris", +>> "id":"kris", +>> // data: +>> "name":"Kris Zyp" +>> } +>> } +>> } +>> +>> And we could define a schema: +>> Content-Type: application/schema+json; +>> schema="http://json-schema.org/schema" +>> { +>> "metadata": { # mappings of our properties to REST metadata +>> "contentTypeProperty":"type", +>> "hrefProperty":"href" +>> }, +>> "envelopeFor": "data", # indicating that the value of the data is +>> the real representation +>> "properties":{ +>> "projectOwner":{ # schema for projectOwner values +>> "properties:"{ +>> "name":{"type":"string"} # this is a JSON Schema +>> property constraint (value must be a string) +>> } +>> } +>> } +>> } +>> +>> This schema provides all the information necessary for a user agent to +>> understand the properties of the instance (/Project/proposal). +>> +>> An example of a collection: +>> GET /Project/ +>> Content-Type: application/myapp+json; schema="/projectCollectionSchema" +>> { +>> "lastModified":"some date", +>> "members":[ +>> { +>> // metadata: +>> "type": "application/project+json", +>> "href": "proposal", +>> "id": "proposal", +>> .... +>> +>> ] +>> } +>> +>> And a schema for the collection: +>> GET /projectCollectionSchema +>> Content-Type: application/schema+json; +>> schema="http://json-schema.org/schema" +>> { +>> "metadata": { # mappings of our properties to REST metadata +>> "lastModifiedProperty":"lastModified" +>> }, +>> "envelopeFor": "members", # indicating that the value of the members +>> is the "real" representation +>> "items":{ # definition of the items in the array/collection +>> # hyperlink to the schema for each project object +>> # using the hyperlink property defined at +>> http://json-schema.org/schema +>> "$ref":"projectSchema" +>> } +>> } +>> +>> Additional definitions that could be provided in the schema (and not +>> shown in these examples) could be differenting between a URL property +>> that does provide a full object representation (locator) vs one that +>> points to another location to retrieve the data (href), and perhaps +>> includes a partial/summary representation. Also, a baseUrl could be +>> defined for subobjects to support leveraging existing identifier +>> properties in more complex URL schemes (like those used by Rails). +>> +>> Thanks, +>> Kris +>> +>> [1] http://json-schema.org and http://groups.google.com/group/json-schema +>> +>> +>> diff --git a/implementations.html b/implementations.html new file mode 100644 index 0000000..b90e9c1 --- /dev/null +++ b/implementations.html @@ -0,0 +1,22 @@ + + + JSON Schema Implementations + + +

JSON Schema Implementations:

+ + + \ No newline at end of file diff --git a/index.html b/index.html new file mode 100644 index 0000000..7fb0973 --- /dev/null +++ b/index.html @@ -0,0 +1,27 @@ + + +JSON Schema + + +

JSON Schema

+

Please see the JSON Schema Internet Draft for the latest specification. +

+

Schemas

+

The following are schemas that are available for referencing: +

    +
  • Core Meta-Schema - This is the meta-schema definition for schemas themselves (the type/validation part of schemas).
    • +
  • Hyper Meta-Schema - This is the extended full meta-schema definition for schemas with link definitions (hyper schemas).
    • +
  • JSON Referencing - This is the schema that defines a generic linking mechanism called JSON referencing (which is used by the meta-schema for links).
    • +
  • JSON Schema Interfaces - This is the meta-schema definition for schemas which define class-style method interfaces for programming languages.
    • +
  • Geographic Coordinate
    • +
  • Card - A schema for microformat style representation of a person, company, organization, or place.
    • +
  • Calendar - A schema for microformat style representation of an event.
    • +
  • Address - A schema for microformat style representation of an address.
    • +
+

+

Tools

+

A list of JSON Schema implementations can be found here.

+

Discussion

+

Discussion about usage and development of JSON Schema can be found at the json-schema google group.

+ + \ No newline at end of file diff --git a/interfaces b/interfaces new file mode 100644 index 0000000..c1c08fc --- /dev/null +++ b/interfaces @@ -0,0 +1,23 @@ +{ + "extends":"http://json-schema.org/hyper-schema", + "description":"A schema for schema interface definitions that describe programmatic class structures using JSON schema syntax", + "properties":{ + "methods":{ + "type":"object", + "description":"This defines the set of methods available to the class instances", + "additionalProperties":{ + "type":"object", + "description":"The definition of the method", + "properties":{ + "parameters":{ + "type":"array", + "description":"The set of parameters that should be passed to the method when it is called", + "items":"#", + "required": true + }, + "returns":"#" + } + } + } + } +} diff --git a/interfaces-v2 b/interfaces-v2 new file mode 100644 index 0000000..7118195 --- /dev/null +++ b/interfaces-v2 @@ -0,0 +1,23 @@ +{ + "extends":{"$ref":"http://json-schema.org/hyper-schema"}, + "description":"A schema for schema interface definitions that describe programmatic class structures using JSON schema syntax", + "properties":{ + "methods":{ + "type":"object", + "description":"This defines the set of methods available to the class instances", + "optional":true, + "additionalProperties":{ + "type":"object", + "description":"The definition of the method", + "properties":{ + "parameters":{ + "type":"array", + "description":"The set of parameters that should be passed to the method when it is called", + "items":{"$ref":"#"} + }, + "returns":{"$ref":"#"} + } + } + } + } +} diff --git a/json-ref b/json-ref new file mode 100644 index 0000000..323df0c --- /dev/null +++ b/json-ref @@ -0,0 +1,26 @@ +{ + "$schema" : "http://json-schema.org/hyper-schema", + "id" : "http://json-schema.org/json-ref", + + "items" : "#", + "additionalProperties" : "#", + + "links" : [ + { + "href" : "{$ref}", + "rel" : "full" + }, + + { + "href" : "{$schema}", + "rel" : "describedby" + }, + + { + "href" : "{id}", + "rel" : "self" + } + ], + + "fragmentResolution" : "dot-delimited" +} \ No newline at end of file diff --git a/json-ref-v2 b/json-ref-v2 new file mode 100644 index 0000000..9b12616 --- /dev/null +++ b/json-ref-v2 @@ -0,0 +1,26 @@ +{ + "$schema" : "http://json-schema.org/hyper-schema#", + "id" : "http://json-schema.org/json-ref#", + + "items" : {"$ref" : "#"}, + "additionalProperties" : {"$ref" : "#"}, + + "links" : [ + { + "href" : "{$ref}", + "rel" : "full" + }, + + { + "href" : "{$schema}", + "rel" : "describedby" + }, + + { + "href" : "{id}", + "rel" : "self" + } + ], + + "fragmentResolution" : "dot-delimited" +} \ No newline at end of file diff --git a/links b/links new file mode 100644 index 0000000..2704100 --- /dev/null +++ b/links @@ -0,0 +1,34 @@ +{ + "$schema" : "http://json-schema.org/hyper-schema", + "id" : "http://json-schema.org/links", + "type" : "object", + + "properties" : { + "href" : { + "type" : "string", + "required": true + }, + + "rel" : { + "type" : "string", + "required": true + }, + + "targetSchema" : "http://json-schema.org/hyper-schema", + + "method" : { + "type" : "string", + "default" : "GET" + }, + + "enctype" : { + "type" : "string", + "requires" : "method" + }, + + "properties" : { + "type" : "object", + "additionalProperties" : "http://json-schema.org/hyper-schema" + } + } +} \ No newline at end of file diff --git a/links-v2 b/links-v2 new file mode 100644 index 0000000..6989b6d --- /dev/null +++ b/links-v2 @@ -0,0 +1,35 @@ +{ + "$schema" : "http://json-schema.org/hyper-schema#", + "id" : "http://json-schema.org/links#", + "type" : "object", + + "properties" : { + "href" : { + "type" : "string" + }, + + "rel" : { + "type" : "string" + }, + + "targetSchema" : {"$ref" : "http://json-schema.org/hyper-schema#"}, + + "method" : { + "type" : "string", + "default" : "GET", + "optional" : true + }, + + "enctype" : { + "type" : "string", + "requires" : "method", + "optional" : true + }, + + "properties" : { + "type" : "object", + "additionalProperties" : {"$ref" : "http://json-schema.org/hyper-schema#"}, + "optional" : true + } + } +} \ No newline at end of file diff --git a/schema b/schema new file mode 100644 index 0000000..dd0d1ce --- /dev/null +++ b/schema @@ -0,0 +1,137 @@ +{ + "id" : "http://json-schema.org/schema#", + "type" : ["object","string"], + "format": "uri", + + "properties" : { + "type" : { + "type" : ["string", "array"], + "items" : { + "type" : ["string", "#"] + }, + "uniqueItems" : true, + "default" : "any" + }, + + "properties" : { + "type" : "object", + "additionalProperties" : "#", + "default" : {} + }, + + "items" : { + "type" : ["#", "array"], + "items" : "#", + "default" : {} + }, + + "required" : { + "type" : "boolean", + "default" : false + }, + + "additionalProperties" : { + "type" : ["#", "boolean"], + "default" : {} + }, + "additionalItems" : { + "type" : ["#", "boolean"], + "default" : {} + }, + + "requires" : { + "type" : ["string", "#"] + }, + + "minimum" : { + "type" : "number" + }, + + "maximum" : { + "type" : "number" + }, + + "exclusiveMinimum" : { + "type" : "number" + }, + + "exclusiveMaximum" : { + "type" : "number" + }, + + "minItems" : { + "type" : "integer", + "minimum" : 0, + "default" : 0 + }, + + "maxItems" : { + "type" : "integer" + }, + + "uniqueItems" : { + "type" : "boolean", + "default" : false + }, + + "pattern" : { + "type" : "string", + "format" : "regex" + }, + + "minLength" : { + "type" : "integer", + "minimum" : 0, + "default" : 0 + }, + + "maxLength" : { + "type" : "integer" + }, + + "enum" : { + "type" : "array", + "minItems" : 1, + "uniqueItems" : true + }, + + "title" : { + "type" : "string" + }, + + "description" : { + "type" : "string" + }, + + "format" : { + "type" : "string" + }, + + "maxDecimal" : { + "type" : "number", + "minimum" : 0 + }, + + "disallow" : { + "type" : ["string", "array", "#"], + "items" : { + "type" : ["string", "#"] + }, + "uniqueItems" : true + }, + + "extends" : { + "type" : ["#", "array"], + "items" : "#", + "default" : {} + } + }, + "links" : [ + { + "href" : "{id}", + "rel" : "self" + } + ], + + "default" : {} +} \ No newline at end of file diff --git a/schema-v2 b/schema-v2 new file mode 100644 index 0000000..f9d1a01 --- /dev/null +++ b/schema-v2 @@ -0,0 +1,165 @@ +{ + "$schema" : "http://json-schema.org/hyper-schema#", + "id" : "http://json-schema.org/schema#", + "type" : "object", + + "properties" : { + "type" : { + "type" : ["string", "array"], + "items" : { + "type" : ["string", {"$ref" : "#"}] + }, + "optional" : true, + "uniqueItems" : true, + "default" : "any" + }, + + "properties" : { + "type" : "object", + "additionalProperties" : {"$ref" : "#"}, + "optional" : true, + "default" : {} + }, + + "items" : { + "type" : [{"$ref" : "#"}, "array"], + "items" : {"$ref" : "#"}, + "optional" : true, + "default" : {} + }, + + "optional" : { + "type" : "boolean", + "optional" : true, + "default" : false + }, + + "additionalProperties" : { + "type" : [{"$ref" : "#"}, "boolean"], + "optional" : true, + "default" : {} + }, + + "requires" : { + "type" : ["string", {"$ref" : "#"}], + "optional" : true + }, + + "minimum" : { + "type" : "number", + "optional" : true + }, + + "maximum" : { + "type" : "number", + "optional" : true + }, + + "minimumCanEqual" : { + "type" : "boolean", + "optional" : true, + "requires" : "minimum", + "default" : true + }, + + "maximumCanEqual" : { + "type" : "boolean", + "optional" : true, + "requires" : "maximum", + "default" : true + }, + + "minItems" : { + "type" : "integer", + "optional" : true, + "minimum" : 0, + "default" : 0 + }, + + "maxItems" : { + "type" : "integer", + "optional" : true + }, + + "uniqueItems" : { + "type" : "boolean", + "optional" : true, + "default" : false + }, + + "pattern" : { + "type" : "string", + "optional" : true, + "format" : "regex" + }, + + "minLength" : { + "type" : "integer", + "optional" : true, + "minimum" : 0, + "default" : 0 + }, + + "maxLength" : { + "type" : "integer", + "optional" : true + }, + + "enum" : { + "type" : "array", + "optional" : true, + "minItems" : 1, + "uniqueItems" : true + }, + + "title" : { + "type" : "string", + "optional" : true + }, + + "description" : { + "type" : "string", + "optional" : true + }, + + "format" : { + "type" : "string", + "optional" : true + }, + + "contentEncoding" : { + "type" : "string", + "optional" : true + }, + + "default" : { + "type" : "any", + "optional" : true + }, + + "divisibleBy" : { + "type" : "number", + "minimum" : 0, + "minimumCanEqual" : false, + "optional" : true, + "default" : 1 + }, + + "disallow" : { + "type" : ["string", "array"], + "items" : {"type" : "string"}, + "optional" : true, + "uniqueItems" : true + }, + + "extends" : { + "type" : [{"$ref" : "#"}, "array"], + "items" : {"$ref" : "#"}, + "optional" : true, + "default" : {} + } + }, + + "optional" : true, + "default" : {} +} \ No newline at end of file diff --git a/schema.properties b/schema.properties new file mode 100644 index 0000000..3f4041a --- /dev/null +++ b/schema.properties @@ -0,0 +1,136 @@ +{ + "type":{ + "type":["string","array"], + "items":{"$ref":"$.properties.type"}, + "description":"This is a type definition value. This can be a simple type, or a union type", + "options":[{"value":"string"},{"value":"object"},{"value":"array"},{"value":"boolean"},{"value":"number"},{"value":"integer"},{"value":"null"},{"value":"any"}], + "unconstrained":true, + "optional":true, + "default":"any"}, + "optional":{ + "type":"boolean", + "description":"This indicates that the instance property in the instance object is not required.", + "optional":true, + "default":false}, + "properties":{ + "type":"object", + "additionalProperties":{"$ref":"$"}, + "description":"This is a definition for the properties of an object value", + "optional":true, + "default":{} + }, + "items":{ + "type":"object", + "properties":{"$ref":"$.properties"}, + "description":"When the value is an array, this indicates the schema to use to validate each item in an array", + "optional":true, + "default":{}}, + "additionalProperties":{ + "type":["boolean","object"], + "properties":{"$ref":"$.properties"}, + "description":"This provides a default property definition for all properties that are not explicitly defined in an object type definition.", + "optional":true, + "default":{}}, + "specificity":{ + "type":"number", + "description":"This indicates an order of specificity of properties. If an instance defines another property with a higher specificity than this one, than this instance property is required.", + "optional":true, + "default":false}, + "identity":{ + "type":"boolean", + "description":"This indicates that the instance property is an identity property and can be used to uniquely identify this instance.", + "optional":true, + "default":false}, + "minimum":{ + "type":"number", + "optional":true, + "description":"This indicates the minimum value for the instance property when the type of the instance value is a number, or it indicates the minimum number of values in an array when an array is the instance value."}, + "maximum":{ + "type":"number", + "optional":true, + "description":"This indicates the maximum value for the instance property when the type of the instance value is a number, or it indicates the maximum number of values in an array when an array is the instance value."}, + "pattern":{ + "type":"string", + "format":"regex", + "description":"When the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid.", + "optional":true, + "default":".*"}, + "maxLength" :{ + "type":"number", + "optional":true, + "description":"When the instance value is a string, this indicates maximum length of the string."}, + "minLength" :{ + "type":"number", + "optional":true, + "description":"When the instance value is a string, this indicates minimum length of the string."}, + "maxItems" :{ + "type":"number", + "optional":true, + "description":"When the instance value is an array, this indicates maximum number of items."}, + "minItems" :{ + "type":"number", + "optional":true, + "description":"When the instance value is an array, this indicates minimum number of items."}, + "enum" : { + "type":"array", + "optional":true, + "description":"This provides an enumeration of possible values that are valid for the instance property."}, + "options" : { + "type":"array", + "items":{ + "properties":{ + "label":{ + "type":"string", + "description":"This is the label for this option", + "optional":true + }, + "value":{ + "description":"This is the value for this option" + } + }, + "description":"This is an option for list of possible values" + }, + "optional":true, + "description":"This provides a list of suggested options for the instance property."}, + "readonly":{ + "type":"boolean", + "description":"This indicates that the instance property should not be changed (this is only for interaction, it has no effect for standalone validation).", + "optional":true, + "default":false}, + "description":{ + "type":"string", + "optional":true, + "description":"This provides a description of the purpose the instance property. The value can be a string or it can be an object with properties corresponding to various different instance languages (with an optional default property indicating the default description)."}, + "format":{ + "type":"string", + "optional":true, + "description":"This indicates what format the data is among some predefined formats which may include:\n\ndate - a string following the ISO format \naddress \nschema - a schema definition object \nperson \npage \nhtml - a string representing HTML"}, + "default":{ + "type":"any", + "optional":true, + "description":"This indicates the default for the instance property."}, + "transient":{ + "type":"boolean", + "optional":true, + "description":"This indicates that the property will be used for transient/volatile values that should not be persisted.", + "default":false}, + "maxDecimal":{ + "type":"integer", + "optional":true, + "description":"This indicates the maximum number of decimal places in a floating point number."}, + "hidden":{ + "type":"boolean", + "optional":true, + "description":"This indicates whether the property should be hidden in user interfaces."}, + "extends":{ + "type":"object", + "properties":{"$ref":"$.properties"}, + "description":"This indicates the schema extends the given schema. All instances of this schema must be valid to by the extended schema also.", + "optional":true, + "default":{}}, + "id":{ + "type":["string","number"], + "optional":true, + "format":"url", + "identity":true} +} \ No newline at end of file diff --git a/schema.type b/schema.type new file mode 100644 index 0000000..67b6afd --- /dev/null +++ b/schema.type @@ -0,0 +1,73 @@ +{ + "type":{ + "type":["string",{},[]], + "additionalProperties":{"$ref":"$"}, + "description":"This is a type definition value. This can be an object type definition, an array type definition, simple type, or a union type", + "options":[{"value":"string"},{"value":"object"},{"value":"array"},{"value":"boolean"},{"value":"number"},{"value":"integer"},{"value":"null"},{"value":"any"}], + "unconstrained":true, + "default":"any"}, + "optional":{ + "type":"boolean", + "description":"This indicates that the instance property in the instance object is not required.", + "default":false}, + "additionalProperties":{ + "type":{"$ref":"$"}, + "description":"This provides a default property definition for all properties that are not explicitly defined in an object type definition.", + "default":{}}, + "final":{ + "type":"boolean", + "description":"This indicates that the instance objects should not have any additional properties beyond what is defined in the object type definition, and the schema definition should not be extended.", + "default":false}, + "specificity":{ + "type":"number", + "description":"This indicates an order of specificity of properties. If an instance defines another property with a higher specificity than this one, than this instance property is required.", + "default":false}, + "unique":{ + "type":"boolean", + "description":"This indicates that the instance property should have unique values. No other property with the same name in the instance object tree should have the same value.", + "default":false}, + "minimum":{ + "type":"number", + "description":"This indicates the minimum value for the instance property when the type of the instance value is a number, or it indicates the minimum number of values in an array when an array is the instance value."}, + "maximum":{ + "type":"number", + "description":"This indicates the maximum value for the instance property when the type of the instance value is a number, or it indicates the maximum number of values in an array when an array is the instance value."}, + "pattern":{ + "type":"string", + "format":"regex", + "description":"When the instance value is a string, this provides a regular expression that a instance string value should match in order to be valid.", + "default":".*"}, + "maxLength" :{ + "type":"number", + "description":"When the instance value is a string, this indicates maximum length of the string."}, + "minLength" :{ + "type":"number", + "description":"When the instance value is a string, this indicates minimum length of the string."}, + "options" : { + "type":[], + "description":"This provides an enumeration of possible values that are valid for the instance property."}, + "unconstrained":{ + "type":"boolean", + "description":"When used in conjunction with the options property, this indicates a value can be used that is not in the list of options. This has no meaning when the options property is not a sibling.", + "default":false}, + "readonly":{ + "type":"boolean", + "description":"This indicates that the instance property should not be changed (this is only for interaction, it has no effect for standalone validation).", + "default":false}, + "description":{ + "type":"string", + "description":"This provides a description of the purpose the instance property. The value can be a string or it can be an object with properties corresponding to various different instance languages (with an optional default property indicating the default description)."}, + "format":{ + "type":"string", + "description":"This indicates what format the data is among some predefined formats which may include:\n\ndate - a string following the ISO format \naddress \nschema - a schema definition object \nperson \npage \nhtml - a string representing HTML"}, + "default":{ + "type":"any", + "description":"This indicates the default for the instance property."}, + "transient":{ + "type":"boolean", + "description":"This indicates that the property will be used for transient/volatile values that should not be persisted.", + "default":false}, + "maxDecimal":{ + "type":"integer", + "description":"This indicates the maximum number of decimal places in a floating point number."} +} \ No newline at end of file diff --git a/shared.html b/shared.html new file mode 100644 index 0000000..cc51cb0 --- /dev/null +++ b/shared.html @@ -0,0 +1,58 @@ + + +Common JSON Schema Definitions + + + +

The following are a list of some of the future common JSON Schema definitions. Included is the URL to reference and download the schema and object type definition. These shared definitions can be referenced in JSON Schemas and SMDs using JSON referencing (here is a suggested method).

+ + + + + + + + + + + \ No newline at end of file