Skip to content

Make properties/items wording consistent. #111

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Nov 4, 2016
Merged

Make properties/items wording consistent. #111

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a9d2d3b
Make properties/items wording consistent.
handrews Oct 25, 2016
a0979f3
Futher clarify primitive vs child validation.
handrews Nov 3, 2016
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
98 changes: 73 additions & 25 deletions jsonschema-validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,20 @@
</t>
</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>
<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.
Expand Down Expand Up @@ -297,32 +311,45 @@
</t>
</section>

<section title="additionalItems and items">
<section title="items">
<t>
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.
</t>
<t>
The value of "items" MUST be either a schema or array of schemas.
If absent, it can be considered present with an empty schema.
</t>
<t>
Successful validation of an array instance with regards to these two
keywords is determined as follows:
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
</t>
<t>
If "items" is a schema, child validation succeeds if all elements
in the array successfully validate against that schema.
</t>
<t>
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.
</t>
</section>

<list>
<t>if "items" is not present, or its value is an object, validation
of the instance always succeeds, regardless of the value of
"additionalItems";</t>
<t>if the value of "additionalItems" is boolean value true or an
object, validation of the instance always succeeds;</t>
<t>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".</t>
</list>
<section title="additionalItems">
<t>
The value of "additionalItems" MUST be a boolean or an object.
If it is an object, the object MUST be a valid JSON Schema.
</t>
<t>
If absent, it can be considered present with an empty schema.
</t>
<t>
If either keyword is absent, it may be considered present with an empty
schema.
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
</t>
<t>
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".
</t>
</section>

Expand Down Expand Up @@ -415,6 +442,15 @@
<t>
If absent, it can be considered the same as an empty object.
</t>
<t>
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
</t>
<t>
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.
</t>
</section>

<section title="patternProperties">
Expand All @@ -427,27 +463,39 @@
<t>
If absent, it can be considered the same as an empty object.
</t>
<t>
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
</t>
<t>
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.
</t>
</section>

<section title="additionalProperties">
<t>
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has the effect of only permitting schemas that happen to be objects; it's entirely possible schemas might also take the form of a boolean, and in earlier drafts they could be a string, too.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It says:

MUST be a boolean or an object.

which I think allows for booleans? The separation of "or a schema" into "or an object. If it is..." was done to make it the same as all of the other keywords that specify a boolean or a schema.

I am not aware of anywhere recent, including either the current draft or draft 04, that allowed strings for schemas in general or for this keyword in particular, so I am unclear on your purpose for that comment.

Copy link
Member

@awwright awwright Nov 4, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. Iirc I was trying to make it consistent the other way, because saying "If it's an object, then it's a schema" seems redundant when a schema is already defined to be an object. I'll consider making that change if you don't see any problems with that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was about to put up a pull request for #101 which updates all of this a little bit by no longer requiring the boolean case to be specially explained in two places.

I think my wording for that accomplishes your goal, and if not, definitely feel free to fix it in another way. I'll have the PR up later today.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@awwright : PR #128 has the new wording.

</t>
<t>
If "additionalProperties" is absent, it may be considered present with
an empty schema as a value.
</t>
<t>
If "additionalProperties" is true, validation always succeeds.
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
</t>
<t>
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".
Child validation with "additionalProperties" applies only to the child
values of instance names that do not match any names in "properties",
and do not match any regular expression in "patternProperties".
</t>
<t>
If "additionalProperties" is an object, validate the value as a schema to all
of the properties that weren't validated by "properties" nor "patternProperties".
For all such properties, child validation succeeds if the child instance
validates agains the "additionalProperties" schema.
</t>
</section>

Expand Down