Skip to content

Commit 828035b

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 a9924a7 commit 828035b

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
@@ -1517,7 +1540,8 @@
15171540
without requiring JSON Pointer references to be updated.
15181541
</t>
15191542
<t>
1520-
The "$anchor" keyword is used to specify such a fragment.
1543+
The "$anchor" keyword is used to specify such a fragment. It is an
1544+
identifier keyword that can only be used to create plain name fragments.
15211545
</t>
15221546
<t>
15231547
If present, the value of this keyword MUST be a string, which MUST start with
@@ -1545,11 +1569,11 @@
15451569
Several keywords can be used to reference a schema which is to be applied to the
15461570
current instance ___location. "$ref" and "$recursiveRef" are applicator
15471571
keywords, applying the referenced schema to the instance. "$recursiveAnchor"
1548-
is a helper keyword that controls how the referenced schema of "$recursiveRef"
1549-
is determined.
1572+
is an identifier keyword that controls how the base URI for resolving
1573+
the URI-reference value of "$recursiveRef is determined.
15501574
</t>
15511575
<t>
1552-
As the value of "$ref" and "$recursiveRef" are URI References, this allows
1576+
As the values of "$ref" and "$recursiveRef" are URI References, this allows
15531577
the possibility to externalise or divide a schema across multiple files,
15541578
and provides the ability to validate recursive structures through
15551579
self-reference.

0 commit comments

Comments
 (0)