Skip to content

Commit b0ece6e

Browse files
committed
clarfication around $dynamicAnchor and its separation from $ref semantics
1 parent c53747f commit b0ece6e

File tree

1 file changed

+19
-15
lines changed

1 file changed

+19
-15
lines changed

specs/jsonschema-core.md

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -946,17 +946,18 @@ The `$anchor` and `$dynamicAnchor` keywords are used to specify such fragments.
946946
They are identifier keywords that can only be used to create plain name
947947
fragments, rather than absolute IRIs as seen with `$id`.
948948

949-
The base IRI to which the resulting fragment is appended is the canonical IRI of
950-
the schema resource containing the `$anchor` or `$dynamicAnchor` in question.
951-
As discussed in the previous section, this is either the nearest `$id` in the
952-
same or parent schema object, or the base IRI for the document as determined
953-
according to [RFC 3987](#rfc3987) and [RFC 3986](#rfc3986).
954-
955-
Separately from the usual usage of IRIs, `$dynamicAnchor` indicates that the
956-
fragment is an extension point when used with the `$dynamicRef` keyword. This
957-
low-level, advanced feature makes it easier to extend recursive schemas such as
958-
the meta-schemas, without imposing any particular semantics on that extension.
959-
See the section on [`$dynamicRef`](#dynamic-ref) for details.
949+
`$anchor` defines a reference target for `$ref`. The fragment defined by this
950+
keyword is appended is the IRI of the schema resource containing it. As
951+
discussed in {{id-keyword}}, this is either the nearest `$id` in the same or an
952+
ancestor schema object, or the base IRI for the document as determined according
953+
to [RFC 3987](#rfc3987) and [RFC 3986](#rfc3986).
954+
955+
In contrast, `$dynamicAnchor` operates independently of resource IRIs and is
956+
instead dependent on the dynamic scope of the evaluation. `$dynamicAnchor`
957+
defines a reference target for the `$dynamicRef` keyword. This advanced feature
958+
makes it easier to extend recursive schemas such as the meta-schemas, without
959+
imposing any particular semantics on that extension. See {{dynamic-ref}} for
960+
details.
960961

961962
In most cases, the normal fragment behavior both suffices and is more intuitive.
962963
Therefore it is RECOMMENDED that `$anchor` be used to create plain name
@@ -1012,12 +1013,15 @@ resolution until runtime, at which point it is resolved each time it is
10121013
encountered while evaluating an instance.
10131014

10141015
Together with `$dynamicAnchor`, `$dynamicRef` implements a cooperative extension
1015-
mechanism that is primarily useful to extend recursive schemas. The extension
1016-
point is defined with `$dynamicAnchor` and only exhibits runtime dynamic
1017-
behavior when referenced with `$dynamicRef`.
1016+
mechanism that is primarily useful to extend recursive schemas, where
1017+
`$dynamicRef` defines the extension point, and `$dynamicAnchor` defines the
1018+
target.
10181019

10191020
The value of the `$dynamicRef` property MUST be a valid
1020-
[plain name fragment](#anchors).
1021+
[plain name fragment](#anchors).[^3]
1022+
1023+
[^3]: `$dynamicAnchor` defines the anchor with plain text, e.g. `foo`; the
1024+
`$dynamicRef` that references it uses a URI fragment syntax, e.g. `#foo`.
10211025

10221026
Resolution of `$dynamicRef` begins by identifying the the outermost schema
10231027
resource in the [dynamic scope](#scopes) which defines a matching

0 commit comments

Comments
 (0)