diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index 19ef4c5e..e5ddec9d 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -1306,30 +1306,6 @@
as those listed here.
-
-
- Implementations MUST recognize a schema as a meta-schema if it
- is being examined because it was identified as such by another
- schema's "$schema" keyword. This means that a single schema
- document might sometimes be considered a regular schema, and
- other times be considered a meta-schema.
-
-
- In the case of examining a schema which is its own meta-schema,
- when an implementation begins processing it as a regular schema,
- it is processed under those rules. However, when loaded a second
- time as a result of checking its own "$schema" value, it is treated
- as a meta-schema. So the same document is processed both ways in
- the course of one session.
-
-
- Implementations MAY allow a schema to be explicitly passed as a meta-schema,
- for implementation-specific purposes, such as pre-loading a commonly
- used meta-schema and checking its vocabulary support requirements
- up front. Meta-schema authors MUST NOT expect such features to be
- interoperable across implementations.
-
-
@@ -1344,34 +1320,6 @@
it is necessary to establish a base URI in order to resolve the reference.
-
-
- RFC3986 Section 5.1 defines how to determine the
- default base URI of a document.
-
-
- Informatively, the initial base URI of a schema is the URI at which it was
- found, whether that was a network location, a local filesystem, or any other
- situation identifiable by a URI of any known scheme.
-
-
- If a schema document defines no explicit base URI with "$id"
- (embedded in content), the base URI is that determined per
- RFC 3986 section 5.
-
-
- If no source is known, or no URI scheme is known for the source, a suitable
- implementation-specific default URI MAY be used as described in
- RFC 3986 Section 5.1.4. It is RECOMMENDED
- that implementations document any default base URI that they assume.
-
-
- Unless the "$id" keyword described in the next section is present in the
- root schema, this base URI SHOULD be considered the canonical URI of the
- schema document's root schema resource.
-
-
-
The "$id" keyword identifies a schema resource with its
@@ -1428,106 +1376,6 @@
but no fragment).
-
-
- Since JSON Pointer URI fragments are constructed based on the structure
- of the schema document, an embedded schema resource and its subschemas
- can be identified by JSON Pointer fragments relative to either its own
- canonical URI, or relative to the containing resource's URI.
-
-
- Conceptually, a set of linked schema resources should behave
- identically whether each resource is a separate document connected with
- schema references, or is structured as
- a single document with one or more schema resources embedded as
- subschemas.
-
-
- Since URIs involving JSON Pointer fragments relative to the parent
- schema resource's URI cease to be valid when the embedded schema
- is moved to a separate document and referenced, applications and schemas
- SHOULD NOT use such URIs to identify embedded schema resources or
- locations within them.
-
-
-
- Consider the following schema document that contains another
- schema resource embedded within it:
-
-
-
-
-
- The URI "https://example.com/foo#/items/additionalProperties"
- points to the schema of the "additionalProperties" keyword in
- the embedded resource. The canonical URI of that schema, however,
- is "https://example.com/bar#/additionalProperties".
-
-
-
-
- Now consider the following two schema resources linked by reference
- using a URI value for "$ref":
-
-
-
-
-
- Here we see that the canonical URI for that "additionalProperties"
- subschema is still valid, while the non-canonical URI with the fragment
- beginning with "#/items/$ref" now resolves to nothing.
-
-
-
- Note also that "https://example.com/foo#/items" is valid in both
- arrangments, but resolves to a different value. This URI ends up
- functioning similarly to a retrieval URI for a resource. While valid,
- examining the resolved value and either using the "$id" (if the value
- is a subschema), or resolving the reference and using the "$id" of the
- reference target, is preferable.
-
-
- An implementation MAY choose not to support addressing schemas
- by non-canonical URIs. As such, it is RECOMENDED that schema authors only
- use canonical URIs, as using non-canonical URIs may reduce
- schema interoperability.
-
- This is to avoid requiring implementations to keep track of a whole
- stack of possible base URIs and JSON Pointer fragments for each,
- given that all but one will be fragile if the schema resources
- are reorganized. Some have argued that this is easy so there is
- no point in forbidding it, while others have argued that it complicates
- schema identification and should be forbidden. Feedback on this
- topic is encouraged.
-
-
-
- Further examples of such non-canonical URIs, as well as the appropriate
- canonical URIs to use instead, are provided in appendix
- .
-
-
@@ -1696,141 +1544,6 @@
-
-
- A schema MUST NOT be run into an infinite loop against an instance. For
- example, if two schemas "#alice" and "#bob" both have an "allOf" property
- that refers to the other, a naive validator might get stuck in an infinite
- recursive loop trying to validate the instance. Schemas SHOULD NOT make
- use of infinite recursive nesting like this; the behavior is undefined.
-
-
-
-
-
- Subschema objects (or booleans) are recognized by their use with known
- applicator keywords or with location-reserving keywords such as
- "$defs" that take one or more subschemas
- as a value. These keywords may be "$defs" and the standard applicators
- from this document, or extension keywords from a known vocabulary, or
- implementation-specific custom keywords.
-
-
- Multi-level structures of unknown keywords are capable of introducing
- nested subschemas, which would be subject to the processing rules for
- "$id". Therefore, having a reference target in such an unrecognized
- structure cannot be reliably implemented, and the resulting behavior
- is undefined. Similarly, a reference target under a known keyword,
- for which the value is known not to be a schema, results in undefined
- behavior in order to avoid burdening implementations with the need
- to detect such targets.
-
- These scenarios are analogous to fetching a schema over HTTP
- but receiving a response with a Content-Type other than
- application/schema+json. An implementation can certainly
- try to interpret it as a schema, but the origin server
- offered no guarantee that it actually is any such thing.
- Therefore, interpreting it as such has security implications
- and may produce unpredictable results.
-
-
-
- Note that single-level custom keywords with identical syntax and
- semantics to "$defs" do not allow for any intervening "$id" keywords,
- and therefore will behave correctly under implementations that attempt
- to use any reference target as a schema. However, this behavior is
- implementation-specific and MUST NOT be relied upon for interoperability.
-
-
-
-
-
- The use of URIs to identify remote schemas does not necessarily mean anything is downloaded,
- but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using,
- and the URIs that identify them.
-
-
- When schemas are downloaded,
- for example by a generic user-agent that doesn't know until runtime which schemas to download,
- see Usage for Hypermedia.
-
-
- Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
- schema and/or automatically associate a schema's "$id"-given URI, depending
- on the trust that the validator has in the schema. Such URIs and schemas
- can be supplied to an implementation prior to processing instances, or may
- be noted within a schema document as it is processed, producing associations
- as shown in appendix .
-
-
- A schema MAY (and likely will) have multiple URIs, but there is no way for a
- URI to identify more than one schema. When multiple schemas try to identify
- as the same URI, validators SHOULD raise an error condition.
-
-
-
-
- Schemas can be identified by any URI that has been given to them, including
- a JSON Pointer or their URI given directly by "$id". In all cases,
- dereferencing a "$ref" reference involves first resolving its value as a
- URI reference against the current base URI per
- RFC 3986.
-
-
- If the resulting URI identifies a schema within the current document, or
- within another schema document that has been made available to the implementation,
- then that schema SHOULD be used automatically.
-
-
- For example, consider this schema:
-
-
-
-
-
-
-
-
- When an implementation encounters the <#/$defs/single> schema,
- it resolves the "$id" URI reference against the current base URI to form
- <https://example.net/root.json#item>.
-
-
- When an implementation then looks inside the <#/items> schema, it
- encounters the <#item> reference, and resolves this to
- <https://example.net/root.json#item>, which it has seen defined in
- this same document and can therefore use automatically.
-
-
- When an implementation encounters the reference to "other.json", it resolves
- this to <https://example.net/other.json>, which is not defined in this
- document. If a schema with that identifier has otherwise been supplied to
- the implementation, it can also be used automatically.
-
- What should implementations do when the referenced schema is not known?
- Are there circumstances in which automatic network dereferencing is
- allowed? A same origin policy? A user-configurable option? In the
- case of an evolving API described by Hyper-Schema, it is expected that
- new schemas will be added to the system dynamically, so placing an
- absolute requirement of pre-loading schema documents is not feasible.
-
-
-
@@ -1906,6 +1619,306 @@
+
+
+
+
+
+
+ RFC3986 Section 5.1 defines how to determine the
+ default base URI of a document.
+
+
+ Informatively, the initial base URI of a schema is the URI at which it was
+ found, whether that was a network location, a local filesystem, or any other
+ situation identifiable by a URI of any known scheme.
+
+
+ If a schema document defines no explicit base URI with "$id"
+ (embedded in content), the base URI is that determined per
+ RFC 3986 section 5.
+
+
+ If no source is known, or no URI scheme is known for the source, a suitable
+ implementation-specific default URI MAY be used as described in
+ RFC 3986 Section 5.1.4. It is RECOMMENDED
+ that implementations document any default base URI that they assume.
+
+
+ Unless the "$id" keyword described in the next section is present in the
+ root schema, this base URI SHOULD be considered the canonical URI of the
+ schema document's root schema resource.
+
+
+
+
+
+ The use of URIs to identify remote schemas does not necessarily mean anything is downloaded,
+ but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using,
+ and the URIs that identify them.
+
+
+ When schemas are downloaded,
+ for example by a generic user-agent that doesn't know until runtime which schemas to download,
+ see Usage for Hypermedia.
+
+
+ Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
+ schema and/or automatically associate a schema's "$id"-given URI, depending
+ on the trust that the validator has in the schema. Such URIs and schemas
+ can be supplied to an implementation prior to processing instances, or may
+ be noted within a schema document as it is processed, producing associations
+ as shown in appendix .
+
+
+ A schema MAY (and likely will) have multiple URIs, but there is no way for a
+ URI to identify more than one schema. When multiple schemas try to identify
+ as the same URI, validators SHOULD raise an error condition.
+
+
+
+
+
+ Implementations MUST recognize a schema as a meta-schema if it
+ is being examined because it was identified as such by another
+ schema's "$schema" keyword. This means that a single schema
+ document might sometimes be considered a regular schema, and
+ other times be considered a meta-schema.
+
+
+ In the case of examining a schema which is its own meta-schema,
+ when an implementation begins processing it as a regular schema,
+ it is processed under those rules. However, when loaded a second
+ time as a result of checking its own "$schema" value, it is treated
+ as a meta-schema. So the same document is processed both ways in
+ the course of one session.
+
+
+ Implementations MAY allow a schema to be explicitly passed as a meta-schema,
+ for implementation-specific purposes, such as pre-loading a commonly
+ used meta-schema and checking its vocabulary support requirements
+ up front. Meta-schema authors MUST NOT expect such features to be
+ interoperable across implementations.
+
+
+
+
+
+
+ Schemas can be identified by any URI that has been given to them, including
+ a JSON Pointer or their URI given directly by "$id". In all cases,
+ dereferencing a "$ref" reference involves first resolving its value as a
+ URI reference against the current base URI per
+ RFC 3986.
+
+
+ If the resulting URI identifies a schema within the current document, or
+ within another schema document that has been made available to the implementation,
+ then that schema SHOULD be used automatically.
+
+
+ For example, consider this schema:
+
+
+
+
+
+
+
+
+ When an implementation encounters the <#/$defs/single> schema,
+ it resolves the "$id" URI reference against the current base URI to form
+ <https://example.net/root.json#item>.
+
+
+ When an implementation then looks inside the <#/items> schema, it
+ encounters the <#item> reference, and resolves this to
+ <https://example.net/root.json#item>, which it has seen defined in
+ this same document and can therefore use automatically.
+
+
+ When an implementation encounters the reference to "other.json", it resolves
+ this to <https://example.net/other.json>, which is not defined in this
+ document. If a schema with that identifier has otherwise been supplied to
+ the implementation, it can also be used automatically.
+
+ What should implementations do when the referenced schema is not known?
+ Are there circumstances in which automatic network dereferencing is
+ allowed? A same origin policy? A user-configurable option? In the
+ case of an evolving API described by Hyper-Schema, it is expected that
+ new schemas will be added to the system dynamically, so placing an
+ absolute requirement of pre-loading schema documents is not feasible.
+
+
+
+
+
+ Since JSON Pointer URI fragments are constructed based on the structure
+ of the schema document, an embedded schema resource and its subschemas
+ can be identified by JSON Pointer fragments relative to either its own
+ canonical URI, or relative to the containing resource's URI.
+
+
+ Conceptually, a set of linked schema resources should behave
+ identically whether each resource is a separate document connected with
+ schema references, or is structured as
+ a single document with one or more schema resources embedded as
+ subschemas.
+
+
+ Since URIs involving JSON Pointer fragments relative to the parent
+ schema resource's URI cease to be valid when the embedded schema
+ is moved to a separate document and referenced, applications and schemas
+ SHOULD NOT use such URIs to identify embedded schema resources or
+ locations within them.
+
+
+
+ Consider the following schema document that contains another
+ schema resource embedded within it:
+
+
+
+
+
+ The URI "https://example.com/foo#/items/additionalProperties"
+ points to the schema of the "additionalProperties" keyword in
+ the embedded resource. The canonical URI of that schema, however,
+ is "https://example.com/bar#/additionalProperties".
+
+
+
+
+ Now consider the following two schema resources linked by reference
+ using a URI value for "$ref":
+
+
+
+
+
+ Here we see that the canonical URI for that "additionalProperties"
+ subschema is still valid, while the non-canonical URI with the fragment
+ beginning with "#/items/$ref" now resolves to nothing.
+
+
+
+ Note also that "https://example.com/foo#/items" is valid in both
+ arrangments, but resolves to a different value. This URI ends up
+ functioning similarly to a retrieval URI for a resource. While valid,
+ examining the resolved value and either using the "$id" (if the value
+ is a subschema), or resolving the reference and using the "$id" of the
+ reference target, is preferable.
+
+
+ An implementation MAY choose not to support addressing schemas
+ by non-canonical URIs. As such, it is RECOMENDED that schema authors only
+ use canonical URIs, as using non-canonical URIs may reduce
+ schema interoperability.
+
+ This is to avoid requiring implementations to keep track of a whole
+ stack of possible base URIs and JSON Pointer fragments for each,
+ given that all but one will be fragile if the schema resources
+ are reorganized. Some have argued that this is easy so there is
+ no point in forbidding it, while others have argued that it complicates
+ schema identification and should be forbidden. Feedback on this
+ topic is encouraged.
+
+
+
+ Further examples of such non-canonical URIs, as well as the appropriate
+ canonical URIs to use instead, are provided in appendix
+ .
+
+
+
+
+
+
+
+ A schema MUST NOT be run into an infinite loop against an instance. For
+ example, if two schemas "#alice" and "#bob" both have an "allOf" property
+ that refers to the other, a naive validator might get stuck in an infinite
+ recursive loop trying to validate the instance. Schemas SHOULD NOT make
+ use of infinite recursive nesting like this; the behavior is undefined.
+
+
+
+
+
+ Subschema objects (or booleans) are recognized by their use with known
+ applicator keywords or with location-reserving keywords such as
+ "$defs" that take one or more subschemas
+ as a value. These keywords may be "$defs" and the standard applicators
+ from this document, or extension keywords from a known vocabulary, or
+ implementation-specific custom keywords.
+
+
+ Multi-level structures of unknown keywords are capable of introducing
+ nested subschemas, which would be subject to the processing rules for
+ "$id". Therefore, having a reference target in such an unrecognized
+ structure cannot be reliably implemented, and the resulting behavior
+ is undefined. Similarly, a reference target under a known keyword,
+ for which the value is known not to be a schema, results in undefined
+ behavior in order to avoid burdening implementations with the need
+ to detect such targets.
+
+ These scenarios are analogous to fetching a schema over HTTP
+ but receiving a response with a Content-Type other than
+ application/schema+json. An implementation can certainly
+ try to interpret it as a schema, but the origin server
+ offered no guarantee that it actually is any such thing.
+ Therefore, interpreting it as such has security implications
+ and may produce unpredictable results.
+
+
+
+ Note that single-level custom keywords with identical syntax and
+ semantics to "$defs" do not allow for any intervening "$id" keywords,
+ and therefore will behave correctly under implementations that attempt
+ to use any reference target as a schema. However, this behavior is
+ implementation-specific and MUST NOT be relied upon for interoperability.
+
+
+
+
+
+
This section defines a vocabulary of applicator keywords that