Skip to content

Commit d4f897b

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 ec2f8a2 commit d4f897b

File tree

2 files changed

+33
-8
lines changed

2 files changed

+33
-8
lines changed

jsonschema-core.xml

Lines changed: 26 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,10 @@
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
325+
</t>
322326
</list>
323327
</t>
324328
<t>
@@ -1004,6 +1008,22 @@
10041008
</section>
10051009
</section>
10061010
</section>
1011+
<section title="Reserved Locations">
1012+
<t>
1013+
A fourth category of keywords simply reserve a location to hold re-usable
1014+
components or data of interest to schema authors that is not suitable
1015+
for re-use. These keywords do not affect validation or annotation results.
1016+
Their purpose in the core vocabulary is to ensure that locations are
1017+
available for certain purposes and will not be redefined by extension
1018+
keywords.
1019+
</t>
1020+
<t>
1021+
While these keywords do not directly affect results, as explained in section
1022+
<xref target="non-schemas" format="counter"></xref> unrecognized
1023+
extension keywords that reserve locations for re-usable schemas may have
1024+
undesirable interactions with references in certain circumstances.
1025+
</t>
1026+
</section>
10071027
</section>
10081028
<section title="The JSON Schema Core Vocabulary">
10091029
<t>
@@ -1848,10 +1868,10 @@
18481868
</t>
18491869
</section>
18501870

1851-
<section title="References to Possible Non-Schemas">
1871+
<section title="References to Possible Non-Schemas" anchor="non-schemas">
18521872
<t>
18531873
Subschema objects (or booleans) are recognized by their use with known
1854-
applicator keywords, or with placeholder keywords such as
1874+
applicator keywords or with placeholder keywords such as
18551875
<xref target="defs">"$defs"</xref> that take one or more subschemas
18561876
as a value. These keywords may be "$defs" and the standard applicators
18571877
from this document, or extension keywords from a known vocabulary, or
@@ -1977,7 +1997,7 @@
19771997

19781998
<section title='Schema Re-Use With "$defs"' anchor="defs">
19791999
<t>
1980-
The "$defs" keyword provides a standardized location for schema
2000+
The "$defs" keyword reserves a location for schema
19812001
authors to inline re-usable JSON Schemas into a more general schema.
19822002
The keyword does not directly affect the validation result.
19832003
</t>
@@ -2012,8 +2032,8 @@
20122032

20132033
<section title='Comments With "$comment"'>
20142034
<t>
2015-
This keyword is reserved for comments from schema authors to readers or
2016-
maintainers of the schema.
2035+
This keyword is reserved a location for comments from schema authors
2036+
to readers or maintainers of the schema.
20172037

20182038
The value of this keyword MUST be a string. Implementations MUST NOT present this
20192039
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)