diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 651c8ba1..0ceb2e0a 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1208,6 +1208,15 @@ must be repeated in the root of each schema document intended for use as a meta-schema. This is demonstrated in the example meta-schema. + + This requirement allows implementations to find all vocabulary + requirement information in a single place for each meta-schema. + As schema extensibility means that there are endless potential + ways to combine more fine-grained meta-schemas by reference, + requiring implementations to anticipate all possibilities and + search for vocabularies in referenced meta-schemas would + be overly burdensome. + @@ -1308,53 +1317,93 @@
+ + This meta-schema explicitly declares both the Core and Applicator vocabularies, + together with an extension vocabulary, and combines their meta-schemas with + an "allOf". The extension vocabulary's meta-schema, which describes only the + keywords in that vocabulary, is shown after the main example meta-schema. + + + The main example meta-schema also restricts the usage of the Applicator + vocabulary by forbidding the keywords prefixed with "unevaluated", which + are particularly complex to implement. This does not change the semantics + or set of keywords defined by the Applicator vocabulary. It just ensures + that schemas using this meta-schema that attempt to use the keywords + prefixed with "unevaluted" will fail validation against this meta-schema. + + + Finally, this meta-schema describes the syntax of a keyword, "localKeyword", + that is not part of any vocabulary. Presumably, the implementors and users + of this meta-schema will understand the semantics of "localKeyword". + JSON Schema does not define any mechanism for expressing keyword semantics + outside of vocabularies, making them unsuitable for use except in a + specific environment in which they are understood. +
- This meta-schema explicitly declares both the Core and Applicator - vocabularies, and combines their meta-schemas with an "allOf". - It additionally restricts the usage of the Applicator vocabulary - by forbidding the keyword prefixed with "unevaluated". It also - describes a keyword, "localKeyword", that is not part of either - vocabulary. Note that it is its own meta-schema, - as it relies on both the Core vocabulary (as all schemas do) - and the Applicator vocabulary (for "allOf"). + This meta-schema combines several vocabularies for general use. - - As shown above, even though each of the referenced standard - meta-schemas declares its corresponding vocabulary, this new - meta-schema must re-declare them for itself. It would be - valid to leave the core vocabulary out of the "$vocabulary" keyword, - but it needs to be referenced through the "allOf" keyword in order - for its terms to be validated. There is no special case for - validation of core keywords. - +
+
+ + This meta-schema describes only a single extension vocabulary. + + + +
+ + As shown above, even though each of the single-vocabulary meta-schemas + referenced in the general-use meta-schema's "allOf" declares its + corresponding vocabulary, this new meta-schema must re-declare them. + The standard meta-schemas that combine all vocabularies defined by the Core and Validation specification, and that combine all vocabularies @@ -1363,6 +1412,17 @@ meta-schemas may be found in the Validation and Hyper-Schema specifications, respectively. + + While the general-use meta-schema can validate the syntax of "minDate", + it is the vocabulary that defines the logic behind the semantic meaning + of "minDate". Without an understanding of the semantics (in this example, + that the instance value must be a date equal to or after the date + provided as the keyword's value in the schema), an implementation can + only validate the syntactic usage. In this case, that means validating + that it is a date-formatted string (using "pattern" to ensure that it is + validated even when "format" functions purely as an annotation, as explained + in the Validation specification. +
@@ -1598,7 +1658,7 @@