Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add general validation principles and examples. #143

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 47 additions & 33 deletions jsonschema-validation.xml
Original file line number Diff line number Diff line change
Expand Up @@ -158,55 +158,69 @@

<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>
<section title="Keyword independence">
<t>
For arrays, primitive type validation consists of validating restrictions on length.
Validation keywords typically operate independently, without
affecting each other's outcomes.
</t>
<t>
For objects, primitive type validation consists of validating restrictions on the presence
or absence of property names.
</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 behavior may change for a special value of "exclusiveMinimum" and "exclusiveMaximum", respectively</t>
</list>
</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 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"; and</t>
<t>"minimum" and "maximum", whose behavior may change for a special value of "exclusiveMinimum" and "exclusiveMaximum", respectively.</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="Meta-schema">
Expand Down