|
554 | 554 | This value SHOULD be normalized, and SHOULD NOT be an empty fragment <#>
|
555 | 555 | or an empty string <>.
|
556 | 556 | </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> |
587 | 605 | <section title="Schema identification examples" anchor="idExamples">
|
588 | 606 | <figure>
|
589 | 607 | <preamble>
|
|
0 commit comments