Skip to content

Commit 287093b

Browse files
committed
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.
1 parent a9d154c commit 287093b

File tree

2 files changed

+32
-8
lines changed

2 files changed

+32
-8
lines changed

jsonschema-core.xml

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,7 @@
307307
<t>
308308
Object properties that are applied to the instance are called keywords,
309309
or schema keywords. Broadly speaking, keywords fall into one
310-
of three categories:
310+
of four categories:
311311
<list style="hanging">
312312
<t hangText="assertions:">
313313
produce a boolean result when applied to an instance
@@ -319,6 +319,9 @@
319319
apply one or more subschemas to a particular location
320320
in the instance, and combine or modify their results
321321
</t>
322+
<t hangText="reserved locations:">
323+
do not directly affect results, but reserve a place
324+
for a specific purpose to ensure interoperability
322325
</list>
323326
</t>
324327
<t>
@@ -1004,6 +1007,22 @@
10041007
</section>
10051008
</section>
10061009
</section>
1010+
<section title="Reserved Locations">
1011+
<t>
1012+
A fourth category of keywords simply reserve a location to hold re-usable
1013+
components or data of interest to schema authors that is not suitable
1014+
for re-use. These keywords do not affect validation or annotation results.
1015+
Their purpose in the core vocabulary is to ensure that locations are
1016+
available for certain purposes and will not be redefined by extension
1017+
keywords.
1018+
</t>
1019+
<t>
1020+
While these keywords do not directly affect results, as explained in section
1021+
<xref target="non-schemas" format="counter"></xref> unrecognized
1022+
extension keywords that reserve locations for re-usable schemas may have
1023+
undesirable interactions with references in certain circumstances.
1024+
</t>
1025+
</section>
10071026
</section>
10081027
<section title="The JSON Schema Core Vocabulary">
10091028
<t>
@@ -1786,10 +1805,10 @@
17861805
</t>
17871806
</section>
17881807

1789-
<section title="References to Possible Non-Schemas">
1808+
<section title="References to Possible Non-Schemas" anchor="non-schemas">
17901809
<t>
17911810
Subschema objects (or booleans) are recognized by their use with known
1792-
applicator keywords, or with placeholder keywords such as
1811+
applicator keywords or with placeholder keywords such as
17931812
<xref target="defs">"$defs"</xref> that take one or more subschemas
17941813
as a value. These keywords may be "$defs" and the standard applicators
17951814
from this document, or extension keywords from a known vocabulary, or
@@ -1915,7 +1934,7 @@
19151934

19161935
<section title='Schema Re-Use With "$defs"' anchor="defs">
19171936
<t>
1918-
The "$defs" keyword provides a standardized location for schema
1937+
The "$defs" keyword reserves a location for schema
19191938
authors to inline re-usable JSON Schemas into a more general schema.
19201939
The keyword does not directly affect the validation result.
19211940
</t>
@@ -1950,8 +1969,8 @@
19501969

19511970
<section title='Comments With "$comment"'>
19521971
<t>
1953-
This keyword is reserved for comments from schema authors to readers or
1954-
maintainers of the schema.
1972+
This keyword is reserved a location for comments from schema authors
1973+
to readers or maintainers of the schema.
19551974

19561975
The value of this keyword MUST be a string. Implementations MUST NOT present this
19571976
string to end users. Tools for editing schemas SHOULD support displaying and

jsonschema-validation.xml

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,8 @@
179179
The current URI for the JSON Schema Validation meta-schema is
180180
<eref target="http://json-schema.org/draft/2019-08/schema#"/>.
181181
For schema author convenience, this meta-schema describes all vocabularies
182-
defined in this specification and the JSON Schema Core specification.
182+
defined in this specification and the JSON Schema Core specification,
183+
as well as two former keywords which are reserved for a transitional period.
183184
Individual vocabulary and vocabulary meta-schema URIs are given for
184185
each section below. Certain vocabularies are optional to support, which
185186
is explained in detail in the relevant sections.
@@ -1352,7 +1353,11 @@
13521353
Renamed to "$defs" to match "$ref" and be shorter to type.
13531354
Schema vocabulary authors SHOULD NOT define a "definitions" keyword
13541355
with different behavior in order to avoid invalidating schemas that
1355-
still use the older name.
1356+
still use the older name. While "definitions" is absent in the
1357+
single-vocabulary meta-schemas referenced by this document, it
1358+
remains present in the default meta-schema, and implementations
1359+
SHOULD assume that "$defs" and "definitions" have the same
1360+
behavior when that meta-schema is used.
13561361
</t>
13571362
<t hangText='"allOf", "anyOf", "oneOf", "not", "if", "then", "else",
13581363
"items", "additionalItems", "contains", "propertyNames",

0 commit comments

Comments
 (0)