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.
+
+
-
+
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.