Skip to content

Commit

Permalink
Merge pull request #595 from handrews/applicator
Browse files Browse the repository at this point in the history 
Create an Applicators section, group into a Keyword Behaviors section
  • Loading branch information
@handrews
handrews authored Jun 21, 2018
2 parents 5b51942 + e80b135 commit bc84825
Showing 1 changed file with 109 additions and 58 deletions.
167 changes: 109 additions & 58 deletions jsonschema-core.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,63 +122,124 @@
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
attach information that applications may use in any way they see fit.
Applicators apply subschemas to parts of the instance and combine
their results.
</t>
<t>
JSON Schema implementations produce a single boolean result when evaluating
an instance against schema assertions.
Evaluating an instance against a schema involves processing all of the
keywords in the schema against the appropriate locations within the instance.
Typically, applicator keywords are processed until a schema object with no
applicators (and therefore no subschemas) is reached. The appropriate
location in the instance is evaluated against the assertion and
annotation keywords in the schema object, and their results are gathered
into the parent schema according to the rules of the applicator.
</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.
Evaluation of a parent schema object can complete once all of its
subschemas have been evaluated, although in some circumstance evaluation
may be short-circuited due to assertion results.
</t>
<section title="Assertions and Instance Primitive Types">
<t>
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>
<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.
Applicators allow for building more complex schemas than can be accomplished
with a single schema object. Evaluation of an instance against a
<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 @@ -362,7 +423,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 @@ -438,7 +499,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 @@ -1005,17 +1066,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

0 comments on commit bc84825

Please sign in to comment.