Merge pull request #783 from handrews/defs

Clarify the nature of schema placeholder keywords

Author: handrews

jsonschema-core.xml

@@ -307,7 +307,7 @@
                     <t>
                         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:
                         <list style="hanging">
                             <t hangText="assertions:">
                                 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
                             </t>
+                            <t hangText="reserved locations:">
+                                do not directly affect results, but reserve a place
+                                for a specific purpose to ensure interoperability
+                            </t>
                         </list>
                     </t>
                     <t>
@@ -1004,6 +1008,22 @@
                     </section>
                 </section>
             </section>
+            <section title="Reserved Locations">
+                <t>
+                    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.
+                </t>
+                <t>
+                    While these keywords do not directly affect results, as explained in section
+                    <xref target="non-schemas" format="counter"></xref> unrecognized
+                    extension keywords that reserve locations for re-usable schemas may have
+                    undesirable interactions with references in certain circumstances.
+                </t>
+            </section>
         </section>
         <section title="The JSON Schema Core Vocabulary">
             <t>
@@ -1848,10 +1868,12 @@
                         </t>
                     </section>
 
-                    <section title="References to Possible Non-Schemas">
+                    <section title="References to Possible Non-Schemas" anchor="non-schemas">
                         <t>
                             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
+                            <xref target="defs">"$defs"</xref> 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.
                         </t>
@@ -1973,9 +1995,9 @@
                     </section>
                 </section>
 
-                <section title='Schema Re-Use With "$defs"'>
+                <section title='Schema Re-Use With "$defs"' anchor="defs">
                     <t>
-                        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.
                     </t>
@@ -2010,8 +2032,8 @@
 
             <section title='Comments With "$comment"'>
                 <t>
-                    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

jsonschema-validation.xml

@@ -179,7 +179,8 @@
                 The current URI for the JSON Schema Validation meta-schema is
                 <eref target="http://json-schema.org/draft/2019-08/schema#"/>.
                 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.
                     </t>
                     <t hangText='"allOf", "anyOf", "oneOf", "not", "if", "then", "else",
                                  "items", "additionalItems", "contains", "propertyNames",