Skip to content

Commit a469d9b

Browse files
gregsdennisgregsdennis
committed
updated output structure description, example schema and instances, and explanation of results
1 parent 91fea47 commit a469d9b

File tree

1 file changed

+146
-58
lines changed

1 file changed

+146
-58
lines changed

‎jsonschema-core.xml‎

Lines changed: 146 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -2756,9 +2756,9 @@
27562756
Implementations MAY elect to provide additional information.
27572757
</t>
27582758

2759-
<section title="Keyword Relative Location">
2759+
<section title="Subschema Relative Location">
27602760
<t>
2761-
The relative location of the validating keyword that follows the path
2761+
The relative location of the validating subschema that follows the path
27622762
traversed through the schema. The value MUST be expressed as a JSON
27632763
Pointer, and it MUST include any by-reference applicators such as
27642764
"$ref" or "$dynamicRef".
@@ -2776,22 +2776,20 @@
27762776
</artwork>
27772777
</figure>
27782778
<t>
2779-
Note that this pointer may not be resolvable by the normal JSON Pointer process
2780-
due to the inclusion of these by-reference applicator keywords.
2779+
Note that this pointer may not be resolvable by the normal JSON Pointer process
2780+
due to the inclusion of these by-reference applicator keywords.
27812781
</t>
27822782
<t>
27832783
The JSON key for this information is "evaluationPath".
27842784
</t>
27852785
</section>
27862786

2787-
<section title="Keyword Absolute Location">
2787+
<section title="Subschema Absolute Location">
27882788
<t>
2789-
The absolute, dereferenced location of the validating keyword. The value MUST
2790-
be expressed as a full IRI using the canonical IRI of the relevant schema resource
2791-
with a JSON Pointer fragment, and it MUST NOT include by-reference applicators
2792-
such as "$ref" or "$dynamicRef" as non-terminal path components.
2793-
It MAY end in such keywords if the error or annotation is for that
2794-
keyword, such as an unresolvable reference.
2789+
The absolute, dereferenced location of the validating subschema. The value MUST
2790+
be expressed as a full IRI using the canonical IRI of the relevant
2791+
schema object, and it MUST NOT include by-reference applicators
2792+
such as "$ref" or "$dynamicRef" as path components.
27952793
<cref>
27962794
Note that "absolute" here is in the sense of "absolute filesystem path"
27972795
(meaning the complete location) rather than the "absolute-IRI"
@@ -2807,10 +2805,6 @@ https://example.com/schemas/common#/$defs/count/minimum
28072805
]]>
28082806
</artwork>
28092807
</figure>
2810-
<t>
2811-
This information MAY be omitted only if either the dynamic scope did not pass
2812-
over a reference or if the schema does not declare an absolute IRI as its "$id".
2813-
</t>
28142808
<t>
28152809
The JSON key for this information is "schemaLocation".
28162810
</t>
@@ -2826,32 +2820,48 @@ https://example.com/schemas/common#/$defs/count/minimum
28262820
</t>
28272821
</section>
28282822

2829-
<section title="Error or Annotation">
2823+
<section title="Errors">
28302824
<t>
2831-
The error or annotation that is produced by the validation.
2825+
Any errors produced by the validation. This property MUST NOT
2826+
be included if the validation was successful. The value
2827+
for this property is an object where the keys are the names of
2828+
keywords and the values are the error message produced by the
2829+
associated keyword.
28322830
</t>
28332831
<t>
2834-
For errors, the specific wording for the message is not defined by this
2832+
The specific wording for the message is not defined by this
28352833
specification. Implementations will need to provide this.
28362834
</t>
28372835
<t>
2838-
For annotations, each keyword that produces an annotation specifies its
2839-
format. By default, it is the keyword's value.
2836+
The JSON key for this information is "errors".
2837+
</t>
2838+
</section>
2839+
2840+
<section title="Annotations">
2841+
<t>
2842+
Any annotations produced by the validation. This property MUST NOT
2843+
be included if the validation was unsuccessful. The value
2844+
for this property is an object where the keys are the names of
2845+
keywords and the values are the annotations produced by the
2846+
associated keyword.
2847+
</t>
2848+
<t>
2849+
Each keyword defines its own annotation data type (e.g. "properties"
2850+
produces a list of keywords, whereas "$title" produces a string).
28402851
</t>
28412852
<t>
2842-
The JSON key for failed validations is "error"; for successful validations
2843-
it is "annotation".
2853+
The JSON key for this information is "annotations".
28442854
</t>
28452855
</section>
28462856

28472857
<section title="Nested Results">
28482858
<t>
28492859
For "basic", this property will appear only at the root node and will hold
2850-
all errors or annotations in a list.
2860+
all results in a flat list.
28512861
</t>
28522862
<t>
2853-
For "detailed" and "verbose", this property will hold nested errors
2854-
and annotations in a tree structure, mimicking that of the schema.
2863+
For "detailed" and "verbose", this property will hold nested results
2864+
in a tree structure, mimicking that of the schema.
28552865
</t>
28562866
<t>
28572867
The JSON key for nested results is "nested".
@@ -2871,67 +2881,145 @@ https://example.com/schemas/common#/$defs/count/minimum
28712881
failure
28722882
</t>
28732883
<t>
2874-
"nested" - the collection of errors or annotations produced by a keyword
2884+
"nested" - the collection of errors or annotations produced by a subschema
28752885
</t>
28762886
</list>
2877-
For these examples, the following schema and instance will be used.
2887+
For these examples, the following schema and instances will be used.
28782888
</t>
28792889
<figure>
28802890
<artwork>
28812891
<![CDATA[
2892+
// schema
28822893
{
2883-
"$id": "https://example.com/polygon",
28842894
"$schema": "https://json-schema.org/draft/next/schema",
2885-
"$defs": {
2886-
"point": {
2895+
"$id": "https://json-schema.org/schemas/example",
2896+
"type": "object",
2897+
"title": "root",
2898+
"properties": {
2899+
"foo": {
28872900
"type": "object",
2901+
"title": "foo-title",
28882902
"properties": {
2889-
"x": { "type": "number" },
2890-
"y": { "type": "number" }
2891-
},
2892-
"additionalProperties": false,
2893-
"required": [ "x", "y" ]
2903+
"foo-prop": {
2904+
"const": 1,
2905+
"title": "foo-prop-title"
2906+
}
2907+
}
2908+
},
2909+
"bar": {
2910+
"$ref": "#/$defs/bar"
28942911
}
28952912
},
2896-
"type": "array",
2897-
"items": { "$ref": "#/$defs/point" },
2898-
"minItems": 3
2913+
"$defs": {
2914+
"bar": {
2915+
"type": "object",
2916+
"title": "bar-title",
2917+
"properties": {
2918+
"bar-prop": {
2919+
"type": "integer",
2920+
"minimum": 10,
2921+
"title": "bar-prop-title"
2922+
}
2923+
}
2924+
}
2925+
}
28992926
}
29002927
2901-
[
2902-
{
2903-
"x": 2.5,
2904-
"y": 1.3
2905-
},
2906-
{
2907-
"x": 1,
2908-
"z": 6.7
2909-
}
2910-
]
2928+
// failing instance
2929+
{
2930+
"foo": {"foo-prop": "not 1"},
2931+
"bar": {"bar-prop": 2}
2932+
}
2933+
2934+
// passing instance
2935+
{
2936+
"foo": {"foo-prop": 1},
2937+
"bar": {"bar-prop": 20}
2938+
}
29112939
]]>
29122940
</artwork>
29132941
</figure>
29142942
<t>
2915-
This instance will fail validation and produce errors, but it's trivial to deduce
2916-
examples for passing schemas that produce annotations.
2943+
The failing instance will produce the following errors:
2944+
<list>
2945+
<t>
2946+
The value at "/foo/foo-prop"
2947+
validated at "/properties/foo/properties/foo-prop"
2948+
by following the path "/properties/foo/properties/foo-prop"
2949+
by the "const" keyword
2950+
is not the constant value 1.
2951+
</t>
2952+
<t>
2953+
The value at "/bar/bar-prop"
2954+
validated at "/$defs/bar/properties/bar-prop"
2955+
by following the path "/properties/bar/$ref/properties/bar-prop"
2956+
by the "type" keyword
2957+
is not a number.
2958+
</t>
2959+
</list>
2960+
<cref>
2961+
"minimum" doesn't produce an error because it only operates on
2962+
instances that are numbers.
2963+
</cref>
2964+
<cref>
2965+
Note that the error message wording as depicted in the examples below is not a
2966+
requirement of this specification. Implementations SHOULD craft error messages
2967+
tailored for their audience or provide a templating mechanism that allows their
2968+
users to craft their own messages.
2969+
</cref>
29172970
</t>
29182971
<t>
2919-
Specifically, the errors it will produce are:
2972+
The passing instance will produce the following annotations:
29202973
<list>
29212974
<t>
2922-
The second object is missing a "y" property.
2975+
The keyword "title"
2976+
validated at ""
2977+
by following the path ""
2978+
will produce "root".
2979+
</t>
2980+
<t>
2981+
The keyword "properties"
2982+
validated at ""
2983+
by following the path ""
2984+
will produce "["foo", "bar"]".
2985+
</t>
2986+
<t>
2987+
The keyword "title"
2988+
validated at "/properties/foo"
2989+
by following the path "/properties/foo"
2990+
will produce "foo-title".
2991+
</t>
2992+
<t>
2993+
The keyword "properties"
2994+
validated at "/properties/foo"
2995+
by following the path "/properties/foo"
2996+
will produce "["foo-prop"]".
2997+
</t>
2998+
<t>
2999+
The keyword "title"
3000+
validated at "/properties/foo/properties/foo-prop"
3001+
by following the path "/properties/foo/properties/foo-prop"
3002+
will produce "foo-prop-title".
3003+
</t>
3004+
<t>
3005+
The keyword "title"
3006+
validated at "/$defs/bar"
3007+
by following the path "/properties/bar/$ref"
3008+
will produce "bar-title".
29233009
</t>
29243010
<t>
2925-
The second object has a disallowed "z" property.
3011+
The keyword "properties"
3012+
validated at "/$defs/bar"
3013+
by following the path "/properties/var/$ref"
3014+
will produce "["bar-prop"]".
29263015
</t>
29273016
<t>
2928-
There are only two objects, but three are required.
3017+
The keyword "title"
3018+
validated at "/$defs/bar/properties/bar-prop"
3019+
by following the path "/properties/bar/$ref/properties/bar-prop"
3020+
will produce "bar-prop-title".
29293021
</t>
29303022
</list>
2931-
Note that the error message wording as depicted in these examples is not a
2932-
requirement of this specification. Implementations SHOULD craft error messages
2933-
tailored for their audience or provide a templating mechanism that allows their
2934-
users to craft their own messages.
29353023
</t>
29363024

29373025
<section title="Flag">

0 commit comments

Comments
 (0)