json-schema-org / json-schema-spec

The JSON Schema specification
http://json-schema.org/
Other
3.82k stars 266 forks source link

Clarify semantics of omitting vocabularies from "$vocabulary" #1294

Closed handrews closed 2 years ago

handrews commented 2 years ago

Per the §8.1.2 of the core spec:

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.

The intent of "identify the vocabularies available for use" is that schemas not identified as available for use are not available for use. We have do have a test for this scenario.

Supporting points for this view include:

An exhaustive discussion of further historical details, complete with citations from old issue and PR discussions, can be found in json-schema-org/JSON-Schema-Test-Suite#574

We just need to add normative language around the omission aspect. A related clarification (also discussed in the linked test suite issue) is that non-vocabulary keywords of the same name as vocabulary keywords are not considered the same keyword, any more than identically named keywords in different vocabularies are. They can be distinguished by whether inclusion in or omission from $vocabulary has an effect on them.