Skip to content

Commit 5947aaf

Browse files
committed
"$id" subsections by use case
This re-organizes and expands the existing text for "$id" into subsections based on the three primary use cases: * Identifying the root schema in a schema document * Changing the base URI (with implications for JSON Pointer fragments) * Defining a location-independent name All of these are demonstrated in the subsequent example section.
1 parent 1ccab5e commit 5947aaf

File tree

1 file changed

+48
-30
lines changed

1 file changed

+48
-30
lines changed

jsonschema-core.xml

Lines changed: 48 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -554,36 +554,54 @@
554554
This value SHOULD be normalized, and SHOULD NOT be an empty fragment <#>
555555
or an empty string <>.
556556
</t>
557-
<t>
558-
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
559-
a URI (containing a scheme). This URI SHOULD either not have a fragment, or
560-
have one that is an empty string.
561-
<!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
562-
<cref>
563-
How should an "$id" URI reference containing a fragment with other components
564-
be interpreted? There are two cases: when the other components match
565-
the current base URI and when they change the base URI.
566-
</cref>
567-
</t>
568-
<t>
569-
To name subschemas in a JSON Schema document,
570-
subschemas can use "$id" to give themselves a document-local identifier.
571-
This is done by setting "$id" to a URI reference consisting
572-
only of a plain name fragment (not a JSON Pointer fragment).
573-
The fragment identifier MUST begin with a letter ([A-Za-z]), followed by
574-
any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
575-
(":"), or periods (".").
576-
</t>
577-
<t>
578-
Providing a plain name fragment enables a subschema to be
579-
relocated within a schema without requiring that JSON
580-
Pointer references are updated.
581-
</t>
582-
<t>
583-
The effect of defining a fragment-only "$id" URI reference that neither
584-
matches the above requirements nor is a valid JSON pointer
585-
is not defined.
586-
</t>
557+
<section title="Identifying the root schema">
558+
<t>
559+
The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
560+
a URI (containing a scheme). This URI SHOULD either not have a fragment, or
561+
have one that is an empty string.
562+
<!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
563+
</t>
564+
</section>
565+
<section title="Changing the base URI within a schema file">
566+
<t>
567+
When an "$id" sets the base URI, the object containing that "$id" and all of
568+
its subschemas can be identified by using a JSON Pointer fragment starting
569+
from that location. This is true even of subschemas that further change the
570+
base URI. Therefore, a single subschema may be accessible by multiple URIs,
571+
each consisting of base URI declared in the subschema or a parent, along with
572+
a JSON Pointer fragment identifying the path from the schema object that
573+
declares the base to the subschema being identified. Examples of this are
574+
shown in section <xref target="idExamples" format="counter"></xref>.
575+
</t>
576+
</section>
577+
<section title="Location-independent identifiers">
578+
<t>
579+
Using JSON Pointer fragments requires knowledge of the structure of the schema.
580+
When writing schema documents with the intention to provide re-usable
581+
schemas, it is preferable to use a plain name fragment that is not tied to
582+
any particular structural location. This allows a subschema to be relocated
583+
without requiring JSON Pointer references to be updated.
584+
</t>
585+
<t>
586+
To name subschemas in a JSON Schema document,
587+
subschemas can use "$id" to give themselves a document-local identifier.
588+
This is done by setting "$id" to a URI reference consisting
589+
only of a plain name fragment (not a JSON Pointer fragment).
590+
The fragment identifier MUST begin with a letter ([A-Za-z]), followed by
591+
any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
592+
(":"), or periods (".").
593+
</t>
594+
<t>
595+
The effect of defining a fragment-only "$id" URI reference that neither
596+
matches the above requirements nor is a valid JSON pointer
597+
is not defined.
598+
<cref>
599+
How should an "$id" URI reference containing a fragment with other components
600+
be interpreted? There are two cases: when the other components match
601+
the current base URI and when they change the base URI.
602+
</cref>
603+
</t>
604+
</section>
587605
<section title="Schema identification examples" anchor="idExamples">
588606
<figure>
589607
<preamble>

0 commit comments

Comments
 (0)