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 1 . Introduction 2 . Conventions RFC 2119 [RFC2119]. 3 . Overview 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 3.2 . Design Considerations 4 . Schema/Instance Association 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: <http://json.com/my-hyper-schema>; 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 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 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 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 5.3 . patternProperties 5.4 . additionalProperties Zyp & Court Expires May 26, 2011 [Page 9]

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 5.10 . maximum 5.11 . exclusiveMinimum 5.12 . exclusiveMaximum 5.13 . minItems 5.14 . maxItems 5.15 . uniqueItems 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 5.17 . minLength 5.18 . maxLength 5.19 . enum Section 5.15). 5.20 . default 5.21 . title Zyp & Court Expires May 26, 2011 [Page 12]

Internet-Draft JSON Schema Media Type November 2010 5.22 . description 5.23 . format 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 5.25 . disallow 5.26 . extends 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 5.28 . $ref 5.29 . $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 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 6.1.1 . Link Description Object http://json-schema.org/links (latest version) or http://json-schema.org/draft-03/links (draft-03 version). 6.1.1.1 . href 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 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 6.1.1.4 . Submission Link Properties 6.1.1.4.1 . method 6.1.1.4.2 . enctype 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 6.2 . fragmentResolution RFC 2396, Sec 5 [RFC2396], and defines the mechanism for resolving references to entities within a document. 6.2.1 . slash-delimited fragment resolution 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 6.3 . readonly Zyp & Court Expires May 26, 2011 [Page 21]

Internet-Draft JSON Schema Media Type November 2010 6.4 . contentEncoding RFC 2045, Sec 6.1 [RFC2045] lists the possible values for this property. 6.5 . pathStart 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 7 . Security Considerations 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 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 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 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]