diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 564dcd5f..f772e3f9 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -156,56 +156,163 @@
-
+
- Most validation keywords only limit the range of values within a certain primitive type. - When the primitive type of the instance is not of the type targeted by the keyword, the - validation succeeds. + Each JSON Schema validation keyword adds constraints that + an instance must satisfy in order to successfully validate. - For example, the "maxLength" keyword will only restrict certain strings (that are too long) from being valid. - If the instance is a number, boolean, null, array, or object, the keyword passes validation. - + Validation keywords that are missing never restrict validation. + In some cases, this no-op behavior is identical to a keyword that + exists with certain values, and these values are noted where relevant. + +
+ + From this principle, it follows that all JSON values + successfully validate against the empty schema: + + + + +
+
+ + Similarly, it follows that no JSON value successfully + validates against the empty schema's negation: + + + + +
-
- - 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. + Validation keywords typically operate independently, without + affecting each other's outcomes. - For objects, primitive type validation consists of validating restrictions on the presence - or absence of property names. + For schema author convenience, there are some exceptions: + + "additionalProperties", whose behavior is defined in terms of "properties" and "patternProperties" + "additionalItems", whose behavior is defined in terms of "items" + "minimum" and "maximum", whose behaviors are modified by "exclusiveMinimum" and "exclusiveMaximum", respectively +
-
+
- Validation keywords that are missing never restrict validation. - In some cases, this no-op behavior is identical to a keyword that exists with certain values, - and these values are noted where known. + Two of the primitive types, array and object, allow for child values. -
- -
- - Validation keywords typically operate independent of each other, without affecting each other. + Nearly all keywords are defined to operate on either the primitive + type of the container instance, or on the child instance(s), but + not both. Those that operate on child instances are applied to + each appropriate child instance separately. - For author convienence, there are some exceptions: + It follows from keyword independence that validation of the primitive + type of the container instance is considered separately from the + values of the child instances or their validation outcomes. + + + Two keywords are exceptions, as they validate properties of arrays as a whole: - "additionalProperties", whose behavior is defined in terms of "properties" and "patternProperties"; and - "additionalItems", whose behavior is defined in terms of "items" + "uniqueItems", which validates a relationship among the child instances + "contains", which provides a schema for child validation, but need only successfully validate any one child instance rather than applying to all children or to a specific subset of children.
+
+ + An important implication of keyword independence is + that most validation keywords only limit the range of values + within a certain primitive type. When the primitive type of + the instance is not of the type targeted by the keyword, the + validation succeeds. + + + For example, the "multipleOf" keyword will only restrict + certain numbers from being valid. + If the instance is a string, boolean, null, array, or object + the keyword passes validation. + +
+ + The utility of this is best illustrated by considering + this schema for odd numbers: + + + + +
+
+ + If "multipleOf" implicitly constrained the type of the + instance to be a number, then both the overall schema + and the negated subschema would require a numeric instance + in order to validate. It would be equivalent to: + + + + + + It is clearly impossible to satisfy this schema, so keywords + must not impose constraints on type. Therefore, as originally written + (without a type constraint) the schema validates both odd integers + and non-numbers. + +
+
+ + The following schema is the correct way to validate + only odd integers, while failing validation for non-numbers: + + + + + + This negates only the even-ness of numbers, without + affecting validation of the instance type within the "not". + The instance type is only constrained outside of the negation. + +
+
+
Validation keywords in a schema impose requirements for successfully validating an instance. @@ -505,7 +612,7 @@ For all such properties, child validation succeeds if the child instance - validates agains the "additionalProperties" schema. + validates against the "additionalProperties" schema.
@@ -663,7 +770,7 @@ Both of these keywords can be used to decorate a user interface with information about the data produced by this user interface. A title will - preferrably be short, whereas a description will provide explanation about + preferably be short, whereas a description will provide explanation about the purpose of the instance described by this schema. @@ -812,11 +919,11 @@
- JSON Schema validation defines a vocabulary for JSON Schema core and conserns all the security considerations listed there. + JSON Schema validation defines a vocabulary for JSON Schema core and concerns all the security considerations listed there. JSON Schema validation allows the use of Regular Expressions, which have numerous different (often incompatible) implementations. - Some implementations allow the embedding of arbritrary code, which is outside the scope of JSON Schema and MUST NOT be permitted. + Some implementations allow the embedding of arbitrary code, which is outside the scope of JSON Schema and MUST NOT be permitted. Regular expressions can often also be crafted to be extremely expensive to compute (with so-called "catastrophic backtracking"), resulting in a denial-of-service attack.