diff --git a/jsonschema-core.xml b/jsonschema-core.xml index d69580b9..50efa8c2 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -920,7 +920,7 @@ the relevant protocol's successful "no content" message, such as an HTTP 204 status. - Vocabulary documents may be added shortly, or in the next draft. + Vocabulary documents may be added in forthcoming drafts. For now, identifying the keyword set is deemed sufficient as that, along with meta-schema validation, is how the current "vocabularies" work today. @@ -931,13 +931,22 @@ 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 MAY choose to proceed with processing + that do not recognize the vocabulary SHOULD proceed with processing such schemas. - When processing a schema that uses unrecognized vocabularies, keywords - declared by those vocabularies are treated like any other unrecognized + Processing a schema with an unrecognized vocabulary (where the value of + the associated vocabulary key is "false") SHOULD result in keywords + declared by that vocabulary (if known) being treated like any other unrecognized keyword, and ignored. + + Opted for SHOULD here, because it's not possible to know what keywords + WERE included in the unkown vocabulary. If another known + vocabulary uses one of the same keywords as the unkown vocabulary, this + shouldn't result in THAT keyword being ignored. (And it's unlikely that it + is possble to tell this anyway. Unless it's a known but unsupported vocabulary, + however I think here the phrase "known" is equivilent to "supported.) + The "$vocabulary" keyword SHOULD be used in the root schema of any schema @@ -1074,17 +1083,32 @@
+ + This meta-schema explicitly declares both the Core and Applicator + vocabularies with its own vocabulary and combines the + Core and Applicator meta-schemas with an "allOf". It does not + need to include itself in the "allOf" since it is its own + meta-schema. It additionally applies three modifications to the + combination of these vocabularies: + + + It restricts the usage of the Applicator vocabulary + by forbidding the keywords prefixed with "unevaluated". + + + It describes a keyword, "startDate", that is defined by + its own vocabulary. + + + It describes a keyword, "localKeyword", that is not + part of any 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", "properties", and "patternProperties"). +
- - 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"). -
+ + "localKeyword" and "startDate" are now valid for any schema that + declares this meta-schema for their "$schema". Note that defining + it in this way does not imply the new keywords are valid within an + instance to be validated by such a schema. + + + Although the meta-schema can validate the syntax of "startDate" + within a schema, it is the vocabulary that defines the logic behind + the semantic meaning of "startDate". Without an understanding of + the semantics (that the instance value should represent a date after that + given in the schema), an implementation can only validate the syntactic + usage of "startDate" (that it is a date-formatted string). This is why + a schema must refuse to validate a schema which uses a meta-schema + that declares a required unknown vocabulary. + + + In order for an implementation to understand the keywords defined by + vocabulary, it may be necessary for the user to augment the + implementation by writing a plug-in or other extension that the + implementation can use to execute the new validation logic. The + mechanisms by which an implementation supports this are not covered + by this specification, however it is RECOMMENDED that implementations + provide such support. + The standard meta-schemas that combine all vocabularies defined by the Core and Validation specification, and that combine all vocabularies