From 9e69ef6b6790785a00b6b7cd2121b2c40f11787a Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 28 Feb 2018 13:22:09 -0700 Subject: [PATCH 1/6] Core: Improve language for schema references section --- jsonschema-core.xml | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index b74fe22a..b1b19993 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -557,8 +557,8 @@
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with - a URI (containing a scheme). This URI SHOULD either not have a fragment, or - have one that is an empty string. + an absolute-URI (containing a scheme, but no fragment), + or this absolute URI but with an empty fragment.
@@ -583,18 +583,16 @@ without requiring JSON Pointer references to be updated. - To name subschemas in a JSON Schema document, - subschemas can use "$id" to give themselves a document-local identifier. - This is done by setting "$id" to a URI reference consisting - only of a plain name fragment (not a JSON Pointer fragment). - The fragment identifier MUST begin with a letter ([A-Za-z]), followed by - any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons - (":"), or periods ("."). + To specify such a subschema identifier, + the "$id" keyword is set to a URI reference with a name fragment (not a JSON Pointer fragment). + This value MUST begin with the number sign that specifies a fragment ("#"), + then a letter ([A-Za-z]), + followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), + colons (":"), or periods ("."). - The effect of defining a fragment-only "$id" URI reference that neither - matches the above requirements nor is a valid JSON pointer - is not defined. + The effect of using a fragment in "$id" that isn't blank or doesn't follow the + name syntax is undefined. How should an "$id" URI reference containing a fragment with other components be interpreted? There are two cases: when the other components match @@ -711,10 +709,10 @@
- To differentiate schemas between each other in a vast ecosystem, schemas are + To differentiate between schemas in a vast ecosystem, schemas are identified by URI. As specified above, this does not necessarily mean anything is downloaded, but instead JSON Schema implementations SHOULD - already understand the schemas they will be using, including the URIs that + understand ahead of time which schemas they will be using, and the URIs that identify them. @@ -728,7 +726,7 @@ 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 - with the same URI, validators SHOULD raise an error condition. + as the same URI, validators SHOULD raise an error condition.
From 6b541c05b0f4bf615c464edfa3fb73e5a000a520 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 28 Feb 2018 13:46:13 -0700 Subject: [PATCH 2/6] Move the schema references preamble back up to the top of the section --- jsonschema-core.xml | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index b1b19993..9af81ff4 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -528,6 +528,11 @@
+ + To differentiate between schemas in a vast ecosystem, schemas are + identified by URI, and can embed references to other schemas by specifying their URI. + +
RFC3986 Section 5.1 defines how to determine the @@ -709,11 +714,14 @@
- To differentiate between schemas in a vast ecosystem, schemas are - identified by URI. As specified above, this 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. + 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 over HTTP. Implementations SHOULD be able to associate arbitrary URIs with an arbitrary @@ -928,7 +936,7 @@ Link: ;rel="schema", ;rel="schema"
-
+
When used for hypermedia systems over a network, HTTP is frequently the protocol of choice for From f51f8cb1515dd0b531cfb7ac3b144e061fadc236 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 28 Feb 2018 13:46:49 -0700 Subject: [PATCH 3/6] Clarify/strenghten some security considerations --- jsonschema-core.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 9af81ff4..cbc00995 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -980,12 +980,12 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 Instances and schemas are both frequently written by untrusted third parties, to be deployed on public Internet servers. - Validators should take care that the parsing of schemas doesn't consume excessive + Validators should take care that the parsing and validating against schemas doesn't consume excessive system resources. Validators MUST NOT fall into an infinite loop. - Servers need to take care that malicious parties can't change the functionality of + Servers MUST ensure that malicious parties can't change the functionality of existing schemas by uploading a schema with an pre-existing or very similar "$id". From adf96df1dd415dcb319428c6196e9316c2194498 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 28 Feb 2018 13:50:44 -0700 Subject: [PATCH 4/6] Core: Cite definition at first usage of URI in the section --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index cbc00995..4eac45b3 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -530,7 +530,7 @@
To differentiate between schemas in a vast ecosystem, schemas are - identified by URI, and can embed references to other schemas by specifying their URI. + identified by URI, and can embed references to other schemas by specifying their URI.
From ad912439de278c8258de58ef2980c28f585e013c Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 28 Feb 2018 19:59:49 -0700 Subject: [PATCH 5/6] s/name/plain name/ --- jsonschema-core.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 4eac45b3..7d7e2b58 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -589,7 +589,7 @@ To specify such a subschema identifier, - the "$id" keyword is set to a URI reference with a name fragment (not a JSON Pointer fragment). + the "$id" keyword is set to a URI reference with a plain name fragment (not a JSON Pointer fragment). This value MUST begin with the number sign that specifies a fragment ("#"), then a letter ([A-Za-z]), followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), @@ -597,7 +597,7 @@ The effect of using a fragment in "$id" that isn't blank or doesn't follow the - name syntax is undefined. + plain name syntax is undefined. How should an "$id" URI reference containing a fragment with other components be interpreted? There are two cases: when the other components match From d9abd158ca6ccc2b6d2aa18b97b0ff89916c8820 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 28 Feb 2018 20:01:52 -0700 Subject: [PATCH 6/6] Core: Link to Hypermedia section instead --- jsonschema-core.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 7d7e2b58..cc379a5d 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -721,7 +721,7 @@ When schemas are downloaded, for example by a generic user-agent that doesn't know until runtime which schemas to download, - see Usage over HTTP. + see Usage for Hypermedia. Implementations SHOULD be able to associate arbitrary URIs with an arbitrary @@ -835,7 +835,7 @@
-
+
JSON has been adopted widely by HTTP servers for automated APIs and robots. This @@ -936,7 +936,7 @@ Link: ;rel="schema", ;rel="schema"
-
+
When used for hypermedia systems over a network, HTTP is frequently the protocol of choice for