Skip to content

Commit 4ccf9b8

Browse files
jdesrosiersjdesrosiers
committed
Simplify process for $dynamicRef/$dynamicAnchor
1 parent e6bead3 commit 4ccf9b8

File tree

1 file changed

+19
-56
lines changed

1 file changed

+19
-56
lines changed

‎jsonschema-core.xml

Lines changed: 19 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -662,12 +662,6 @@
662662
The path from this root schema to any particular keyword (that
663663
includes any "$ref" and "$dynamicRef" keywords that may have
664664
been resolved) is considered the keyword's "validation path."
665-
<cref>
666-
Or should this be the schema object at which processing
667-
begins, even if it is not a root? This has some implications
668-
for the case where "$dynamicAnchor" is only allowed in the
669-
root schema but processing begins in a subschema.
670-
</cref>
671665
</t>
672666
<t>
673667
Lexical and dynamic scopes align until a reference keyword
@@ -1383,7 +1377,6 @@
13831377
The "$anchor" and "$dynamicAnchor" keywords are used to specify such
13841378
fragments. They are identifier keywords that can only be used to create
13851379
plain name fragments, rather than absolute URIs as seen with "$id".
1386-
The behavior of the created fragment is identical for both keywords.
13871380
</t>
13881381
<t>
13891382
The base URI to which the resulting fragment is appended is the canonical
@@ -1393,13 +1386,11 @@
13931386
for the document as determined according to RFC 3986.
13941387
</t>
13951388
<t>
1396-
Separately from the usual usage of URIs, "$dynamicAnchor"
1397-
indicates that the fragment is an extension point when used with
1398-
the "$dynamicRef" keyword. This low-level, advanced feature
1399-
makes it easier to extend recursive schemas such as the meta-schemas,
1400-
without imposing any particular semantics on that extension.
1401-
See the section on <xref target="dynamic-ref">"$dynamicRef"</xref>
1402-
for details.
1389+
In addition to setting an anchor, "$dynamicAnchor" is used to mark locations that
1390+
can be used for dynamic scope resolution. This low-level, advanced feature makes
1391+
it easier to extend recursive schemas such as the meta-schemas, without imposing
1392+
any particular semantics on that extension. See the section on
1393+
<xref target="dynamic-ref">"$dynamicRef"</xref> for details.
14031394
</t>
14041395
<t>
14051396
In most cases, the normal fragment behavior both suffices and
@@ -1451,13 +1442,9 @@
14511442
<t>
14521443
The "$ref" keyword is an applicator that is used to reference a statically
14531444
identified schema. Its results are the results of the referenced schema.
1454-
<cref>
1455-
Note that this definition of how the results are determined means that
1456-
other keywords can appear alongside of "$ref" in the same schema object.
1457-
</cref>
14581445
</t>
14591446
<t>
1460-
The value of the "$ref" property MUST be a string which is a URI-Reference.
1447+
The value of the "$ref" keyword MUST be a string which is a URI-Reference.
14611448
Resolved against the current URI base, it produces the URI of the schema
14621449
to apply. This resolution is safe to perform on schema load, as the
14631450
process of evaluating an instance cannot change how the reference resolves.
@@ -1466,42 +1453,20 @@
14661453

14671454
<section title='Dynamic References with "$dynamicRef"' anchor="dynamic-ref">
14681455
<t>
1469-
The "$dynamicRef" keyword is an applicator that allows for deferring the
1470-
full resolution until runtime, at which point it is resolved each time it is
1471-
encountered while evaluating an instance.
1456+
The "$dynamicRef" keyword is an applicator that uses the dynamic scope to
1457+
reference a schema. Its results are the results of the referenced schema.
14721458
</t>
14731459
<t>
1474-
Together with "$dynamicAnchor", "$dynamicRef" implements a cooperative
1475-
extension mechanism that is primarily useful with recursive schemas
1476-
(schemas that reference themselves). Both the extension point and the
1477-
runtime-determined extension target are defined with "$dynamicAnchor",
1478-
and only exhibit runtime dynamic behavior when referenced with
1479-
"$dynamicRef".
1460+
The URI base for the "$dynamicRef" keyword is the outermost schema resource in
1461+
the <xref target="scopes">dynamic scope</xref> that defines an identically named
1462+
fragment with "$dynamicAnchor". If no "$dynamicAnchor" is found matching the
1463+
fragment in the "$dynamicRef", the URI base is the current lexical scope.
14801464
</t>
14811465
<t>
1482-
The value of the "$dynamicRef" property MUST be a string which is
1483-
a URI-Reference. Resolved against the current URI base, it produces
1484-
the URI used as the starting point for runtime resolution. This initial
1485-
resolution is safe to perform on schema load.
1486-
</t>
1487-
<t>
1488-
If the initially resolved starting point URI includes a fragment that
1489-
was created by the "$dynamicAnchor" keyword, the initial URI MUST be
1490-
replaced by the URI (including the fragment) for the outermost schema
1491-
resource in the <xref target="scopes">dynamic scope</xref> that defines
1492-
an identically named fragment with "$dynamicAnchor".
1493-
<cref>
1494-
Requiring both the initial and final URI fragment to be defined
1495-
by "$dynamicAnchor" ensures that the more common "$anchor"
1496-
never unexpectedly changes the dynamic resolution process
1497-
due to a naming conflict across resources. Users of
1498-
"$dynamicAnchor" are expected to be aware of the possibility
1499-
of such name collisions, while users of "$anchor" are not.
1500-
</cref>
1501-
</t>
1502-
<t>
1503-
Otherwise, its behavior is identical to "$ref", and no runtime
1504-
resolution is needed.
1466+
The value of the "$dynamicRef" keyword MUST be a string which is a URI-Reference.
1467+
Resolved against the URI base, it produces the URI of the schema to apply. This
1468+
resolution is not safe to perform on schema load, as the process of evaluating an
1469+
instance can change how the reference resolves.
15051470
</t>
15061471
<t>
15071472
For a full example using these keyword, see appendix
@@ -3580,7 +3545,7 @@ https://example.com/schemas/common#/$defs/count/minimum
35803545
{
35813546
"$schema": "https://json-schema.org/draft/2020-11/schema",
35823547
"$id": "https://example.com/strict-tree",
3583-
"$dynamicAnchor": node,
3548+
"$dynamicAnchor": "node",
35843549
35853550
"$ref": "tree",
35863551
"unevaluatedProperties": false
@@ -3608,10 +3573,8 @@ https://example.com/schemas/common#/$defs/count/minimum
36083573
If we apply the "strict-tree" schema to the instance, we will follow
36093574
the "$ref" to the "tree" schema, examine its "children" subschema,
36103575
and find the "$dynamicRef": to "#node" (note the "#" for URI fragment syntax)
3611-
in its "items" subschema. That reference resolves to
3612-
"https://example.com/tree#node", which is a URI with a fragment
3613-
created by "$dynamicAnchor". Therefore we must examine the dynamic
3614-
scope before following the reference.
3576+
in its "items" subschema. We then need to examine the dynamic scope before
3577+
following the reference.
36153578
</t>
36163579
<t>
36173580
At this point, the dynamic path is

0 commit comments

Comments
 (0)