From 3f72dc54a10c7efc81b704dae2e35ab1fedec38d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 5 Nov 2018 18:38:03 -0800 Subject: [PATCH 01/16] Create new meta-schemas and vocabularies section and stuff the "$schema" keyword's section under it. This commit does not change any specification text at all, only indentation. It removes a TODO note that is obsolete now that we are adding vocabulary support. --- jsonschema-core.xml | 87 +++++++++++++++++++++++---------------------- 1 file changed, 44 insertions(+), 43 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 637e587d..31950da0 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -807,49 +807,50 @@ -
- - - The "$schema" keyword is both used as a JSON Schema version identifier and the - location of a resource which is itself a JSON Schema, which describes any schema - written for this particular version. - - - The value of this keyword MUST be a URI - (containing a scheme) and this URI MUST be normalized. - The current schema MUST be valid against the meta-schema identified by this URI. - - - If this URI identifies a retrievable resource, that resource SHOULD be of - media type "application/schema+json". - - - The "$schema" keyword SHOULD be used in a root schema. - It MUST NOT appear in subschemas. - - - - Using multiple "$schema" keywords in the same document would imply that the - vocabulary and therefore behavior can change within a document. This would - necessitate resolving a number of implementation concerns that have not yet - been clearly defined. So, while the pattern of using "$schema" only in root - schemas is likely to remain the best practice for schema authoring, - implementation behavior is subject to be revised or liberalized in - future drafts. - - - - - Values for this property are defined in other documents and by other parties. - JSON Schema implementations SHOULD implement support for current and previous - published drafts of JSON Schema vocabularies as deemed reasonable. - +
+
+ + The "$schema" keyword is both used as a JSON Schema version identifier and the + location of a resource which is itself a JSON Schema, which describes any schema + written for this particular version. + + + The value of this keyword MUST be a URI + (containing a scheme) and this URI MUST be normalized. + The current schema MUST be valid against the meta-schema identified by this URI. + + + If this URI identifies a retrievable resource, that resource SHOULD be of + media type "application/schema+json". + + + The "$schema" keyword SHOULD be used in a root schema. + It MUST NOT appear in subschemas. + + + + Using multiple "$schema" keywords in the same document would imply that the + vocabulary and therefore behavior can change within a document. This would + necessitate resolving a number of implementation concerns that have not yet + been clearly defined. So, while the pattern of using "$schema" only in root + schemas is likely to remain the best practice for schema authoring, + implementation behavior is subject to be revised or liberalized in + future drafts. + + + + + Values for this property are defined in other documents and by other parties. + JSON Schema implementations SHOULD implement support for current and previous + published drafts of JSON Schema vocabularies as deemed reasonable. + +
From b69e39494e73720c76d9db98fc79e87504a49a70 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 7 Nov 2018 23:10:52 -0800 Subject: [PATCH 02/16] Generalize $schema from "version" to "feature set" --- jsonschema-core.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 31950da0..ca45ff66 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -810,9 +810,9 @@
- The "$schema" keyword is both used as a JSON Schema version identifier and the - location of a resource which is itself a JSON Schema, which describes any schema - written for this particular version. + The "$schema" keyword is both used as a JSON Schema feature set identifier and + the location of a resource which is itself a JSON Schema, which describes any + schema written for this particular feature set. The value of this keyword MUST be a URI From 8d4ff3d1a83adb8b9bb177559ff18dfe86b7c16c Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 10 Nov 2018 15:42:24 -0800 Subject: [PATCH 03/16] Add "$vocabulary" and the vocabularies concept This defines the $vocabulary keyword and explains how it fits into schema and meta-schema processing. Vocabulary-specific meta-schemas to be added in a subsequent commit. --- jsonschema-core.xml | 219 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 217 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index ca45ff66..091ca3a3 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -808,6 +808,44 @@
+ + Two concepts, meta-schemas and vocabularies, are used to inform an implementation + how to interpret a schema. A schema S declares its meta-schema M with the "$schema" + keyword, and meta-schemas declare vocabularies with the "$vocabulary" keyword. + The vocabularies declared in M are those that are expected to be used in S. + The meta-schema M may itself use a different set of vocabularies, which are + declared in its own meta-schema, M'. + + + The role of the meta-schema is to constrain the structure of conforming schemas, + as well as simplify the process of composing multiple vocabularies into a usable + feature set. Schema authoring is obviously expected to be a common activity, so + schema authors need only understand how to reference a single meta-schema. + + + Meta-schema authoring is an advanced usage of JSON Schema, so the design of + meta-schema features emphasizes flexibility over simplicity. + + + The role of a vocabulary is to declare which keywords (including sub-keywords + such as those in JSON Hyper-Schema's Link Description Object) are in use, + and with which semantics. The semantics are indicated by the document + that publicizes the vocabulary URI. At this time, there is no machine-readable + description of keywords other than validation rules, which appear in the + meta-schema. + + + Meta-schemas are separate from vocabularies to allow for the same sets of + vocabularies to be combined in different ways, and for meta-schema authors + to impose additional constraints such as forbidding certain keywords, or + performing unusually strict syntactical validation, as might be done + during a development and testing cycle. + + + A schema is considered to be processed as meta-schema if it was + identified as such in a schema's "$schema". Implementations MAY + also offer alternate ways to process schemas using meta-schema rules. +
The "$schema" keyword is both used as a JSON Schema feature set identifier and @@ -830,7 +868,7 @@ Using multiple "$schema" keywords in the same document would imply that the - vocabulary and therefore behavior can change within a document. This would + feature set and therefore behavior can change within a document. This would necessitate resolving a number of implementation concerns that have not yet been clearly defined. So, while the pattern of using "$schema" only in root schemas is likely to remain the best practice for schema authoring, @@ -851,6 +889,175 @@ published drafts of JSON Schema vocabularies as deemed reasonable.
+
+ + The "$vocabulary" keyword is used within meta-schemas to declare + the sets of keywords that schemas described by the meta-schema are + expected to use. + + + The value of this keyword MUST be an object. The property names in the + object MUST be URIs, (containing a scheme) and this URI MUST be normalized. + The URI MAY be a URL, but the nature of the retrievable resources is + currently undefined, and reserved for future use. Vocabulary authors + SHOULD NOT serve a document at that URL. A server MAY respond with + 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. + For now, identifying the keyword set is deemed sufficient as that, + along with meta-schema validation, is how the current "vocabularies" + work today. + + + + The values of the object properties MUST be booleans. + 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 + such schemas. + + + When processing a schema that uses unrecognized vocabularies, keywords + declared by those vocabularies are treated like any other unrecognized + keyword, and ignored. + + + 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. + + + The "$vocabulary" keyword MUST be ignored in a schema documents that + is not being processed as a meta-schema. This allows validating + a meta-schema M against its own meta-schema M' without requiring + the validator to understand the vocabularies declared by M. + + + Note that the processing restrictions on "$vocabulary" mean that + meta-schemas that reference other meta-schemas, for example to + provide a meta-schema that extends or composes other meta-schemas, + do not automatically declare the vocabularies of those other + meta-schemas. All such declarations must be repeated in the root + of each schema document intended for use as a meta-schema. + +
+ + Meta-schema authors SHOULD NOT use "$vocabulary" to combine multiple + vocabularies that define conflicting syntax or semantics for the same + keyword. As semantic conflicts are not generally detectable through + schema validation, implementations are not expected to detect such + conflicts. If conflicting vocabularies are declared, the resulting + behavior is undefined. + + + Vocabulary authors SHOULD provide a meta-schema that validates the + expected usage of the vocabulary's keywords. Such meta-schemas + SHOULD NOT forbid additional keywords, and MUST NOT forbid + the "$id", "$schema", or "$vocabulary" keywords in the root schema. + + + It is RECOMMENDED that meta-schema authors reference each vocabulary's + meta-schema using the "allOf" keyword, + although other mechanisms for constructing the meta-schema may be + appropriate for certain use cases. + + + Meta-schemas MAY impose additional constraints, including describing + keywords not present in any vocabulary, beyond what the meta-schemas + associated with the declared vocabularies describe. This allows for + restricting usage to a subset of a vocabulary, and for validating + locally defined keywords not intended for re-use. + + + Meta-schemas intended for local use, with no need to test for + vocabulary support in arbitrary implementations, can safely omit + "$vocabulary" entirely. + +
+
+ + Keywords declared in in this specification that begin with "$" make up + the JSON Schema Core vocabulary. These keywords are either required in + order process any schema or meta-schema, including those split across + multiple documents, or exist to reserve keywords for purposes that + require guaranteed interoperability. + + + The Core vocabulary MUST be considered mandatory at all times, in order + to bootstrap the processing of further vocabularies. Meta-schema + authors MAY explicitly list the Core vocabulary, but do not need + to do so. If present, the Core vocabulary entry MUST have a value + of true indicating that it is required. The behavior of a value + of false is undefined. + + + The current URI for the Core vocabulary is: + . + + + The current URI for the corresponding meta-schema is: + . + +
+
+
+ + This meta-schema explicitly declares both the Core and Applicator + vocabularies, and combines their meta-schemas with an "allOf". + It additional restricts the usage of the Applicator vocabulary + by forbidding the keyword prefixed with "unevaluated". It also + describes a keyword, "localKeyord", 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"0. + + + + + + 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 MUST be referenced through the "allOf" keyword in order + for its terms to be validated. There is no special case for + validation of core keywords. + +
+ + The standard meta-schemas that combine all vocabularies defined by + the Core and Validation specification, and that combine all vocabularies + defined by those specifications as well as the Hyper-Schema specification, + demonstrate additional complex combinations. These URIs for these + meta-schemas may be found in the Validation and Hyper-Schema specifications, + respectively. + +
+
@@ -1616,6 +1823,14 @@ This section defines a vocabulary of applicator keywords that are RECOMMENDED for use as the basis of other vocabularies. + + The current URI for this vocabulary, known as the Applicator vocabulary, is: + . + + + The current URI for the corresponding meta-schema is: + . +
Schema keywords typically operate independently, without @@ -1660,7 +1875,7 @@ keyword to be applied to an instance location with different values. Annotation keywords define their own rules for combining such values. -
+
This keyword's value MUST be a non-empty array. Each item of the array MUST be a valid JSON Schema. From b3d9acfd0401adffb7317d6cec84c6d686afeaf8 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 10 Nov 2018 16:45:49 -0800 Subject: [PATCH 04/16] Core and Applicator vocabulary meta-schemas These are the single-vocabulary meta-schemas. In a future commit, the regular "schema" and "hyper-schema" meta-schemas will be updated to reference these, and use "$vocabulary". This commit just establishes these two meta-schemas on their own. --- applicator.json | 60 +++++++++++++++++++++++++++++++++++++++++++++++++ core.json | 50 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 applicator.json create mode 100644 core.json diff --git a/applicator.json b/applicator.json new file mode 100644 index 00000000..f7247a1a --- /dev/null +++ b/applicator.json @@ -0,0 +1,60 @@ +{ + "$schema": "http://json-schema.org/draft-08/schema#", + "$id": "https://json-schema.org/draft-08/applicator", + "$recursiveAnchor": true, + "$vocabulary": { + "https://json-schema.org/draft-08/vocabularies/applicator": true + }, + + "title": "Applicator vocabulary meta-schema", + "$defs": { + "schemaArray": { + "type": "array", + "minItems": 1, + "items": { "$recursiveRef": "#" } + } + }, + "properties": { + "additionalItems": { "$recursiveRef": "#" }, + "unevaluatedItems": { "$recursiveRef": "#" }, + "items": { + "anyOf": [ + { "$recursiveRef": "#" }, + { "$ref": "#/$defs/schemaArray" } + ] + }, + "contains": { "$recursiveRef": "#" }, + "additionalProperties": { "$recursiveRef": "#" }, + "unevaluatedProperties": { + "type": "object", + "additionalProperties": { + "$recursiveRef": "#" + } + }, + "properties": { + "type": "object", + "additionalProperties": { "$recursiveRef": "#" }, + "default": {} + }, + "patternProperties": { + "type": "object", + "additionalProperties": { "$recursiveRef": "#" }, + "propertyNames": { "format": "regex" }, + "default": {} + }, + "dependentSchemas": { + "type": "object", + "additionalProperties": { + "$recursiveRef": "#" + } + }, + "propertyNames": { "$recursiveRef": "#" }, + "if": { "$recursiveRef": "#" }, + "then": { "$recursiveRef": "#" }, + "else": { "$recursiveRef": "#" }, + "allOf": { "$ref": "#/$defs/schemaArray" }, + "anyOf": { "$ref": "#/$defs/schemaArray" }, + "oneOf": { "$ref": "#/$defs/schemaArray" }, + "not": { "$recursiveRef": "#" } + } +} diff --git a/core.json b/core.json new file mode 100644 index 00000000..e1dec81e --- /dev/null +++ b/core.json @@ -0,0 +1,50 @@ +{ + "$schema": "http://json-schema.org/draft-08/schema#", + "$id": "https://json-schema.org/draft-08/core", + "$recursiveAnchor": true, + "$vocabulary": { + "https://json-schema.org/draft-08/vocabularies/core": true + }, + + "title": "Core vocabulary meta-schema", + "type": ["object", "boolean"], + "properties": { + "$id": { + "type": "string", + "format": "uri-reference" + }, + "$schema": { + "type": "string", + "format": "uri" + }, + "$ref": { + "type": "string", + "format": "uri-reference" + }, + "$recursiveRef": { + "type": "string", + "format": "uri-reference" + }, + "$recursiveAnchor": { + "type": "boolean" + }, + "$vocabulary": { + "type": "object", + "propertyNames": { + "type": "string", + "format": "uri" + }, + "additionalProperties": { + "type": "boolean" + } + }, + "$comment": { + "type": "string" + }, + "$defs": { + "type": "object", + "additionalProperties": { "$recursiveRef": "#" }, + "default": {} + } + } +} From c5612bfbd12de7c341d045b5ba9c161e14759e67 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 12 Nov 2018 09:54:28 -0800 Subject: [PATCH 05/16] Fix vocab section indentation All of those other sections were not intended to be subsections of the "$vocabulary" keyword section. --- jsonschema-core.xml | 184 ++++++++++++++++++++++---------------------- 1 file changed, 92 insertions(+), 92 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 091ca3a3..b63e804b 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -941,78 +941,79 @@ meta-schemas. All such declarations must be repeated in the root of each schema document intended for use as a meta-schema. -
- - Meta-schema authors SHOULD NOT use "$vocabulary" to combine multiple - vocabularies that define conflicting syntax or semantics for the same - keyword. As semantic conflicts are not generally detectable through - schema validation, implementations are not expected to detect such - conflicts. If conflicting vocabularies are declared, the resulting - behavior is undefined. - - - Vocabulary authors SHOULD provide a meta-schema that validates the - expected usage of the vocabulary's keywords. Such meta-schemas - SHOULD NOT forbid additional keywords, and MUST NOT forbid - the "$id", "$schema", or "$vocabulary" keywords in the root schema. - - - It is RECOMMENDED that meta-schema authors reference each vocabulary's - meta-schema using the "allOf" keyword, - although other mechanisms for constructing the meta-schema may be - appropriate for certain use cases. - - - Meta-schemas MAY impose additional constraints, including describing - keywords not present in any vocabulary, beyond what the meta-schemas - associated with the declared vocabularies describe. This allows for - restricting usage to a subset of a vocabulary, and for validating - locally defined keywords not intended for re-use. - - - Meta-schemas intended for local use, with no need to test for - vocabulary support in arbitrary implementations, can safely omit - "$vocabulary" entirely. - -
-
- - Keywords declared in in this specification that begin with "$" make up - the JSON Schema Core vocabulary. These keywords are either required in - order process any schema or meta-schema, including those split across - multiple documents, or exist to reserve keywords for purposes that - require guaranteed interoperability. - - - The Core vocabulary MUST be considered mandatory at all times, in order - to bootstrap the processing of further vocabularies. Meta-schema - authors MAY explicitly list the Core vocabulary, but do not need - to do so. If present, the Core vocabulary entry MUST have a value - of true indicating that it is required. The behavior of a value - of false is undefined. - - - The current URI for the Core vocabulary is: - . - - - The current URI for the corresponding meta-schema is: - . - -
-
-
- - This meta-schema explicitly declares both the Core and Applicator - vocabularies, and combines their meta-schemas with an "allOf". - It additional restricts the usage of the Applicator vocabulary - by forbidding the keyword prefixed with "unevaluated". It also - describes a keyword, "localKeyord", 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"0. - - +
+
+ + Meta-schema authors SHOULD NOT use "$vocabulary" to combine multiple + vocabularies that define conflicting syntax or semantics for the same + keyword. As semantic conflicts are not generally detectable through + schema validation, implementations are not expected to detect such + conflicts. If conflicting vocabularies are declared, the resulting + behavior is undefined. + + + Vocabulary authors SHOULD provide a meta-schema that validates the + expected usage of the vocabulary's keywords. Such meta-schemas + SHOULD NOT forbid additional keywords, and MUST NOT forbid + the "$id", "$schema", or "$vocabulary" keywords in the root schema. + + + It is RECOMMENDED that meta-schema authors reference each vocabulary's + meta-schema using the "allOf" keyword, + although other mechanisms for constructing the meta-schema may be + appropriate for certain use cases. + + + Meta-schemas MAY impose additional constraints, including describing + keywords not present in any vocabulary, beyond what the meta-schemas + associated with the declared vocabularies describe. This allows for + restricting usage to a subset of a vocabulary, and for validating + locally defined keywords not intended for re-use. + + + Meta-schemas intended for local use, with no need to test for + vocabulary support in arbitrary implementations, can safely omit + "$vocabulary" entirely. + +
+
+ + Keywords declared in in this specification that begin with "$" make up + the JSON Schema Core vocabulary. These keywords are either required in + order process any schema or meta-schema, including those split across + multiple documents, or exist to reserve keywords for purposes that + require guaranteed interoperability. + + + The Core vocabulary MUST be considered mandatory at all times, in order + to bootstrap the processing of further vocabularies. Meta-schema + authors MAY explicitly list the Core vocabulary, but do not need + to do so. If present, the Core vocabulary entry MUST have a value + of true indicating that it is required. The behavior of a value + of false is undefined. + + + The current URI for the Core vocabulary is: + . + + + The current URI for the corresponding meta-schema is: + . + +
+
+
+ + This meta-schema explicitly declares both the Core and Applicator + vocabularies, and combines their meta-schemas with an "allOf". + It additional restricts the usage of the Applicator vocabulary + by forbidding the keyword prefixed with "unevaluated". It also + describes a keyword, "localKeyord", 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"0. + + - - - 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 MUST be referenced through the "allOf" keyword in order - for its terms to be validated. There is no special case for - validation of core keywords. - -
- - The standard meta-schemas that combine all vocabularies defined by - the Core and Validation specification, and that combine all vocabularies - defined by those specifications as well as the Hyper-Schema specification, - demonstrate additional complex combinations. These URIs for these - meta-schemas may be found in the Validation and Hyper-Schema specifications, - respectively. - -
+ + + 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 MUST be referenced through the "allOf" keyword in order + for its terms to be validated. There is no special case for + validation of core keywords. + + + + The standard meta-schemas that combine all vocabularies defined by + the Core and Validation specification, and that combine all vocabularies + defined by those specifications as well as the Hyper-Schema specification, + demonstrate additional complex combinations. These URIs for these + meta-schemas may be found in the Validation and Hyper-Schema specifications, + respectively. +
From 8d470002fec6b7a7cb705ff63b7a90a62bed24ea Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 12 Nov 2018 10:01:07 -0800 Subject: [PATCH 06/16] Make a section for identifying meta-schemas Clarify both the mandatory standard way, and that there is a non-interoperable option for implementation-specific functionality or optimizations. --- jsonschema-core.xml | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index b63e804b..acd371d9 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -841,11 +841,6 @@ performing unusually strict syntactical validation, as might be done during a development and testing cycle. - - A schema is considered to be processed as meta-schema if it was - identified as such in a schema's "$schema". Implementations MAY - also offer alternate ways to process schemas using meta-schema rules. -
The "$schema" keyword is both used as a JSON Schema feature set identifier and @@ -928,8 +923,8 @@ document intended for use as a meta-schema. It MUST NOT appear in subschemas. - The "$vocabulary" keyword MUST be ignored in a schema documents that - is not being processed as a meta-schema. This allows validating + The "$vocabulary" keyword MUST be ignored in schema documents that + are not being processed as a meta-schema. This allows validating a meta-schema M against its own meta-schema M' without requiring the validator to understand the vocabularies declared by M. @@ -942,6 +937,30 @@ of each schema document intended for use as a meta-schema.
+
+ + Implementations MUST recognize a schema as a meta-schema if it + is being examined because it was identified as such by another + schema's "$schema" keyword. This means that a single schema + document might sometimes be considered a regular schema, and + other times be considered a meta-schema. + + + In the case of examining a schema which is its own meta-schema, + when an implementation begins processing it as a regular schema, + it is processed under those rules. However, when loaded a second + time as a result of checking its own "$schema" value, it is treated + as a meta-schema. So the same document is processed both ways in + the course of one session. + + + Implementations MAY allow a schema to be passed as a meta-schema, + for implementation-specific purposes, such as pre-loading a commonly + used meta-schema and checking its vocabulary support requirements + up front. Meta-schema authors MUST NOT expect such features to be + interoperable across implementations. + +
Meta-schema authors SHOULD NOT use "$vocabulary" to combine multiple From d7ad56a1b4ae28cf853171463600536d56e29c02 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 12 Nov 2018 10:07:06 -0800 Subject: [PATCH 07/16] Make the core vocabulary mandatory in "$vocabulary" Per review feedback, explicit is probably better than implicit here. At least until we get more real-world feedback. Easier to relax it later if we need to than add it. --- applicator.json | 1 + jsonschema-core.xml | 36 ++++++++++++++++++++++++------------ 2 files changed, 25 insertions(+), 12 deletions(-) diff --git a/applicator.json b/applicator.json index f7247a1a..de770dd2 100644 --- a/applicator.json +++ b/applicator.json @@ -3,6 +3,7 @@ "$id": "https://json-schema.org/draft-08/applicator", "$recursiveAnchor": true, "$vocabulary": { + "https://json-schema.org/draft-08/vocabularies/core": true, "https://json-schema.org/draft-08/vocabularies/applicator": true }, diff --git a/jsonschema-core.xml b/jsonschema-core.xml index acd371d9..11a5ab47 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -930,11 +930,12 @@ Note that the processing restrictions on "$vocabulary" mean that - meta-schemas that reference other meta-schemas, for example to - provide a meta-schema that extends or composes other meta-schemas, - do not automatically declare the vocabularies of those other - meta-schemas. All such declarations must be repeated in the root - of each schema document intended for use as a meta-schema. + meta-schemas that reference other meta-schemas using "$ref" or + similar keywords do not automatically inherit the vocabulary + declarations of those other meta-schemas. All such declarations + 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.
@@ -1005,11 +1006,21 @@ The Core vocabulary MUST be considered mandatory at all times, in order - to bootstrap the processing of further vocabularies. Meta-schema - authors MAY explicitly list the Core vocabulary, but do not need - to do so. If present, the Core vocabulary entry MUST have a value - of true indicating that it is required. The behavior of a value - of false is undefined. + to bootstrap the processing of further vocabularies. Meta-schemas + that use "$vocabulary" MUST explicitly list the Core vocabulary, + which MUST have a value of true indicating that it is required. + + + The behavior of a false value for this vocabulary (and only this + vocabulary) is undefined, as is the behavior when "$vocabulary" + is present but the Core vocabulary is not included. However, it + is RECOMMENDED that implementations detect these cases and raise + an error when they occur. + + + Meta-schemas that do not use "$vocabulary" MUST be considered to + require the Core vocabulary just as if "$vocabulary" were used + with only the Core vocabulary present with a value of true. The current URI for the Core vocabulary is: @@ -1020,7 +1031,8 @@ .
-
+
This meta-schema explicitly declares both the Core and Applicator @@ -1041,7 +1053,7 @@ "$vocabulary": { "https://json-schema.org/draft-08/vocabularies/core": true, "https://json-schema.org/draft-08/vocabularies/applicator": true - }. + }, "allOf": [ {"$ref": "https://json-schema.org/draft-08/core"}, {"$ref": "https://json-schema.org/draft-08/applicator"} From d8314bd5c2574a604b162fb826984f3f5e987bdc Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 12 Nov 2018 10:08:05 -0800 Subject: [PATCH 08/16] Tweak the paragraph about who defines meta-schemas Since we now define two in this document. --- jsonschema-core.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 11a5ab47..6c6e662d 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -879,9 +879,9 @@ --> - Values for this property are defined in other documents and by other parties. - JSON Schema implementations SHOULD implement support for current and previous - published drafts of JSON Schema vocabularies as deemed reasonable. + Values for this property are defined in this and other documents and by other + parties. JSON Schema implementations SHOULD implement support for current + and previous published drafts of JSON Schema vocabularies as deemed reasonable.
From d3a9f99195ab472e5ef89176d44dd9ed6b4bae22 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 12 Nov 2018 10:11:04 -0800 Subject: [PATCH 09/16] Fix typo: additional[ly] --- jsonschema-core.xml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 6c6e662d..3877b673 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -879,9 +879,10 @@ --> - Values for this property are defined in this and other documents and by other - parties. JSON Schema implementations SHOULD implement support for current - and previous published drafts of JSON Schema vocabularies as deemed reasonable. + Values for this property are defined elsewhere in this and other documents, + and by other parties. JSON Schema implementations SHOULD implement support + for current and previous published drafts of JSON Schema vocabularies + as deemed reasonable.
@@ -1037,7 +1038,7 @@ This meta-schema explicitly declares both the Core and Applicator vocabularies, and combines their meta-schemas with an "allOf". - It additional restricts the usage of the Applicator vocabulary + It additionally restricts the usage of the Applicator vocabulary by forbidding the keyword prefixed with "unevaluated". It also describes a keyword, "localKeyord", that is not part of either vocabulary. Note that it is its own meta-schema, From 36840f894281135890c562ca43d958245a05bf10 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 12 Nov 2018 10:55:00 -0800 Subject: [PATCH 10/16] $vocabulary is like other meta-schema keywords It relates to the schemas described by the meta-schema, not to the meta-schema itself. --- jsonschema-core.xml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 3877b673..34f1c9ab 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -887,9 +887,11 @@
- The "$vocabulary" keyword is used within meta-schemas to declare - the sets of keywords that schemas described by the meta-schema are - expected to use. + The "$vocabulary" keyword, like all keywords in meta-schemas, + relates to the schema described by the meta-schema, rather than + to the meta-schema itself. Specifically, "$vocabulary" declares + what sets of keywords are expected to be used in schemas described + by this meta-schema. The value of this keyword MUST be an object. The property names in the From c9abdcbe68d24ba6593203e6a426ad3ea95bca04 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 29 Nov 2018 18:34:00 -0800 Subject: [PATCH 11/16] More review feedback on "$vocabulary" --- jsonschema-core.xml | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 34f1c9ab..c687211a 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -790,7 +790,7 @@ A schema that itself describes a schema is called a meta-schema. Meta-schemas are used to validate JSON Schemas and specify which vocabulary - it is using. + they are using. Authors of extensions to JSON Schema are encouraged to write their own @@ -819,7 +819,7 @@ The role of the meta-schema is to constrain the structure of conforming schemas, as well as simplify the process of composing multiple vocabularies into a usable - feature set. Schema authoring is obviously expected to be a common activity, so + feature set. Schema authoring is expected to be a common activity, so schema authors need only understand how to reference a single meta-schema. @@ -880,18 +880,16 @@ Values for this property are defined elsewhere in this and other documents, - and by other parties. JSON Schema implementations SHOULD implement support - for current and previous published drafts of JSON Schema vocabularies - as deemed reasonable. + and by other parties.
- The "$vocabulary" keyword, like all keywords in meta-schemas, - relates to the schema described by the meta-schema, rather than - to the meta-schema itself. Specifically, "$vocabulary" declares + The "$vocabulary" keyword, which appears in a meta-schema, declares what sets of keywords are expected to be used in schemas described - by this meta-schema. + by that meta-schema, and with what semantics. This is conceptually + analogous to how most other keywords used in meta-schemas describe + the syntax of keywords used in schemas described by that meta-schema. The value of this keyword MUST be an object. The property names in the @@ -940,6 +938,14 @@ for use as a meta-schema. This is demonstrated in the example meta-schema. + + If "$vocabulary" is absent, an implementation MAY determine + behavior based on the meta-schema if it is recognized from the + URI value of the referring schema's "$schema" keyword. + If the meta-schema, as referenced by the schema, is not recognized, + then implementations MAY assume the use of all vocabularies in this + specification and the companion Validation specification. +
@@ -993,6 +999,11 @@ restricting usage to a subset of a vocabulary, and for validating locally defined keywords not intended for re-use. + + However, meta-schemas SHOULD NOT contradict any vocabularies that + they declare, such as by requiring a different JSON type than + the vocabulary expects. The resulting behavior is undefined. + Meta-schemas intended for local use, with no need to test for vocabulary support in arbitrary implementations, can safely omit From 28a8d1be4679eebc232b4cc284af0ab527d2ebdb Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 16 Dec 2018 18:09:52 -0800 Subject: [PATCH 12/16] Further $vocabulary wording feedback. --- jsonschema-core.xml | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index c687211a..49f6b219 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -885,7 +885,7 @@
- The "$vocabulary" keyword, which appears in a meta-schema, declares + The "$vocabulary" keyword, which appears in a meta-schema, identifies what sets of keywords are expected to be used in schemas described by that meta-schema, and with what semantics. This is conceptually analogous to how most other keywords used in meta-schemas describe @@ -893,7 +893,11 @@ The value of this keyword MUST be an object. The property names in the - object MUST be URIs, (containing a scheme) and this URI MUST be normalized. + object MUST be URIs (containing a scheme) and this URI MUST be normalized. + Each URI that appears as a property name identifies a specific set of + keywords and their semantics. + + The URI MAY be a URL, but the nature of the retrievable resources is currently undefined, and reserved for future use. Vocabulary authors SHOULD NOT serve a document at that URL. A server MAY respond with @@ -943,7 +947,8 @@ behavior based on the meta-schema if it is recognized from the URI value of the referring schema's "$schema" keyword. If the meta-schema, as referenced by the schema, is not recognized, - then implementations MAY assume the use of all vocabularies in this + then implementations MUST assume the use of the core vocabulary, + and SHOULD assume the use of all vocabularies in this specification and the companion Validation specification.
@@ -1876,6 +1881,10 @@ The current URI for the corresponding meta-schema is: . + + Meta-schemas that do not use "$vocabulary" SHOULD be considered to + use this vocabulary as if its URI were present with a value of false. +
Schema keywords typically operate independently, without From b5290dfe75be800dfeb87086c2b20783f132442c Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 16 Dec 2018 18:12:16 -0800 Subject: [PATCH 13/16] Have the "schema" meta-schema extend core --- core.json | 4 +++- schema.json | 31 ++----------------------------- 2 files changed, 5 insertions(+), 30 deletions(-) diff --git a/core.json b/core.json index e1dec81e..d845b3dd 100644 --- a/core.json +++ b/core.json @@ -26,7 +26,9 @@ "format": "uri-reference" }, "$recursiveAnchor": { - "type": "boolean" + "type": "boolean", + "const": true, + "default": false }, "$vocabulary": { "type": "object", diff --git a/schema.json b/schema.json index 85cbe9b3..281912c6 100644 --- a/schema.json +++ b/schema.json @@ -2,8 +2,9 @@ "$schema": "http://json-schema.org/draft-08/schema#", "$id": "http://json-schema.org/draft-08/schema#", "$recursiveAnchor": true, + "$recursiveRef": "core", - "title": "Core schema meta-schema", + "title": "Core and Validation specifications meta-schema", "$defs": { "schemaArray": { "type": "array", @@ -38,34 +39,6 @@ }, "type": ["object", "boolean"], "properties": { - "$id": { - "type": "string", - "format": "uri-reference" - }, - "$schema": { - "type": "string", - "format": "uri" - }, - "$ref": { - "type": "string", - "format": "uri-reference" - }, - "$recursiveRef": { - "type": "string", - "format": "uri-reference" - }, - "$recursiveAnchor": { - "const": true, - "default": false - }, - "$comment": { - "type": "string" - }, - "$defs": { - "type": "object", - "additionalProperties": { "$recursiveRef": "#" }, - "default": {} - }, "definitions": { "$comment": "While no longer an official keyword as it is replaced by $defs, this keyword is retained in the meta-schema to prevent incompatible extensions as it remains in common use.", "type": "object", From f631c9e1bf842b874edf44c5b530209446d87567 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 16 Dec 2018 18:18:11 -0800 Subject: [PATCH 14/16] Another vocabulary-related wording tweak --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 49f6b219..5a228b2f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1094,7 +1094,7 @@ 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 MUST be referenced through the "allOf" keyword in order + 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. From 3f652a686cad07f7e4529728cefbb7dab263312b Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sun, 16 Dec 2018 18:25:32 -0800 Subject: [PATCH 15/16] Further default vocabulary tweaks Both of these should be considered required, plus remove the wording implying that only the core vocabulary would be in the default "$vocabulary" value. --- jsonschema-core.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 5a228b2f..00a3dc35 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1038,8 +1038,7 @@ Meta-schemas that do not use "$vocabulary" MUST be considered to - require the Core vocabulary just as if "$vocabulary" were used - with only the Core vocabulary present with a value of true. + require the Core vocabulary as if its URI were present with a value of true. The current URI for the Core vocabulary is: @@ -1883,7 +1882,7 @@ Meta-schemas that do not use "$vocabulary" SHOULD be considered to - use this vocabulary as if its URI were present with a value of false. + require this vocabulary as if its URI were present with a value of true.
From 529b5b1bb922a5c8167cc66eb278915d12c2cb7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Gonz=C3=A1lez?= Date: Mon, 17 Dec 2018 18:52:38 -0800 Subject: [PATCH 16/16] Typo fixes from code review Co-Authored-By: handrews --- jsonschema-core.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 00a3dc35..b4e50e9b 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1057,10 +1057,10 @@ 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, "localKeyord", that is not part of either + 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"0. + and the Applicator vocabulary (for "allOf"). ; rel="describedby" When using the media type application/schema+json, the "schema" parameter - MAY be supplied, If supplied, it SHOULD contain the same URI as identified + MAY be supplied. If supplied, it SHOULD contain the same URI as identified by the "$schema" keyword, and MAY contain additional URIs. The "$schema" URI MUST be considered the schema's canonical meta-schema, regardless of the presence of alternative or additional meta-schemas as a media type @@ -2564,7 +2564,7 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 Type name: application Subtype name: schema+json - >Required parameters: N/A + Required parameters: N/A Optional parameters: