diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 557f2747..18abaf5a 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -791,20 +791,21 @@
- The "$ref" keyword is used to reference a schema, and provides the ability to - validate recursive structures through self-reference. + The "$ref" keyword can be used to reference a schema which is to be applied to the + current instance location. "$ref" is an applicator key word, applying the referenced + schema to the instance. - An object schema with a "$ref" property MUST be interpreted as a "$ref" reference. - The value of the "$ref" property MUST be a URI Reference. + By being an applicator key word, "$ref" allows the posibility to externalise or + segment a schema across multiple files, and provides the ability to validate recursive structures + through self-reference. + + + The value of the "$ref" property MUST be a string URI Reference. Resolved against the current URI base, it identifies the URI of a schema to use. - All other properties in a "$ref" object MUST be ignored. - The URI is not a network locator, only an identifier. A schema need not be - downloadable from the address if it is a network-addressable URL, and - implementations SHOULD NOT assume they should perform a network operation when they - encounter a network-addressable URI. + A URI may be a locator, a name, or both, per RFC 3986. A schema MUST NOT be run into an infinite loop against a schema. For example, if two @@ -814,7 +815,19 @@ Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is undefined. -
+ + A URI reference without a protocol MUST be considered a plain name fragment, + and the URI reference location resolved according to "$id" keyword section. + + + A URI reference with a network addressable locator defined MAY be provided with an interface to resolve + the reference as a network accessible resource. + + + Any URI may be resolvable by use of externally defined references provided to the implementation as per the + Loading a referenced schema section. + +
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, @@ -903,6 +916,24 @@
+
+ + It MUST NOT be expected that any schema can be dereferenced by the means of replacing any object that + uses the "$ref" keyword with the resolved referenced schema (inclusion). An interface MAY be provided + to dereference a schema by means of inclusion, however it MUST NOT be the default behaviour. + + + The use of "$id" and "$ref" from external schemas MUST be evaluate correctly, and not evaluated after + any inclusion process. + + + The result of any inclusion process MUST NOT effect previously adjacent keywords to the original "$ref" keyword + + + A behaviour when a resolved schema which defines a schema version which is different to that of the base JSON Schema document + is not defined. + +