Skip to content

Trivial: Split Keyword Behaviors in to better subsections #622

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
Jun 25, 2018
Merged

Trivial: Split Keyword Behaviors in to better subsections #622

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3365dc3
Split Keyword Behaviors in to better subsections
handrews Jun 22, 2018
7238156
Fix missing "s" typo
handrews Jun 22, 2018
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
90 changes: 47 additions & 43 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,13 @@
Applicators apply subschemas to parts of the instance and combine
their results.
</t>
<t>
Extension keywords SHOULD stay within these categories, keeping in mind
that annotations in particular are extremely flexible. Complex behavior
is usually better delegated to applications on the basis of annotation
data than implemented directly as schema keywords. However, extension
keywords MAY define other behaviors for specialized purposes.
</t>
<t>
Evaluating an instance against a schema involves processing all of the
keywords in the schema against the appropriate locations within the instance.
Expand All @@ -145,56 +152,53 @@
subschemas have been evaluated, although in some circumstance evaluation
may be short-circuited due to assertion results.
</t>
<t>
Keyword behavior MAY be defined in terms of the annotation results
of <xref target="root">subschemas</xref> and/or adjacent keywords.
Such keywords MUST NOT result in a circular dependency.
Keywords MAY modify their behavior based on the presence or absence
of another keyword in the same
<xref target="schema-document">schema object</xref>.
</t>
<t>
A missing keyword MUST NOT produce a false assertion result, MUST
NOT produce annotation results, and MUST NOT cause any other schema
to be evaluated as part of its own behavioral definition.
However, given that missing keywords do not contribute annotations,
the lack of annotation results may indirectly change the behavior
of other keywords.
</t>
<t>
In some cases, the missing keyword assertion behavior of a keyword is
identical to that produced by a certain value, and keyword definitions
SHOULD note such values where known. However, even if the value which
produces the default behavior would produce annotation results if
present, the default behavior still MUST NOT result in annotations.
</t>
<t>
Because annotation collection can add significant cost in terms of both
computation and memory, implementations MAY opt out of this feature.
Keywords known to an implementation to have assertion or applicator behavior
that depend on annotation results MUST then be treated as errors, unless
an alternate implementation producing the same behavior is available.
Keywords of this sort SHOULD describe reasonable alternate approaches
when appropriate. This approach is demonstrated by the
"<xref target="additionalItems" format="title"/>" and
"<xref target="additionalProperties" format="title"/>" keywords in this
document.
</t>
<t>
Extension keywords SHOULD stay within these categories, keeping in mind
that annotations in particular are extremely flexible. Complex behavior
is usually better delegated to applications on the basis of annotation
data than implemented directly as schema keywords. However, extension
keywords MAY define other behaviors for specialized purposes.
</t>
<section title="Keyword Interactions">
<t>
Keyword behavior MAY be defined in terms of the annotation results
of <xref target="root">subschemas</xref> and/or adjacent keywords.
Such keywords MUST NOT result in a circular dependency.
Keywords MAY modify their behavior based on the presence or absence
of another keyword in the same
<xref target="schema-document">schema object</xref>.
</t>
</section>
<section title="Default Behaviors">
<t>
A missing keyword MUST NOT produce a false assertion result, MUST
NOT produce annotation results, and MUST NOT cause any other schema
to be evaluated as part of its own behavioral definition.
However, given that missing keywords do not contribute annotations,
the lack of annotation results may indirectly change the behavior
of other keywords.
</t>
<t>
In some cases, the missing keyword assertion behavior of a keyword is
identical to that produced by a certain value, and keyword definitions
SHOULD note such values where known. However, even if the value which
produces the default behavior would produce annotation results if
present, the default behavior still MUST NOT result in annotations.
</t>
<t>
Because annotation collection can add significant cost in terms of both
computation and memory, implementations MAY opt out of this feature.
Keywords known to an implementation to have assertion or applicator behavior
that depend on annotation results MUST then be treated as errors, unless
an alternate implementation producing the same behavior is available.
Keywords of this sort SHOULD describe reasonable alternate approaches
when appropriate. This approach is demonstrated by the
"<xref target="additionalItems" format="title"/>" and
"<xref target="additionalProperties" format="title"/>" keywords in this
document.
</t>
</section>
<section title="Applicators" anchor="applicators">
<t>
Applicators allow for building more complex schemas than can be accomplished
with a single schema object. Evaluation of an instance against a
<xref target="schema-document">schema document</xref> begins by applying
the <xref target="root">root schema</xref> to the complete instance
document. From there, keywords known as applicators are used to determine
which additional subschemas are applied. Subschema may be applied in-place
which additional subschemas are applied. Subschemas may be applied in-place
to the current location, or to a child location. The subschemas may be all
or part of the keyword's value, or the keyword's value may identify one
or more schemas in a way defined by the keyword.
Expand Down