From ab0453ecd229e92d7108c53cbd5950ed85a6498b Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Mon, 26 Dec 2022 13:45:12 -0500 Subject: [PATCH] Upgrade to rfc2xml v3 --- jsonschema-core.xml | 1305 +++++++++++++++++++++---------------------- 1 file changed, 639 insertions(+), 666 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 38d71473..2672c0d2 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -220,14 +220,14 @@ An instance has one of six primitive types, and a range of possible values depending on the type: - - A JSON "null" value - A "true" or "false" value, from the JSON "true" or "false" value - An unordered set of properties mapping a string to an instance, from the JSON "object" value - An ordered list of instances, from the JSON "array" value - An arbitrary-precision, base-10 decimal number value, from the JSON "number" value - A string of Unicode code points, from the JSON "string" value - +
+
null
A JSON "null" value
+
boolean
A "true" or "false" value, from the JSON "true" or "false" value
+
object
An unordered set of properties mapping a string to an instance, from the JSON "object" value
+
array
An ordered list of instances, from the JSON "array" value
+
number
An arbitrary-precision, base-10 decimal number value, from the JSON "number" value
+
string
A string of Unicode code points, from the JSON "string" value
+
Whitespace and formatting concerns, including different lexical @@ -258,17 +258,17 @@ 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 +
    +
  • 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. - + value.
    • +
Implied in this definition is that arrays must be the same length, @@ -316,27 +316,32 @@ Object properties that are applied to the instance are called keywords, or schema keywords. Broadly speaking, keywords fall into one of five categories: - - - control schema identification through setting a IRI - for the schema and/or changing how the base IRI is determined - - - produce a boolean result when applied to an instance - - - attach information to an instance for application use - - - apply one or more subschemas to a particular location - in the instance, and combine or modify their results - - - do not directly affect results, but reserve a place - for a specific purpose to ensure interoperability - - +
+
identifiers
+
+ control schema identification through setting a IRI + for the schema and/or changing how the base IRI is determined +
+
assertions
+
+ produce a boolean result when applied to an instance +
+
annotations
+
+ attach information to an instance for application use +
+
applicators
+
+ apply one or more subschemas to a particular location + in the instance, and combine or modify their results +
+
reserved locations
+
+ do not directly affect results, but reserve a place + for a specific purpose to ensure interoperability +
+
Keywords may fall into multiple categories, although applicators SHOULD only produce assertion results based on their subschemas' @@ -369,14 +374,19 @@ facilitate schema processing optimizations. They behave identically to the following schema objects (where "not" is part of the subschema application vocabulary defined in this document). - - - Always passes validation, as if the empty schema {} - - - Always fails validation, as if the schema { "not": {} } - - + +
+
true
+
+ Always passes validation, as if the empty schema {} +
+ +
false
+
+ Always fails validation, as if the schema { "not": {} } +
+
+ While the empty schema object is unambiguous, there are many possible equivalents to the "false" schema. Using the boolean values ensures that the intent is clear to both human readers @@ -449,18 +459,14 @@ 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. @@ -584,19 +590,19 @@ schema authors SHOULD limit themselves to the following regular expression tokens: - - individual Unicode characters, as defined by the JSON specification; - simple character classes ([abc]), range character classes ([a-z]); - complemented character classes ([^abc], [^a-z]); - simple quantifiers: "+" (one or more), "*" (zero or more), "?" (zero or - one), and their lazy versions ("+?", "*?", "??"); - range quantifiers: "{x}" (exactly x occurrences), "{x,y}" (at least x, at +
    +
  • individual Unicode characters, as defined by the JSON specification;
    • +
  • simple character classes ([abc]), range character classes ([a-z]);
    • +
  • complemented character classes ([^abc], [^a-z]);
    • +
  • simple quantifiers: "+" (one or more), "*" (zero or more), "?" (zero or + one), and their lazy versions ("+?", "*?", "??");
    • +
  • range quantifiers: "{x}" (exactly x occurrences), "{x,y}" (at least x, at most y, occurrences), {x,} (x occurrences or more), and their lazy - versions; - the beginning-of-input ("^") and end-of-input ("$") anchors; - simple grouping ("(...)") and alternation ("|"). - + versions;
    • +
  • the beginning-of-input ("^") and end-of-input ("$") anchors;
    • +
  • simple grouping ("(...)") and alternation ("|").
    • +
Finally, implementations MUST NOT take regular expressions to be @@ -878,24 +884,20 @@ for a concise expression of use cases such as a function that might return either a string of a certain length or a null value: -
- - - - - If "maxLength" also restricted the instance type to be a string, - then this would be substantially more cumbersome to express because - the example as written would not actually allow null values. - Each keyword is evaluated separately unless explicitly specified - otherwise, so if "maxLength" restricted the instance to strings, - then including "null" in "type" would not have any useful effect. - -
+]]> + + If "maxLength" also restricted the instance type to be a string, + then this would be substantially more cumbersome to express because + the example as written would not actually allow null values. + Each keyword is evaluated separately unless explicitly specified + otherwise, so if "maxLength" restricted the instance to strings, + then including "null" in "type" would not have any useful effect. + @@ -943,27 +945,27 @@ A collected annotation MUST include the following information: - - - The name of the keyword that produces the annotation - - - The instance location to which it is attached, as a JSON Pointer - - - The evaluation path, indicating how reference keywords - such as "$ref" were followed to reach the absolute schema location. - - - The absolute schema location of the attaching keyword, as a IRI. - This MAY be omitted if it is the same as the evaluation path - from above. - - - The attached value(s) - - +
    +
  • + The name of the keyword that produces the annotation +
    • +
  • + The instance location to which it is attached, as a JSON Pointer +
    • +
  • + The evaluation path, indicating how reference keywords + such as "$ref" were followed to reach the absolute schema location. +
    • +
  • + The absolute schema location of the attaching keyword, as a IRI. + This MAY be omitted if it is the same as the evaluation path + from above. +
    • +
  • + The attached value(s) +
    • +
Applications MAY make decisions on which of multiple annotation values @@ -975,12 +977,10 @@ For example, consider this schema, which uses annotations and assertions from the Validation specification: -
- - Note that some lines are wrapped for clarity. - - - + Note that some lines are wrapped for clarity. + + - -
+]]> In this example, both Feature A and Feature B make use of the re-usable "enabledToggle" schema. That schema uses the "title", "description", @@ -1068,9 +1066,7 @@ Note that the overall schema results may still include annotations collected from other schema locations. Given this schema: -
- - - -
+]]> - Against the instance "This is a string", the + Against the instance "This is a string", the title annotation "Integer Value" is discarded because the type assertion in that schema object fails. The title annotation "String Value" is kept, as the instance passes the string type assertions. @@ -1176,22 +1170,24 @@ The meta-schema serves two purposes: - - - The "$vocabulary" keyword, when it appears in a meta-schema, declares - which vocabularies are available to be used in schemas that refer - to that meta-schema. Vocabularies define keyword semantics, - as well as their general syntax. - - - A schema MUST successfully validate against its meta-schema, which - constrains the syntax of the available keywords. The syntax described - is expected to be compatible with the vocabularies declared; while - it is possible to describe an incompatible syntax, such a meta-schema - would be unlikely to be useful. - - +
+
Declaring the vocabularies in use
+
+ The "$vocabulary" keyword, when it appears in a meta-schema, declares + which vocabularies are available to be used in schemas that refer + to that meta-schema. Vocabularies define keyword semantics, + as well as their general syntax. +
+
Describing valid schema syntax
+
+ A schema MUST successfully validate against its meta-schema, which + constrains the syntax of the available keywords. The syntax described + is expected to be compatible with the vocabularies declared; while + it is possible to describe an incompatible syntax, such a meta-schema + would be unlikely to be useful. +
+
Meta-schemas are separate from vocabularies to allow for vocabularies to be combined in different ways, and for meta-schema authors @@ -1604,9 +1600,7 @@ integers, where the positive integer constraint is a subschema in "$defs": -
- - - -
+]]>
@@ -1765,9 +1757,7 @@ For example, consider this schema: -
- - - -
+]]> When an implementation encounters the <#/$defs/single> schema, it resolves the "$anchor" value as a fragment name against the current @@ -1831,13 +1819,11 @@ SHOULD NOT use such IRIs to identify embedded schema resources or locations within them. -
- - Consider the following schema document that contains another - schema resource embedded within it: - - - + Consider the following schema document that contains another + schema resource embedded within it: + + - -
+]]> The IRI "https://example.com/foo#/items" points to the "items" schema, which is an embedded resource. The canonical IRI of that schema @@ -1859,35 +1843,32 @@ to the correct object, but that object's IRI relative to its resource's canonical IRI is "https://example.com/bar#/additionalProperties". -
- - Now consider the following two schema resources linked by reference - using a IRI value for "$ref": - - - + Now consider the following two schema resources linked by reference + using a IRI value for "$ref": + + + - - - Here we see that "https://example.com/bar#/additionalProperties", - using a JSON Pointer fragment appended to the canonical IRI of - the "bar" schema resource, is still valid, while - "https://example.com/foo#/items/additionalProperties", which relied - on a JSON Pointer fragment appended to the canonical IRI of the - "foo" schema resource, no longer resolves to anything. - -
+]]> + + Here we see that "https://example.com/bar#/additionalProperties", + using a JSON Pointer fragment appended to the canonical IRI of + the "bar" schema resource, is still valid, while + "https://example.com/foo#/items/additionalProperties", which relied + on a JSON Pointer fragment appended to the canonical IRI of the + "foo" schema resource, no longer resolves to anything. + Note also that "https://example.com/foo#/items" is valid in both arrangements, but resolves to a different value. This IRI ends up @@ -2080,13 +2061,9 @@ Link header. An example of such a header would be: -
- - ; rel="describedby" - ]]> - -
+ ; rel="describedby" +]]> @@ -2111,13 +2088,9 @@ of significance, the JSON Schema library name/version should precede 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. @@ -2155,20 +2128,20 @@ For schema author convenience, there are some exceptions among the keywords in this vocabulary: - - - "additionalProperties", whose behavior is defined in terms of - "properties" and "patternProperties" - - - "items", whose behavior is defined in terms of "prefixItems" - - - "contains", whose behavior is affected by the presence and value of - "minContains" - - +
@@ -2679,18 +2652,18 @@ Schema keywords typically operate independently, without affecting each other's outcomes. However, the keywords in this vocabulary are notable exceptions: - - - "unevaluatedItems", whose behavior is defined in terms of annotations - from "prefixItems", "items", "contains", and itself - - - "unevaluatedProperties", whose behavior is defined in terms of - annotations from "properties", "patternProperties", - "additionalProperties", "contains", and itself - - +
    +
  • + "unevaluatedItems", whose behavior is defined in terms of annotations + from "prefixItems", "items", "contains", and itself +
    • +
  • + "unevaluatedProperties", whose behavior is defined in terms of + annotations from "properties", "patternProperties", + "additionalProperties", "contains", and itself +
    • +
@@ -2802,20 +2775,25 @@ This specification defines three output formats. See the "Output Structure" section for the requirements of each format. - - - Flag - A boolean which simply indicates the overall validation result - with no further details. - - - List - Provides validation information in a flat list structure. - - - Hierarchical - Provides validation information in a hierarchical - structure that follows the evaluation paths generated while processing - the schema. - - + +
+
Flag
+
+ A boolean which simply indicates the overall validation result + with no further details. +
+
List
+
+ Provides validation information in a flat list structure. +
+
Hierarchical
+
+ Provides validation information in a hierarchical + structure that follows the evaluation paths generated while processing + the schema. +
+
+ An implementation MUST provide the "flag" format and SHOULD provide at least one of the "list" or "hierarchical" formats. Implementations SHOULD specify in their documentation which formats they support. @@ -2839,7 +2817,7 @@
- The evalutaion path to the schema object that produced the output unit. + The evaluation path to the schema object that produced the output unit. The value MUST be expressed as a JSON Pointer, and it MUST include any by-reference applicators such as "$ref" or "$dynamicRef". @@ -2848,13 +2826,9 @@ path only. -
- - - -
+]]> Note that this pointer may not be resolvable by the normal JSON Pointer process due to the inclusion of these by-reference applicator keywords. @@ -2879,13 +2853,10 @@ schema object. -
- - - -
+ The JSON key for this information is "schemaLocation". @@ -3010,19 +2981,18 @@ https://example.com/schemas/common#/$defs/allOf/1 The output MUST be an object containing a boolean property named "valid". When additional information about the result is required, the output MUST also contain "details" as described below. - - - "valid" - a boolean value indicating the overall validation success or failure - - - "details" - the collection of results produced by subschemas - - + +
+
valid
+
a boolean value indicating the overall validation success or failure
+ +
details
+
the collection of results produced by subschemas
+
+ For these examples, the following schema and instances will be used. -
- - - -
+]]> The failing instance will produce the following errors: - - - The value at "/foo" - evaluated at "/properties/foo/allOf/0" - by following the path "/properties/foo/allOf/0" - by the "required" keyword - is missing the property "unspecified-prop". - - - The value at "/foo/foo-prop" - evaluated at "/properties/foo/allOf/1/properties/foo-prop" - by following the path "/properties/foo/allOf/1/properties/foo-prop" - by the "const" keyword - is not the constant value 1. - - - The value at "/bar/bar-prop" - evaluated at "/$defs/bar/properties/bar-prop" - by following the path "/properties/bar/$ref/properties/bar-prop" - by the "type" keyword - is not a number. - - + +
    +
  • + The value at "/foo" + evaluated at "/properties/foo/allOf/0" + by following the path "/properties/foo/allOf/0" + by the "required" keyword + is missing the property "unspecified-prop". +
    • +
  • + The value at "/foo/foo-prop" + evaluated at "/properties/foo/allOf/1/properties/foo-prop" + by following the path "/properties/foo/allOf/1/properties/foo-prop" + by the "const" keyword + is not the constant value 1. +
    • +
  • + The value at "/bar/bar-prop" + evaluated at "/$defs/bar/properties/bar-prop" + by following the path "/properties/bar/$ref/properties/bar-prop" + by the "type" keyword + is not a number. +
    • +
+ "minimum" doesn't produce an error because it only operates on instances that are numbers. @@ -3120,63 +3090,63 @@ https://example.com/schemas/common#/$defs/allOf/1 The passing instance will produce the following annotations: - - - The keyword "title" - evaluated at "" - by following the path "" - will produce "root". - - - The keyword "properties" - evaluated at "" - by following the path "" - will produce ["foo", "bar"]. - - - The keyword "title" - evaluated at "/properties/foo" - by following the path "/properties/foo" - will produce "foo-title". - - - The keyword "properties" - evaluated at "/properties/foo/allOf/1" - by following the path "/properties/foo/allOf/1" - will produce ["foo-prop"]. - - - The keyword "additionalProperties" - evaluated at "/properties/foo/allOf/1" - by following the path "/properties/foo/allOf/1" - will produce ["unspecified-prop"]. - - - The keyword "title" - evaluated at "/properties/foo/allOf/1/properties/foo-prop" - by following the path "/properties/foo/allOf/1/properties/foo-prop" - will produce "foo-prop-title". - - - The keyword "title" - evaluated at "/$defs/bar" - by following the path "/properties/bar/$ref" - will produce "bar-title". - - - The keyword "properties" - evaluated at "/$defs/bar" - by following the path "/properties/var/$ref" - will produce ["bar-prop"]. - - - The keyword "title" - evaluated at "/$defs/bar/properties/bar-prop" - by following the path "/properties/bar/$ref/properties/bar-prop" - will produce "bar-prop-title". - - +
    +
  • + The keyword "title" + evaluated at "" + by following the path "" + will produce "root". +
    • +
  • + The keyword "properties" + evaluated at "" + by following the path "" + will produce ["foo", "bar"]. +
    • +
  • + The keyword "title" + evaluated at "/properties/foo" + by following the path "/properties/foo" + will produce "foo-title". +
    • +
  • + The keyword "properties" + evaluated at "/properties/foo/allOf/1" + by following the path "/properties/foo/allOf/1" + will produce ["foo-prop"]. +
    • +
  • + The keyword "additionalProperties" + evaluated at "/properties/foo/allOf/1" + by following the path "/properties/foo/allOf/1" + will produce ["unspecified-prop"]. +
    • +
  • + The keyword "title" + evaluated at "/properties/foo/allOf/1/properties/foo-prop" + by following the path "/properties/foo/allOf/1/properties/foo-prop" + will produce "foo-prop-title". +
    • +
  • + The keyword "title" + evaluated at "/$defs/bar" + by following the path "/properties/bar/$ref" + will produce "bar-title". +
    • +
  • + The keyword "properties" + evaluated at "/$defs/bar" + by following the path "/properties/var/$ref" + will produce ["bar-prop"]. +
    • +
  • + The keyword "title" + evaluated at "/$defs/bar/properties/bar-prop" + by following the path "/properties/bar/$ref/properties/bar-prop" + will produce "bar-prop-title". +
    • +
@@ -3184,15 +3154,11 @@ https://example.com/schemas/common#/$defs/allOf/1 needs to be fulfilled. For this format, all other information is explicitly omitted. -
- - - -
+]]> Because no errors or annotations are returned with this format, it is RECOMMENDED that implementations use short-circuiting logic to return @@ -3220,9 +3186,7 @@ https://example.com/schemas/common#/$defs/allOf/1 from this format, however implementations MAY choose to include them for completeness. -
- - - -
+]]>
@@ -3339,9 +3301,7 @@ https://example.com/schemas/common#/$defs/allOf/1 The location properties of the root output unit MAY be omitted. -
- - - -
+
@@ -3582,60 +3541,77 @@ https://example.com/schemas/common#/$defs/allOf/1
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 above. - - - Interoperability considerations: See Sections - , - , and - above. - - - Fragment identifier considerations: See - - - +
+
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 above.
+ +
Interoperability considerations:
+
+ See Sections + , + , and + above. +
+ +
Fragment identifier considerations:
+
+ See +
+
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: N/A - - Encoding considerations: Encoding considerations are - identical to those specified for the "application/json" - media type. See JSON. - - - Security considerations: See above. - - - Interoperability considerations: See Sections - , - , and - above. - - - Fragment identifier considerations: See - - +
+
Type name:
+
application
+ +
Subtype name:
+
schema-instance+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 above.
+ +
Interoperability considerations:
+
+ See Sections + , + , and + above. +
+ +
Fragment identifier considerations:
+
See
+
@@ -3729,14 +3705,12 @@ https://example.com/schemas/common#/$defs/allOf/1
-
- - Consider the following schema, which shows "$id" being used to identify - both the root schema and various subschemas, and "$anchor" being used - to define plain name fragment identifiers. - - - + Consider the following schema, which shows "$id" being used to identify + both the root schema and various subschemas, and "$anchor" being used + to define plain name fragment identifiers. + + - -
+]]> The schemas at the following IRI-encoded JSON Pointers (relative to the root schema) have the following base IRIs, and are identifiable by any listed IRI in accordance with and above. - - - - - - https://example.com/root.json - - - https://example.com/root.json# - - - - - - https://example.com/root.json - - https://example.com/root.json#foo - - - https://example.com/root.json#/$defs/A - - - - - - https://example.com/other.json - - https://example.com/other.json# - - - https://example.com/root.json#/$defs/B - - - - - - https://example.com/other.json - - https://example.com/other.json#bar - - - https://example.com/other.json#/$defs/X - - - https://example.com/root.json#/$defs/B/$defs/X - - - - - - https://example.com/t/inner.json - - https://example.com/t/inner.json#bar - - - https://example.com/t/inner.json# - - - https://example.com/other.json#/$defs/Y - - - https://example.com/root.json#/$defs/B/$defs/Y - - - - - - - urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f - - - urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f# - - - https://example.com/root.json#/$defs/C - - - - - +
+
# (document root)
+
+
+
canonical (and base) IRI"
+
https://example.com/root.json
+ +
canonical resource IRI plus pointer fragment"
+
https://example.com/root.json#
+
+
+ +
#/$defs/A
+
+
+
base IRI
+
https://example.com/root.json
+ +
canonical resource IRI plus plain fragment
+
https://example.com/root.json#foo
+ +
canonical resource IRI plus pointer fragment
+
https://example.com/root.json#/$defs/A
+
+
+ +
#/$defs/B
+
+
+
canonical (and base) IRI
+
https://example.com/other.json
+ +
canonical resource IRI plus pointer fragment
+
https://example.com/other.json#
+ +
base IRI of enclosing (root.json) resource plus fragment
+
https://example.com/root.json#/$defs/B
+
+
+ +
#/$defs/B/$defs/X
+
+
+
base IRI
+
https://example.com/other.json
+ +
canonical resource IRI plus plain fragment
+
https://example.com/other.json#bar
+ +
canonical resource IRI plus pointer fragment
+
https://example.com/other.json#/$defs/X
+ +
base IRI of enclosing (root.json) resource plus fragment
+
https://example.com/root.json#/$defs/B/$defs/X
+
+
+ +
#/$defs/B/$defs/Y
+
+
+
canonical (and base) IRI
+
https://example.com/t/inner.json
+ +
canonical IRI plus plain fragment
+
https://example.com/t/inner.json#bar
+ +
canonical IRI plus pointer fragment
+
https://example.com/t/inner.json#
+ +
base IRI of enclosing (other.json) resource plus fragment
+
https://example.com/other.json#/$defs/Y
+ +
base IRI of enclosing (root.json) resource plus fragment
+
https://example.com/root.json#/$defs/B/$defs/Y
+
+
+ +
#/$defs/C
+
+
+
canonical (and base) IRI
+
urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f
+ +
canonical IRI plus pointer fragment
+
urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f#
+ +
base IRI of enclosing (root.json) resource plus fragment
+
https://example.com/root.json#/$defs/C
+
+
+
Note: The fragment part of the IRI does not make it canonical or non-canonical, rather, the base IRI used (as part of the full IRI with any fragment) is what @@ -3911,17 +3894,15 @@ https://example.com/schemas/common#/$defs/allOf/1
-
- + Consider the following two schemas describing a simple recursive tree structure, where each node in the tree can have a "data" field of any type. The first schema allows and ignores other instance properties. The second is more strict and only allows the "data" and "children" properties. An example instance with "data" misspelled as "daat" is also shown. - - - + - -
+]]> When we load these two schemas, we will notice the "$dynamicAnchor" named "node" (note the lack of "#" as this is just the name) present in each, resulting in the following full schema IRIs: - - "https://example.com/tree#node" - "https://example.com/strict-tree#node" - +
    +
  • "https://example.com/tree#node"
    • +
  • "https://example.com/strict-tree#node"
    • +
In addition, JSON Schema implementations keep track of the fact that these fragments were created with "$dynamicAnchor". @@ -3981,22 +3960,22 @@ https://example.com/schemas/common#/$defs/allOf/1 At this point, the evaluation path is "#/$ref/properties/children/items/$dynamicRef", with a dynamic scope containing (from the outermost scope to the innermost): - - "https://example.com/strict-tree#" - "https://example.com/tree#" - "https://example.com/tree#/properties/children" - "https://example.com/tree#/properties/children/items" - +
    +
  1. "https://example.com/strict-tree#"
    2. +
  2. "https://example.com/tree#"
    3. +
  3. "https://example.com/tree#/properties/children"
    4. +
  4. "https://example.com/tree#/properties/children/items"
    5. +
Since we are looking for a plain name fragment, which can be defined anywhere within a schema resource, the JSON Pointer fragments are irrelevant to this check. That means that we can remove those fragments and eliminate consecutive duplicates, producing: - - "https://example.com/strict-tree" - "https://example.com/tree" - +
    +
  1. "https://example.com/strict-tree"
    2. +
  2. "https://example.com/tree"
    3. +
In this case, the outermost resource also has a "node" fragment @@ -4109,12 +4088,10 @@ https://example.com/schemas/common#/$defs/allOf/1 outside of vocabularies, making them unsuitable for use except in a specific environment in which they are understood. -
- - This meta-schema combines several vocabularies for general use. - - - + This meta-schema combines several vocabularies for general use. + + - -
-
- - This meta-schema describes only a single extension vocabulary. - - - + + This meta-schema describes only a single extension vocabulary. + + - -
+]]> As shown above, even though each of the single-vocabulary meta-schemas referenced in the general-use meta-schema's "allOf" declares its @@ -4207,16 +4178,14 @@ https://example.com/schemas/common#/$defs/allOf/1 is to create an annotation keyword for use in the same schema object alongside of a reference keyword such as "$ref". -
- - For example, here is a hypothetical keyword for determining - whether a code generator should consider the reference - target to be a distinct class, and how those classes are related. - Note that this example is solely for illustrative purposes, and is - not intended to propose a functional code generation keyword. - - - + For example, here is a hypothetical keyword for determining + whether a code generator should consider the reference + target to be a distinct class, and how those classes are related. + Note that this example is solely for illustrative purposes, and is + not intended to propose a functional code generation keyword. + + - -
+]]> Here, this schema represents some sort of object-oriented class. The first reference in the "allOf" is noted as the base class. @@ -4285,140 +4252,146 @@ https://example.com/schemas/common#/$defs/allOf/1
-
+
This section to be removed before leaving Internet-Draft status. - - - - - "contains" now applies to objects as well as arrays - Use IRIs instead of URIs - Remove bookending requirement for "$dynamicRef" - Add "propertyDependencies" keyword - - - - - Improve and clarify the "type", "contains", "unevaluatedProperties", and "unevaluatedItems" keyword explanations - Clarify various aspects of "canonical URIs" - Comment on ambiguity around annotations and "additionalProperties" - Clarify Vocabularies need not be formally defined - Remove references to remaining media-type parameters - Fix multiple examples - - - - - "$schema" MAY change for embedded resources - Array-value "items" functionality is now "prefixItems" - "items" subsumes the old function of "additionalItems" - "contains" annotation behavior, and "contains" and "unevaluatedItems" interactions now specified - Rename $recursive* to $dynamic*, with behavior modification - $dynamicAnchor defines a fragment like $anchor - $dynamic* (previously $recursive) no longer use runtime base URI determination - Define Compound Schema Documents (bundle) and processing - Reference ECMA-262, 11th edition for regular expression support - Regular expression should support unicode - Remove media type parameters - Specify Unknown keywords are collected as annotations - Moved "unevaluatedItems" and "unevaluatedProperties" from core into their own vocabulary - - - - - Update to RFC 8259 for JSON specification - Moved "definitions" from the Validation specification here as "$defs" - Moved applicator keywords from the Validation specification as their own vocabulary - Moved the schema form of "dependencies" from the Validation specification as "dependentSchemas" - Formalized annotation collection - Specified recommended output formats - Defined keyword interactions in terms of annotation and assertion results - Added "unevaluatedProperties" and "unevaluatedItems" - Define "$ref" behavior in terms of the assertion, applicator, and annotation model - Allow keywords adjacent to "$ref" - Note undefined behavior for "$ref" targets involving unknown keywords - Add recursive referencing, primarily for meta-schema extension - Add the concept of formal vocabularies, and how they can be recognized through meta-schemas - Additional guidance on initial base URIs beyond network retrieval - Allow "schema" media type parameter for "application/schema+json" - Better explanation of media type parameters and the HTTP Accept header - Use "$id" to establish canonical and base absolute-URIs only, no fragments - Replace plain-name-fragment-only form of "$id" with "$anchor" - Clarified that the behavior of JSON Pointers across "$id" boundary is unreliable - - - - - This draft is purely a clarification with no functional changes - Emphasized annotations as a primary usage of JSON Schema - Clarified $id by use cases - Exhaustive schema identification examples - Replaced "external referencing" with how and when an implementation might know of a schema from another document - Replaced "internal referencing" with how an implementation should recognized schema identifiers during parsing - Dereferencing the former "internal" or "external" references is always the same process - Minor formatting improvements - - - - - Make the concept of a schema keyword vocabulary more clear - Note that the concept of "integer" is from a vocabulary, not the data model - Classify keywords as assertions or annotations and describe their general behavior - Explain the boolean schemas in terms of generalized assertions - Reserve "$comment" for non-user-visible notes about the schema - Wording improvements around "$id" and fragments - Note the challenges of extending meta-schemas with recursive references - Add "application/schema-instance+json" media type - Recommend a "schema" link relation / parameter instead of "profile" - - - - - Updated intro - Allowed for any schema to be a boolean - "$schema" SHOULD NOT appear in subschemas, although that may change - Changed "id" to "$id"; all core keywords prefixed with "$" - Clarify and formalize fragments for application/schema+json - Note applicability to formats such as CBOR that can be represented in the JSON data model - - - - - Updated references to JSON - Updated references to HTTP - Updated references to JSON Pointer - Behavior for "id" is now specified in terms of RFC3986 - Aligned vocabulary usage for URIs with RFC3986 - Removed reference to draft-pbryan-zyp-json-ref-03 - Limited use of "$ref" to wherever a schema is expected - Added definition of the "JSON Schema data model" - Added additional security considerations - Defined use of subschema identifiers for "id" - Rewrote section on usage with HTTP - Rewrote section on usage with rel="describedBy" and rel="profile" - Fixed numerous invalid examples - - - - - Salvaged from draft v3. - Split validation keywords into separate document. - Split hypermedia keywords into separate document. - Initial post-split draft. - Mandate the use of JSON Reference, JSON Pointer. - Define the role of "id". Define URI resolution scope. - Add interoperability considerations. - - - - - Initial draft. - - - - + +
+
    +
  • "contains" now applies to objects as well as arrays
    • +
  • Use IRIs instead of URIs
    • +
  • Remove bookending requirement for "$dynamicRef"
    • +
  • Add "propertyDependencies" keyword
    • +
+
+ +
+
    +
  • Improve and clarify the "type", "contains", "unevaluatedProperties", and "unevaluatedItems" keyword explanations
    • +
  • Clarify various aspects of "canonical URIs"
    • +
  • Comment on ambiguity around annotations and "additionalProperties"
    • +
  • Clarify Vocabularies need not be formally defined
    • +
  • Remove references to remaining media-type parameters
    • +
  • Fix multiple examples
    • +
+
+ +
+
    +
  • "$schema" MAY change for embedded resources
    • +
  • Array-value "items" functionality is now "prefixItems"
    • +
  • "items" subsumes the old function of "additionalItems"
    • +
  • "contains" annotation behavior, and "contains" and "unevaluatedItems" interactions now specified
    • +
  • Rename $recursive* to $dynamic*, with behavior modification
    • +
  • $dynamicAnchor defines a fragment like $anchor
    • +
  • $dynamic* (previously $recursive) no longer use runtime base URI determination
    • +
  • Define Compound Schema Documents (bundle) and processing
    • +
  • Reference ECMA-262, 11th edition for regular expression support
    • +
  • Regular expression should support unicode
    • +
  • Remove media type parameters
    • +
  • Specify Unknown keywords are collected as annotations
    • +
  • Moved "unevaluatedItems" and "unevaluatedProperties" from core into their own vocabulary
    • +
+
+ +
+
    +
  • Update to RFC 8259 for JSON specification
    • +
  • Moved "definitions" from the Validation specification here as "$defs"
    • +
  • Moved applicator keywords from the Validation specification as their own vocabulary
    • +
  • Moved the schema form of "dependencies" from the Validation specification as "dependentSchemas"
    • +
  • Formalized annotation collection
    • +
  • Specified recommended output formats
    • +
  • Defined keyword interactions in terms of annotation and assertion results
    • +
  • Added "unevaluatedProperties" and "unevaluatedItems"
    • +
  • Define "$ref" behavior in terms of the assertion, applicator, and annotation model
    • +
  • Allow keywords adjacent to "$ref"
    • +
  • Note undefined behavior for "$ref" targets involving unknown keywords
    • +
  • Add recursive referencing, primarily for meta-schema extension
    • +
  • Add the concept of formal vocabularies, and how they can be recognized through meta-schemas
    • +
  • Additional guidance on initial base URIs beyond network retrieval
    • +
  • Allow "schema" media type parameter for "application/schema+json"
    • +
  • Better explanation of media type parameters and the HTTP Accept header
    • +
  • Use "$id" to establish canonical and base absolute-URIs only, no fragments
    • +
  • Replace plain-name-fragment-only form of "$id" with "$anchor"
    • +
  • Clarified that the behavior of JSON Pointers across "$id" boundary is unreliable
    • +
+
+ +
+
    +
  • This draft is purely a clarification with no functional changes
    • +
  • Emphasized annotations as a primary usage of JSON Schema
    • +
  • Clarified $id by use cases
    • +
  • Exhaustive schema identification examples
    • +
  • Replaced "external referencing" with how and when an implementation might know of a schema from another document
    • +
  • Replaced "internal referencing" with how an implementation should recognized schema identifiers during parsing
    • +
  • Dereferencing the former "internal" or "external" references is always the same process
    • +
  • Minor formatting improvements
    • +
+
+ +
+
    +
  • Make the concept of a schema keyword vocabulary more clear
    • +
  • Note that the concept of "integer" is from a vocabulary, not the data model
    • +
  • Classify keywords as assertions or annotations and describe their general behavior
    • +
  • Explain the boolean schemas in terms of generalized assertions
    • +
  • Reserve "$comment" for non-user-visible notes about the schema
    • +
  • Wording improvements around "$id" and fragments
    • +
  • Note the challenges of extending meta-schemas with recursive references
    • +
  • Add "application/schema-instance+json" media type
    • +
  • Recommend a "schema" link relation / parameter instead of "profile"
    • +
+
+ +
+
    +
  • Updated intro
    • +
  • Allowed for any schema to be a boolean
    • +
  • "$schema" SHOULD NOT appear in subschemas, although that may change
    • +
  • Changed "id" to "$id"; all core keywords prefixed with "$"
    • +
  • Clarify and formalize fragments for application/schema+json
    • +
  • Note applicability to formats such as CBOR that can be represented in the JSON data model
    • +
+
+ +
+
    +
  • Updated references to JSON
    • +
  • Updated references to HTTP
    • +
  • Updated references to JSON Pointer
    • +
  • Behavior for "id" is now specified in terms of RFC3986
    • +
  • Aligned vocabulary usage for URIs with RFC3986
    • +
  • Removed reference to draft-pbryan-zyp-json-ref-03
    • +
  • Limited use of "$ref" to wherever a schema is expected
    • +
  • Added definition of the "JSON Schema data model"
    • +
  • Added additional security considerations
    • +
  • Defined use of subschema identifiers for "id"
    • +
  • Rewrote section on usage with HTTP
    • +
  • Rewrote section on usage with rel="describedBy" and rel="profile"
    • +
  • Fixed numerous invalid examples
    • +
+
+ +
+
    +
  • Salvaged from draft v3.
    • +
  • Split validation keywords into separate document.
    • +
  • Split hypermedia keywords into separate document.
    • +
  • Initial post-split draft.
    • +
  • Mandate the use of JSON Reference, JSON Pointer.
    • +
  • Define the role of "id". Define URI resolution scope.
    • +
  • Add interoperability considerations.
    • +
+
+ +
+
    +
  • Initial draft.
    • +
+