From a9d2d3be701d81f679e61280e25e450412a1395f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 25 Oct 2016 14:25:02 -0700 Subject: [PATCH 1/2] 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). --- jsonschema-validation.xml | 105 +++++++++++++++++++++++++++++--------- 1 file changed, 81 insertions(+), 24 deletions(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 2633bf21..71ade365 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -297,31 +297,59 @@ -
+
- The value of "additionalItems" MUST be either a boolean or an object. If - it is an object, this object MUST be a valid JSON Schema. + The value of "items" MUST be either an object or an array of objects. + Each object MUST be a valid JSON Schema. - The value of "items" MUST be either a schema or array of schemas. + If absent, it can be considered present with an empty schema. - Successful validation of an array instance with regards to these two - keywords is determined as follows: + Validation of this keyword against the instance always succeeds. + + + If "items" is a schema, child validation succeeds if all elements + in the array successfully validate against that schema. + + + If "items" is an array of schemas, child validation succeeds if + each element of the instance validates against the schema at the + same position, if any. + +
- - if "items" is not present, or its value is an object, validation - of the instance always succeeds, regardless of the value of - "additionalItems"; - if the value of "additionalItems" is boolean value true or an - object, validation of the instance always succeeds; - if the value of "additionalItems" is boolean value false and the - value of "items" is an array, the instance is valid if - its size is less than, or equal to, the size of "items". - +
+ + The value of "additionalItems" MUST be a boolean or an object. + If it is an object, the object MUST be a valid JSON Schema. + + + If absent, it can be considered present with an empty schema. + + + If "additionalItems" is true or a schema, or if "items" + is absent or a single schema, or if the instance is not + an array, then validation of the instance always succeeds. + + + If "additionalItems" is false, and "items" is an array + of schemas, validation of the instance succeeds if + the size of the instance is less than, or equal to, + the size of "items". - If either keyword is absent, it may be considered present with an empty + Child validation with respect to "additionalItems" only applies + when "items" is an array of schemas, and only applies to + instance elements at positions greater than the size of "items". + + + If "additionalItems" is true, child validation always succeeds. + + + If "additionalItems" is a schema, child validation succeeds + if all instance elements at positions greater than the size + of "items" successfully validate against the "additionalItems" schema.
@@ -415,6 +443,14 @@ If absent, it can be considered the same as an empty object. + + Validation of this keyword against the instance always succeeds. + + + Child validation succeeds if, for each name that appears in both + the instance and as a name within this keyword's value, the instance + value successfully validates against the corresponding schema. +
@@ -427,27 +463,48 @@ If absent, it can be considered the same as an empty object. + + Validaton of this keyword against the instance always succeeds. + + + Child validation succeeds if, for each instance name that matches any + regular expressions that appear as a property name in this keyword's value, + the child instance for that name successfully validates against each + schema that corresponds to a matching regular expression. +
- The value of "additionalProperties" MUST be a boolean or a schema. + The value of "additionalProperties" MUST be a boolean or an + object. If it is an object, the object MUST be a valid JSON Schema. If "additionalProperties" is absent, it may be considered present with an empty schema as a value. - If "additionalProperties" is true, validation always succeeds. + If "additionalProperties" is either true or a schema, or if the instance + is not an object, validation against the instance always succeeds. + + + If "additionalProperties" is false and the instance is an object, + validation against the instance succeeds only if all properties names + in the instance match a name specified in "properties" and/or match + at least one regular expression specified in "patternProperties". + + + Child validation with "additionalProperties" applies only to the child + valuse of instance names that do not match any names in "properties", + and do not match any regular expression in "patternProperties". - If "additionalProperties" is false, validation succeeds only if the instance - is an object and all properties on the instance were covered by "properties" - and/or "patternProperties". + If "additionalProperties" is true, child validation always succeeds. - If "additionalProperties" is an object, validate the value as a schema to all - of the properties that weren't validated by "properties" nor "patternProperties". + If "additionalProperties" is a schema, child validation succeeds if + all child instances to which "additionalProperties" applies validate + against that schema.
From a0979f363295bcf671c3856088e316ee6c87b70c Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 3 Nov 2016 12:30:11 -0700 Subject: [PATCH 2/2] Futher clarify primitive vs child validation. A lot of the most confusing language around the "additional" keywords can be removed if we consider keywords strictly with respect to either the instance's primitive type or against child instances. Describing {"additionalItems": false} as failing child validation of elements beyond the length of "items" is more straightforward and has the same effect as the more convoluted reasoning about length. --- jsonschema-validation.xml | 69 +++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 39 deletions(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 71ade365..d265e21c 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -168,6 +168,20 @@ +
+ + Two of the primitive types, array and object, allow for child values. The validation of + the primitive type is considered separately from the validation of child instances. + + + For arrays, primitive type validation consists of validating restrictions on length. + + + For objects, primitive type validation consists of validating restrictions on the presence + or absence of property names. + +
+
Validation keywords that are missing never restrict validation. @@ -306,7 +320,8 @@ If absent, it can be considered present with an empty schema. - Validation of this keyword against the instance always succeeds. + This keyword controls child instance validation. Validation of the + primitive instance type against this keyword always succeeds. If "items" is a schema, child validation succeeds if all elements @@ -328,29 +343,13 @@ If absent, it can be considered present with an empty schema. - If "additionalItems" is true or a schema, or if "items" - is absent or a single schema, or if the instance is not - an array, then validation of the instance always succeeds. - - - If "additionalItems" is false, and "items" is an array - of schemas, validation of the instance succeeds if - the size of the instance is less than, or equal to, - the size of "items". - - - Child validation with respect to "additionalItems" only applies - when "items" is an array of schemas, and only applies to - instance elements at positions greater than the size of "items". - - - If "additionalItems" is true, child validation always succeeds. + This keyword controls child instance validation. Validation of the + primitive instance type against this keyword always succeeds. - If "additionalItems" is a schema, child validation succeeds - if all instance elements at positions greater than the size - of "items" successfully validate against the "additionalItems" - schema. + If "items" is an array of schemas, child validation succeeds + if every instance element at a position greater than the size + of "items" validates against "additionalItems".
@@ -444,7 +443,8 @@ If absent, it can be considered the same as an empty object. - Validation of this keyword against the instance always succeeds. + This keyword controls child instance validation. Validation of the + primitive instance type against this keyword always succeeds. Child validation succeeds if, for each name that appears in both @@ -464,7 +464,8 @@ If absent, it can be considered the same as an empty object. - Validaton of this keyword against the instance always succeeds. + This keyword controls child instance validation. Validation of the + primitive instance type against this keyword always succeeds. Child validation succeeds if, for each instance name that matches any @@ -484,27 +485,17 @@ an empty schema as a value. - If "additionalProperties" is either true or a schema, or if the instance - is not an object, validation against the instance always succeeds. - - - If "additionalProperties" is false and the instance is an object, - validation against the instance succeeds only if all properties names - in the instance match a name specified in "properties" and/or match - at least one regular expression specified in "patternProperties". + This keyword controls child instance validation. Validation of the + primitive instance type against this keyword always succeeds. Child validation with "additionalProperties" applies only to the child - valuse of instance names that do not match any names in "properties", + values of instance names that do not match any names in "properties", and do not match any regular expression in "patternProperties". - If "additionalProperties" is true, child validation always succeeds. - - - If "additionalProperties" is a schema, child validation succeeds if - all child instances to which "additionalProperties" applies validate - against that schema. + For all such properties, child validation succeeds if the child instance + validates agains the "additionalProperties" schema.