Skip to content

Commit a7f1aa2

Browse files
handrewshandrews
authored
Merge pull request #1295 from handrews/omit-vocab
Normative language for "$vocabulary"
2 parents 5728120 + 7b51ad6 commit a7f1aa2

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
@@ -1132,7 +1132,7 @@
11321132
</t>
11331133
</section>
11341134
</section>
1135-
<section title="The JSON Schema Core Vocabulary">
1135+
<section title="The JSON Schema Core Vocabulary" anchor="core">
11361136
<t>
11371137
Keywords declared in this section, which all begin with "$", make up
11381138
the JSON Schema Core vocabulary. These keywords are either required in
@@ -1238,17 +1238,13 @@
12381238
<section title='The "$vocabulary" Keyword'>
12391239
<t>
12401240
The "$vocabulary" keyword is used in meta-schemas to identify the
1241-
vocabularies available for use in schemas described by that meta-schema.
1242-
It is also used to indicate whether each vocabulary is required or optional,
1243-
in the sense that an implementation MUST understand the required vocabularies
1244-
in order to successfully process the schema. Together, this information forms
1245-
a dialect. Any vocabulary that is understood by the implementation MUST be
1246-
processed in a manner consistent with the semantic definitions contained
1247-
within the vocabulary.
1241+
vocabularies available for use in schemas described by that meta-schema,
1242+
and whether each vocabulary is required or optional. Together, this
1243+
information forms a dialect.
12481244
</t>
12491245
<t>
12501246
The value of this keyword MUST be an object. The property names in the
1251-
object MUST be IRIs (containing a scheme) and this IRI MUST be normalized.
1247+
object MUST be IRIs (containing a scheme) and each IRI MUST be normalized.
12521248
Each IRI that appears as a property name identifies a specific set of
12531249
keywords and their semantics.
12541250
</t>
@@ -1268,32 +1264,79 @@
12681264
</t>
12691265
<t>
12701266
The values of the object properties MUST be booleans.
1271-
If the value is true, then implementations that do not recognize
1272-
the vocabulary MUST refuse to process any schemas that declare
1273-
this meta-schema with "$schema". If the value is false, implementations
1274-
that do not recognize the vocabulary SHOULD proceed with processing
1275-
such schemas. The value has no impact if the implementation
1276-
understands the vocabulary.
1267+
If the value is true, then the vocabulary MUST be considered to be required.
1268+
If the value is false, then the vocabulary MUST be considered to be optional.
12771269
</t>
1278-
<t>
1279-
Per <xref target="extending" format="counter"></xref>, unrecognized
1280-
keywords SHOULD be treated as annotations.
1281-
This remains the case for keywords defined
1282-
by unrecognized vocabularies. It is not currently possible to distinguish
1283-
between unrecognized keywords that are defined in vocabularies from
1284-
those that are not part of any vocabulary.
1285-
</t>
1286-
<t>
1287-
The "$vocabulary" keyword SHOULD be used in the root schema of any schema
1288-
resource intended for use as a meta-schema. It MUST NOT appear in subschemas.
1289-
</t>
1290-
<t>
1291-
The "$vocabulary" keyword MUST be ignored in schema resources that
1292-
are not being processed as a meta-schema. This allows validating
1293-
a meta-schema M against its own meta-schema M' without requiring
1294-
the validator to understand the vocabularies declared by M.
1295-
</t>
1296-
<section title="Default vocabularies">
1270+
<section title="Required, optional, and omitted vocabularies">
1271+
<t>
1272+
A schema is said to use a dialect and its constituent vocabularies if it is
1273+
associated with a meta-schema defining the dialect with "$vocabulary",
1274+
either through "$schema", through appropriately defined media type parameters
1275+
or link relation types, or through documented default implementation-defined
1276+
behavior in the absence of an explicit meta-schema. If a meta-schema
1277+
does not contain "$vocabulary", the set of vocabularies in use is determined
1278+
according to section <xref target="default-vocabs" format="counter"></xref>.
1279+
</t>
1280+
<t>
1281+
Any vocabulary in use by a schema and understood by the implementation
1282+
MUST be processed in a manner consistent with the semantic definitions
1283+
contained within the vocabulary, regardless of whether that vocabulary
1284+
is required or optional.
1285+
</t>
1286+
<t>
1287+
Any vocabulary that is not present in "$vocabulary" MUST NOT be made
1288+
available for use in schemas described by that meta-schema, except for
1289+
the core vocabulary as specified by the introduction to section
1290+
<xref target="core" format="counter"></xref>.
1291+
</t>
1292+
<t>
1293+
Implementations that do not support a vocabulary required by a schema
1294+
MUST refuse to process that schema.
1295+
</t>
1296+
<t>
1297+
Implementations that do not support a vocabulary that is optionally used
1298+
by a schema SHOULD proceed with processing the schema. The keywords will
1299+
be considered to be unrecognized keywords as addressed by section
1300+
<xref target="unrecognized" format="counter"></xref>. Note that since
1301+
the recommended behavior for such keywords is to collect them as
1302+
annotations, vocabularies consisting only of annotations will have
1303+
the same behavior when used optionally whether the implementation
1304+
supports them or not. This allows annotation-only vocabularies to
1305+
be supported without custom code, even in implementations that do
1306+
not support providing custom code for extension vocabularies.
1307+
</t>
1308+
</section>
1309+
<section title="Vocabularies are schema resource-scoped">
1310+
<t>
1311+
The "$vocabulary" keyword SHOULD be used in the root schema of any schema
1312+
resource intended for use as a meta-schema. It MUST NOT appear in subschemas.
1313+
</t>
1314+
<t>
1315+
The "$vocabulary" keyword MUST be ignored in schema resources that
1316+
are not being processed as a meta-schema. This allows validating
1317+
a meta-schema M against its own meta-schema M' without requiring
1318+
the validator to understand the vocabularies declared by M.
1319+
</t>
1320+
</section>
1321+
<section title="Vocabulary and non-vocabulary keywords">
1322+
<t>
1323+
Keywords from different vocabularies, as well as non-vocabulary
1324+
extension keywords, can have identical names. These are not
1325+
considered to be the same keyword from the perspective of
1326+
enabling or disabling them through "$vocabulary".
1327+
</t>
1328+
<t>
1329+
In particular the keywords defined in this specification and its
1330+
companion documents MUST be considered to be vocabulary keywords,
1331+
with availability governed by "$vocabulary" even in implementations
1332+
that do not support any extension vocabularies.
1333+
</t>
1334+
<t>
1335+
Guidance regarding vocabularies with identically-named keywords is provided
1336+
in Appendix <xref target="vocab-practices" format="counter"></xref>.
1337+
</t>
1338+
</section>
1339+
<section title="Default vocabularies" anchor="default-vocabs">
12971340
<t>
12981341
If "$vocabulary" is absent, an implementation MAY determine
12991342
behavior based on the meta-schema if it is recognized from the
@@ -3936,7 +3979,8 @@ https://example.com/schemas/common#/$defs/allOf/1
39363979
</section>
39373980

39383981
<section title="Working with vocabularies">
3939-
<section title="Best practices for vocabulary and meta-schema authors">
3982+
<section title="Best practices for vocabulary and meta-schema authors"
3983+
anchor="vocab-practices">
39403984
<t>
39413985
Vocabulary authors should
39423986
take care to avoid keyword name collisions if the vocabulary is intended

0 commit comments

Comments
 (0)