Skip to content

Improve child validation wording from feedback. #193

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 1 commit into from
Jan 23, 2017
Merged

Improve child validation wording from feedback. #193

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
52 changes: 33 additions & 19 deletions jsonschema-validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,15 +179,26 @@

<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.
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.
For arrays, primitive type validation consists of validating
restrictions on length with "minItems" and "maxItems", while
"items" and "additionalItems" determine which subschemas apply
to which elements of the array. In addition, "uniqueItems"
Copy link
Member

Choose a reason for hiding this comment

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

I find the phrasing

...control which subschemas apply to which elements of the array.

a little confusing. It may be just my lack of understanding though. Can you expand on this section please?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Those keywords tell you whether a given subschema applies to a given child instance or not.

This is the critically important point that differentiates these keywords from all others. Rather than applying rules to the immediate instance and producing a validation rule based on that, these keywords just say "the validation outcome of this keyword is simply the result of applying the subschema to certain child instances", and give you rules on which child instances are affected by the subschema.

Does that help?

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's extremely important because implementing these is different from implementing other keywords. There are basically four types of validation keywords:

  • Immediate instance keywords (most of them)
  • Apply-subschema-to-child-instance keywords (these)
  • Logical combinations of schema results ("allOf"/"anyOf"/"oneOf"/"not"/"dependencies"/"if"-"then"-"else" assuming it eventually goes in)
  • Array content keywords ("uniqueItems" and "contains") that can only be evaluated by looking at the entire array and all of its contents

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 also highlights how these keywords (like "allOf"/"anyOf"/"oneOf"/"not") are important for more than just validation. All other vocabularies, such as hyper-schema, are pretty much useless without these keywords as they are the only way to apply other vocabularies to complex instances. The core vocabulary ("$schema", "$id", "$ref") does not provide any such mechanism, and vocabularies such as hyper-schema should not re-implement the process. These keywords and the logical keywords have implications far beyond validation.

and "contains" validate array contents as a whole.
</t>
<t>
For objects, primitive type validation consists of validating restrictions on the presence
or absence of property names.
For objects, primitive type validation consists of validating
restrictions on which and how many properties appear with
"required", "minProperties", "maxProperties", "propertyNames",
and the string array form of "dependencies", while "properties",
"patternProperties", and "additionalProperties" determine which
subschemas apply to which object property values.
Copy link
Member

Choose a reason for hiding this comment

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

I'd consider adding "... and do not directly validate the instance itself.", after reading your explanation at #161 (comment) I found your phrasing there explaining...

I recently rewrote the items, additionalItems, properties, patternProperties, and additionalProperties to make it clear that they do not directly validate the instance, but instead control which subschemas are applied to which child instances.

to actually be a clearer explanation that the changes you've made.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@Relequestual I have made the changes you requested and replaced "validation always succeeds" with "does not directly validate the instance itself."

In addition, the schema form of "dependencies" validates the
object as a whole based on the presence of specific property names.
</t>
</section>

Expand Down Expand Up @@ -335,8 +346,8 @@
If absent, it can be considered present with an empty schema.
</t>
<t>
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
This keyword determines how child instances validate for arrays,
and does not directly validate the immediate instance itself.
</t>
<t>
If "items" is a schema, child validation succeeds if all elements
Expand All @@ -357,8 +368,8 @@
If absent, it can be considered present with an empty schema.
</t>
<t>
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
This keyword determines how child instances validate for arrays,
and does not directly validate the immediate instance itself.
</t>
<t>
If "items" is an array of schemas, child validation succeeds
Expand Down Expand Up @@ -473,16 +484,17 @@
MUST be a valid JSON Schema.
</t>
<t>
If absent, it can be considered the same as an empty object.
If absent, it can be considered the same as an empty schema.
</t>
<t>
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
This keyword determines how child instances validate for objects,
and does not directly validate the immediate instance itself.
</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.
the instance and as a name within this keyword's value, the child
instance for that name successfully validates against the
corresponding schema.
</t>
</section>

Expand All @@ -494,11 +506,13 @@
MUST be a valid JSON Schema.
</t>
<t>
If absent, it can be considered the same as an empty object.
If absent, it can be considered the same as an empty schema.
</t>
<t>
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
This keyword determines how child instances validate for objects,
and does not directly validate the immediate instance itself.
Validation of the primitive instance type against this keyword
always succeeds.
</t>
<t>
Child validation succeeds if, for each instance name that matches any
Expand All @@ -517,8 +531,8 @@
an empty schema as a value.
</t>
<t>
This keyword controls child instance validation. Validation of the
primitive instance type against this keyword always succeeds.
This keyword determines how child instances validate for objects,
and does not directly validate the immediate instance itself.
</t>
<t>
Child validation with "additionalProperties" applies only to the child
Expand Down