Skip to content

Commit 0942a62

Browse files
handrewshandrews
committed
Define additional* in terms of annotations
This aligns the behavior of "additionalItems" and "additionalProperties" with the rules given for dependent keywords in the previous commit. Specifically, "additionalItems" depends on the presence or absence of "items", and its newly defined annotation results, while "additionalProperties" depends on the annotation results of "properties" and "patternProperties". The standard explicitly allows implementing these keywords in other ways (presumably the way implementations currently handle them) as either an optimization or to support the keywords in implementations that do not support annotations. This avoids requiring existing assertion-only validators to change their behavior. Note that the rationale for "additionalItems" being ignored when "items" is absent has been changed to align it with this new framework. Doing anything else would have required an absent keyword to produce annotation results as default behavior, which leads to very difficult problems as the set of keywords with such behavior grows.
1 parent c809546 commit 0942a62

File tree

1 file changed

+86
-19
lines changed

1 file changed

+86
-19
lines changed

‎jsonschema-core.xml

Lines changed: 86 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,10 @@
162162
that depend on annotation results MUST then be treated as errors, unless
163163
an alternate implementation producing the same behavior is available.
164164
Keywords of this sort SHOULD describe reasonable alternate approaches
165-
when appropriate.
165+
when appropriate. This approach is demonstrated by the
166+
"<xref target="additionalItems" format="title"/>" and
167+
"<xref target="additionalProperties" format="title"/>" keywords in this
168+
document.
166169
</t>
167170
<t>
168171
Extension keywords SHOULD stay within these categories, keeping in mind
@@ -1227,8 +1230,8 @@
12271230
<section title="Keywords for Applying Subschemas to Arrays">
12281231
<section title="items">
12291232
<t>
1230-
The value of "items" MUST be either a valid JSON Schema or an array of valid
1231-
JSON Schemas.
1233+
The value of "items" MUST be either a valid JSON Schema or
1234+
an array of valid JSON Schemas.
12321235
</t>
12331236
<t>
12341237
If "items" is a schema, validation succeeds if all elements
@@ -1240,26 +1243,52 @@
12401243
same position, if any.
12411244
</t>
12421245
<t>
1243-
Omitting this keyword has the same behavior as an empty schema.
1246+
This keyword produces an annotation value which is the largest
1247+
index to which this keyword applied a subschema. The value
1248+
MAY be a boolean true if a subschema was applied to every
1249+
index of the instance, such as when "items" is a schema.
1250+
</t>
1251+
<t>
1252+
Annotation results from multiple "items" keyword are combined
1253+
by setting the combined result to true if any of the values
1254+
are true, and otherwise retaining the larges numerical value.
1255+
</t>
1256+
<t>
1257+
Omitting this keyword has the same assertion behavior as
1258+
an empty schema.
12441259
</t>
12451260
</section>
12461261

1247-
<section title="additionalItems">
1262+
<section title="additionalItems" anchor="additionalItems">
12481263
<t>
12491264
The value of "additionalItems" MUST be a valid JSON Schema.
12501265
</t>
12511266
<t>
1252-
If "items" is an array of schemas, validation succeeds
1253-
if every instance element at a position greater than the size
1254-
of "items" validates against "additionalItems".
1267+
The behavior of this keyword depends on the presence and
1268+
annotation result of "items" within the same schema object.
1269+
If "items" is present, and its annotation result is a number,
1270+
validation succeeds if every instance element at an index
1271+
greater than that number validates against "additionalItems".
12551272
</t>
12561273
<t>
1257-
Otherwise, "additionalItems" MUST be ignored, as the "items"
1258-
schema (possibly the default value of an empty schema) is
1259-
applied to all elements.
1274+
Otherwise, if "items" is absent or its annotation result
1275+
is the boolean true, "additionalItems" MUST be ignored.
12601276
</t>
12611277
<t>
1262-
Omitting this keyword has the same behavior as an empty schema.
1278+
If the "additionalItems" subschema is applied to any
1279+
positions within the instance array, it produces an
1280+
annotation result of boolean true, analogous to the
1281+
single schema behavior of "items".
1282+
</t>
1283+
<t>
1284+
Omitting this keyword has the same assertion behavior as
1285+
an empty schema.
1286+
</t>
1287+
<t>
1288+
Implementation MAY choose to implement or optimize this keyword
1289+
in another way that produces the same effect, such as by directly
1290+
checking for the presence and size of an "items" array.
1291+
Implementations that do not support annotation collection MUST do so.
12631292
</t>
12641293
</section>
12651294

@@ -1269,7 +1298,16 @@
12691298
</t>
12701299
<t>
12711300
An array instance is valid against "contains" if at least one of
1272-
its elements is valid against the given schema.
1301+
its elements is valid against the given schema. This keyword
1302+
does not produce annotation results.
1303+
<cref>
1304+
Should it produce a set of the indices for which the
1305+
array element is valid against the subschema? "contains"
1306+
does not affect "additionalItems" or any other current
1307+
or proposed keyword, but the information could be useful,
1308+
and implementation that collect annotations need to
1309+
apply "contains" to every element anyway.
1310+
</cref>
12731311
</t>
12741312
</section>
12751313
</section>
@@ -1287,7 +1325,14 @@
12871325
corresponding schema.
12881326
</t>
12891327
<t>
1290-
Omitting this keyword has the same behavior as an empty object.
1328+
The annotation result of this keyword is the set of instance
1329+
property names matched by this keyword. Multiple annotation
1330+
results for "properties" are combined by taking the union
1331+
of the sets.
1332+
</t>
1333+
<t>
1334+
Omitting this keyword has the same assertion behavior as
1335+
an empty object.
12911336
</t>
12921337
</section>
12931338

@@ -1305,25 +1350,47 @@
13051350
schema that corresponds to a matching regular expression.
13061351
</t>
13071352
<t>
1308-
Omitting this keyword has the same behavior as an empty object.
1353+
The annotation result of this keyword is the set of instance
1354+
property names matched by this keyword. Multiple annotation
1355+
results for "patternProperties" are combined by taking the union
1356+
of the sets.
1357+
</t>
1358+
<t>
1359+
Omitting this keyword has the same assertion behavior as
1360+
an empty object.
13091361
</t>
13101362
</section>
13111363

1312-
<section title="additionalProperties">
1364+
<section title="additionalProperties" anchor="additionalProperties">
13131365
<t>
13141366
The value of "additionalProperties" MUST be a valid JSON Schema.
13151367
</t>
13161368
<t>
1369+
The behavior of this keyword depends on the presence and
1370+
annotation results of "properties" and "patternProperties"
1371+
within the same schema object.
13171372
Validation with "additionalProperties" applies only to the child
1318-
values of instance names that do not match any names in "properties",
1319-
and do not match any regular expression in "patternProperties".
1373+
values of instance names that do not appear in the annotation
1374+
results of either "properties" or "patternProperties".
13201375
</t>
13211376
<t>
13221377
For all such properties, validation succeeds if the child instance
13231378
validates against the "additionalProperties" schema.
13241379
</t>
13251380
<t>
1326-
Omitting this keyword has the same behavior as an empty schema.
1381+
The annotation result of this keyword is the set of instance
1382+
property names validated by this keyword's subschema.
1383+
</t>
1384+
<t>
1385+
Omitting this keyword has the same assertion behavior as
1386+
an empty schema.
1387+
</t>
1388+
<t>
1389+
Implementation MAY choose to implement or optimize this keyword
1390+
in another way that produces the same effect, such as by directly
1391+
checking the names in "properties" and the patterns in
1392+
"patternProperties" against the instance property set.
1393+
Implementations that do not support annotation collection MUST do so.
13271394
</t>
13281395
</section>
13291396

0 commit comments

Comments
 (0)