diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 1517ccc2..2977500e 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -456,14 +456,21 @@ 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 fragment. + 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 ("."). - The effect of defining an "$id" that neither matches the above - requirements nor is a valid JSON pointer is not defined. + Providing a plain name fragment enables a subschema to be + relocated within a schema without requiring that JSON + Pointer references are updated. + + + The effect of defining a URI fragment "$id" that neither + matches the above requirements nor is a valid JSON pointer + is not defined. For example: @@ -548,7 +555,8 @@ 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. + defined elsewhere in the same document without needing to + resolve the fragment against the base URI.