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 @@