Skip to content

Commit 09790c7

Browse files
handrewshandrews
authored
Merge pull request #600 from handrews/annot-results
Keywords can depend on subschema or adjacent keyword annotation results
2 parents bc84825 + bc2a042 commit 09790c7

File tree

1 file changed

+128
-43
lines changed

1 file changed

+128
-43
lines changed

‎jsonschema-core.xml

+128-43
Original file line numberDiff line numberDiff line change
@@ -125,8 +125,9 @@
125125
<section title="Keyword Behaviors">
126126
<t>
127127
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.
128+
Assertions validate that an instance satisfies constraints, producing
129+
a boolean result. Annotations attach information that applications
130+
may use in any way they see fit.
130131
Applicators apply subschemas to parts of the instance and combine
131132
their results.
132133
</t>
@@ -144,6 +145,41 @@
144145
subschemas have been evaluated, although in some circumstance evaluation
145146
may be short-circuited due to assertion results.
146147
</t>
148+
<t>
149+
Keyword behavior MAY be defined in terms of the annotation results
150+
of <xref target="root">subschemas</xref> and/or adjacent keywords.
151+
Such keywords MUST NOT result in a circular dependency.
152+
Keywords MAY modify their behavior based on the presence or absence
153+
of another keyword in the same
154+
<xref target="schema-document">schema object</xref>.
155+
</t>
156+
<t>
157+
A missing keyword MUST NOT produce a false assertion result, MUST
158+
NOT produce annotation results, and MUST NOT cause any other schema
159+
to be evaluated as part of its own behavioral definition.
160+
However, given that missing keywords do not contribute annotations,
161+
the lack of annotation results may indirectly change the behavior
162+
of other keywords.
163+
</t>
164+
<t>
165+
In some cases, the missing keyword assertion behavior of a keyword is
166+
identical to that produced by a certain value, and keyword definitions
167+
SHOULD note such values where known. However, even if the value which
168+
produces the default behavior would produce annotation results if
169+
present, the default behavior still MUST NOT result in annotations.
170+
</t>
171+
<t>
172+
Because annotation collection can add significant cost in terms of both
173+
computation and memory, implementations MAY opt out of this feature.
174+
Keywords known to an implementation to have assertion or applicator behavior
175+
that depend on annotation results MUST then be treated as errors, unless
176+
an alternate implementation producing the same behavior is available.
177+
Keywords of this sort SHOULD describe reasonable alternate approaches
178+
when appropriate. This approach is demonstrated by the
179+
"<xref target="additionalItems" format="title"/>" and
180+
"<xref target="additionalProperties" format="title"/>" keywords in this
181+
document.
182+
</t>
147183
<t>
148184
Extension keywords SHOULD stay within these categories, keeping in mind
149185
that annotations in particular are extremely flexible. Complex behavior
@@ -189,9 +225,7 @@
189225
</t>
190226
<t>
191227
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.
228+
195229
</t>
196230
<section title="Assertions and Instance Primitive Types">
197231
<t>
@@ -1243,12 +1277,8 @@
12431277
<section title="Keywords for Applying Subschemas to Arrays">
12441278
<section title="items">
12451279
<t>
1246-
The value of "items" MUST be either a valid JSON Schema or an array of valid
1247-
JSON Schemas.
1248-
</t>
1249-
<t>
1250-
This keyword determines how child instances validate for arrays,
1251-
and does not directly validate the immediate instance itself.
1280+
The value of "items" MUST be either a valid JSON Schema or
1281+
an array of valid JSON Schemas.
12521282
</t>
12531283
<t>
12541284
If "items" is a schema, validation succeeds if all elements
@@ -1260,30 +1290,56 @@
12601290
same position, if any.
12611291
</t>
12621292
<t>
1263-
Omitting this keyword has the same behavior as an empty schema.
1293+
This keyword produces an annotation value which is the largest
1294+
index to which this keyword applied a subschema. The value
1295+
MAY be a boolean true if a subschema was applied to every
1296+
index of the instance, such as when "items" is a schema.
1297+
</t>
1298+
<t>
1299+
Annotation results for "items" keywords from multiple
1300+
schemas applied to the same instance location are combined
1301+
by setting the combined result to true if any of the values
1302+
are true, and otherwise retaining the largest numerical value.
1303+
</t>
1304+
<t>
1305+
Omitting this keyword has the same assertion behavior as
1306+
an empty schema.
12641307
</t>
12651308
</section>
12661309

1267-
<section title="additionalItems">
1310+
<section title="additionalItems" anchor="additionalItems">
12681311
<t>
12691312
The value of "additionalItems" MUST be a valid JSON Schema.
12701313
</t>
12711314
<t>
1272-
This keyword determines how child instances validate for arrays,
1273-
and does not directly validate the immediate instance itself.
1315+
The behavior of this keyword depends on the presence and
1316+
annotation result of "items" within the same schema object.
1317+
If "items" is present, and its annotation result is a number,
1318+
validation succeeds if every instance element at an index
1319+
greater than that number validates against "additionalItems".
12741320
</t>
12751321
<t>
1276-
If "items" is an array of schemas, validation succeeds
1277-
if every instance element at a position greater than the size
1278-
of "items" validates against "additionalItems".
1322+
Otherwise, if "items" is absent or its annotation result
1323+
is the boolean true, "additionalItems" MUST be ignored.
12791324
</t>
12801325
<t>
1281-
Otherwise, "additionalItems" MUST be ignored, as the "items"
1282-
schema (possibly the default value of an empty schema) is
1283-
applied to all elements.
1326+
If the "additionalItems" subschema is applied to any
1327+
positions within the instance array, it produces an
1328+
annotation result of boolean true, analogous to the
1329+
single schema behavior of "items". If any "additionalItems"
1330+
keyword from any subschema applied to the same instance
1331+
location produces an annotation value of true, then
1332+
the combined result from these keywords is also true.
12841333
</t>
12851334
<t>
1286-
Omitting this keyword has the same behavior as an empty schema.
1335+
Omitting this keyword has the same assertion behavior as
1336+
an empty schema.
1337+
</t>
1338+
<t>
1339+
Implementations MAY choose to implement or optimize this keyword
1340+
in another way that produces the same effect, such as by directly
1341+
checking for the presence and size of an "items" array.
1342+
Implementations that do not support annotation collection MUST do so.
12871343
</t>
12881344
</section>
12891345

@@ -1293,7 +1349,16 @@
12931349
</t>
12941350
<t>
12951351
An array instance is valid against "contains" if at least one of
1296-
its elements is valid against the given schema.
1352+
its elements is valid against the given schema. This keyword
1353+
does not produce annotation results.
1354+
<cref>
1355+
Should it produce a set of the indices for which the
1356+
array element is valid against the subschema? "contains"
1357+
does not affect "additionalItems" or any other current
1358+
or proposed keyword, but the information could be useful,
1359+
and implementation that collect annotations need to
1360+
apply "contains" to every element anyway.
1361+
</cref>
12971362
</t>
12981363
</section>
12991364
</section>
@@ -1304,18 +1369,22 @@
13041369
The value of "properties" MUST be an object.
13051370
Each value of this object MUST be a valid JSON Schema.
13061371
</t>
1307-
<t>
1308-
This keyword determines how child instances validate for objects,
1309-
and does not directly validate the immediate instance itself.
1310-
</t>
13111372
<t>
13121373
Validation succeeds if, for each name that appears in both
13131374
the instance and as a name within this keyword's value, the child
13141375
instance for that name successfully validates against the
13151376
corresponding schema.
13161377
</t>
13171378
<t>
1318-
Omitting this keyword has the same behavior as an empty object.
1379+
The annotation result of this keyword is the set of instance
1380+
property names matched by this keyword. Annotation results
1381+
for "properties" keywords from multiple schemas applied to
1382+
the same instance location are combined by taking the union
1383+
of the sets.
1384+
</t>
1385+
<t>
1386+
Omitting this keyword has the same assertion behavior as
1387+
an empty object.
13191388
</t>
13201389
</section>
13211390

@@ -1326,42 +1395,58 @@
13261395
ECMA 262 regular expression dialect. Each property value of this object
13271396
MUST be a valid JSON Schema.
13281397
</t>
1329-
<t>
1330-
This keyword determines how child instances validate for objects,
1331-
and does not directly validate the immediate instance itself.
1332-
Validation of the primitive instance type against this keyword
1333-
always succeeds.
1334-
</t>
13351398
<t>
13361399
Validation succeeds if, for each instance name that matches any
13371400
regular expressions that appear as a property name in this keyword's value,
13381401
the child instance for that name successfully validates against each
13391402
schema that corresponds to a matching regular expression.
13401403
</t>
13411404
<t>
1342-
Omitting this keyword has the same behavior as an empty object.
1405+
The annotation result of this keyword is the set of instance
1406+
property names matched by this keyword. Annotation results
1407+
for "patternProperties" keywords from multiple schemas applied to
1408+
the same instance location are combined by taking the union
1409+
of the sets.
1410+
</t>
1411+
<t>
1412+
Omitting this keyword has the same assertion behavior as
1413+
an empty object.
13431414
</t>
13441415
</section>
13451416

1346-
<section title="additionalProperties">
1417+
<section title="additionalProperties" anchor="additionalProperties">
13471418
<t>
13481419
The value of "additionalProperties" MUST be a valid JSON Schema.
13491420
</t>
13501421
<t>
1351-
This keyword determines how child instances validate for objects,
1352-
and does not directly validate the immediate instance itself.
1353-
</t>
1354-
<t>
1422+
The behavior of this keyword depends on the presence and
1423+
annotation results of "properties" and "patternProperties"
1424+
within the same schema object.
13551425
Validation with "additionalProperties" applies only to the child
1356-
values of instance names that do not match any names in "properties",
1357-
and do not match any regular expression in "patternProperties".
1426+
values of instance names that do not appear in the annotation
1427+
results of either "properties" or "patternProperties".
13581428
</t>
13591429
<t>
13601430
For all such properties, validation succeeds if the child instance
13611431
validates against the "additionalProperties" schema.
13621432
</t>
13631433
<t>
1364-
Omitting this keyword has the same behavior as an empty schema.
1434+
The annotation result of this keyword is the set of instance
1435+
property names validated by this keyword's subschema.
1436+
Annotation results for "additionalProperties" keywords from
1437+
multiple schemas applied to the same instance location are combined
1438+
by taking the union of the sets.
1439+
</t>
1440+
<t>
1441+
Omitting this keyword has the same assertion behavior as
1442+
an empty schema.
1443+
</t>
1444+
<t>
1445+
Implementation MAY choose to implement or optimize this keyword
1446+
in another way that produces the same effect, such as by directly
1447+
checking the names in "properties" and the patterns in
1448+
"patternProperties" against the instance property set.
1449+
Implementations that do not support annotation collection MUST do so.
13651450
</t>
13661451
</section>
13671452

0 commit comments

Comments
 (0)