From 331821050a22ad97d5ea67feb4cef330a766945e Mon Sep 17 00:00:00 2001 From: Ben Hutton Date: Fri, 4 May 2018 13:46:10 +0100 Subject: [PATCH 1/5] $ref is applicable to the current instance. Other properties of an object containing $ref as a key no longer MUST be ignored. --- jsonschema-core.xml | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 557f2747..bc9018b6 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -791,14 +791,19 @@
- 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 assertion key word, which MUST produce a boolean + assertion result when the resolved schema is applied. + + The use of "$ref" MUST NOT effect adjacent keywords. + Given previously the use of "$ref" would negate the use of other keywords in that object, + it seems like a good thing to mention. + Should be removed before leaving Internet Draft + - 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. 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 From cf2aea02077137fe28c01132a894e6d5645abd47 Mon Sep 17 00:00:00 2001 From: Ben Hutton Date: Wed, 9 May 2018 13:35:34 +0100 Subject: [PATCH 2/5] Added information about dereferencing URIs where a protocol is defined using an interface provided by the implementation. May be just a reiteration of the "loading a referenced schema", but I've added a use case. --- jsonschema-core.xml | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index bc9018b6..c436e364 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -806,10 +806,7 @@ 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-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 @@ -819,7 +816,30 @@ 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 retrieve + the network accessible resource. + + + A schema author wants to define a means to retrieve a specific URI protocol. An implementation may allow + the user to specify a method to perform a network operation (or other operation) to retrieve the reference + content. For example, the behaviour of a URI with a protocol of "file" is not defined. The implementation + provides an interface to define a function which is called when it encounters a URI which uses the specified + URI protocol (which is "file" in this case). The user defines "file" as the protocol, and includes a function + (or some form of instruction) using the interface, which will be triggered to retrieve any reference defined + with a URI that uses a protocol of "file". This is similar to "adding a schema" where implementations track + added schema's $id, allowing them to be later used in reference. + + + 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, From 649dba99901ea6e93dfb7e097cb3a574bf94b330 Mon Sep 17 00:00:00 2001 From: Ben Hutton Date: Wed, 9 May 2018 15:34:25 +0100 Subject: [PATCH 3/5] Defined behaviour for dereferencing by inclusion, which MUST NOT be the default behaviour, but MAY be provided as an option. --- jsonschema-core.xml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index c436e364..46ffa9c4 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -928,6 +928,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. + +
From 1bb0f5a5ac552fc3b5d97d47e20ed12e95b83a54 Mon Sep 17 00:00:00 2001 From: Ben Hutton Date: Thu, 21 Jun 2018 10:42:19 +0100 Subject: [PATCH 4/5] Changed language to make clear that `$ref` is an applicator key word and not an assertion key word. Removed sections which explain implementation detail or use case. Slightly modified language around network addressable locators. Mention recursive structures. --- jsonschema-core.xml | 35 ++++++++++++----------------------- 1 file changed, 12 insertions(+), 23 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 46ffa9c4..93a13c1b 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -792,17 +792,16 @@
The "$ref" keyword can be used to reference a schema which is to be applied to the - current instance location. "$ref" is an assertion key word, which MUST produce a boolean - assertion result when the resolved schema is applied. + current instance location. "$ref" is an applicator key word, applying the referenced + schema to the instance. + + + 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 use of "$ref" MUST NOT effect adjacent keywords. - Given previously the use of "$ref" would negate the use of other keywords in that object, - it seems like a good thing to mention. - Should be removed before leaving Internet Draft - - The value of the "$ref" property MUST be a URI 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. @@ -820,22 +819,12 @@ 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 retrieve - the network accessible resource. + A URI reference with a network addressable locator defined MAY be provided with an interface to resolve + the reference as a network accessible resource. - - A schema author wants to define a means to retrieve a specific URI protocol. An implementation may allow - the user to specify a method to perform a network operation (or other operation) to retrieve the reference - content. For example, the behaviour of a URI with a protocol of "file" is not defined. The implementation - provides an interface to define a function which is called when it encounters a URI which uses the specified - URI protocol (which is "file" in this case). The user defines "file" as the protocol, and includes a function - (or some form of instruction) using the interface, which will be triggered to retrieve any reference defined - with a URI that uses a protocol of "file". This is similar to "adding a schema" where implementations track - added schema's $id, allowing them to be later used in reference. - - Any URI may be resolvable by use of externally defined references provided to the implementation as per the - Loading a referenced schema section. + Any URI may be resolvable by use of externally defined references provided to the implementation as per the + Loading a referenced schema section. From 97c3c291086d15caf40417725db2d357241fe006 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 21 Jun 2018 15:12:10 -0700 Subject: [PATCH 5/5] Fix misplaced elements --- jsonschema-core.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 93a13c1b..18abaf5a 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -819,14 +819,13 @@ 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. - -