Skip to content

Commit 84fea95

Browse files
handrewshandrews
committed
Define subschemas -> child instances in core
This is a trial balloon for fixing json-schema-org#161. This moves several keywords that control which subschemas apply to which child instances from validation to core. The only actual validation that these keywords defined was that all child instances need to validate against all applicable subschemas. This simple child validation principle has been moved up to the general considerations section of the validation spec. The moved keywords are now prefixed with "$", which is what we've discussed doing for all core keywords (Another potential core keyword would be "$data", for instance, as it would be used in multiple vocabularies depending on which proposals we accept, if any.) As with "id" vs "$id" and the boolean forms of exclusiveMinimum/Maximum, the old forms are still allowed but expected to be removed before RFC. Migrating an old schema to the new form is trivial, and was discussed before we decided to rename "id". It is equally applicable here.
1 parent 6b33025 commit 84fea95

File tree

2 files changed

+127
-119
lines changed

2 files changed

+127
-119
lines changed

‎jsonschema-core.xml

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,127 @@
297297
</t>
298298
</section>
299299

300+
<section title="Applying subschemas to child instances">
301+
<t>
302+
The keywords in this section are used to control which subschemas
303+
apply to child instances. They are independent of any specific
304+
schema vocabulary. Vocabulary specifications SHOULD define any
305+
vocabulary-specific effects of applying subschemas.
306+
</t>
307+
<section title="$items">
308+
<t>
309+
The value of "$items" MUST be either an object or an array of objects.
310+
Each object MUST be a valid subschema.
311+
</t>
312+
<t>
313+
If absent, it can be considered present with an empty schema.
314+
</t>
315+
<t>
316+
This keyword applies only to array instances.
317+
</t>
318+
<t>
319+
If "$items" is a schema, that subschema applies to all elements
320+
in the instance array.
321+
</t>
322+
<t>
323+
If "$items" is an array of schemas, each subschema applies to
324+
the child instance element at the same position, if any.
325+
</t>
326+
</section>
327+
328+
<section title="$additionalItems">
329+
<t>
330+
The value of "$additionalItems" MUST be valid subschema.
331+
</t>
332+
<t>
333+
If absent, it can be considered present with an empty schema.
334+
</t>
335+
<t>
336+
This keyword applies only to array instances.
337+
</t>
338+
<t>
339+
If "$items" is an array of schemas, the "$additionalItems"
340+
schema applies to every element of the instance array at
341+
a position greater than the size of "$items".
342+
</t>
343+
<t>
344+
Otherwise, "$additionalItems" MUST be ignored, as the "$items"
345+
schema (possibly the default value of an empty schema) is
346+
applied to all instance array elements.
347+
</t>
348+
</section>
349+
350+
<section title="$properties">
351+
<t>
352+
The value of "$properties" MUST be an object. Each value of this object
353+
MUST be a a valid subschema.
354+
</t>
355+
<t>
356+
If absent, it can be considered the same as an empty object.
357+
</t>
358+
<t>
359+
This keyword applies only to object instances.
360+
</t>
361+
<t>
362+
For each property name that appears in both the "$properties" value
363+
and the instance object, the subschema given for that property
364+
name is applied to the value of that property in the instance object.
365+
</t>
366+
</section>
367+
368+
<section title="$patternProperties">
369+
<t>
370+
The value of "$patternProperties" MUST be an object. Each property name
371+
of this object SHOULD be a valid regular expression, according to the
372+
ECMA 262 regular expression dialect. Each property value of this object
373+
MUST be a valid subschema.
374+
</t>
375+
<t>
376+
If absent, it can be considered the same as an empty object.
377+
</t>
378+
<t>
379+
This keyword applies only to object instances.
380+
</t>
381+
<t>
382+
For each instance object property name that matches any
383+
regular expressions that appear as a property name in this keyword's
384+
value, the subschemas associated with each matching pattern
385+
are applied to the value of that instance property.
386+
</t>
387+
</section>
388+
389+
<section title="$additionalProperties">
390+
<t>
391+
The value of "$additionalProperties" MUST be a valid subschema.
392+
</t>
393+
<t>
394+
If "$additionalProperties" is absent, it may be considered present with
395+
an empty schema as a value.
396+
</t>
397+
<t>
398+
This keyword applies only to object instances.
399+
</t>
400+
<t>
401+
The keyword's subschema is applied only to the instance object
402+
property values whose property names neither appear in "$properties"
403+
nor match any regular expression in "$patternProperties".
404+
</t>
405+
</section>
406+
407+
<section title="Compatibility with earlier drafts">
408+
<t>
409+
Implementations MAY support "items", "additionalItems", "properties",
410+
"patternProperties", and "additionalProperties" as synonyms for their
411+
dollar sign-prefixed equivalents for aiding in migrating from earlier
412+
drafts. An implementation that supports any of these keywords
413+
SHOULD support all of them.
414+
</t>
415+
<t>
416+
Schema authors SHOULD NOT use these forms of the keywords.
417+
</t>
418+
</section>
419+
</section>
420+
300421
<section title="Schema references with $ref">
301422
<t>
302423
Any time a subschema is expected, a schema may instead use an object containing a "$ref" property.

‎jsonschema-validation.xml

Lines changed: 6 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -170,15 +170,14 @@
170170

171171
<section title="Validation of primitive types and child values">
172172
<t>
173-
Two of the primitive types, array and object, allow for child values. The validation of
174-
the primitive type is considered separately from the validation of child instances.
173+
Two of the primitive types, array and object, allow for child values.
174+
The JSON Schema core specification defines keywords that determine
175+
which subschemas are applied to each child value.
175176
</t>
176177
<t>
177-
For arrays, primitive type validation consists of validating restrictions on length.
178-
</t>
179-
<t>
180-
For objects, primitive type validation consists of validating restrictions on the presence
181-
or absence of property names.
178+
Validation of arrays and objects succeed if, in addition to validating
179+
against any relevant validation keywords, each child instance
180+
successfully validates against all subschemas that apply to it.
182181
</t>
183182
</section>
184183

@@ -310,53 +309,6 @@
310309
</t>
311310
</section>
312311

313-
<section title="items">
314-
<t>
315-
The value of "items" MUST be either an object or an array of objects.
316-
Each object MUST be a valid JSON Schema.
317-
</t>
318-
<t>
319-
If absent, it can be considered present with an empty schema.
320-
</t>
321-
<t>
322-
This keyword controls child instance validation. Validation of the
323-
primitive instance type against this keyword always succeeds.
324-
</t>
325-
<t>
326-
If "items" is a schema, child validation succeeds if all elements
327-
in the array successfully validate against that schema.
328-
</t>
329-
<t>
330-
If "items" is an array of schemas, child validation succeeds if
331-
each element of the instance validates against the schema at the
332-
same position, if any.
333-
</t>
334-
</section>
335-
336-
<section title="additionalItems">
337-
<t>
338-
The value of "additionalItems" MUST be a boolean or an object.
339-
If it is an object, the object MUST be a valid JSON Schema.
340-
</t>
341-
<t>
342-
If absent, it can be considered present with an empty schema.
343-
</t>
344-
<t>
345-
This keyword controls child instance validation. Validation of the
346-
primitive instance type against this keyword always succeeds.
347-
</t>
348-
<t>
349-
If "items" is an array of schemas, child validation succeeds
350-
if every instance element at a position greater than the size
351-
of "items" validates against "additionalItems".
352-
</t>
353-
<t>
354-
Otherwise, "additionalItems" MUST be ignored, as the "items"
355-
schema (possibly the default value of an empty schema) is
356-
applied to all elements.
357-
</t>
358-
</section>
359-
360312
<section title="maxItems">
361313
<t>
362314
The value of this keyword MUST be an integer. This integer MUST be
@@ -448,71 +400,6 @@
448400
</t>
449401
</section>
450402

451-
<section title="properties">
452-
<t>
453-
The value of "properties" MUST be an object. Each value of this object
454-
MUST be an object, and each object MUST be a valid JSON Schema.
455-
</t>
456-
<t>
457-
If absent, it can be considered the same as an empty object.
458-
</t>
459-
<t>
460-
This keyword controls child instance validation. Validation of the
461-
primitive instance type against this keyword always succeeds.
462-
</t>
463-
<t>
464-
Child validation succeeds if, for each name that appears in both
465-
the instance and as a name within this keyword's value, the instance
466-
value successfully validates against the corresponding schema.
467-
</t>
468-
</section>
469-
470-
<section title="patternProperties">
471-
<t>
472-
The value of "patternProperties" MUST be an object. Each property name
473-
of this object SHOULD be a valid regular expression, according to the
474-
ECMA 262 regular expression dialect. Each property value of this object
475-
MUST be an object, and each object MUST be a valid JSON Schema.
476-
</t>
477-
<t>
478-
If absent, it can be considered the same as an empty object.
479-
</t>
480-
<t>
481-
This keyword controls child instance validation. Validation of the
482-
primitive instance type against this keyword always succeeds.
483-
</t>
484-
<t>
485-
Child validation succeeds if, for each instance name that matches any
486-
regular expressions that appear as a property name in this keyword's value,
487-
the child instance for that name successfully validates against each
488-
schema that corresponds to a matching regular expression.
489-
</t>
490-
</section>
491-
492-
<section title="additionalProperties">
493-
<t>
494-
The value of "additionalProperties" MUST be a boolean or an
495-
object. If it is an object, the object MUST be a valid JSON Schema.
496-
</t>
497-
<t>
498-
If "additionalProperties" is absent, it may be considered present with
499-
an empty schema as a value.
500-
</t>
501-
<t>
502-
This keyword controls child instance validation. Validation of the
503-
primitive instance type against this keyword always succeeds.
504-
</t>
505-
<t>
506-
Child validation with "additionalProperties" applies only to the child
507-
values of instance names that do not match any names in "properties",
508-
and do not match any regular expression in "patternProperties".
509-
</t>
510-
<t>
511-
For all such properties, child validation succeeds if the child instance
512-
validates against the "additionalProperties" schema.
513-
</t>
514-
</section>
515-
516403
<section title="dependencies">
517404
<t>
518405
This keyword specifies rules that are evaluated if the instance is an object and

0 commit comments

Comments
 (0)