diff --git a/jsonschema-core.xml b/jsonschema-core.xml index db34921a..681ef6a7 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -323,24 +323,27 @@ -
+
- The "id" keyword defines a URI for the schema, - and the base URI that other URI references within the schema are resolved against. - The "id" keyword itself is resolved against the base URI that the object as a whole appears in. + The "$base" keyword defines the base URI against which + other URI references within the schema are resolved. + The "$base" keyword itself is resolved against the base URI + in which the object as a whole appears. If present, the value for this keyword MUST be a string, and MUST represent a valid URI-reference. - This value SHOULD be normalized, and SHOULD NOT be an empty fragment <#> or an empty string <>. + This value SHOULD be normalized, and SHOULD NOT contain a fragment or be an empty string. Fragments cannot affect the base URI, and MUST be ignored. To provide a fragment identifier for a schema, use "$anchor". The root schema of a JSON Schema document SHOULD contain an "id" keyword with an absolute-URI (containing a scheme, but no fragment). +
+ +
To name subschemas in a JSON Schema document, - subschemas can use "id" to give themselves a document-local identifier. - This form of "id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference, - followed by a letter ([A-Za-z]), followed by any number of + subschemas can use "$anchor" to give themselves a document-local identifier for use as a plain name URI fragment. + This identifier MUST start with a letter ([A-Za-z]), followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods ("."). @@ -350,18 +353,18 @@ urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f -
- - Schemas can be identified by any URI that has been given to them, including a JSON Pointer or - their URI given directly by "id". - - - Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "id". - This is known as "Internal referencing". - +
- - For example, consider this schema: - +
+ + Schemas can be identified by any URI that has been given to them, including URIs using either + a JSON Pointer fragment or the plain name fragment given directly by "$anchor". + + + Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "$base" and/or "$anchor". + This is known as "Internal referencing". + -
- + + For example, consider this schema: + + +
+ - -
- - When an implementation encounters the <#/definitions/single> schema, it resolves the "id" URI reference - against the current base URI to form <http://example.net/root.json#item>. - - - When an implementation then looks inside the <#/items> schema, it encounters the <#item> reference, - and resolves this to <http://example.net/root.json#item> which is understood as the schema defined elsewhere in the same document. - -
-
- - 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. - - - 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 the validator - has in the schema. - - - 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. - -
+ + + + When an implementation encounters the <#/definitions/single> schema, it notices the anchor which is used with + the current base URI to form <http://example.net/root.json#item>. + + + When an implementation then looks inside the <#/items> schema, it encounters the <#item> reference, + and resolves this to <http://example.net/root.json#item> which is understood as the schema defined elsewhere in the same document. + +
+
+ + 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. + + + Implementations SHOULD be able to associate arbitrary URIs with an arbitrary schema and/or + automatically associate a schema's "$base"- and "$anchor"-given URI, depending on the trust that the the validator + has in the schema. + + + 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. +