From 7b51ad611976d39833f22f8c270983c417acdb84 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 18 Sep 2022 18:34:32 -0700 Subject: [PATCH] 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. --- jsonschema-core.xml | 114 ++++++++++++++++++++++++++++++-------------- 1 file changed, 79 insertions(+), 35 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 4802e29d..3cc27d93 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1132,7 +1132,7 @@ -
+
Keywords declared in this section, which all begin with "$", make up the JSON Schema Core vocabulary. These keywords are either required in @@ -1238,17 +1238,13 @@
The "$vocabulary" keyword is used in meta-schemas to identify the - vocabularies available for use in schemas described by that meta-schema. - It is also used to indicate whether each vocabulary is required or optional, - in the sense that an implementation MUST understand the required vocabularies - in order to successfully process the schema. Together, this information forms - a dialect. Any vocabulary that is understood by the implementation MUST be - processed in a manner consistent with the semantic definitions contained - within the vocabulary. + vocabularies available for use in schemas described by that meta-schema, + and whether each vocabulary is required or optional. Together, this + information forms a dialect. The value of this keyword MUST be an object. The property names in the - object MUST be IRIs (containing a scheme) and this IRI MUST be normalized. + object MUST be IRIs (containing a scheme) and each IRI MUST be normalized. Each IRI that appears as a property name identifies a specific set of keywords and their semantics. @@ -1268,32 +1264,79 @@ The values of the object properties MUST be booleans. - If the value is true, then implementations that do not recognize - the vocabulary MUST refuse to process any schemas that declare - this meta-schema with "$schema". If the value is false, implementations - that do not recognize the vocabulary SHOULD proceed with processing - such schemas. The value has no impact if the implementation - understands the vocabulary. + If the value is true, then the vocabulary MUST be considered to be required. + If the value is false, then the vocabulary MUST be considered to be optional. - - Per , unrecognized - keywords SHOULD be treated as annotations. - This remains the case for keywords defined - by unrecognized vocabularies. It is not currently possible to distinguish - between unrecognized keywords that are defined in vocabularies from - those that are not part of any vocabulary. - - - The "$vocabulary" keyword SHOULD be used in the root schema of any schema - resource intended for use as a meta-schema. It MUST NOT appear in subschemas. - - - The "$vocabulary" keyword MUST be ignored in schema resources that - are not being processed as a meta-schema. This allows validating - a meta-schema M against its own meta-schema M' without requiring - the validator to understand the vocabularies declared by M. - -
+
+ + A schema is said to use a dialect and its constituent vocabularies if it is + associated with a meta-schema defining the dialect with "$vocabulary", + either through "$schema", through appropriately defined media type parameters + or link relation types, or through documented default implementation-defined + behavior in the absence of an explicit meta-schema. If a meta-schema + does not contain "$vocabulary", the set of vocabularies in use is determined + according to section . + + + Any vocabulary in use by a schema and understood by the implementation + MUST be processed in a manner consistent with the semantic definitions + contained within the vocabulary, regardless of whether that vocabulary + is required or optional. + + + Any vocabulary that is not present in "$vocabulary" MUST NOT be made + available for use in schemas described by that meta-schema, except for + the core vocabulary as specified by the introduction to section + . + + + Implementations that do not support a vocabulary required by a schema + MUST refuse to process that schema. + + + Implementations that do not support a vocabulary that is optionally used + by a schema SHOULD proceed with processing the schema. The keywords will + be considered to be unrecognized keywords as addressed by section + . Note that since + the recommended behavior for such keywords is to collect them as + annotations, vocabularies consisting only of annotations will have + the same behavior when used optionally whether the implementation + supports them or not. This allows annotation-only vocabularies to + be supported without custom code, even in implementations that do + not support providing custom code for extension vocabularies. + +
+
+ + The "$vocabulary" keyword SHOULD be used in the root schema of any schema + resource intended for use as a meta-schema. It MUST NOT appear in subschemas. + + + The "$vocabulary" keyword MUST be ignored in schema resources that + are not being processed as a meta-schema. This allows validating + a meta-schema M against its own meta-schema M' without requiring + the validator to understand the vocabularies declared by M. + +
+
+ + Keywords from different vocabularies, as well as non-vocabulary + extension keywords, can have identical names. These are not + considered to be the same keyword from the perspective of + enabling or disabling them through "$vocabulary". + + + In particular the keywords defined in this specification and its + companion documents MUST be considered to be vocabulary keywords, + with availability governed by "$vocabulary" even in implementations + that do not support any extension vocabularies. + + + Guidance regarding vocabularies with identically-named keywords is provided + in Appendix . + +
+
If "$vocabulary" is absent, an implementation MAY determine behavior based on the meta-schema if it is recognized from the @@ -3936,7 +3979,8 @@ https://example.com/schemas/common#/$defs/allOf/1
-
+
Vocabulary authors should take care to avoid keyword name collisions if the vocabulary is intended