Skip to content
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

Specify a naming scheme for non-assertion keywords #1399

Closed
wants to merge 1 commit into from
Closed

Specify a naming scheme for non-assertion keywords #1399

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
69 changes: 48 additions & 21 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,43 +313,70 @@
</t>
<section title="JSON Schema Objects and Keywords">
<t>
Object properties that are applied to the instance are called keywords,
or schema keywords. Broadly speaking, keywords fall into one
of five categories:
Object properties that are applied to the instance are called keywords, or schema keywords.
Two properties in the same schema object are referred to as adjacent keywords.
As an authoring convenience, adjacent keywords can sometimes affect each other in a way that a property from a different schema (including sub-schemas) cannot.
Copy link
Member

Choose a reason for hiding this comment

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

Is this an authoring convenience?

Can a keyword from a different schema affect a keyword locally (excluding keywords that explicitly do this like unevaluated*)?

Does this statement add value?

</t>
<t>
Keywords are classified into one or more of six categories:
</t>
<dl>
<dt>identifiers</dt>
<dt>Core keywords</dt>
<dd>
Keywords that may configure how the schema is processed,
and can modify the meaning of other keywords in the schema.
Copy link
Member

Choose a reason for hiding this comment

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

What kind of core keyword can modify the meaning of another keyword?

There's maybe $vocabulary, but this defines what the keywords mean; it doesn't modify them.

</dd>
<dt>Assertion keywords</dt>
<dd>
control schema identification through setting a IRI
for the schema and/or changing how the base IRI is determined
Keywords that may decide an instance is invalid.
</dd>
<dt>assertions</dt>
<dt>Annotation keywords</dt>
<dd>
produce a boolean result when applied to an instance
Keywords that produce output generated from an instance.
</dd>
<dt>annotations</dt>
<dt>Applicator keywords</dt>
<dd>
attach information to an instance for application use
A keyword that has one or more subschemas,
that are applied against the instance,
or some value within the instance,
and logically aggregated together.
</dd>
<dt>applicators</dt>
<dt>Reserved keywords</dt>
<dd>
apply one or more subschemas to a particular location
in the instance, and combine or modify their results
Keywords that are permitted in a schema,
but that do not do anything by themselves,
though their value may be read by or referred to by another keyword.
Comment on lines +344 to +348
Copy link
Member

Choose a reason for hiding this comment

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

Do you have an example of a "reserved" keyword? What would the purpose of this be?

</dd>
<dt>reserved locations</dt>
<dt>Arguments</dt>
<dd>
do not directly affect results, but reserve a place
for a specific purpose to ensure interoperability
Arguments are properties in a schema that are used by an adjacent keyword,
and whose meaning may only be defined in the presence of that keyword.
Comment on lines +350 to +353
Copy link
Member

Choose a reason for hiding this comment

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

I assume these are keywords like minContains which affect contains but do nothing else.

</dd>
</dl>
<t>
Keywords may fall into multiple categories, although applicators
SHOULD only produce assertion results based on their subschemas'
results. They should not define additional constraints independent
of their subschemas.
Some properties may be classified into multiple categories.
Some keywords are also arguments to other keywords,
and applicator keywords are both assertions and annotations.
Copy link
Member

Choose a reason for hiding this comment

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

Applicator keywords may be assertive and annotative, but not necessarily so. anyOf isn't annotative. Its subschemas produce annotations, but the keyword itself does not.

</t>
<t>
Keywords which are properties within the same schema object are referred to as adjacent keywords.
The categories that a keyword belongs to is defined per keyword.
Additionally, there are naming conventions that impose limits or requirements on the categories that keywords belong to:
</t>
<ul>
<li>
A keyword that begins with "annotation-" is never a core keyword or assertion keyword, but may be an annotation or reserved keyword. These keywords MUST NOT affect a validation result.
Copy link
Member

Choose a reason for hiding this comment

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

I agree with @jdesrosiers that this needs to align with the x- decision that we've already made.

<cref>
This naming is subject to change.
</cref>
</li>
<li>
A keyword that begins with "$" is a core keyword, unless defined otherwise.
(For example, "$comment" behaves as a reserved keyword.)
Comment on lines +373 to +374
Copy link
Member

Choose a reason for hiding this comment

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

See #1388

</li>
</ul>
<t>
If a validator encounters a keyword whose assertion behavior is unknown (a keyword besides an "annotation-" keyword),
then attempting to compute the validation result SHOULD raise an error.
Comment on lines +378 to +379
Copy link
Member

Choose a reason for hiding this comment

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

Instead of "raise an error", would it be better to say the result is "indeterminate"? (Has the "indeterminate" concept made it into the spec yet? It might need to be defined.) I often use "raise an error" as shorthand, but not all languages have a concept of raising an error and even then, it's not required that they use that mechanism to report the indeterminate result. But, I'm probably being overly pedantic.

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, that's more specific too.

Copy link
Member

Choose a reason for hiding this comment

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

What does "attempting to compute the validation result" mean? Does it mean "it is incorrect for the evaluator to compute a validation result from this keyword"?

</t>
<t>
Extension keywords, meaning those defined outside of this document
Expand Down