diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 9c53b2d9..2d91ffe6 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,12 @@
-
+
Subschema objects (or booleans) are recognized by their use with known - applicator keywords. These keywords may be the standard applicators + applicator keywords or with location-reserving 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,9 +1995,9 @@
-
+
- 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. @@ -2010,8 +2032,8 @@
- This keyword is reserved for comments from schema authors to readers or - maintainers of the schema. + 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 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.