Skip to content

Commit b72cdd6

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 a771f51 commit b72cdd6

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
@@ -176,7 +176,10 @@
176176
that depend on annotation results MUST then be treated as errors, unless
177177
an alternate implementation producing the same behavior is available.
178178
Keywords of this sort SHOULD describe reasonable alternate approaches
179-
when appropriate.
179+
when appropriate. This approach is demonstrated by the
180+
"<xref target="additionalItems" format="title"/>" and
181+
"<xref target="additionalProperties" format="title"/>" keywords in this
182+
document.
180183
</t>
181184
<t>
182185
Extension keywords SHOULD stay within these categories, keeping in mind
@@ -1242,8 +1245,8 @@
12421245
<section title="Keywords for Applying Subschemas to Arrays">
12431246
<section title="items">
12441247
<t>
1245-
The value of "items" MUST be either a valid JSON Schema or an array of valid
1246-
JSON Schemas.
1248+
The value of "items" MUST be either a valid JSON Schema or
1249+
an array of valid JSON Schemas.
12471250
</t>
12481251
<t>
12491252
If "items" is a schema, validation succeeds if all elements
@@ -1255,26 +1258,52 @@
12551258
same position, if any.
12561259
</t>
12571260
<t>
1258-
Omitting this keyword has the same behavior as an empty schema.
1261+
This keyword produces an annotation value which is the largest
1262+
index to which this keyword applied a subschema. The value
1263+
MAY be a boolean true if a subschema was applied to every
1264+
index of the instance, such as when "items" is a schema.
1265+
</t>
1266+
<t>
1267+
Annotation results from multiple "items" keyword are combined
1268+
by setting the combined result to true if any of the values
1269+
are true, and otherwise retaining the larges numerical value.
1270+
</t>
1271+
<t>
1272+
Omitting this keyword has the same assertion behavior as
1273+
an empty schema.
12591274
</t>
12601275
</section>
12611276

1262-
<section title="additionalItems">
1277+
<section title="additionalItems" anchor="additionalItems">
12631278
<t>
12641279
The value of "additionalItems" MUST be a valid JSON Schema.
12651280
</t>
12661281
<t>
1267-
If "items" is an array of schemas, validation succeeds
1268-
if every instance element at a position greater than the size
1269-
of "items" validates against "additionalItems".
1282+
The behavior of this keyword depends on the presence and
1283+
annotation result of "items" within the same schema object.
1284+
If "items" is present, and its annotation result is a number,
1285+
validation succeeds if every instance element at an index
1286+
greater than that number validates against "additionalItems".
12701287
</t>
12711288
<t>
1272-
Otherwise, "additionalItems" MUST be ignored, as the "items"
1273-
schema (possibly the default value of an empty schema) is
1274-
applied to all elements.
1289+
Otherwise, if "items" is absent or its annotation result
1290+
is the boolean true, "additionalItems" MUST be ignored.
12751291
</t>
12761292
<t>
1277-
Omitting this keyword has the same behavior as an empty schema.
1293+
If the "additionalItems" subschema is applied to any
1294+
positions within the instance array, it produces an
1295+
annotation result of boolean true, analogous to the
1296+
single schema behavior of "items".
1297+
</t>
1298+
<t>
1299+
Omitting this keyword has the same assertion behavior as
1300+
an empty schema.
1301+
</t>
1302+
<t>
1303+
Implementation MAY choose to implement or optimize this keyword
1304+
in another way that produces the same effect, such as by directly
1305+
checking for the presence and size of an "items" array.
1306+
Implementations that do not support annotation collection MUST do so.
12781307
</t>
12791308
</section>
12801309

@@ -1284,7 +1313,16 @@
12841313
</t>
12851314
<t>
12861315
An array instance is valid against "contains" if at least one of
1287-
its elements is valid against the given schema.
1316+
its elements is valid against the given schema. This keyword
1317+
does not produce annotation results.
1318+
<cref>
1319+
Should it produce a set of the indices for which the
1320+
array element is valid against the subschema? "contains"
1321+
does not affect "additionalItems" or any other current
1322+
or proposed keyword, but the information could be useful,
1323+
and implementation that collect annotations need to
1324+
apply "contains" to every element anyway.
1325+
</cref>
12881326
</t>
12891327
</section>
12901328
</section>
@@ -1302,7 +1340,14 @@
13021340
corresponding schema.
13031341
</t>
13041342
<t>
1305-
Omitting this keyword has the same behavior as an empty object.
1343+
The annotation result of this keyword is the set of instance
1344+
property names matched by this keyword. Multiple annotation
1345+
results for "properties" are combined by taking the union
1346+
of the sets.
1347+
</t>
1348+
<t>
1349+
Omitting this keyword has the same assertion behavior as
1350+
an empty object.
13061351
</t>
13071352
</section>
13081353

@@ -1320,25 +1365,47 @@
13201365
schema that corresponds to a matching regular expression.
13211366
</t>
13221367
<t>
1323-
Omitting this keyword has the same behavior as an empty object.
1368+
The annotation result of this keyword is the set of instance
1369+
property names matched by this keyword. Multiple annotation
1370+
results for "patternProperties" are combined by taking the union
1371+
of the sets.
1372+
</t>
1373+
<t>
1374+
Omitting this keyword has the same assertion behavior as
1375+
an empty object.
13241376
</t>
13251377
</section>
13261378

1327-
<section title="additionalProperties">
1379+
<section title="additionalProperties" anchor="additionalProperties">
13281380
<t>
13291381
The value of "additionalProperties" MUST be a valid JSON Schema.
13301382
</t>
13311383
<t>
1384+
The behavior of this keyword depends on the presence and
1385+
annotation results of "properties" and "patternProperties"
1386+
within the same schema object.
13321387
Validation with "additionalProperties" applies only to the child
1333-
values of instance names that do not match any names in "properties",
1334-
and do not match any regular expression in "patternProperties".
1388+
values of instance names that do not appear in the annotation
1389+
results of either "properties" or "patternProperties".
13351390
</t>
13361391
<t>
13371392
For all such properties, validation succeeds if the child instance
13381393
validates against the "additionalProperties" schema.
13391394
</t>
13401395
<t>
1341-
Omitting this keyword has the same behavior as an empty schema.
1396+
The annotation result of this keyword is the set of instance
1397+
property names validated by this keyword's subschema.
1398+
</t>
1399+
<t>
1400+
Omitting this keyword has the same assertion behavior as
1401+
an empty schema.
1402+
</t>
1403+
<t>
1404+
Implementation MAY choose to implement or optimize this keyword
1405+
in another way that produces the same effect, such as by directly
1406+
checking the names in "properties" and the patterns in
1407+
"patternProperties" against the instance property set.
1408+
Implementations that do not support annotation collection MUST do so.
13421409
</t>
13431410
</section>
13441411

0 commit comments

Comments
 (0)