diff --git a/jsonschema-core.xml b/jsonschema-core.xml index b74fe22a..cc379a5d 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 @@ -557,8 +562,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 +588,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 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 ("_"), + 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 + 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 @@ -711,11 +714,14 @@
- To differentiate schemas between each other 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 - 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 for Hypermedia. Implementations SHOULD be able to associate arbitrary URIs with an arbitrary @@ -728,7 +734,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.
@@ -829,7 +835,7 @@
-
+
JSON has been adopted widely by HTTP servers for automated APIs and robots. This @@ -974,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".