Skip to content

Commit 73699f5

Browse files
handrewshandrews
committed
Normative language for "$vocabulary"
This reworks the language around "$vocabulary" to capture the original intent in normative language. In particular, it explicitly addresses vocabularies omitted from "$vocabulary". The new text emphasizes the concepts of required or optional vocabularies more than the true and false boolean values that implement them, and adds some explanation of the utility of optional vocabularies. It also adds a clarification around identically-named vocabulary and non-vocabulary keywords, including that the standard keywords MUST be considered vocabulary keywords and subject to "$vocabulary" control even if the implementation does not support custom vocabularies at all.
1 parent d59bda8 commit 73699f5

File tree

1 file changed

+79
-35
lines changed

1 file changed

+79
-35
lines changed

‎jsonschema-core.xml

+79-35
Original file line numberDiff line numberDiff line change
@@ -1120,7 +1120,7 @@
11201120
</t>
11211121
</section>
11221122
</section>
1123-
<section title="The JSON Schema Core Vocabulary">
1123+
<section title="The JSON Schema Core Vocabulary" anchor="core">
11241124
<t>
11251125
Keywords declared in this section, which all begin with "$", make up
11261126
the JSON Schema Core vocabulary. These keywords are either required in
@@ -1226,17 +1226,13 @@
12261226
<section title='The "$vocabulary" Keyword'>
12271227
<t>
12281228
The "$vocabulary" keyword is used in meta-schemas to identify the
1229-
vocabularies available for use in schemas described by that meta-schema.
1230-
It is also used to indicate whether each vocabulary is required or optional,
1231-
in the sense that an implementation MUST understand the required vocabularies
1232-
in order to successfully process the schema. Together, this information forms
1233-
a dialect. Any vocabulary that is understood by the implementation MUST be
1234-
processed in a manner consistent with the semantic definitions contained
1235-
within the vocabulary.
1229+
vocabularies available for use in schemas described by that meta-schema,
1230+
and whether each vocabulary is required or optional. Together, this
1231+
information forms a dialect.
12361232
</t>
12371233
<t>
12381234
The value of this keyword MUST be an object. The property names in the
1239-
object MUST be IRIs (containing a scheme) and this IRI MUST be normalized.
1235+
object MUST be IRIs (containing a scheme) and each IRI MUST be normalized.
12401236
Each IRI that appears as a property name identifies a specific set of
12411237
keywords and their semantics.
12421238
</t>
@@ -1256,32 +1252,79 @@
12561252
</t>
12571253
<t>
12581254
The values of the object properties MUST be booleans.
1259-
If the value is true, then implementations that do not recognize
1260-
the vocabulary MUST refuse to process any schemas that declare
1261-
this meta-schema with "$schema". If the value is false, implementations
1262-
that do not recognize the vocabulary SHOULD proceed with processing
1263-
such schemas. The value has no impact if the implementation
1264-
understands the vocabulary.
1255+
If the value is true, then the vocabulary MUST be considered to be required.
1256+
If the value is false, then the vocabulary MUST be considered to be optional.
12651257
</t>
1266-
<t>
1267-
Per <xref target="extending" format="counter"></xref>, unrecognized
1268-
keywords SHOULD be treated as annotations.
1269-
This remains the case for keywords defined
1270-
by unrecognized vocabularies. It is not currently possible to distinguish
1271-
between unrecognized keywords that are defined in vocabularies from
1272-
those that are not part of any vocabulary.
1273-
</t>
1274-
<t>
1275-
The "$vocabulary" keyword SHOULD be used in the root schema of any schema
1276-
document intended for use as a meta-schema. It MUST NOT appear in subschemas.
1277-
</t>
1278-
<t>
1279-
The "$vocabulary" keyword MUST be ignored in schema documents that
1280-
are not being processed as a meta-schema. This allows validating
1281-
a meta-schema M against its own meta-schema M' without requiring
1282-
the validator to understand the vocabularies declared by M.
1283-
</t>
1284-
<section title="Default vocabularies">
1258+
<section title="Required, optional, and omitted vocabularies">
1259+
<t>
1260+
A schema is said to use a dialect and its constituent vocabularies if it is
1261+
associated with a meta-schema defining the dialect with "$vocabulary",
1262+
either through "$schema", through appropriately defined media type parameters
1263+
or link relation types, or through documented default implementation-defined
1264+
behavior in the absence of an explicit meta-schema. If a meta-schema
1265+
does not contain "$vocabulary", the set of vocabularies in use is determined
1266+
according to section <xref target="default-vocabs" format="counter"></xref>.
1267+
</t>
1268+
<t>
1269+
Any vocabulary in use by a schema and understood by the implementation
1270+
MUST be processed in a manner consistent with the semantic definitions
1271+
contained within the vocabulary, regardless of whether that vocabulary
1272+
is required or optional.
1273+
</t>
1274+
<t>
1275+
Any vocabulary that is not present in "$vocabulary" MUST NOT be made
1276+
available for use in schemas described by that meta-schema, except for
1277+
the core vocabulary as specified by the introduction to section
1278+
<xref target="core" format="counter"></xref>.
1279+
</t>
1280+
<t>
1281+
Implementations that do not support a vocabulary required by a schema
1282+
MUST refuse to process that schema.
1283+
</t>
1284+
<t>
1285+
Implementations that do not support a vocabulary that is optionally used
1286+
by a schema SHOULD proceed with processing the schema. The keywords will
1287+
be considered to be unrecognized keywords as addressed by section
1288+
<xref target="unrecognized" format="counter"></xref>. Note that since
1289+
the recommended behavior for such keywords is to collect them as
1290+
annotations, vocabularies consisting only of annotations will have
1291+
the same behavior when used optionally whether the implementation
1292+
supports them or not. This allows annotation-only vocabularies to
1293+
be supported without custom code, even in implementations that do
1294+
not support providing custom code for extension vocabularies.
1295+
</t>
1296+
</section>
1297+
<section title="Vocabularies are schema resource-scoped">
1298+
<t>
1299+
The "$vocabulary" keyword SHOULD be used in the root schema of any schema
1300+
resource intended for use as a meta-schema. It MUST NOT appear in subschemas.
1301+
</t>
1302+
<t>
1303+
The "$vocabulary" keyword MUST be ignored in schema resources that
1304+
are not being processed as a meta-schema. This allows validating
1305+
a meta-schema M against its own meta-schema M' without requiring
1306+
the validator to understand the vocabularies declared by M.
1307+
</t>
1308+
</section>
1309+
<section title="Vocabulary and non-vocabulary keywords">
1310+
<t>
1311+
Keywords from different vocabularies, as well as non-vocabulary
1312+
extension keywords, can have identical names. These are not
1313+
considered to be the same keyword from the perspective of
1314+
enabling or disabling them through "$vocabulary".
1315+
</t>
1316+
<t>
1317+
In particular the keywords defined in this specification and its
1318+
companion documents MUST be considered to be vocabulary keywords,
1319+
with availability governed by "$vocabulary" even in implementations
1320+
that do not support any extension vocabularies.
1321+
</t>
1322+
<t>
1323+
Guidance regarding vocabularies with identically-named keywords is provided
1324+
in Appendix <xref target="vocab-practices" format="counter"></xref>.
1325+
</t>
1326+
</section>
1327+
<section title="Default vocabularies" anchor="default-vocabs">
12851328
<t>
12861329
If "$vocabulary" is absent, an implementation MAY determine
12871330
behavior based on the meta-schema if it is recognized from the
@@ -3910,7 +3953,8 @@ https://example.com/schemas/common#/$defs/allOf/1
39103953
</section>
39113954

39123955
<section title="Working with vocabularies">
3913-
<section title="Best practices for vocabulary and meta-schema authors">
3956+
<section title="Best practices for vocabulary and meta-schema authors"
3957+
anchor="vocab-practices">
39143958
<t>
39153959
Vocabulary authors should
39163960
take care to avoid keyword name collisions if the vocabulary is intended

0 commit comments

Comments
 (0)