|
654 | 654 | appear in a schema resource's root schema. |
655 | 655 | </t> |
656 | 656 | <t> |
657 | | - Other keywords may take into account the dynamic scope that |
658 | | - exists during the evaluation of a schema, typically together |
659 | | - with an instance document. The outermost dynamic scope is the |
660 | | - root schema of the schema document in which processing begins. |
661 | | - The path from this root schema to any particular keyword (that |
662 | | - includes any "$ref" and "$dynamicRef" keywords that may have |
663 | | - been resolved) is considered the keyword's "validation path." |
664 | | - <cref> |
665 | | - Or should this be the schema object at which processing |
666 | | - begins, even if it is not a root? This has some implications |
667 | | - for the case where "$dynamicAnchor" is only allowed in the |
668 | | - root schema but processing begins in a subschema. |
669 | | - </cref> |
| 657 | + Other keywords may take into account the dynamic scope that exists during the |
| 658 | + evaluation of a schema. The outermost dynamic scope is the root schema of the |
| 659 | + schema document in which processing begins. The path from this root schema to |
| 660 | + any particular keyword (that includes any "$ref" and "$dynamicRef" keywords that |
| 661 | + may have been resolved) is considered the keyword's "validation path." |
670 | 662 | </t> |
671 | 663 | <t> |
672 | 664 | Lexical and dynamic scopes align until a reference keyword |
673 | 665 | is encountered. While following the reference keyword moves processing |
674 | 666 | from one lexical scope into a different one, from the perspective |
675 | | - of dynamic scope, following reference is no different from descending |
| 667 | + of dynamic scope, following a reference is no different from descending |
676 | 668 | into a subschema present as a value. A keyword on the far side of |
677 | 669 | that reference that resolves information through the dynamic scope |
678 | 670 | will consider the originating side of the reference to be their |
|
741 | 733 | <t> |
742 | 734 | Canonical schema URIs MUST NOT change while processing an instance, but |
743 | 735 | keywords that affect URI-reference resolution MAY have behavior that |
744 | | - is only fully determined at runtime. |
| 736 | + is only fully determined dynamically. |
745 | 737 | </t> |
746 | 738 | <t> |
747 | 739 | While custom identifier keywords are possible, vocabulary designers should |
|
798 | 790 | of an instance against a schema. |
799 | 791 | </t> |
800 | 792 | <t> |
801 | | - For some by-reference applicators, such as |
802 | | - <xref target="ref">"$ref"</xref>, the referenced schema can be determined |
803 | | - by static analysis of the schema document's lexical scope. Others, |
804 | | - such as "$dynamicRef" (with "$dynamicAnchor"), may make use of dynamic |
805 | | - scoping, and therefore only be resolvable in the process of evaluating |
806 | | - the schema with an instance. |
| 793 | + For some by-reference applicators, such as <xref target="ref">"$ref"</xref>, the |
| 794 | + referenced schema can be determined by static analysis of the schema document's |
| 795 | + lexical scope. Others, such as "$dynamicRef" (with "$dynamicAnchor"), are only |
| 796 | + resolvable with knowledge of all the schemas in it's dynamic scope. |
807 | 797 | </t> |
808 | 798 | </section> |
809 | 799 | </section> |
|
1397 | 1387 | The "$anchor" and "$dynamicAnchor" keywords are used to specify such |
1398 | 1388 | fragments. They are identifier keywords that can only be used to create |
1399 | 1389 | plain name fragments, rather than absolute URIs as seen with "$id". |
1400 | | - The behavior of the created fragment is identical for both keywords. |
1401 | 1390 | </t> |
1402 | 1391 | <t> |
1403 | 1392 | The base URI to which the resulting fragment is appended is the canonical |
|
1471 | 1460 | </cref> |
1472 | 1461 | </t> |
1473 | 1462 | <t> |
1474 | | - The value of the "$ref" property MUST be a string which is a URI-Reference. |
| 1463 | + The value of the "$ref" keyword MUST be a string which is a URI-Reference. |
1475 | 1464 | Resolved against the current URI base, it produces the URI of the schema |
1476 | | - to apply. This resolution is safe to perform on schema load, as the |
1477 | | - process of evaluating an instance cannot change how the reference resolves. |
| 1465 | + to apply. This resolution is safe to perform on schema load as neither other |
| 1466 | + schemas nor the instance can change how the reference resolves. |
1478 | 1467 | </t> |
1479 | 1468 | </section> |
1480 | 1469 |
|
1481 | 1470 | <section title='Dynamic References with "$dynamicRef"' anchor="dynamic-ref"> |
1482 | 1471 | <t> |
1483 | | - The "$dynamicRef" keyword is an applicator that allows for deferring the |
1484 | | - full resolution until runtime, at which point it is resolved each time it is |
1485 | | - encountered while evaluating an instance. |
| 1472 | + The "$dynamicRef" keyword is an applicator that is used to reference a |
| 1473 | + dynamically identified schema. |
1486 | 1474 | </t> |
1487 | 1475 | <t> |
1488 | 1476 | Together with "$dynamicAnchor", "$dynamicRef" implements a cooperative |
1489 | 1477 | extension mechanism that is primarily useful with recursive schemas |
1490 | 1478 | (schemas that reference themselves). Both the extension point and the |
1491 | | - runtime-determined extension target are defined with "$dynamicAnchor", |
1492 | | - and only exhibit runtime dynamic behavior when referenced with |
1493 | | - "$dynamicRef". |
| 1479 | + extension target are defined with "$dynamicAnchor", and only exhibit dynamic |
| 1480 | + behavior when referenced with "$dynamicRef". |
1494 | 1481 | </t> |
1495 | 1482 | <t> |
1496 | | - The value of the "$dynamicRef" property MUST be a string which is |
1497 | | - a URI-Reference. Resolved against the current URI base, it produces |
1498 | | - the URI used as the starting point for runtime resolution. This initial |
1499 | | - resolution is safe to perform on schema load. |
| 1483 | + The value of the "$dynamicRef" property MUST be a string which is a |
| 1484 | + URI-Reference. Resolved against the current URI base, it produces the URI used |
| 1485 | + as the starting point for resolution. This initial resolution is safe to perform |
| 1486 | + on schema load. |
1500 | 1487 | </t> |
1501 | 1488 | <t> |
1502 | 1489 | If the initially resolved starting point URI includes a fragment that |
1503 | 1490 | was created by the "$dynamicAnchor" keyword, the initial URI MUST be |
1504 | 1491 | replaced by the URI (including the fragment) for the outermost schema |
1505 | 1492 | resource in the <xref target="scopes">dynamic scope</xref> that defines |
1506 | 1493 | an identically named fragment with "$dynamicAnchor". |
1507 | | - <cref> |
1508 | | - Requiring both the initial and final URI fragment to be defined |
1509 | | - by "$dynamicAnchor" ensures that the more common "$anchor" |
1510 | | - never unexpectedly changes the dynamic resolution process |
1511 | | - due to a naming conflict across resources. Users of |
1512 | | - "$dynamicAnchor" are expected to be aware of the possibility |
1513 | | - of such name collisions, while users of "$anchor" are not. |
1514 | | - </cref> |
1515 | 1494 | </t> |
1516 | 1495 | <t> |
1517 | | - Otherwise, its behavior is identical to "$ref", and no runtime |
1518 | | - resolution is needed. |
| 1496 | + Otherwise, its behavior is identical to "$ref", and no dynamic resolution is |
| 1497 | + needed. |
1519 | 1498 | </t> |
1520 | 1499 | <t> |
1521 | 1500 | For a full example using these keyword, see appendix |
@@ -3510,7 +3489,7 @@ https://example.com/schemas/common#/$defs/count/minimum |
3510 | 3489 | { |
3511 | 3490 | "$schema": "https://json-schema.org/draft/2020-11/schema", |
3512 | 3491 | "$id": "https://example.com/strict-tree", |
3513 | | - "$dynamicAnchor": node, |
| 3492 | + "$dynamicAnchor": "node", |
3514 | 3493 | |
3515 | 3494 | "$ref": "tree", |
3516 | 3495 | "unevaluatedProperties": false |
|
0 commit comments