diff --git a/Makefile b/Makefile index 0895a74d..7fb894d7 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ XML2RFC=xml2rfc OUT = \ jsonschema-core.html jsonschema-core.txt \ - jsonschema-schema.html jsonschema-schema.txt \ + jsonschema-validation.html jsonschema-validation.txt \ jsonschema-hyperschema.html jsonschema-hyperschema.txt diff --git a/README.md b/README.md index e9a978c7..5ff3bb6f 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,36 @@ This repository contains the current, and historical, JSON Schema specifications. + ## Call for reviews Specifications are starting to get written. Reviews, comments and suggestions are of paramount importance to JSON Schema. It is humbly asked to you, dear reader, that you bring your contribution. + +## Contents + +Makefile - scripts to build the Internet-Draft txt/html +archive - files for other/older JSON Schema implementations +hyper-schema.json - the JSON Hyper-schema meta-schema +schema.json - the JSON Schema meta-schema +jsonschema-core.xml - sources for "core" spec +jsonschema-validation - sources for JSON Schema validation +jsonschema-hyperschema.xml - sources for hyper-schema spec + +Type "make" at a shell to build the .txt and .html spec files. + +A primer on the RFC XML format is at + + ## The website The JSON Schema web site is at http://json-schema.org/ +The source for the website is maintained in a separate repository. + + ## License The source material in this repository is licensed under the AFL or BSD license. diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 28d15b9b..442adc19 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -5,8 +5,8 @@ - + ]> @@ -102,116 +102,100 @@
-
+
- When referring to a JSON Object, as defined by , the - terms "member" and "property" may be used interchangeably. + A JSON document is an information resource (series of octets) describable by the application/json media type. - - When referring to a JSON Array, as defined by , the terms - "element" and "item" may be used interchangeably. + In JSON Schema, the terms "JSON document", "JSON text", and "JSON value" are interchangable because of the data model it defines.
-
+
- 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. + JSON Schema interperts JSON data according to a data model. A JSON value interperted according to this data model is called an "instance". + + An instance has one of six primitive types, and a range of possible values depending on the type: + + A JSON "null" production + A "true" or "false" value, from the JSON "true" or "false" productions + An unordered set of properties mapping a string to an instance, from the JSON "object" production + An ordered list of instances, from the JSON "array" production + An arbitrary-precision, base-10 decimal number value, from the JSON "number" production + A string of Unicode code points, from the JSON "string" production + + - 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. + Whitespace and formatting conserns are thus outside the scope of JSON Schema. - - A JSON Schema MAY contain properties which are not schema keywords. + Since an object cannot have two properties with the same key, behavior for a JSON document that tries to define two properties (the "member" production) with the same key (the "string" production) in a single object is undefined.
-
+
- An empty schema is a JSON Schema with no properties, or with properties which - are not schema keywords. + Two JSON instances are said to be equal if and only if they are of the same type and have the same value according to the data model. Specifically, this is if: + + + both are null; or + both are true; or + 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. + + + + Implied in this definition is that arrays must be the same length, objects must have the same number of members, there is no way to define multiple properties with the same key, and mere formatting differences (indentation, placement of commas, trailing zeros) are insignificant.
-
+
- This example of a JSON Schema has no subschemas: + A JSON Schema document, or simply a schema, is a JSON document used to describe an instance. + A schema is itself interperted as an instance. A JSON schema MUST be an object. -
- - - -
+ + Properties that are used to describe the instance are called keywords, or schema keywords. The meaning of properties is specified by the vocabulary that the schema is using. + + + A JSON Schema MAY contain properties which are not schema keywords. + Unknown keywords SHOULD be ignored. + + + A schema that itself describes a schema is called a meta-schema. Meta-schemas are used to validate JSON Schemas and specify which vocabulary it is using. + + + An empty schema is a JSON Schema with no properties, or only unknown properties. + +
+
- JSON Schemas can also be nested, as in this example: + 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:
- - - In this example, "nested" and "alsoNested" are subschemas, and "root" is a root - schema. - -
- -
- - JSON Schema defines six primitive types for JSON values: - - A JSON "object" production. - A JSON "array" production - A JSON "true" or "false" production - A JSON "number" production - A JSON "null" production - A JSON "string" production - - -
- -
- - Two JSON values are said to be equal if and only if: - - - both are null; or - both are true; or - 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. - - -
- -
- 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". + In this example document, the schema titled "alsoNested" is a subschema, + and the schema titled "root" is the root schema.
@@ -232,7 +216,9 @@ 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. + + Validation behaviour and keywords are specified in a separate document. +
@@ -240,47 +226,26 @@ 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. - Hyper-schema behaviour and keywords are specified in a separate document. + + Hyper-schema behaviour and keywords are specified in a separate document. +
-
+
- It is acknowledged that an instance may be any valid JSON value as defined by . - As such, JSON Schema does not mandate that an instance be of a particular type: JSON Schema can describe any JSON value, including null. + An instance may be any valid JSON value as defined by JSON. + JSON Schema imposes no restrictions on type: JSON Schema can describe any JSON value, including, for example, null.
- JSON Schema is programming language agnostic. The only limitations are the ones - expressed by and those of the host programming - language. - -
- -
- - This specification acknowledges the role of HTTP - as the dominant protocol in use on the Internet, and the wealth of - official specifications related to it. - - - - This specification uses a subset of these specifications to recommend a set of - mechanisms, usable by this protocol, to associate JSON instances to one or more - schemas. - -
- -
- - JSON Schema does not define any semantics for the client-server interface for - any other protocols than HTTP. These semantics are application dependent, or - subject to agreement between the parties involved in the use of JSON Schema for - their own needs. + 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.
@@ -289,7 +254,6 @@ 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. @@ -318,130 +282,113 @@ location of a resource which is itself a JSON Schema, which describes any schema written for this particular version. - - This keyword SHOULD be located at the root of a JSON Schema. The value of this - keyword MUST be a URI and a valid JSON Reference; this URI MUST be normalized. - The resource identified by this URI MUST successfully describe the current - schema document. It is RECOMMENDED that schema authors include this keyword in their - schemas. + The root schema of a JSON Schema document SHOULD use this keyword. + The value of this keyword MUST be a URI (an "absolute" URI), + 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: - - - JSON Schema written - against this version. - JSON Schema hyperschema - written against this version. - JSON Schema written - against JSON Schema, draft v4. - JSON Schema hyperschema - written against JSON Schema, draft v3. - JSON Schema written - against JSON Schema, draft v3. - JSON Schema hyperschema - written against JSON Schema, draft - v3. - + Values for this property are defined in other documents and by other parties. + JSON Schema implementations SHOULD implement support for current and previous published drafts + of JSON Schema vocabularies as deemed reasonable.
+
+ + 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. + +
+
-
+
- JSON Schema uses JSON Reference as a - mechanism for schema addressing. It extends this specification in two ways: - - - JSON Schema offers facilities to alter the base URI against which a - URI reference must resolve by the means of the "id" keyword; - it offers schemas a mechanism to declare their own URIs, placing no limits on the structure of the URI - - + RFC3986 Section 5.1 defines how to determine the default base URI of a document. - - - The initial base URI of a schema is the URI of the schema itself, or a suitable substitute URI if none is known. + Informatively, the initial base URI of a schema is the URI it was found at, or a suitable substitute URI if none is known.
-
- - 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 "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 outermost schema of a JSON Schema document SHOULD be an absolute-URI (containing a scheme, but no fragment) - or an absolute-URI with an empty fragment. - - - For example: - + + 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 represent a valid URI-reference. + This value SHOULD be normalized, and SHOULD NOT be an empty fragment <#> or an empty string <>. + + + The root schema of a JSON Schema document SHOULD have an "id" with a valid absolute-URI (containing a scheme, but no fragment). + + + To facilitate the identification of subschemas in a JSON Schema document, + subschemas can use "id" to give themselves a URI with a custom fragment-part. + This form of "id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference, + followed by a letter ([A-Za-z]), followed by any number of + letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods ("."). + + + + For example:
- + + + Subschemas at the following URI-encoded JSON + Pointers (starting from the root schema) have the following + base URIs, and are identifiable by either URI: + + + + http://example.com/root.json# + http://example.com/root.json#foo + http://example.com/other + http://example.com/other#bar + http://example.com/t/inner + urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f + + +
- Subschemas at the following URI-encoded JSON - Pointers (starting from the root schema) define the following - base URIs: - - - http://example.com/rootschema.json# - http://example.com/rootschema.json#foo - http://example.com/otherschema.json# - http://example.com/otherschema.json#bar - http://example.com/t/inner.json#a - urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f - + 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. - This is known as "canonical referencing". - - - 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". + Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "id". + This is known as "Internal referencing". @@ -452,108 +399,50 @@ - - When an implementation encounters the "schema1" reference, it resolves it - against the current base URI, leading to URI - "http://my.site/schema1#". The way to process this URI will differ - according to the chosen dereferencing mode: - - - if canonical dereferencing is used, the implementation will - dereference this URI, and fetch the content at this URI; - if inline dereferencing is used, the implementation MAY notice that - the base URI "http://my.site/schema1#" is already defined within the - schema, and choose to use the appropriate subschema. - + When an implementation encounters the <#/definitions/single> schema, it resolves the "id" URI reference + against the current base URI to <http://example.net/schema1>. + + + When an implementation then looks inside the <#/items> schema, it encounters the <schema1> reference, + and resolves this to <http://example.net/schema1> which is understood as the schema defined elsewhere in the same document. -
- -
+
- When using inline dereferencing, a base URI may lead to a URI which - has a non-empty fragment part which is not a JSON Pointer, as in this - example: + To differentiate schemas between each other in a vast ecosystem, schemas are identified by URI. + As specified above, this does not necessarially mean anything is downloaded, but instead JSON Schema + implementations SHOULD provide ways to import a schema by URI so that other schemas can successfully reference it. - -
- - - -
- - An implementation choosing to support inline dereferencing SHOULD be able to use this kind of reference. + Implementations SHOULD be able to associate arbritrary URIs with an arbritrary schema and/or + automatically associate a schema's "id"-given URI, depending on the trust that the the validator + has in the schema. + + + A schema MAY (and likely will) have multiple URIs, but a URI has no way to identify more than one schema. + Validators that try to have multiple schemas associated to the same URI SHOULD raise an error condition.
- -
- -
- - Inline dereferencing can produce canonical URIs which differ from the canonical URI - of the root schema. Schema authors SHOULD ensure that implementations using - canonical dereferencing obtain the same content as implementations using inline - dereferencing. - - - - Extended JSON References using fragments which are not JSON Pointers are not dereferenceable by implementations that do not support inline dereferencing. - Schema authors should bear in mind that this support is optional before using it. -
-
- - When used for hypermedia systems over a network, HTTP 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: -
- - - -
- - - Clients SHOULD be able to make requests with a "From" header so that server operators can contact the owner of a potentially misbehaving script. - -
- -
+
One of the largest adoptors of JSON has been HTTP servers for automated APIs and robots. @@ -584,7 +473,7 @@ Link: ; rel="describedby"
Instances MAY specify a "profile" as described in The 'profile' Link Relation. - 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). + When used as a media-type parameter, HTTP servers gain the ability to perform Content-Type Negotiation based on profile. The media-type parameter 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. @@ -632,7 +521,31 @@ Link: ; rel="profile", ; rel="profile"
-
+
+ + When used for hypermedia systems over a network, HTTP 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. + Distributed systems SHOULD make use of a shared cache and/or caching proxy. + + + 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: +
+ + + +
+ + + Clients SHOULD be able to make requests with a "From" header so that server operators can contact the owner of a potentially misbehaving script. + +
+ +
@@ -690,7 +603,7 @@ Link: ; rel="profile", ; rel="profile" &RFC6901; &RFC6906; &RFC7231; - JSON Schema: interactive and non interactive validation @@ -722,45 +635,6 @@ Link: ; rel="profile", ; rel="profile" - - - JSON Reference (work in progress) - - ForgeRock US, Inc. - - - SitePen (USA) - - - - - - - JSON Schema, draft 3 - - - - - SitePen (USA) - - - - - - - JSON Schema, draft 3 - - - - - SitePen (USA) - - - -
diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 70b12b99..72b600b8 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -416,8 +416,8 @@
The value of the "href" link description property is a template used to determine the target URI of the related resource. - The value of the instance property SHOULD be resolved as a URI-Reference per RFC 3986 and MAY be a URI reference. - The base URI to be used for relative URI resolution SHOULD be the URI used to retrieve the instance object (not the schema). + The value of the instance property MUST be resolved as a URI-reference. + The base URI to be used for relative URI resolution MUST be the URI of instance (not the schema). @@ -495,32 +495,26 @@
- -
- For example, here are some possible values for "href", followed by the results after pre-processing: - - - - - Note that in the final example, because the "+" was outside the brackets, it remained unescaped, whereas in the fourth example the "+" was escaped. - -
- + + For example, here are some possible values for "href", followed by the results after pre-processing: + Input + Output + "no change" "no change" + "(no change)" "(no change)" + "{(escape space)}" "{escape%20space}" + "{(escape+plus)}" "{escape%2Bplus}" + "{(escape*asterisk)}" "{escape%2Aasterisk}" + "{(escape(bracket)}" "{escape%28bracket}" + "{(escape))bracket)}" "{escape%29bracket}" + "{(a))b)}" "{a%29b} + "{(a (b)))}" "{a%20%28b%29} + "{()}" "{%65mpty} + "{+$*}" "{+%73elf*} + "{+($)*}" "{+%24*} + + Note that in the final example, because the "+" was outside the brackets, it remained unescaped, whereas in the fourth example the "+" was escaped. + +
@@ -692,7 +686,7 @@ Input Output To correctly resolve the URL "http://example.com/data/12345", we must take the "root" link into account. Here are some example URIs, along with the data they would resolve to: -
- - - -
+ + URI + Data + http://example.com/data/12345 {"title": "Breaking news"} + http://example.com/data/12345#/title "Breaking news" +
@@ -742,25 +732,26 @@ GET /foo/
- With a response of: + With a response of (with newlines and whitespace added): -
@@ -807,8 +798,8 @@ GET /foo/ "name": "Jason", "id": 8 }, - "message": "It's easy, you just add some HTML like - this: " + "message": "It's easy, just add some HTML like + this: " }]]> @@ -826,7 +817,7 @@ GET /foo/ "targetSchema": { "properties": { "message": { - "description": "Re-interpret the message text as HTML", + "description": "Re-interpret `message` as HTML", "media": { "type": "text/html" } diff --git a/jsonschema-schema.xml b/jsonschema-validation.xml similarity index 97% rename from jsonschema-schema.xml rename to jsonschema-validation.xml index 28a46f4d..c8bbcd7e 100644 --- a/jsonschema-schema.xml +++ b/jsonschema-validation.xml @@ -64,7 +64,7 @@ JSON Schema (application/schema+json) has several purposes, one of which is JSON instance - validation. This document specifies a vocabulary for JSON Schema to makes assertions about + validation. This document specifies a vocabulary for JSON Schema to make assertions about valid instances. @@ -100,12 +100,12 @@ This specification uses the term "property set" to refer to the set of an object's - member names; for instance, the property set of JSON Object { "a": 1, "b": 2 } is [ - "a", "b" ]. + member names; for instance, the property set of JSON Object { "a": 1, "b": 2 } is + [ "a", "b" ]. Elements in an array value are said to be unique if no two elements of this array - are equal, as defined by the core specification. + are equal.
@@ -121,7 +121,7 @@
- The JSON specification allows numbers with arbritrary prevision, and JSON Schema does not add any such bounds. + The JSON specification allows numbers with arbitrary precision, and JSON Schema does not add any such bounds. This means that numeric instances processed by JSON Schema can be arbitrarily large and/or have an arbitrarily large decimal part, regardless of the ability of the underlying programming language to deal with such data. @@ -177,11 +177,11 @@
-
+
Validation keywords that are missing never restrict validation. - In some cases, this behavior is identical to certain values that also are no-op. - Since these values can be safely ignored or removed, they are noted where known. + In some cases, this no-op behavior is identical to a keyword that exists with certain values, + and these values are noted where known.
@@ -206,13 +206,15 @@ The value of "maximum" MUST be a number, representing an upper limit for a numeric instance. - A numeric instance described by this keyword MUST either be less than this value or possibly equal to it (see "exclusiveMaximum"). + If the instance is a number, then this keyword validates if "exclusiveMaximum" is true and instance is less than the provided value, + or else if the instance is less than or exactly equal to the provided value.
- The value of "exclusiveMaximum" MUST be a boolean, representing whether the limit in "maximum" is exclusive or not. It defaults to false. + The value of "exclusiveMaximum" MUST be a boolean, representing whether the limit in "maximum" is exclusive or not. + An undefined value is the same as false. If "exclusiveMaximum" is true, then a numeric instance MUST NOT be equal to the value specified in "maximum". @@ -225,13 +227,15 @@ The value of "minimum" MUST be a number, representing a lower limit for a numeric instance. - A numeric instance described by this keyword MUST either be more than this value or possibly equal to it (see "exclusiveMinimum"). + If the instance is a number, then this keyword validates if "exclusiveMinimum" is true and instance is greater than the provided value, + or else if the instance is greater than or exactly equal to the provided value.
- The value of "exclusiveMinimum" MUST be a boolean, representing whether the limit in "minimum" is exclusive or not. It defaults to false. + The value of "exclusiveMinimum" MUST be a boolean, representing whether the limit in "minimum" is exclusive or not. + An undefined value is the same as false. If "exclusiveMinimum" is true, then a numeric instance MUST NOT be equal to the value specified in "minimum".