Skip to content

Commit 5232aee

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 40ae2aa commit 5232aee

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
@@ -980,7 +980,7 @@
980980
</section>
981981
<section title="The JSON Schema Core Vocabulary">
982982
<t>
983-
Keywords declared in in this specification that begin with "$" make up
983+
Keywords declared in in this section, which all begin with "$", make up
984984
the JSON Schema Core vocabulary. These keywords are either required in
985985
order process any schema or meta-schema, including those split across
986986
multiple documents, or exist to reserve keywords for purposes that
@@ -989,15 +989,17 @@
989989
<t>
990990
The Core vocabulary MUST be considered mandatory at all times, in order
991991
to bootstrap the processing of further vocabularies. Meta-schemas
992-
that use "$vocabulary" MUST explicitly list the Core vocabulary,
992+
that use the <xref target="vocabulary">"$vocabulary"</xref> keyword
993+
to declare the vocabularies in use MUST explicitly list the Core vocabulary,
993994
which MUST have a value of true indicating that it is required.
994995
</t>
995996
<t>
996997
The behavior of a false value for this vocabulary (and only this
997998
vocabulary) is undefined, as is the behavior when "$vocabulary"
998999
is present but the Core vocabulary is not included. However, it
9991000
is RECOMMENDED that implementations detect these cases and raise
1000-
an error when they occur.
1001+
an error when they occur. It is not meaningful to declare that
1002+
a meta-schema optionally uses Core.
10011003
</t>
10021004
<t>
10031005
Meta-schemas that do not use "$vocabulary" MUST be considered to
@@ -1012,11 +1014,9 @@
10121014
<eref target="https://json-schema.org/draft/2019-08/meta/core"/>.
10131015
</t>
10141016
<t>
1015-
Updated vocabulary and meta-schema URIs MAY be published between
1016-
specification drafts in order to correct errors. Implementations
1017-
SHOULD consider URIs dated after this specification draft and
1018-
before the next to indicate the same syntax and semantics
1019-
as those listed here.
1017+
While the "$" prefix is not formally reserved for the Core vocabulary,
1018+
it is RECOMMENDED that extension keywords (in vocabularies or otherwise)
1019+
begin with a character other than "$" to avoid possible future collisions.
10201020
</t>
10211021

10221022
<section title="Meta-Schemas and Vocabularies" anchor="vocabulary">
@@ -1184,6 +1184,15 @@
11841184
</t>
11851185
</section>
11861186
</section>
1187+
<section title="Updates to Meta-Schema and Vocabulary URIs">
1188+
<t>
1189+
Updated vocabulary and meta-schema URIs MAY be published between
1190+
specification drafts in order to correct errors. Implementations
1191+
SHOULD consider URIs dated after this specification draft and
1192+
before the next to indicate the same syntax and semantics
1193+
as those listed here.
1194+
</t>
1195+
</section>
11871196
<section title="Detecting a Meta-Schema">
11881197
<t>
11891198
Implementations MUST recognize a schema as a meta-schema if it

0 commit comments

Comments
 (0)