Skip to content

Commit a9d2d3b

Browse files
handrewshandrews
committed
Make properties/items wording consistent.
Separate "items" and "additionalItems" for consistency with the separate "properties", "patternProperties", and "additionalProperties". Fix wording bug: non-objects always successfully validate against "additionalProperties". Arrange the wording for each of these to follow this pattern: * keyword value type requirements * value to assume if absent (if relevant) * validation against the instance (independent of child validation) * validation of children (possibly first explaining to which children this keyword applies).
1 parent df8d370 commit a9d2d3b

File tree

1 file changed

+81
-24
lines changed

1 file changed

+81
-24
lines changed

‎jsonschema-validation.xml

Lines changed: 81 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -297,31 +297,59 @@
297297
</t>
298298
</section>
299299

300-
<section title="additionalItems and items">
300+
<section title="items">
301301
<t>
302-
The value of "additionalItems" MUST be either a boolean or an object. If
303-
it is an object, this object MUST be a valid JSON Schema.
302+
The value of "items" MUST be either an object or an array of objects.
303+
Each object MUST be a valid JSON Schema.
304304
</t>
305305
<t>
306-
The value of "items" MUST be either a schema or array of schemas.
306+
If absent, it can be considered present with an empty schema.
307307
</t>
308308
<t>
309-
Successful validation of an array instance with regards to these two
310-
keywords is determined as follows:
309+
Validation of this keyword against the instance always succeeds.
310+
</t>
311+
<t>
312+
If "items" is a schema, child validation succeeds if all elements
313+
in the array successfully validate against that schema.
314+
</t>
315+
<t>
316+
If "items" is an array of schemas, child validation succeeds if
317+
each element of the instance validates against the schema at the
318+
same position, if any.
319+
</t>
320+
</section>
311321

312-
<list>
313-
<t>if "items" is not present, or its value is an object, validation
314-
of the instance always succeeds, regardless of the value of
315-
"additionalItems";</t>
316-
<t>if the value of "additionalItems" is boolean value true or an
317-
object, validation of the instance always succeeds;</t>
318-
<t>if the value of "additionalItems" is boolean value false and the
319-
value of "items" is an array, the instance is valid if
320-
its size is less than, or equal to, the size of "items".</t>
321-
</list>
322+
<section title="additionalItems">
323+
<t>
324+
The value of "additionalItems" MUST be a boolean or an object.
325+
If it is an object, the object MUST be a valid JSON Schema.
326+
</t>
327+
<t>
328+
If absent, it can be considered present with an empty schema.
329+
</t>
330+
<t>
331+
If "additionalItems" is true or a schema, or if "items"
332+
is absent or a single schema, or if the instance is not
333+
an array, then validation of the instance always succeeds.
334+
</t>
335+
<t>
336+
If "additionalItems" is false, and "items" is an array
337+
of schemas, validation of the instance succeeds if
338+
the size of the instance is less than, or equal to,
339+
the size of "items".
322340
</t>
323341
<t>
324-
If either keyword is absent, it may be considered present with an empty
342+
Child validation with respect to "additionalItems" only applies
343+
when "items" is an array of schemas, and only applies to
344+
instance elements at positions greater than the size of "items".
345+
</t>
346+
<t>
347+
If "additionalItems" is true, child validation always succeeds.
348+
</t>
349+
<t>
350+
If "additionalItems" is a schema, child validation succeeds
351+
if all instance elements at positions greater than the size
352+
of "items" successfully validate against the "additionalItems"
325353
schema.
326354
</t>
327355
</section>
@@ -415,6 +443,14 @@
415443
<t>
416444
If absent, it can be considered the same as an empty object.
417445
</t>
446+
<t>
447+
Validation of this keyword against the instance always succeeds.
448+
</t>
449+
<t>
450+
Child validation succeeds if, for each name that appears in both
451+
the instance and as a name within this keyword's value, the instance
452+
value successfully validates against the corresponding schema.
453+
</t>
418454
</section>
419455

420456
<section title="patternProperties">
@@ -427,27 +463,48 @@
427463
<t>
428464
If absent, it can be considered the same as an empty object.
429465
</t>
466+
<t>
467+
Validaton of this keyword against the instance always succeeds.
468+
</t>
469+
<t>
470+
Child validation succeeds if, for each instance name that matches any
471+
regular expressions that appear as a property name in this keyword's value,
472+
the child instance for that name successfully validates against each
473+
schema that corresponds to a matching regular expression.
474+
</t>
430475
</section>
431476

432477
<section title="additionalProperties">
433478
<t>
434-
The value of "additionalProperties" MUST be a boolean or a schema.
479+
The value of "additionalProperties" MUST be a boolean or an
480+
object. If it is an object, the object MUST be a valid JSON Schema.
435481
</t>
436482
<t>
437483
If "additionalProperties" is absent, it may be considered present with
438484
an empty schema as a value.
439485
</t>
440486
<t>
441-
If "additionalProperties" is true, validation always succeeds.
487+
If "additionalProperties" is either true or a schema, or if the instance
488+
is not an object, validation against the instance always succeeds.
489+
</t>
490+
<t>
491+
If "additionalProperties" is false and the instance is an object,
492+
validation against the instance succeeds only if all properties names
493+
in the instance match a name specified in "properties" and/or match
494+
at least one regular expression specified in "patternProperties".
495+
</t>
496+
<t>
497+
Child validation with "additionalProperties" applies only to the child
498+
valuse of instance names that do not match any names in "properties",
499+
and do not match any regular expression in "patternProperties".
442500
</t>
443501
<t>
444-
If "additionalProperties" is false, validation succeeds only if the instance
445-
is an object and all properties on the instance were covered by "properties"
446-
and/or "patternProperties".
502+
If "additionalProperties" is true, child validation always succeeds.
447503
</t>
448504
<t>
449-
If "additionalProperties" is an object, validate the value as a schema to all
450-
of the properties that weren't validated by "properties" nor "patternProperties".
505+
If "additionalProperties" is a schema, child validation succeeds if
506+
all child instances to which "additionalProperties" applies validate
507+
against that schema.
451508
</t>
452509
</section>
453510

0 commit comments

Comments
 (0)