Skip to content

Create an Applicators section, group into a Keyword Behaviors section #595

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 5 commits into from
Jun 21, 2018
Merged

Create an Applicators section, group into a Keyword Behaviors section #595

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3546fa0
Create an Applicators section
handrews May 25, 2018
9740818
Make a Keyword Behavior section
handrews May 26, 2018
18844c1
Add an intro for Keyword Behaviors
handrews May 26, 2018
719629d
Fix some typos
handrews May 26, 2018
e80b135
Explain evaluation, minor wording improvements
handrews Jun 12, 2018
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
156 changes: 96 additions & 60 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,63 +123,109 @@
data in several ways.
</t>

<section title="Assertions">
<section title="Keyword Behaviors">
<t>
JSON Schema can be used to assert constraints on a JSON document, which
either passes or fails the assertions. This approach can be used to validate
conformance with the constraints, or document what is needed to satisfy them.
JSON Schema keywords fall into several general behavior categories.
Assertions validate that an instance satisfies constraints, annotations
Copy link
Member

Choose a reason for hiding this comment

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

I'd break this into three sentences.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

OK. Do you think sentences work well for it, or should I make a little bullet-point list? I've gone back and forth on it.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Updated- I went with sentences for now.

attach information that applications may use in any way they see fit,
and applicators allow for building more complex schemas than a single
Copy link
Member

Choose a reason for hiding this comment

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

Would it be accurate to say something like "Applicators allow a sub-schema to be applied recursively to some part of the instance, or the entire instance." ?
The current description wasn't clear to me.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I don't think so? Applicators are not inherently recursive. I mean, you can do that by using $ref in particular, but just applying properties or items for one level does not fit that description.

"allow for building more complex schemas" is definitely vague, but the rest of the section is supposed to explain it in more detail.

Copy link
Member

Choose a reason for hiding this comment

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

Well maybe not "recursive"

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Throughout these PRs (and earlier changes) I classify applicators as "in-place" or "child" applicators. I would not say "the entire instance" because people will take that to mean the whole instance document, which may be a much larger chunk of JSON than the current location.

Just saying "Applicators allow a sub-schema to be applied to some part of the instance." might be fine, though? We'd just leave the enumeration of the different locations to the more detailed explanation.

schema object would allow.
</t>
<t>
JSON Schema implementations produce a single boolean result when evaluating
an instance against schema assertions.
Extension keywords SHOULD stay within these categories, keeping in mind
that annotations in particular are extremely flexible. Complex behavior
is usually better delegated to applications on the basis of annotation
data than implemented directly as schema keywords. However, extension
keywords MAY define other behaviors for specialized purposes.
</t>
<t>
An instance can only fail an assertion that is present in the schema.
In some cases, this no-op behavior is identical to a keyword that exists with
certain values, and keyword defintions SHOULD note such values where known.
These default behaviors MUST NOT result in assertion failures.
</t>
<section title="Assertions and Instance Primitive Types">
<section title="Applicators" anchor="applicators">
<t>
Most assertions only constrain values within a certain
primitive type. When the type of the instance is not of the type
targeted by the keyword, the instance is considered to conform
to the assertion.
Evaluation of an instance against a
Copy link
Member

Choose a reason for hiding this comment

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

Is there a difference between "evaluation" and "application"?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Hmm... yes that's unclear. There is a difference, I'll add some text in the Keyword Behaviors intro section about it.

<xref target="schema-document">schema document</xref> begins by applying
the <xref target="root">root schema</xref> to the complete instance
document. From there, keywords known as applicators are used to determine
which additional subschemas are applied. Subschema may be applied in-place
to the current location, or to a child location. The subschemas may be all
or part of the keyword's value, or the keyword's value may identify one
or more schemas in a way defined by the keyword.
</t>
<t>
For example, the "maxLength" keyword from the companion validation
vocabulary will only restrict certain strings
(that are too long) from being valid. If the instance is a number,
boolean, null, array, or object, then it is valid against this assertion.
Applicator keywords also define how subschema boolean
<xref target="assertions">assertion</xref>
results are modified and/or combined to produce the boolean result
of the applicator. Applicators may apply any boolean logic operation
to the assertion results of subschemas, but MUST NOT introduce new
assertion conditions of their own.
</t>
<t>
<xref target="annotations">Annotation</xref> results are
combined according to the rules specified by each annotation keyword.
</t>
</section>
</section>

<section title="Annotations" anchor="annotations">
<t>
JSON Schema can annotate an instance with information, whenever the instance
validates against the schema object containing the annotation, and all of its
parent schema objects. The information can be a simple value, or can be
calculated based on the instance contents.
</t>
<t>
Annotations are attached to specific locations in an instance.
Since many subschemas can be applied to any single
location, annotation keywords need to specify any unusual handling of
multiple applicable occurrences of the keyword with different values.
The default behavior is simply to collect all values.
</t>
<t>
Unlike assertion results, annotation data can take a wide variety of forms,
which are provided to applications to use as they see fit. JSON Schema
implementations are not expected to make use of the collected information
on behalf of applications.
</t>
<t>
While "short-circuit" evaluation is possible for assertions, collecting
annotations requires examining all schemas that apply to an instance
location, even if they cannot change the overall assertion result.
</t>
<section title="Assertions" anchor="assertions">
<t>
JSON Schema can be used to assert constraints on a JSON document, which
either passes or fails the assertions. This approach can be used to validate
conformance with the constraints, or document what is needed to satisfy them.
</t>
<t>
JSON Schema implementations produce a single boolean result when evaluating
an instance against schema assertions.
</t>
<t>
An instance can only fail an assertion that is present in the schema.
In some cases, this no-op behavior is identical to a keyword that exists with
certain values, and keyword definitions SHOULD note such values where known.
These default behaviors MUST NOT result in assertion failures.
</t>
<section title="Assertions and Instance Primitive Types">
<t>
Most assertions only constrain values within a certain
primitive type. When the type of the instance is not of the type
targeted by the keyword, the instance is considered to conform
to the assertion.
</t>
<t>
For example, the "maxLength" keyword from the companion validation
vocabulary will only restrict certain strings
(that are too long) from being valid. If the instance is a number,
boolean, null, array, or object, then it is valid against this assertion.
</t>
</section>
</section>

<section title="Annotations" anchor="annotations">
<t>
JSON Schema can annotate an instance with information, whenever the instance
validates against the schema object containing the annotation, and all of its
parent schema objects. The information can be a simple value, or can be
calculated based on the instance contents.
</t>
<t>
Annotations are attached to specific locations in an instance.
Since many subschemas can be applied to any single
location, annotation keywords need to specify any unusual handling of
multiple applicable occurrences of the keyword with different values.
</t>
<t>
The default behavior is simply to collect all values in a list in
indeterminate order. Given the extensibility of keywords, including
applicators, it is not possible to define a universally predictable
order of processing.
</t>
<t>
Unlike assertion results, annotation data can take a wide variety of forms,
which are provided to applications to use as they see fit. JSON Schema
implementations are not expected to make use of the collected information
on behalf of applications.
</t>
<t>
While "short-circuit" evaluation is possible for assertions, collecting
annotations requires examining all schemas that apply to an instance
location, even if they cannot change the overall assertion result.
</t>
</section>
</section>

<section title="Schema Vocabularies" anchor="vocabulary">
Expand Down Expand Up @@ -363,7 +409,7 @@
</section>
</section>

<section title="JSON Schema Documents">
<section title="JSON Schema Documents" anchor="schema-document">
<t>
A JSON Schema document, or simply a schema, is a JSON document used to describe
an instance.
Expand Down Expand Up @@ -439,7 +485,7 @@
and implementations.
</t>
</section>
<section title="Root Schema and Subschemas">
<section title="Root Schema and Subschemas" anchor="root">
<t>
The root schema is the schema that comprises the entire JSON document
in question.
Expand Down Expand Up @@ -973,17 +1019,7 @@

<section title="A Vocabulary for Applying Subschemas">
<t>
Evaluation of an instance against a schema begins by applying the root schema
to the complete instance document. From there, various keywords are used
to determine which additional subschemas are applied to either the current
location, or a child location. These keywords also define how subschema
assertion results are modified and/or combined. Annotation results are
combined according to the rules specified by each annotation keyword.
</t>
<t>
Keyword that apply subschemas are called applicators, and do not assert
conditions on their own. Rather, they control how assertions are applied
and evaluated. This section defines a set of applicator keywords that
This section defines a vocabulary of applicator keywords that
are RECOMMENDED for use as the basis of other vocabularies.
</t>
<section title="Keyword Independence">
Expand Down