Skip to content

Improve guidance on annotations and output #787

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
Sep 3, 2019
Merged

Improve guidance on annotations and output #787

Show file tree
Hide file tree
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
44 changes: 29 additions & 15 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -812,22 +812,26 @@
location, annotation keywords need to specify any unusual handling of
multiple applicable occurrences of the keyword with different values.
</t>
<t>
The default behavior is simply to collect all values in a list in
indeterminate order. Given the extensibility of keywords, including
applicators, it is not possible to define a universally predictable
order of processing.
Copy link

Choose a reason for hiding this comment

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

Seems like the spec is moving towards defining rules for handling annotations in overlapping subschemas (as this paragraph is removed, and the wording in readOnly and writeOnly show), which is good.

</t>
<t>
Unlike assertion results, annotation data can take a wide variety of forms,
which are provided to applications to use as they see fit. JSON Schema
implementations are not expected to make use of the collected information
on behalf of applications.
</t>
<t>
Unless otherwise specified, the value of an annotation keyword's
annotation is the keyword's value. However, other behaviors are possible.
For example, <xref target="json-hyper-schema">JSON Hyper-Schema's</xref>
"links" keyword is a complex annotation that produces a value based
in part on the instance data.
</t>
<t>
While "short-circuit" evaluation is possible for assertions, collecting
annotations requires examining all schemas that apply to an instance
location, even if they cannot change the overall assertion result.
The only exception is that subschemas of a schema object that has
failed validation MAY be skipped, as annotations are not retained
for failing schemas.
</t>

<section title="Collecting Annotations">
Expand Down Expand Up @@ -863,7 +867,9 @@
If the same keyword attaches values from multiple schema locations
to the same instance location, and the annotation defines a process
for combining such values, then the combined value MUST also be associated
with the instance location.
with the instance location. The <xref target="output">output formats</xref>
described in this specification that include annotation information
meet this requirement.
</t>
<section title="Distinguishing Among Multiple Values">
<t>
Expand Down Expand Up @@ -2649,13 +2655,13 @@
<figure>
<artwork>
<![CDATA[
#/properties/minLength/$ref/minimum
#/properties/width/$ref/minimum
]]>
</artwork>
</figure>
<t>
Note that this pointer may not be resolvable due to the inclusion of these
applicator keywords.
Note that this pointer may not be resolvable by the normal JSON Pointer process
due to the inclusion of these by-reference applicator keywords.
</t>
<t>
The JSON key for this information is "keywordLocation".
Expand All @@ -2665,13 +2671,16 @@
<section title="Keyword Absolute Location">
<t>
The absolute, dereferenced location of the validating keyword. The value MUST
be expressed as an absolute URI, and it MUST NOT include by-reference applicators
such as "$ref" or "$recursiveRef".
be expressed as an absolute URI using the canonical URI of the relevant
schema object, and it MUST NOT include by-reference applicators
such as "$ref" or "$recursiveRef" as non-terminal path components.
It MAY end in such keywords if the error or annotation is for that
keyword, such as an unresolvable reference.
</t>
<figure>
<artwork>
<![CDATA[
https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
https://example.com/schemas/common#/$defs/count/minimum
]]>
</artwork>
</figure>
Expand All @@ -2687,7 +2696,7 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
<section title="Instance Location">
<t>
The location of the JSON value within the instance being validated. The
value MUST be expressed as a JSON Pointer.
value MUST be expressed as a URI fragment-encoded JSON Pointer.
</t>
<t>
The JSON key for this information is "instanceLocation".
Expand All @@ -2702,6 +2711,10 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
For errors, the specific wording for the message is not defined by this
specification. Implementations will need to provide this.
</t>
<t>
For annotations, each keyword that produces an annotation specifies its
format. By default, it is the keyword's value.
</t>
<t>
The JSON key for failed validations is "error"; for successful validations
it is "annotation".
Expand All @@ -2715,7 +2728,8 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
</t>
<t>
The JSON key for nested results in failed validations is "errors"; for
successful validations it is "annotations".
successful validations it is "annotations". Note the plural forms, as
a keyword with nested results can also have a local error or annotation.
</t>
</section>

Expand Down
17 changes: 9 additions & 8 deletions jsonschema-validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,10 @@
<t>
This specification defines a set of assertion keywords, as well as a small vocabulary
of metadata keywords that can be used to annotate the JSON instance with
useful information. The <xref target="format" /> and <xref target="content" />
keywords are also useful as annotations as well as being optional assertions,
as they convey additional usage guidance for the instance data.
useful information. The <xref target="format" /> keyword is intended primarily
as an annotation, but can optionally be used as an assertion. The
<xref target="content" /> keywords are annotations for working with documents
embedded as JSON strings.
</t>
</section>

Expand Down Expand Up @@ -1157,9 +1158,9 @@
<section title='"deprecated"'>
<t>
The value of this keyword MUST be a boolean. When multiple occurrences
of this keyword are applicable to a single sub-instance, the resulting
value MUST be true if any occurrence specifies a true value, and MUST
be false otherwise.
of this keyword are applicable to a single sub-instance, applications
SHOULD consider the instance location to be deprecated if any occurrence
specifies a true value.
</t>
<t>
If "deprecated" has a value of boolean true, it indicates that applications
Expand All @@ -1179,8 +1180,8 @@
<t>
The value of these keywords MUST be a boolean. When multiple occurrences
of these keywords are applicable to a single sub-instance, the resulting
value MUST be true if any occurrence specifies a true value, and MUST
be false otherwise.
behavior SHOULD be as for a true value if any occurrence specifies a true value,
and SHOULD be as for a false value otherwise.
</t>
<t>
If "readOnly" has a value of boolean true, it indicates that the value
Expand Down