Skip to content

Commit fc4665c

Browse files
committed
Rework core vocab text for new section layout.
A few minor clarifications are added, including a RECOMMENDATION against using "$" as the first character of extension keywords. The paragraph about bug-fix meta-schema and vocabulary URIs seemed out of place, and worth calling out more clearly, so it became its own section.
1 parent 5409706 commit fc4665c

File tree

1 file changed

+17
-8
lines changed

1 file changed

+17
-8
lines changed

jsonschema-core.xml

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1007,7 +1007,7 @@
10071007
</section>
10081008
<section title="The JSON Schema Core Vocabulary">
10091009
<t>
1010-
Keywords declared in in this specification that begin with "$" make up
1010+
Keywords declared in in this section, which all begin with "$", make up
10111011
the JSON Schema Core vocabulary. These keywords are either required in
10121012
order process any schema or meta-schema, including those split across
10131013
multiple documents, or exist to reserve keywords for purposes that
@@ -1016,15 +1016,17 @@
10161016
<t>
10171017
The Core vocabulary MUST be considered mandatory at all times, in order
10181018
to bootstrap the processing of further vocabularies. Meta-schemas
1019-
that use "$vocabulary" MUST explicitly list the Core vocabulary,
1019+
that use the <xref target="vocabulary">"$vocabulary"</xref> keyword
1020+
to declare the vocabularies in use MUST explicitly list the Core vocabulary,
10201021
which MUST have a value of true indicating that it is required.
10211022
</t>
10221023
<t>
10231024
The behavior of a false value for this vocabulary (and only this
10241025
vocabulary) is undefined, as is the behavior when "$vocabulary"
10251026
is present but the Core vocabulary is not included. However, it
10261027
is RECOMMENDED that implementations detect these cases and raise
1027-
an error when they occur.
1028+
an error when they occur. It is not meaningful to declare that
1029+
a meta-schema optionally uses Core.
10281030
</t>
10291031
<t>
10301032
Meta-schemas that do not use "$vocabulary" MUST be considered to
@@ -1039,11 +1041,9 @@
10391041
<eref target="https://json-schema.org/draft/2019-08/meta/core"/>.
10401042
</t>
10411043
<t>
1042-
Updated vocabulary and meta-schema URIs MAY be published between
1043-
specification drafts in order to correct errors. Implementations
1044-
SHOULD consider URIs dated after this specification draft and
1045-
before the next to indicate the same syntax and semantics
1046-
as those listed here.
1044+
While the "$" prefix is not formally reserved for the Core vocabulary,
1045+
it is RECOMMENDED that extension keywords (in vocabularies or otherwise)
1046+
begin with a character other than "$" to avoid possible future collisions.
10471047
</t>
10481048

10491049
<section title="Meta-Schemas and Vocabularies" anchor="vocabulary">
@@ -1211,6 +1211,15 @@
12111211
</t>
12121212
</section>
12131213
</section>
1214+
<section title="Updates to Meta-Schema and Vocabulary URIs">
1215+
<t>
1216+
Updated vocabulary and meta-schema URIs MAY be published between
1217+
specification drafts in order to correct errors. Implementations
1218+
SHOULD consider URIs dated after this specification draft and
1219+
before the next to indicate the same syntax and semantics
1220+
as those listed here.
1221+
</t>
1222+
</section>
12141223
<section title="Detecting a Meta-Schema">
12151224
<t>
12161225
Implementations MUST recognize a schema as a meta-schema if it

0 commit comments

Comments
 (0)