Skip to content

Commit bc84825

Browse files
handrewshandrews
authored
Merge pull request #595 from handrews/applicator
Create an Applicators section, group into a Keyword Behaviors section
2 parents 5b51942 + e80b135 commit bc84825

File tree

1 file changed

+109
-58
lines changed

1 file changed

+109
-58
lines changed

Diff for: ‎jsonschema-core.xml

+109-58
Original file line numberDiff line numberDiff line change
@@ -122,63 +122,124 @@
122122
data in several ways.
123123
</t>
124124

125-
<section title="Assertions">
125+
<section title="Keyword Behaviors">
126126
<t>
127-
JSON Schema can be used to assert constraints on a JSON document, which
128-
either passes or fails the assertions. This approach can be used to validate
129-
conformance with the constraints, or document what is needed to satisfy them.
127+
JSON Schema keywords fall into several general behavior categories.
128+
Assertions validate that an instance satisfies constraints. Annotations
129+
attach information that applications may use in any way they see fit.
130+
Applicators apply subschemas to parts of the instance and combine
131+
their results.
130132
</t>
131133
<t>
132-
JSON Schema implementations produce a single boolean result when evaluating
133-
an instance against schema assertions.
134+
Evaluating an instance against a schema involves processing all of the
135+
keywords in the schema against the appropriate locations within the instance.
136+
Typically, applicator keywords are processed until a schema object with no
137+
applicators (and therefore no subschemas) is reached. The appropriate
138+
location in the instance is evaluated against the assertion and
139+
annotation keywords in the schema object, and their results are gathered
140+
into the parent schema according to the rules of the applicator.
134141
</t>
135142
<t>
136-
An instance can only fail an assertion that is present in the schema.
137-
In some cases, this no-op behavior is identical to a keyword that exists with
138-
certain values, and keyword defintions SHOULD note such values where known.
139-
These default behaviors MUST NOT result in assertion failures.
143+
Evaluation of a parent schema object can complete once all of its
144+
subschemas have been evaluated, although in some circumstance evaluation
145+
may be short-circuited due to assertion results.
140146
</t>
141-
<section title="Assertions and Instance Primitive Types">
147+
<t>
148+
Extension keywords SHOULD stay within these categories, keeping in mind
149+
that annotations in particular are extremely flexible. Complex behavior
150+
is usually better delegated to applications on the basis of annotation
151+
data than implemented directly as schema keywords. However, extension
152+
keywords MAY define other behaviors for specialized purposes.
153+
</t>
154+
<section title="Applicators" anchor="applicators">
142155
<t>
143-
Most assertions only constrain values within a certain
144-
primitive type. When the type of the instance is not of the type
145-
targeted by the keyword, the instance is considered to conform
146-
to the assertion.
156+
Applicators allow for building more complex schemas than can be accomplished
157+
with a single schema object. Evaluation of an instance against a
158+
<xref target="schema-document">schema document</xref> begins by applying
159+
the <xref target="root">root schema</xref> to the complete instance
160+
document. From there, keywords known as applicators are used to determine
161+
which additional subschemas are applied. Subschema may be applied in-place
162+
to the current location, or to a child location. The subschemas may be all
163+
or part of the keyword's value, or the keyword's value may identify one
164+
or more schemas in a way defined by the keyword.
147165
</t>
148166
<t>
149-
For example, the "maxLength" keyword from the companion validation
150-
vocabulary will only restrict certain strings
151-
(that are too long) from being valid. If the instance is a number,
152-
boolean, null, array, or object, then it is valid against this assertion.
167+
Applicator keywords also define how subschema boolean
168+
<xref target="assertions">assertion</xref>
169+
results are modified and/or combined to produce the boolean result
170+
of the applicator. Applicators may apply any boolean logic operation
171+
to the assertion results of subschemas, but MUST NOT introduce new
172+
assertion conditions of their own.
173+
</t>
174+
<t>
175+
<xref target="annotations">Annotation</xref> results are
176+
combined according to the rules specified by each annotation keyword.
153177
</t>
154178
</section>
155-
</section>
156179

157-
<section title="Annotations" anchor="annotations">
158-
<t>
159-
JSON Schema can annotate an instance with information, whenever the instance
160-
validates against the schema object containing the annotation, and all of its
161-
parent schema objects. The information can be a simple value, or can be
162-
calculated based on the instance contents.
163-
</t>
164-
<t>
165-
Annotations are attached to specific locations in an instance.
166-
Since many subschemas can be applied to any single
167-
location, annotation keywords need to specify any unusual handling of
168-
multiple applicable occurrences of the keyword with different values.
169-
The default behavior is simply to collect all values.
170-
</t>
171-
<t>
172-
Unlike assertion results, annotation data can take a wide variety of forms,
173-
which are provided to applications to use as they see fit. JSON Schema
174-
implementations are not expected to make use of the collected information
175-
on behalf of applications.
176-
</t>
177-
<t>
178-
While "short-circuit" evaluation is possible for assertions, collecting
179-
annotations requires examining all schemas that apply to an instance
180-
location, even if they cannot change the overall assertion result.
181-
</t>
180+
<section title="Assertions" anchor="assertions">
181+
<t>
182+
JSON Schema can be used to assert constraints on a JSON document, which
183+
either passes or fails the assertions. This approach can be used to validate
184+
conformance with the constraints, or document what is needed to satisfy them.
185+
</t>
186+
<t>
187+
JSON Schema implementations produce a single boolean result when evaluating
188+
an instance against schema assertions.
189+
</t>
190+
<t>
191+
An instance can only fail an assertion that is present in the schema.
192+
In some cases, this no-op behavior is identical to a keyword that exists with
193+
certain values, and keyword definitions SHOULD note such values where known.
194+
These default behaviors MUST NOT result in assertion failures.
195+
</t>
196+
<section title="Assertions and Instance Primitive Types">
197+
<t>
198+
Most assertions only constrain values within a certain
199+
primitive type. When the type of the instance is not of the type
200+
targeted by the keyword, the instance is considered to conform
201+
to the assertion.
202+
</t>
203+
<t>
204+
For example, the "maxLength" keyword from the companion validation
205+
vocabulary will only restrict certain strings
206+
(that are too long) from being valid. If the instance is a number,
207+
boolean, null, array, or object, then it is valid against this assertion.
208+
</t>
209+
</section>
210+
</section>
211+
212+
<section title="Annotations" anchor="annotations">
213+
<t>
214+
JSON Schema can annotate an instance with information, whenever the instance
215+
validates against the schema object containing the annotation, and all of its
216+
parent schema objects. The information can be a simple value, or can be
217+
calculated based on the instance contents.
218+
</t>
219+
<t>
220+
Annotations are attached to specific locations in an instance.
221+
Since many subschemas can be applied to any single
222+
location, annotation keywords need to specify any unusual handling of
223+
multiple applicable occurrences of the keyword with different values.
224+
</t>
225+
<t>
226+
The default behavior is simply to collect all values in a list in
227+
indeterminate order. Given the extensibility of keywords, including
228+
applicators, it is not possible to define a universally predictable
229+
order of processing.
230+
</t>
231+
<t>
232+
Unlike assertion results, annotation data can take a wide variety of forms,
233+
which are provided to applications to use as they see fit. JSON Schema
234+
implementations are not expected to make use of the collected information
235+
on behalf of applications.
236+
</t>
237+
<t>
238+
While "short-circuit" evaluation is possible for assertions, collecting
239+
annotations requires examining all schemas that apply to an instance
240+
location, even if they cannot change the overall assertion result.
241+
</t>
242+
</section>
182243
</section>
183244

184245
<section title="Schema Vocabularies" anchor="vocabulary">
@@ -362,7 +423,7 @@
362423
</section>
363424
</section>
364425

365-
<section title="JSON Schema Documents">
426+
<section title="JSON Schema Documents" anchor="schema-document">
366427
<t>
367428
A JSON Schema document, or simply a schema, is a JSON document used to describe
368429
an instance.
@@ -438,7 +499,7 @@
438499
and implementations.
439500
</t>
440501
</section>
441-
<section title="Root Schema and Subschemas">
502+
<section title="Root Schema and Subschemas" anchor="root">
442503
<t>
443504
The root schema is the schema that comprises the entire JSON document
444505
in question.
@@ -1005,17 +1066,7 @@
10051066

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

0 commit comments

Comments
 (0)