From 689947fba3a62c4bc1297a61e615d533973520df Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 30 Jun 2019 13:22:11 +1200 Subject: [PATCH 1/8] added some verbiage to the vocabularies example for clarity --- jsonschema-core.xml | 70 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 13 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index d69580b9..dc810334 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. @@ -935,9 +935,9 @@ such schemas. - When processing a schema that uses unrecognized vocabularies, keywords - declared by those vocabularies are treated like any other unrecognized - keyword, and ignored. + When processing a schema that uses an unrecognized vocabulary (the value for + the vocabulary is false), keywords declared by that vocabulary are + treated like any other unrecognized keyword, and ignored. The "$vocabulary" keyword SHOULD be used in the root schema of any schema @@ -1077,13 +1077,28 @@
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"). + 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 keyword prefixed with "unevaluated". + + + It describes a keyword, "pastDate", 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").
+ + "localKeyword" and "pastDate" 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 "pastDate" + within a schema, it is the vocabulary that defines the logic behind + the semantic meaning of "pastDate". Without an understanding of + the semantics, an implementation can only validate the syntactic usage + of "pastDate". 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 From bbb0c0a60eb9017d87d44d56399c5f76991ecfde Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 30 Jun 2019 13:30:05 +1200 Subject: [PATCH 2/8] moved 'preamble' for vocab example to just text to support list --- jsonschema-core.xml | 50 ++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index dc810334..1d33cd01 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1074,32 +1074,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 keyword prefixed with "unevaluated". + + + It describes a keyword, "pastDate", 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 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 keyword prefixed with "unevaluated". - - - It describes a keyword, "pastDate", 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"). - Date: Sun, 30 Jun 2019 15:56:07 +1200 Subject: [PATCH 3/8] clarified the distinction between semantic and syntatic validation --- jsonschema-core.xml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 1d33cd01..058b902f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1152,9 +1152,11 @@ Although the meta-schema can validate the syntax of "pastDate" within a schema, it is the vocabulary that defines the logic behind the semantic meaning of "pastDate". Without an understanding of - the semantics, an implementation can only validate the syntactic usage - of "pastDate". This is why a schema MUST refuse to validate a schema - which uses a meta-schema that declares a required unknown vocabulary. + the semantics (that the value should represent a date prior to the + moment of validation), an implementation can only validate the syntactic + usage of "pastDate" (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 From 351b5d172e2846dee1510fecce72807df750f714 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 30 Jun 2019 18:35:02 +1200 Subject: [PATCH 4/8] use 'startDate' instead of 'pastDate' --- jsonschema-core.xml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 058b902f..3f7426ce 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1087,7 +1087,7 @@ by forbidding the keyword prefixed with "unevaluated". - It describes a keyword, "pastDate", that is defined by + It describes a keyword, "startDate", that is defined by its own vocabulary. @@ -1119,7 +1119,7 @@ "^unevaluated.*$": false }, "properties": { - "pastDate": { + "startDate": { "$comment": "Defined by vocabulary" "type": "string", "format": "date" @@ -1143,18 +1143,18 @@
- "localKeyword" and "pastDate" are now valid for any schema that + "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 "pastDate" + 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 "pastDate". Without an understanding of - the semantics (that the value should represent a date prior to the - moment of validation), an implementation can only validate the syntactic - usage of "pastDate" (that it is a date-formatted string). This is why + the semantic meaning of "startDate". Without an understanding of + the semantics (that the value should represent a date prior 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. From e00832bdaadaa271d2df6ff4228ab1116cea0bc3 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 1 Jul 2019 08:42:31 +1200 Subject: [PATCH 5/8] a bit more clarity --- jsonschema-core.xml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 3f7426ce..a3cd3282 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -935,9 +935,10 @@ such schemas. - When processing a schema that uses an unrecognized vocabulary (the value for - the vocabulary is false), keywords declared by that vocabulary are - treated like any other unrecognized keyword, and ignored. + When processing a schema that uses an unrecognized vocabulary + (implying that the value for the vocabulary must be false), keywords + declared by that vocabulary are treated like any other unrecognized + keyword, and ignored. The "$vocabulary" keyword SHOULD be used in the root schema of any schema @@ -1084,7 +1085,7 @@ It restricts the usage of the Applicator vocabulary - by forbidding the keyword prefixed with "unevaluated". + by forbidding the keywords prefixed with "unevaluated". It describes a keyword, "startDate", that is defined by @@ -1152,7 +1153,7 @@ 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 value should represent a date prior that + 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 From 68e314066e0b59b6cdcf17ffcbe2c41a3651e677 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Tue, 2 Jul 2019 07:14:21 +1200 Subject: [PATCH 6/8] lowercased a 'must' since it's informative --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index a3cd3282..0ac253f1 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1156,7 +1156,7 @@ 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 + a schema must refuse to validate a schema which uses a meta-schema that declares a required unknown vocabulary. From a5a0343abd0b961ce5d44a0e999993dfb8dcd912 Mon Sep 17 00:00:00 2001 From: Ben Hutton Date: Wed, 3 Jul 2019 12:45:10 +0100 Subject: [PATCH 7/8] Make handling of unkown vocabs clearer Make it clearer that if an unkown vocab has `false` as its value, it can be ignored, and any keywords it would add should be ignored. Redefine behaviour of `false` value on `$vocabularies` object to SHOULD rather than MAY, which I feel is likely better in line with intent and schema authors expectations, given the `true/false` value represents if the vocab is always required for procesing (or not). --- jsonschema-core.xml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 0ac253f1..90cf4ef6 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -931,15 +931,23 @@ 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 an unrecognized vocabulary - (implying that the value for the vocabulary must be false), keywords - declared by that vocabulary 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 document intended for use as a meta-schema. It MUST NOT appear in subschemas. From bf1f8e63ba6a5bafee5be56cf019428401a5ca1e Mon Sep 17 00:00:00 2001 From: Ben Hutton Date: Tue, 9 Jul 2019 12:57:05 +0100 Subject: [PATCH 8/8] Moved cref inside t tag --- jsonschema-core.xml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 90cf4ef6..50efa8c2 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -939,15 +939,15 @@ 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.) + - - 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 document intended for use as a meta-schema. It MUST NOT appear in subschemas.