Skip to content

Clarify the nature of schema placeholder keywords #783

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 21, 2019
Merged

Clarify the nature of schema placeholder keywords #783

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ec2f8a2
Clarify the nature of schema placeholder keywords
handrews Aug 18, 2019
d4f897b
Further clarification of $defs/definitions
handrews Aug 20, 2019
762bc74
A few more "reserved location" wording tweaks
handrews Aug 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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>
Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here I'd suggest to use the term placeholder keyword at least once, maybe even emphasized. For example:

These placeholder keywords do not affect validation[...]

Then when the term placeholder keyword is used further down below such as in section References to Possible Non-Schemas it is terminologically clear that placeholder keywords is the phrase used to refer to keywords falling into the category of reserved locations.

Overall the recent additions make things much more consistent and comprehensible, I think. 👍

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I'd actually meant to get rid of "placeholder" and use the "location" terminology. I'll sort that out and fix the out-of-order wording, too- thanks!

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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand Down
9 changes: 7 additions & 2 deletions jsonschema-validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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",
Expand Down