Skip to content

Commit c5e8c62

Browse files
committed
Add "identifier" keyword category.
This fills in a bit of a conceptual gap, and I think will help folks understand the "$id" / "$anchor" split. It also clarified some thinking on "$recursiveAnchor" for me which will be followed up on in future commits.
1 parent 27338fe commit c5e8c62

File tree

1 file changed

+28
-4
lines changed

1 file changed

+28
-4
lines changed

jsonschema-core.xml

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,10 @@
310310
or schema keywords. Broadly speaking, keywords fall into one
311311
of four categories:
312312
<list style="hanging">
313+
<t hangText="identifiers:">
314+
control schema identification through setting the schema's
315+
canonical URI and/or changing how the base URI is determined
316+
</t>
313317
<t hangText="assertions:">
314318
produce a boolean result when applied to an instance
315319
</t>
@@ -704,6 +708,25 @@
704708
document.
705709
</t>
706710
</section>
711+
<section title="Identifiers" anchor="identifiers">
712+
<t>
713+
Identifiers set the canonical URI of a schema, or affect how such URIs are
714+
resolved in <xref target="references">references</xref>, or both.
715+
The Core vocabulary defined in this document defines several
716+
identifying keywords, most notably "$id".
717+
</t>
718+
<t>
719+
Canonical schema URIs MUST NOT change while processing an instance, but
720+
keywords that affect URI-reference resolution MAY have behavior that
721+
is only fully determined at runtime.
722+
</t>
723+
<t>
724+
While custom identifier keywords are possible, vocabulary designers should
725+
take care not to disrupt the functioning of core keywords. For example,
726+
the "$recursiveAnchor" keyword in this specification limits its URI resolution
727+
effects to the matching "$recursiveRef" keyword, leaving "$ref" undisturbed.
728+
</t>
729+
</section>
707730
<section title="Applicators" anchor="applicators">
708731
<t>
709732
Applicators allow for building more complex schemas than can be accomplished
@@ -1509,7 +1532,8 @@
15091532
without requiring JSON Pointer references to be updated.
15101533
</t>
15111534
<t>
1512-
The "$anchor" keyword is used to specify such a fragment.
1535+
The "$anchor" keyword is used to specify such a fragment. It is an
1536+
identifier keyword that can only be used to create plain name fragments.
15131537
</t>
15141538
<t>
15151539
If present, the value of this keyword MUST be a string, which MUST start with
@@ -1537,11 +1561,11 @@
15371561
Several keywords can be used to reference a schema which is to be applied to the
15381562
current instance location. "$ref" and "$recursiveRef" are applicator
15391563
keywords, applying the referenced schema to the instance. "$recursiveAnchor"
1540-
is a helper keyword that controls how the referenced schema of "$recursiveRef"
1541-
is determined.
1564+
is an identifier keyword that controls how the base URI for resolving
1565+
the URI-reference value of "$recursiveRef is determined.
15421566
</t>
15431567
<t>
1544-
As the value of "$ref" and "$recursiveRef" are URI References, this allows
1568+
As the values of "$ref" and "$recursiveRef" are URI References, this allows
15451569
the possibility to externalise or divide a schema across multiple files,
15461570
and provides the ability to validate recursive structures through
15471571
self-reference.

0 commit comments

Comments
 (0)