Skip to content

Commit d9e5b38

Browse files
authored
Merge pull request #787 from handrews/no-rollup
Improve guidance on annotations and output
2 parents 71612be + 77d7f9e commit d9e5b38

File tree

2 files changed

+38
-23
lines changed

2 files changed

+38
-23
lines changed

jsonschema-core.xml

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -812,22 +812,26 @@
812812
location, annotation keywords need to specify any unusual handling of
813813
multiple applicable occurrences of the keyword with different values.
814814
</t>
815-
<t>
816-
The default behavior is simply to collect all values in a list in
817-
indeterminate order. Given the extensibility of keywords, including
818-
applicators, it is not possible to define a universally predictable
819-
order of processing.
820-
</t>
821815
<t>
822816
Unlike assertion results, annotation data can take a wide variety of forms,
823817
which are provided to applications to use as they see fit. JSON Schema
824818
implementations are not expected to make use of the collected information
825819
on behalf of applications.
826820
</t>
821+
<t>
822+
Unless otherwise specified, the value of an annotation keyword's
823+
annotation is the keyword's value. However, other behaviors are possible.
824+
For example, <xref target="json-hyper-schema">JSON Hyper-Schema's</xref>
825+
"links" keyword is a complex annotation that produces a value based
826+
in part on the instance data.
827+
</t>
827828
<t>
828829
While "short-circuit" evaluation is possible for assertions, collecting
829830
annotations requires examining all schemas that apply to an instance
830831
location, even if they cannot change the overall assertion result.
832+
The only exception is that subschemas of a schema object that has
833+
failed validation MAY be skipped, as annotations are not retained
834+
for failing schemas.
831835
</t>
832836

833837
<section title="Collecting Annotations">
@@ -863,7 +867,9 @@
863867
If the same keyword attaches values from multiple schema locations
864868
to the same instance location, and the annotation defines a process
865869
for combining such values, then the combined value MUST also be associated
866-
with the instance location.
870+
with the instance location. The <xref target="output">output formats</xref>
871+
described in this specification that include annotation information
872+
meet this requirement.
867873
</t>
868874
<section title="Distinguishing Among Multiple Values">
869875
<t>
@@ -2654,13 +2660,13 @@
26542660
<figure>
26552661
<artwork>
26562662
<![CDATA[
2657-
#/properties/minLength/$ref/minimum
2663+
#/properties/width/$ref/minimum
26582664
]]>
26592665
</artwork>
26602666
</figure>
26612667
<t>
2662-
Note that this pointer may not be resolvable due to the inclusion of these
2663-
applicator keywords.
2668+
Note that this pointer may not be resolvable by the normal JSON Pointer process
2669+
due to the inclusion of these by-reference applicator keywords.
26642670
</t>
26652671
<t>
26662672
The JSON key for this information is "keywordLocation".
@@ -2670,13 +2676,16 @@
26702676
<section title="Keyword Absolute Location">
26712677
<t>
26722678
The absolute, dereferenced location of the validating keyword. The value MUST
2673-
be expressed as an absolute URI, and it MUST NOT include by-reference applicators
2674-
such as "$ref" or "$recursiveRef".
2679+
be expressed as an absolute URI using the canonical URI of the relevant
2680+
schema object, and it MUST NOT include by-reference applicators
2681+
such as "$ref" or "$recursiveRef" as non-terminal path components.
2682+
It MAY end in such keywords if the error or annotation is for that
2683+
keyword, such as an unresolvable reference.
26752684
</t>
26762685
<figure>
26772686
<artwork>
26782687
<![CDATA[
2679-
https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
2688+
https://example.com/schemas/common#/$defs/count/minimum
26802689
]]>
26812690
</artwork>
26822691
</figure>
@@ -2692,7 +2701,7 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
26922701
<section title="Instance Location">
26932702
<t>
26942703
The location of the JSON value within the instance being validated. The
2695-
value MUST be expressed as a JSON Pointer.
2704+
value MUST be expressed as a URI fragment-encoded JSON Pointer.
26962705
</t>
26972706
<t>
26982707
The JSON key for this information is "instanceLocation".
@@ -2707,6 +2716,10 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
27072716
For errors, the specific wording for the message is not defined by this
27082717
specification. Implementations will need to provide this.
27092718
</t>
2719+
<t>
2720+
For annotations, each keyword that produces an annotation specifies its
2721+
format. By default, it is the keyword's value.
2722+
</t>
27102723
<t>
27112724
The JSON key for failed validations is "error"; for successful validations
27122725
it is "annotation".
@@ -2720,7 +2733,8 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
27202733
</t>
27212734
<t>
27222735
The JSON key for nested results in failed validations is "errors"; for
2723-
successful validations it is "annotations".
2736+
successful validations it is "annotations". Note the plural forms, as
2737+
a keyword with nested results can also have a local error or annotation.
27242738
</t>
27252739
</section>
27262740

jsonschema-validation.xml

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -137,9 +137,10 @@
137137
<t>
138138
This specification defines a set of assertion keywords, as well as a small vocabulary
139139
of metadata keywords that can be used to annotate the JSON instance with
140-
useful information. The <xref target="format" /> and <xref target="content" />
141-
keywords are also useful as annotations as well as being optional assertions,
142-
as they convey additional usage guidance for the instance data.
140+
useful information. The <xref target="format" /> keyword is intended primarily
141+
as an annotation, but can optionally be used as an assertion. The
142+
<xref target="content" /> keywords are annotations for working with documents
143+
embedded as JSON strings.
143144
</t>
144145
</section>
145146

@@ -1157,9 +1158,9 @@
11571158
<section title='"deprecated"'>
11581159
<t>
11591160
The value of this keyword MUST be a boolean. When multiple occurrences
1160-
of this keyword are applicable to a single sub-instance, the resulting
1161-
value MUST be true if any occurrence specifies a true value, and MUST
1162-
be false otherwise.
1161+
of this keyword are applicable to a single sub-instance, applications
1162+
SHOULD consider the instance location to be deprecated if any occurrence
1163+
specifies a true value.
11631164
</t>
11641165
<t>
11651166
If "deprecated" has a value of boolean true, it indicates that applications
@@ -1185,8 +1186,8 @@
11851186
<t>
11861187
The value of these keywords MUST be a boolean. When multiple occurrences
11871188
of these keywords are applicable to a single sub-instance, the resulting
1188-
value MUST be true if any occurrence specifies a true value, and MUST
1189-
be false otherwise.
1189+
behavior SHOULD be as for a true value if any occurrence specifies a true value,
1190+
and SHOULD be as for a false value otherwise.
11901191
</t>
11911192
<t>
11921193
If "readOnly" has a value of boolean true, it indicates that the value

0 commit comments

Comments
 (0)