Skip to content

Commit 9740818

Browse files
handrewshandrews
committed
Make a Keyword Behavior section
This is purely a reformatting plus the new section tags, no text has been changed. Group the Annotation, Assertion, and Application sections. This new section will get an intro paragraph in the next commit. Arguably, this has overgrown the "Overview" section, but since the "Vocabulary" part of the overview is also about to be expanded, let's wait until then to figure out how to refactor it.
1 parent 3546fa0 commit 9740818

File tree

1 file changed

+82
-80
lines changed

1 file changed

+82
-80
lines changed

‎jsonschema-core.xml

Lines changed: 82 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -123,93 +123,95 @@
123123
data in several ways.
124124
</t>
125125

126-
<section title="Applicators" anchor="applicators">
127-
<t>
128-
Evaluation of an instance against a
129-
<xref target="schema-document">schema document</xref> begins by applying
130-
the <xref target="root">root schema</xref> to the complete instance document.
131-
From there, keywords known as applicators are used to determine which
132-
additional subschemas are applied. Subschema may be applied in-place
133-
to the current location, or to a child location. The subschemas may be all
134-
or part of the keyword's value, or the keyword's value may identify one
135-
or more schemas in a way defined by the keyword.
136-
</t>
137-
<t>
138-
Applicator keywords also define how subschema booolean
139-
<xref target="assertions">assertion</xref>
140-
results are modified and/or combined to produce the boolean result
141-
of the applicator. Applicators may apply any boolean logic operation
142-
to the assertion results of subschemas, but MUST NOT introduce new
143-
assertion conditions of their own.
144-
</t>
145-
<t>
146-
<xref target="annotations">Annotation</xref> results are
147-
combined according to the rules specified by each annotation keyword.
148-
</t>
149-
</section>
126+
<section title="Keyword Behaviors">
127+
<section title="Applicators" anchor="applicators">
128+
<t>
129+
Evaluation of an instance against a
130+
<xref target="schema-document">schema document</xref> begins by applying
131+
the <xref target="root">root schema</xref> to the complete instance
132+
document. From there, keywords known as applicators are used to determine
133+
which additional subschemas are applied. Subschema may be applied in-place
134+
to the current location, or to a child location. The subschemas may be all
135+
or part of the keyword's value, or the keyword's value may identify one
136+
or more schemas in a way defined by the keyword.
137+
</t>
138+
<t>
139+
Applicator keywords also define how subschema booolean
140+
<xref target="assertions">assertion</xref>
141+
results are modified and/or combined to produce the boolean result
142+
of the applicator. Applicators may apply any boolean logic operation
143+
to the assertion results of subschemas, but MUST NOT introduce new
144+
assertion conditions of their own.
145+
</t>
146+
<t>
147+
<xref target="annotations">Annotation</xref> results are
148+
combined according to the rules specified by each annotation keyword.
149+
</t>
150+
</section>
150151

151-
<section title="Assertions" anchor="assertions">
152-
<t>
153-
JSON Schema can be used to assert constraints on a JSON document, which
154-
either passes or fails the assertions. This approach can be used to validate
155-
conformance with the constraints, or document what is needed to satisfy them.
156-
</t>
157-
<t>
158-
JSON Schema implementations produce a single boolean result when evaluating
159-
an instance against schema assertions.
160-
</t>
161-
<t>
162-
An instance can only fail an assertion that is present in the schema.
163-
In some cases, this no-op behavior is identical to a keyword that exists with
164-
certain values, and keyword defintions SHOULD note such values where known.
165-
These default behaviors MUST NOT result in assertion failures.
166-
</t>
167-
<section title="Assertions and Instance Primitive Types">
152+
<section title="Assertions" anchor="assertions">
153+
<t>
154+
JSON Schema can be used to assert constraints on a JSON document, which
155+
either passes or fails the assertions. This approach can be used to validate
156+
conformance with the constraints, or document what is needed to satisfy them.
157+
</t>
168158
<t>
169-
Most assertions only constrain values within a certain
170-
primitive type. When the type of the instance is not of the type
171-
targeted by the keyword, the instance is considered to conform
172-
to the assertion.
159+
JSON Schema implementations produce a single boolean result when evaluating
160+
an instance against schema assertions.
173161
</t>
174162
<t>
175-
For example, the "maxLength" keyword from the companion validation
176-
vocabulary will only restrict certain strings
177-
(that are too long) from being valid. If the instance is a number,
178-
boolean, null, array, or object, then it is valid against this assertion.
163+
An instance can only fail an assertion that is present in the schema.
164+
In some cases, this no-op behavior is identical to a keyword that exists with
165+
certain values, and keyword defintions SHOULD note such values where known.
166+
These default behaviors MUST NOT result in assertion failures.
179167
</t>
168+
<section title="Assertions and Instance Primitive Types">
169+
<t>
170+
Most assertions only constrain values within a certain
171+
primitive type. When the type of the instance is not of the type
172+
targeted by the keyword, the instance is considered to conform
173+
to the assertion.
174+
</t>
175+
<t>
176+
For example, the "maxLength" keyword from the companion validation
177+
vocabulary will only restrict certain strings
178+
(that are too long) from being valid. If the instance is a number,
179+
boolean, null, array, or object, then it is valid against this assertion.
180+
</t>
181+
</section>
180182
</section>
181-
</section>
182183

183-
<section title="Annotations" anchor="annotations">
184-
<t>
185-
JSON Schema can annotate an instance with information, whenever the instance
186-
validates against the schema object containing the annotation, and all of its
187-
parent schema objects. The information can be a simple value, or can be
188-
calculated based on the instance contents.
189-
</t>
190-
<t>
191-
Annotations are attached to specific locations in an instance.
192-
Since many subschemas can be applied to any single
193-
location, annotation keywords need to specify any unusual handling of
194-
multiple applicable occurrences of the keyword with different values.
195-
</t>
196-
<t>
197-
The default behavior is simply to collect all values in a list in
198-
indeterminate order. Given the extensibility of keywords, including
199-
applicators, it is not possible to define a universally predictable
200-
order of processing.
201-
</t>
202-
<t>
203-
Unlike assertion results, annotation data can take a wide variety of forms,
204-
which are provided to applications to use as they see fit. JSON Schema
205-
implementations are not expected to make use of the collected information
206-
on behalf of applications.
207-
</t>
208-
<t>
209-
While "short-circuit" evaluation is possible for assertions, collecting
210-
annotations requires examining all schemas that apply to an instance
211-
location, even if they cannot change the overall assertion result.
212-
</t>
184+
<section title="Annotations" anchor="annotations">
185+
<t>
186+
JSON Schema can annotate an instance with information, whenever the instance
187+
validates against the schema object containing the annotation, and all of its
188+
parent schema objects. The information can be a simple value, or can be
189+
calculated based on the instance contents.
190+
</t>
191+
<t>
192+
Annotations are attached to specific locations in an instance.
193+
Since many subschemas can be applied to any single
194+
location, annotation keywords need to specify any unusual handling of
195+
multiple applicable occurrences of the keyword with different values.
196+
</t>
197+
<t>
198+
The default behavior is simply to collect all values in a list in
199+
indeterminate order. Given the extensibility of keywords, including
200+
applicators, it is not possible to define a universally predictable
201+
order of processing.
202+
</t>
203+
<t>
204+
Unlike assertion results, annotation data can take a wide variety of forms,
205+
which are provided to applications to use as they see fit. JSON Schema
206+
implementations are not expected to make use of the collected information
207+
on behalf of applications.
208+
</t>
209+
<t>
210+
While "short-circuit" evaluation is possible for assertions, collecting
211+
annotations requires examining all schemas that apply to an instance
212+
location, even if they cannot change the overall assertion result.
213+
</t>
214+
</section>
213215
</section>
214216

215217
<section title="Schema Vocabularies" anchor="vocabulary">

0 commit comments

Comments
 (0)