812
812
location, annotation keywords need to specify any unusual handling of
813
813
multiple applicable occurrences of the keyword with different values.
814
814
</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 >
821
815
<t >
822
816
Unlike assertion results, annotation data can take a wide variety of forms,
823
817
which are provided to applications to use as they see fit. JSON Schema
824
818
implementations are not expected to make use of the collected information
825
819
on behalf of applications.
826
820
</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 >
827
828
<t >
828
829
While "short-circuit" evaluation is possible for assertions, collecting
829
830
annotations requires examining all schemas that apply to an instance
830
831
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.
831
835
</t >
832
836
833
837
<section title =" Collecting Annotations" >
863
867
If the same keyword attaches values from multiple schema locations
864
868
to the same instance location, and the annotation defines a process
865
869
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.
867
873
</t >
868
874
<section title =" Distinguishing Among Multiple Values" >
869
875
<t >
2654
2660
<figure >
2655
2661
<artwork >
2656
2662
<![CDATA[
2657
- #/properties/minLength /$ref/minimum
2663
+ #/properties/width /$ref/minimum
2658
2664
]]>
2659
2665
</artwork >
2660
2666
</figure >
2661
2667
<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.
2664
2670
</t >
2665
2671
<t >
2666
2672
The JSON key for this information is "keywordLocation".
2670
2676
<section title =" Keyword Absolute Location" >
2671
2677
<t >
2672
2678
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.
2675
2684
</t >
2676
2685
<figure >
2677
2686
<artwork >
2678
2687
<![CDATA[
2679
- https://json-schema.org/draft/2019-08/schema #/$defs/nonNegativeInteger /minimum
2688
+ https://example.com/schemas/common #/$defs/count /minimum
2680
2689
]]>
2681
2690
</artwork >
2682
2691
</figure >
@@ -2692,7 +2701,7 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
2692
2701
<section title =" Instance Location" >
2693
2702
<t >
2694
2703
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.
2696
2705
</t >
2697
2706
<t >
2698
2707
The JSON key for this information is "instanceLocation".
@@ -2707,6 +2716,10 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
2707
2716
For errors, the specific wording for the message is not defined by this
2708
2717
specification. Implementations will need to provide this.
2709
2718
</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 >
2710
2723
<t >
2711
2724
The JSON key for failed validations is "error"; for successful validations
2712
2725
it is "annotation".
@@ -2720,7 +2733,8 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
2720
2733
</t >
2721
2734
<t >
2722
2735
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.
2724
2738
</t >
2725
2739
</section >
2726
2740
0 commit comments