Skip to content

Commit 32cabec

Browse files
committed
Add general validation principles and examples.
This paritally addresses issue #55 plus concerns raised in the comments of issue #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.
1 parent e784d5d commit 32cabec

File tree

1 file changed

+47
-33
lines changed

1 file changed

+47
-33
lines changed

jsonschema-validation.xml

Lines changed: 47 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -158,55 +158,69 @@
158158

159159
<section title="General validation considerations">
160160

161-
<section title="Keywords and instance primitive types">
161+
<section title="Constraints and missing keywords">
162162
<t>
163-
Most validation keywords only limit the range of values within a certain primitive type.
164-
When the primitive type of the instance is not of the type targeted by the keyword, the
165-
validation succeeds.
163+
Each JSON Schema validation keyword adds constraints that
164+
an instance must satisfy in order to successfully validate.
166165
</t>
167166
<t>
168-
For example, the "maxLength" keyword will only restrict certain strings (that are too long) from being valid.
169-
If the instance is a number, boolean, null, array, or object, the keyword passes validation.
170-
</t>
167+
Validation keywords that are missing never restrict validation.
168+
In some cases, this no-op behavior is identical to a keyword that
169+
exists with certain values, and these values are noted where relevant.
170+
</t>
171+
<figure>
172+
<preamble>
173+
From this principle, it follows that all JSON values
174+
successfully validate against the empty schema:
175+
</preamble>
176+
<artwork>
177+
<![CDATA[
178+
{}
179+
]]>
180+
</artwork>
181+
</figure>
182+
<figure>
183+
<preamble>
184+
Similarly, it follows that no JSON value successfully
185+
validates against the empty schema's negation:
186+
</preamble>
187+
<artwork>
188+
<![CDATA[
189+
{
190+
"not": {}
191+
}
192+
]]>
193+
</artwork>
194+
</figure>
171195
</section>
172196

173-
<section title="Validation of primitive types and child values">
174-
<t>
175-
Two of the primitive types, array and object, allow for child values. The validation of
176-
the primitive type is considered separately from the validation of child instances.
177-
</t>
197+
<section title="Keyword independence">
178198
<t>
179-
For arrays, primitive type validation consists of validating restrictions on length.
199+
Validation keywords typically operate independently, without
200+
affecting each other's outcomes.
180201
</t>
181202
<t>
182-
For objects, primitive type validation consists of validating restrictions on the presence
183-
or absence of property names.
184-
</t>
185-
</section>
186-
187-
<section title="Missing keywords">
188-
<t>
189-
Validation keywords that are missing never restrict validation.
190-
In some cases, this no-op behavior is identical to a keyword that exists with certain values,
191-
and these values are noted where known.
203+
For schema author convenience, there are some exceptions:
204+
<list>
205+
<t>"additionalProperties", whose behavior is defined in terms of "properties" and "patternProperties"</t>
206+
<t>"additionalItems", whose behavior is defined in terms of "items"</t>
207+
<t>"minimum" and "maximum", whose behavior may change for a special value of "exclusiveMinimum" and "exclusiveMaximum", respectively</t>
208+
</list>
209+
</list>
192210
</t>
193211
</section>
194212

195-
<section title="Linearity">
196-
<!-- I call this "linear" in the same manner e.g. waves are linear, they don't interact with each other -->
213+
<section title="Keywords and instance primitive types">
197214
<t>
198-
Validation keywords typically operate independent of each other, without affecting each other.
215+
Most validation keywords only limit the range of values within a certain primitive type.
216+
When the primitive type of the instance is not of the type targeted by the keyword, the
217+
validation succeeds.
199218
</t>
200219
<t>
201-
For author convenience, there are some exceptions:
202-
<list>
203-
<t>"additionalProperties", whose behavior is defined in terms of "properties" and "patternProperties";</t>
204-
<t>"additionalItems", whose behavior is defined in terms of "items"; and</t>
205-
<t>"minimum" and "maximum", whose behavior may change for a special value of "exclusiveMinimum" and "exclusiveMaximum", respectively.</t>
206-
</list>
220+
For example, the "maxLength" keyword will only restrict certain strings (that are too long) from being valid.
221+
If the instance is a number, boolean, null, array, or object, the keyword passes validation.
207222
</t>
208223
</section>
209-
210224
</section>
211225

212226
<section title="Meta-schema">

0 commit comments

Comments
 (0)