Internet Engineering Task Force F. Galiegue, Ed. Internet-Draft Intended status: Informational K. Zyp, Ed. Expires: March 19, 2017 SitePen (USA) G. Court September 15, 2016 JSON Schema: core definitions and terminology draft-zyp-json-schema-05 Abstract JSON Schema defines the media type "application/schema+json", a JSON based format for defining the structure of JSON data. JSON Schema asserts what a JSON document must look like and how to interact with it, ideal for annotating existing JSON APIs that would not hypermedia controls or otherwise be machine-accessible. 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 March 19, 2017. Copyright Notice Copyright (c) 2016 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 Galiegue, et al. Expires March 19, 2017 [Page 1] Internet-Draft JSON Schema September 2016 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 3. Core terminology . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Property, item . . . . . . . . . . . . . . . . . . . . . 3 3.2. JSON Schema, keywords . . . . . . . . . . . . . . . . . . 3 3.3. Empty schema . . . . . . . . . . . . . . . . . . . . . . 3 3.4. Root schema and subschemas . . . . . . . . . . . . . . . 4 3.5. JSON Schema primitive types . . . . . . . . . . . . . . . 4 3.6. JSON value equality . . . . . . . . . . . . . . . . . . . 4 3.7. Instance . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1. Validation . . . . . . . . . . . . . . . . . . . . . . . 5 4.2. Hypermedia and linking . . . . . . . . . . . . . . . . . 5 5. General considerations . . . . . . . . . . . . . . . . . . . 6 5.1. Range of JSON values . . . . . . . . . . . . . . . . . . 6 5.2. Programming language independence . . . . . . . . . . . . 6 5.3. Mathematical integers . . . . . . . . . . . . . . . . . . 6 5.4. Extending JSON Schema . . . . . . . . . . . . . . . . . . 6 6. The "$schema" keyword . . . . . . . . . . . . . . . . . . . . 6 6.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 6 7. Schema references with $ref . . . . . . . . . . . . . . . . . 7 8. Base URI and dereferencing . . . . . . . . . . . . . . . . . 7 8.1. Initial base URI . . . . . . . . . . . . . . . . . . . . 7 8.2. Base URI alteration with the "id" keyword . . . . . . . . 8 8.2.1. Methods for dereferencing . . . . . . . . . . . . . . 9 9. Usage over HTTP . . . . . . . . . . . . . . . . . . . . . . . 10 10. Recommended correlation mechanisms for hypermedia . . . . . . 11 10.1. Linking to a schema . . . . . . . . . . . . . . . . . . 11 10.2. Describing a profile of JSON . . . . . . . . . . . . . . 11 11. Security considerations . . . . . . . . . . . . . . . . . . . 12 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 13.1. Normative References . . . . . . . . . . . . . . . . . . 12 13.2. Informative References . . . . . . . . . . . . . . . . . 13 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 1. Introduction JSON Schema is a JSON media type for defining the structure of JSON data. JSON Schema is intended to define validation, documentation, hyperlink navigation, and interaction control of JSON data. Galiegue, et al. Expires March 19, 2017 [Page 2] Internet-Draft JSON Schema September 2016 This specification defines JSON Schema core terminology and mechanisms, including how to dereference a JSON Schema, pointing to another JSON Schema by reference, setting the vocabulary being used and asserting the minimum vocabulary that must be supported. Other specifications define the vocabularies that perform assertions about validation, linking, annotation, navigation, and interaction. 2. Conventions and Terminology 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]. The terms "JSON", "JSON text", "JSON value", "member", "element", "object", "array", "number", "string", "boolean", "true", "false", and "null" in this document are to be interpreted as defined in RFC 7159 [RFC7159]. 3. Core terminology 3.1. Property, item When referring to a JSON Object, as defined by [RFC7159], the terms "member" and "property" may be used interchangeably. When referring to a JSON Array, as defined by [RFC7159], the terms "element" and "item" may be used interchangeably. 3.2. JSON Schema, keywords A JSON Schema is a JSON document, and that document MUST be an object. Object members (or properties) defined by JSON Schema (this specification, or related specifications) are called keywords, or schema keywords. If an instance is described by a schema, and a keyword is defined in the schema, then within this document that instance is informally said to be "described by" the keyword as well. A JSON Schema MAY contain properties which are not schema keywords. Unknown keywords SHOULD be ignored. 3.3. Empty schema An empty schema is a JSON Schema with no properties, or only unknown properties. Galiegue, et al. Expires March 19, 2017 [Page 3] Internet-Draft JSON Schema September 2016 3.4. Root schema and subschemas The root schema is the schema that comprises the entire JSON document in question. Some keywords take schemas themselves, allowing JSON Schemas can be nested: { "title": "root", "items": { "title": "alsoNested" } } In this example document, the schema titled "alsoNested" is a subschema, and the schema titled "root" is the root schema. 3.5. JSON Schema primitive types JSON Schema validates and interperts data according to a data model. JSON Schema defines six primitive types for JSON values: object A JSON "object" production array A JSON "array" production boolean A JSON "true" or "false" production number A JSON "number" production null A JSON "null" production string A JSON "string" production Whitespace and formatting conserns are thus outside the scope of JSON Schema. 3.6. JSON value equality Two JSON values are said to be equal if and only if: both are null; or both are true; or Galiegue, et al. Expires March 19, 2017 [Page 4] Internet-Draft JSON Schema September 2016 both are false; or both are strings, and are the same codepoint-for-codepoint; or both are numbers, and have the same mathematical value; or both are arrays, and have an equal value item-for-item; or both are objects, and each property in one has exactly one property with an equal key the other, and that other property has an equal value. 3.7. Instance An instance is any JSON value being described by a schema. An instance may also be referred to as a "JSON instance", "JSON data", "JSON-text", or "JSON document". 4. Overview This document proposes a new media type "application/schema+json" to identify JSON Schema for describing JSON data. JSON Schemas are themselves written in JSON. This, and related specifications, define keywords allowing to describe this data in terms of allowable values, textual descriptions and interpreting relations with other resources. The following sections are a summary of features defined by related specifications. 4.1. Validation JSON Schema describes the structure of a JSON document (for instance, required properties and array length constraints). Applications can use this information to validate instances (check that constraints are met), or inform interfaces to collect user input such that the constraints are satisfied. Validation behaviour and keywords are specified in a separate document [json-schema-validation]. 4.2. Hypermedia and linking JSON Hyper-Schema describes the hypertext structure of a JSON document. This includes link relations from the instance to other resources, interpretation of instances as multimedia data, and submission data required to use an API. Galiegue, et al. Expires March 19, 2017 [Page 5] Internet-Draft JSON Schema September 2016 Hyper-schema behaviour and keywords are specified in a separate document [json-hyper-schema]. 5. General considerations 5.1. Range of JSON values An instance may be any valid JSON value as defined by JSON [RFC7159]. JSON Schema imposes no restrictions on type: JSON Schema can describe any JSON value, including, for example, null. 5.2. Programming language independence JSON Schema is programming language agnostic, and supports the full range of values described in the data model. Be aware, however, that some languages and JSON parsers may not be able to represent in memory the full range of values describable by JSON. 5.3. Mathematical integers Some programming languages and parsers use different internal representations for floating point numbers than they do for integers. For constistency, integer JSON numbers SHOULD NOT be encoded with a fractional part. 5.4. Extending JSON Schema Implementations MAY choose to define additional keywords to JSON Schema. Save for explicit agreement, schema authors SHALL NOT expect these additional keywords to be supported by peer implementations. Implementations SHOULD ignore keywords they do not support. Authors of extensions to JSON Schema are encouraged to write their own meta-schemas, which extend the existing meta-schemas using "allOf". This extended meta-schema SHOULD be referenced using the "$schema" keyword, to allow tools to follow the correct behaviour. 6. The "$schema" keyword 6.1. Purpose The "$schema" keyword is both used as a JSON Schema version identifier and the location of a resource which is itself a JSON Schema, which describes any schema written for this particular version. Galiegue, et al. Expires March 19, 2017 [Page 6] Internet-Draft JSON Schema September 2016 This keyword SHOULD be located at the root of a JSON Schema document. The value of this keyword MUST be a URI [RFC3986], a valid JSON Pointer [RFC6901], and this URI MUST be normalized. The current schema MUST be valid against the meta-schema identified by this URI. The following values are predefined: http://json-schema.org/draft-05/schema# JSON Schema written against this version. http://json-schema.org/draft-05/hyper-schema# JSON Schema hyperschema written against this version. http://json-schema.org/draft-04/schema# JSON Schema written against JSON Schema, draft v4 [json-schema-04]. http://json-schema.org/draft-04/hyper-schema# JSON Schema hyperschema written against JSON Schema, draft v3 [json-schema-04]. http://json-schema.org/draft-03/schema# JSON Schema written against JSON Schema, draft v3 [json-schema-03]. http://json-schema.org/draft-03/hyper-schema# JSON Schema hyperschema written against JSON Schema, draft v3 [json-schema-03]. 7. Schema references with $ref Any time a subschema is expected, a schema may instead use an object containing a "$ref" property. The value of the $ref is a URI Reference. Resolved against the current URI base, it identifies the URI of a schema to use. The URI is not a network locator, only an identifier. A schema need not be downloadable from the address if it is a network-addressible URL, and implementations MUST NOT assume they should perform a network operation when they encounter a network-addressible URI. 8. Base URI and dereferencing 8.1. Initial base URI RFC3986 Section 5.1 [RFC3986] defines how to determine the default base URI of a document. Informatively, the initial base URI of a schema is the URI it was found at, or a suitable substitute URI if none is known. Galiegue, et al. Expires March 19, 2017 [Page 7] Internet-Draft JSON Schema September 2016 8.2. Base URI alteration with the "id" keyword The "id" keyword defines the URI of the schema and the base URI that other URI references within the schema are resolved against. The "id" keyword itself is resolved against a base URI as specified in [RFC3986]. The value for this keyword MUST be a string, and MUST be a valid URI- reference [RFC3986]. This URI SHOULD be normalized, and SHOULD NOT be an empty fragment (#) or the empty string. The outermost schema of a JSON Schema document SHOULD be an absolute- URI (containing a scheme, but no fragment). To identify a particular subschema in a document without needing a JSON Pointer, subschemas can give themselves ids that can be identified by a fragment-part. These "id" keywords with a fragment MUST begin with a letter ([A-Za-z]), to be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods ("."). For example: { "id": "http://example.com/root.json#", "definitions": { "schema1": { "id": "#foo" }, "schema2": { "id": "other", "definitions": { "a": { "id": "#bar" }, "b": { "id": "t/inner" } } }, "schema3": { "id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f" } } } Subschemas at the following URI-encoded JSON Pointers [RFC6901] (starting from the root schema) have the following base URIs, and are identifiable by either URI: # (document root) http://example.com/root.json# Galiegue, et al. Expires March 19, 2017 [Page 8] Internet-Draft JSON Schema September 2016 #/definitions/schema1 http://example.com/root.json#foo #/definitions/schema2 http://example.com/other #/definitions/schema2/definitions/a http://example.com/other#bar #/definitions/schema2/definitions/b http://example.com/t/inner #/definitions/schema3 urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f 8.2.1. Methods for dereferencing Schemas can be identified by any URI that has been given to them, including a JSON Pointer or their URI given directly by "id". When resolving a URI to obtain a schema, tools MUST support the lookup of documents based on this URI, and the use of JSON Pointer fragments to locate particular locations within a schema document. Tools MAY also take note of the URIs schemas provide for themselves using "id", and use these values for schema dereferencing as well. This is known as "inline referencing". For example, consider this schema: { "id": "http://example.net/myschema#", "definitions": { "schema1": { "id": "schema1", "type": "integer" }, "schema2", { "type": "array", "items": { "$ref": "schema1" } } } } When an implementation encounters the "schema1" schema, it resolves the "id" URI reference against the current base URI, resolving to . When an implementation then looks inside the "schema2" schema, it encounters the "schema1" reference, and resolves this the URI Galiegue, et al. Expires March 19, 2017 [Page 9] Internet-Draft JSON Schema September 2016 which is understood as a schema defined elsewhere in the document. An example with fragment "id" keywords: { "id": "http://some.site/schema#", "not": { "$ref": "#inner" }, "definitions": { "schema1": { "id": "#inner", "type": "boolean" } } } 9. Usage over HTTP When used for hypermedia systems over a network, HTTP [RFC7231] is frequently the protocol of choice for distributing schemas. Misbehaved clients can pose problems for server maintainers if they pull a schema over the network more frequently than necessary, when it's instead possible to cache a schema for a long period of time. HTTP servers SHOULD set long-lived caching headers on JSON Schemas. HTTP clients SHOULD observe caching headers and not re-request documents within their freshness period. Clients SHOULD set or prepend a User-Agent header specific to the JSON Schema implementation or software product. Since symbols are listed in decreasing order of significance, the JSON Schema library name/version goes first, then the more generic HTTP library name (if any). For example: User-Agent: so-cool-json-schema/1.0.2 curl/7.43.0 Clients SHOULD be able to make requests with a "From" header so that server operators can contact the owner of a potentially misbehaving script. Galiegue, et al. Expires March 19, 2017 [Page 10] Internet-Draft JSON Schema September 2016 10. Recommended correlation mechanisms for hypermedia One of the largest adoptors of JSON has been HTTP servers for automated APIs and robots. This section describes how to enhance processing of JSON documents in a more RESTful manner when used with protocols that support media types and Web linking [RFC5988]. 10.1. Linking to a schema It is RECOMMENDED that instances described by a schema/profile provide a link to a downloadable JSON Schema using the link relation "describedby", as defined by Linked Data Protocol 1.0, section 8.1 [W3C.REC-ldp-20150226]. In HTTP, such links can be attached to any response using the Link header [RFC5988]. An example of such a header would be: Link: ; rel="describedby" 10.2. Describing a profile of JSON Instances MAY specify a "profile" as described in The 'profile' Link Relation [RFC6906]. When used as a media-type parameter, HTTP servers gain the ability to perform Content-Type Negotiation based on profile. The media-type paramater MUST be a whitespace-separated list of URIs (i.e. relative references are invalid). The profile URI is opaque and SHOULD NOT automatically be dereferenced. If the implementation does not understand the semantics of the provided profile, the implementation can instead follow the "describedby" links, if any, which may provide information on how to handle the profile. Since "profile" doesn't necessarily point to a network location, the "describedby" relation is used for linking to a downloadable schema. However, for simplicity, schema authors should make these URIs point to the same resource when possible. In HTTP, the media-type parameter would be sent inside the Content- Type header: Content-Type: application/json; profile="http://example.com/my-hyper-schema#" Multiple profiles are whitespace seperated: Galiegue, et al. Expires March 19, 2017 [Page 11] Internet-Draft JSON Schema September 2016 Content-Type: application/json; profile="http://example.com/alice http://example.com/bob" HTTP can also send the "profile" in a Link, though this may impact media-type semantics and Content-Type negotiation if this replaces the media-type parameter: Link: ; rel="profile", ; rel="profile" 11. Security considerations Both schemas and instances are JSON values. As such, all security considerations defined in RFC 7159 [RFC7159] apply. Instances and schemas are both frequently witten by untrusted third parties, to be deployed on public Internet servers. Validators should take care that the parsing of schemas doesn't consume excessive system resources. Validators MUST NOT fall into an infinite loop. Individual JSON Schema vocabularies are liable to also have their own security considerations. Consult the respective specifications for more information. 12. IANA Considerations The proposed MIME media type for JSON Schema is defined as follows: type name: application; subtype name: schema+json. 13. References 13.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . Galiegue, et al. Expires March 19, 2017 [Page 12] Internet-Draft JSON Schema September 2016 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . [W3C.REC-ldp-20150226] Speicher, S., Arwe, J., and A. Malhotra, "Linked Data Platform 1.0", Feburary 2015, . 13.2. Informative References [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ RFC5988, October 2010, . [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, DOI 10.17487/RFC6906, March 2013, . [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, . [json-schema-validation] Galiegue, F., Court, G., and K. Zyp, "JSON Schema: interactive and non interactive validation", January 2013, . [json-hyper-schema] Luff, G., Court, G., and K. Zyp, "JSON Hyper-Schema: Hypertext definitions for JSON Schema", January 2013, . [json-schema-03] Court, G. and K. Zyp, "JSON Schema, draft 3", September 2012, . Galiegue, et al. Expires March 19, 2017 [Page 13] Internet-Draft JSON Schema September 2016 [json-schema-04] Court, G. and K. Zyp, "JSON Schema, draft 3", January 2013, . Galiegue, et al. Expires March 19, 2017 [Page 14] Internet-Draft JSON Schema September 2016 Appendix A. ChangeLog draft-00 * Initial draft. * Salvaged from draft v3. * Mandate the use of JSON Reference, JSON Pointer. * Define the role of "id". Define URI resolution scope. * Add interoperability considerations. Authors' Addresses Francis Galiegue (editor) EMail: fgaliegue@gmail.com Kris Zyp (editor) SitePen (USA) 530 Lytton Avenue Palo Alto, CA 94301 USA Phone: +1 650 968 8787 EMail: kris@sitepen.com Gary Court Calgary, AB Canada EMail: gary.court@gmail.com Galiegue, et al. Expires March 19, 2017 [Page 15]