From ec2f8a2700b7c9245d76efa3be498c318125125f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 17 Aug 2019 17:04:54 -0700 Subject: [PATCH 1/3] Clarify the nature of schema placeholder keywords Acknowledge that "$defs" and placeholders like it also indicate that their values are schemas, which is relevant to whether they can be detected as a proper "$ref" target or place where "$id" may appear. This ensures that similar extension keywords are understood to have the same concerns as extension applicator keywords. --- jsonschema-core.xml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 9c53b2d9..3044e1b5 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1851,7 +1851,9 @@
Subschema objects (or booleans) are recognized by their use with known - applicator keywords. These keywords may be the standard applicators + applicator keywords, or with placeholder keywords such as + "$defs" that take one or more subschemas + as a value. These keywords may be "$defs" and the standard applicators from this document, or extension keywords from a known vocabulary, or implementation-specific custom keywords. @@ -1973,7 +1975,7 @@
-
+
The "$defs" keyword provides a standardized location for schema authors to inline re-usable JSON Schemas into a more general schema. From d4f897b72fe63e760bd8565d5006af5702d966eb Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 19 Aug 2019 21:19:24 -0700 Subject: [PATCH 2/3] Further clarification of $defs/definitions Introduce the category of reserved location keywords, which are basically just $defs and $comment. This should make it more clear that you can create keywords of your own like this, and fits them more nicely into the overall keyword taxonomy. Part of this change refers to the typical core+validation meta-schema as the "default meta-schema", which is a change made in another PR. --- jsonschema-core.xml | 32 ++++++++++++++++++++++++++------ jsonschema-validation.xml | 9 +++++++-- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 3044e1b5..ef24d479 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -307,7 +307,7 @@ Object properties that are applied to the instance are called keywords, or schema keywords. Broadly speaking, keywords fall into one - of three categories: + of four categories: produce a boolean result when applied to an instance @@ -319,6 +319,10 @@ apply one or more subschemas to a particular location in the instance, and combine or modify their results + + do not directly affect results, but reserve a place + for a specific purpose to ensure interoperability + @@ -1004,6 +1008,22 @@
+
+ + A fourth category of keywords simply reserve a location to hold re-usable + components or data of interest to schema authors that is not suitable + for re-use. These keywords do not affect validation or annotation results. + Their purpose in the core vocabulary is to ensure that locations are + available for certain purposes and will not be redefined by extension + keywords. + + + While these keywords do not directly affect results, as explained in section + unrecognized + extension keywords that reserve locations for re-usable schemas may have + undesirable interactions with references in certain circumstances. + +
@@ -1848,10 +1868,10 @@
-
+
Subschema objects (or booleans) are recognized by their use with known - applicator keywords, or with placeholder keywords such as + applicator keywords or with placeholder keywords such as "$defs" that take one or more subschemas as a value. These keywords may be "$defs" and the standard applicators from this document, or extension keywords from a known vocabulary, or @@ -1977,7 +1997,7 @@
- The "$defs" keyword provides a standardized location for schema + The "$defs" keyword reserves a location for schema authors to inline re-usable JSON Schemas into a more general schema. The keyword does not directly affect the validation result. @@ -2012,8 +2032,8 @@
- This keyword is reserved for comments from schema authors to readers or - maintainers of the schema. + This keyword is reserved a location for comments from schema authors + to readers or maintainers of the schema. The value of this keyword MUST be a string. Implementations MUST NOT present this string to end users. Tools for editing schemas SHOULD support displaying and diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 48babe35..f0881992 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -179,7 +179,8 @@ The current URI for the JSON Schema Validation meta-schema is . For schema author convenience, this meta-schema describes all vocabularies - defined in this specification and the JSON Schema Core specification. + defined in this specification and the JSON Schema Core specification, + as well as two former keywords which are reserved for a transitional period. Individual vocabulary and vocabulary meta-schema URIs are given for each section below. Certain vocabularies are optional to support, which is explained in detail in the relevant sections. @@ -1352,7 +1353,11 @@ Renamed to "$defs" to match "$ref" and be shorter to type. Schema vocabulary authors SHOULD NOT define a "definitions" keyword with different behavior in order to avoid invalidating schemas that - still use the older name. + still use the older name. While "definitions" is absent in the + single-vocabulary meta-schemas referenced by this document, it + remains present in the default meta-schema, and implementations + SHOULD assume that "$defs" and "definitions" have the same + behavior when that meta-schema is used. - This keyword is reserved a location for comments from schema authors + This keyword reserves a location for comments from schema authors to readers or maintainers of the schema. The value of this keyword MUST be a string. Implementations MUST NOT present this