diff --git a/jsonschema-core.xml b/jsonschema-core.xml index db6a9896..28d83b60 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -50,9 +50,10 @@ for describing the structure of JSON data. JSON Schema asserts what a JSON document must look like, ways to extract information from it, - and how to interact with it, - ideal for annotating existing JSON APIs that would not otherwise have hypermedia - controls or be machine-readable. + and how to interact with it. + The "application/schema-instance+json" media type provides additional + feature-rich integration with "application/schema+json" beyond what can be offered + for "application/json" documents. @@ -110,6 +111,8 @@ This document proposes a new media type "application/schema+json" to identify a JSON Schema for describing JSON data. + It also proposes a further optional media type, "application/schema-instance+json", + to provide additional integration features. JSON Schemas are themselves JSON documents. This, and related specifications, define keywords allowing authors to describe JSON data in several ways. @@ -164,64 +167,96 @@
- JSON Schema interprets documents according to a data model. A JSON value - interpreted according to this data model is called an "instance". + A JSON document to which a schema is applied is known as 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 - - - - Whitespace and formatting concerns are thus outside the scope of JSON Schema. - - - 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. - -
+
+ + JSON Schema interprets documents according to a data model. A JSON value + interpreted 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 + + + + Whitespace and formatting concerns are thus outside the scope of JSON Schema. + + + 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. + +
-
- - 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 means: +
+ + JSON Schema is designed to fully work with "application/json" documents, + as well as media types using the "+json" structured syntax suffix. + + + Some functionality that is useful for working with schemas is + defined by each media type, namely media type parameters and + URI fragment identifier syntax and semantics. These features are + useful in content negotiation and in caclulating URIs for specific + locations within an instance, respectively. + + + This specification defines the "application/schema-instance+json" + media type in order to allow instance authors to take full advantage + of parameters and fragment identifiers for these purposes. + +
- - 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 - a key equal to the other's, 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, - properties in objects are unordered, - there is no way to define multiple properties with the same key, - and mere formatting differences (indentation, placement of commas, trailing - zeros) are insignificant. - +
+ + 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 means: + + + 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 + a key equal to the other's, 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, + properties in objects are unordered, + there is no way to define multiple properties with the same key, + and mere formatting differences (indentation, placement of commas, trailing + zeros) are insignificant. + +
A JSON Schema document, or simply a schema, is a JSON document used to describe an instance. - A schema is itself interpreted as an instance. + A schema is itself interpreted as an instance, but SHOULD always be given + the media type "application/schema+json" rather than + "application/schema-instance+json". The "application/schema+json" media + type is defined to offer a superset of the media type parameter and + fragment identifier syntax and semantics provided by + "application/schema-instance+json". + + A JSON Schema MUST be an object or a boolean. @@ -248,17 +283,16 @@ An empty schema is a JSON Schema with no properties, or only unknown properties. -
-
- - The root schema is the schema that comprises the entire JSON document in question. - - - Some keywords take schemas themselves, allowing JSON Schemas to be nested: - -
- +
+ + The root schema is the schema that comprises the entire JSON document in question. + + + Some keywords take schemas themselves, allowing JSON Schemas to be nested: + +
+ - -
- - In this example document, the schema titled "array item" is a subschema, - and the schema titled "root" is the root schema. - - - As with the root schema, a subschema is either an object or a boolean. - + +
+ + In this example document, the schema titled "array item" is a subschema, + and the schema titled "root" is the root schema. + + + As with the root schema, a subschema is either an object or a boolean. + +
@@ -291,22 +326,27 @@ Additionally, the "application/schema+json" media type supports two fragment identifier structures: plain names and JSON Pointers. + The "application/schema-instance+json" media type supports one + fragment identifier structure: JSON Pointers. + + The use of JSON Pointers as URI fragment identifiers is described in RFC 6901. - Fragment identifiers matching the JSON Pointer syntax, including - the empty string, MUST be interpreted as JSON Pointer fragment - identifiers. + For "application/schema+json", which supports two fragment identifier syntaxes, + fragment identifiers matching the JSON Pointer syntax, including the empty string, + MUST be interpreted as JSON Pointer fragment identifiers. Per the W3C's best practices for fragment identifiers, - plain name fragment identifiers are reserved for referencing + plain name fragment identifiers in "application/schema+json" are reserved for referencing locally named schemas. All fragment identifiers that do not match the JSON Pointer syntax MUST be interpreted as plain name fragment identifiers. - Defining and referencing a plain name fragment identifier are specified + Defining and referencing a plain name fragment identifier within an + "application/schema+json" document are specified in the "$id" keyword section. @@ -377,6 +417,10 @@ (containing a scheme) and this URI MUST be normalized. The current schema MUST be valid against the meta-schema identified by this URI. + + If this URI identifies a retrievable resource, that resource SHOULD be of + media type "application/schema+json". + The "$schema" keyword SHOULD be used in a root schema. It MUST NOT appear in subschemas. @@ -783,34 +827,78 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
- - The proposed MIME media type for JSON Schema is defined as follows: +
+ + The proposed MIME media type for JSON Schema is defined as follows: - - Type name: application - Subtype name: schema+json - Required parameters: N/A - - Encoding considerations: Encoding considerations are - identical to those specified for the "application/json" - media type. See JSON. - - - Security considerations: See Section - above. - - - Interoperability considerations: See Sections - and - above. - - - Fragment identifier considerations: See Section - - - - + + Type name: application + Subtype name: schema+json + Required parameters: N/A + + Encoding considerations: Encoding considerations are + identical to those specified for the "application/json" + media type. See JSON. + + + Security considerations: See Section + above. + + + Interoperability considerations: See Sections + and + above. + + + Fragment identifier considerations: See Section + + + + +
+
+ + The proposed MIME media type for JSON Schema Instances that require + a JSON Schema-specific media type is defined as follows: + + Type name: application + Subtype name: schema-instance+json + + Required parameters: + + + A non-empty list of space-separated URIs, each identifying + a JSON Schema resource. The instance SHOULD successfully + validate against at least one of these schemas. + Non-validating schemas MAY be included for purposes such + as allowing clients to make use of older versions of a schema + as long as the runtime instance validates against that + older version. + + + + + Encoding considerations: Encoding considerations are + identical to those specified for the "application/json" + media type. See JSON. + + + Security considerations: See Section + above. + + + Interoperability considerations: See Sections + and + above. + + + Fragment identifier considerations: See Section + + + + +