Skip to content

Commit

Permalink
Add general validation principles and examples.
Browse files Browse the repository at this point in the history 
This paritally addresses issue json-schema-org#55 plus concerns raised in
the comments of issue json-schema-org#101.

I replaced "linearity" with "independence" as I think it is
more general and intuitive.

The general considerations section has been reorganized
to start with the behavior of the empty schema, then explain
keyword independence, and finally cover type applicability.

In draft 04, the wording obscured the connection between
keyword independence and container/child independence.
I thought I needed this primitive type vs child validation
section even with the rewritten keywords, but going over
it now based on feedback, I agree that it is superfluous.

The list of non-independent keywords has been updated to
include minimum/maximum and their "exclusive" booleans.
  • Loading branch information
@handrews
handrews committed Nov 17, 2016
1 parent b5afae7 commit f28a7f6
Showing 1 changed file with 50 additions and 36 deletions.
86 changes: 50 additions & 36 deletions jsonschema-validation.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -156,54 +156,68 @@

<section title="General validation considerations">

<section title="Keywords and instance primitive types">
<section title="Constraints and missing keywords">
<t>
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.
</t>
<t>
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.
</t>
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.
</t>
<figure>
<preamble>
From this principle, it follows that all JSON values
successfully validate against the empty schema:
</preamble>
<artwork>
<![CDATA[
{}
]]>
</artwork>
</figure>
<figure>
<preamble>
Similarly, it follows that no JSON value successfully
validates against the empty schema's negation:
</preamble>
<artwork>
<![CDATA[
{
"not": {}
}
]]>
</artwork>
</figure>
</section>

<section title="Validation of primitive types and child values">
<t>
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.
</t>
<t>
For arrays, primitive type validation consists of validating restrictions on length.
</t>
<section title="Keyword independence">
<t>
For objects, primitive type validation consists of validating restrictions on the presence
or absence of property names.
Validation keywords typically operate independently, without
affecting each other's outcomes.
</t>
</section>

<section title="Missing keywords">
<t>
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.
For schema author convenience, there are some exceptions:
<list>
<t>"additionalProperties", whose behavior is defined in terms of "properties" and "patternProperties"</t>
<t>"additionalItems", whose behavior is defined in terms of "items"</t>
<t>"minimum" and "maximum", whose behaviors are modified by "exclusiveMinimum" and "exclusiveMaximum", respectively</t>
</list>
</t>
</section>

<section title="Linearity">
<!-- I call this "linear" in the same manner e.g. waves are linear, they don't interact with each other -->
<section title="Keywords and instance primitive types">
<t>
Validation keywords typically operate independent of each other, without affecting each other.
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.
</t>
<t>
For author convienence, there are some exceptions:
<list>
<t>"additionalProperties", whose behavior is defined in terms of "properties" and "patternProperties"; and</t>
<t>"additionalItems", whose behavior is defined in terms of "items"</t>
</list>
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.
</t>
</section>

</section>

<section title="Validation keywords">
Expand Down Expand Up @@ -505,7 +519,7 @@
</t>
<t>
For all such properties, child validation succeeds if the child instance
validates agains the "additionalProperties" schema.
validates against the "additionalProperties" schema.
</t>
</section>

Expand Down Expand Up @@ -663,7 +677,7 @@
<t>
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.
</t>
<t>
Expand Down Expand Up @@ -812,11 +826,11 @@

<section title="Security considerations">
<t>
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.
</t>
<t>
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.
</t>
Expand Down

0 comments on commit f28a7f6

Please sign in to comment.