Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 475757c

Browse files
updated output structure description, example schema and instances, and explanation of results
1 parent 4d1f63f commit 475757c

File tree

1 file changed

+144
-56
lines changed

1 file changed

+144
-56
lines changed

‎jsonschema-core.xml

Lines changed: 144 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -2702,9 +2702,9 @@
27022702
Implementations MAY elect to provide additional information.
27032703
</t>
27042704

2705-
<section title="Keyword Relative Location">
2705+
<section title="Subschema Relative Location">
27062706
<t>
2707-
The relative location of the validating keyword that follows the path
2707+
The relative location of the validating subschema that follows the path
27082708
traversed through the schema. The value MUST be expressed as a JSON
27092709
Pointer, and it MUST include any by-reference applicators such as
27102710
"$ref" or "$dynamicRef".
@@ -2722,22 +2722,20 @@
27222722
</artwork>
27232723
</figure>
27242724
<t>
2725-
Note that this pointer may not be resolvable by the normal JSON Pointer process
2726-
due to the inclusion of these by-reference applicator keywords.
2725+
Note that this pointer may not be resolvable by the normal JSON Pointer process
2726+
due to the inclusion of these by-reference applicator keywords.
27272727
</t>
27282728
<t>
27292729
The JSON key for this information is "evaluationPath".
27302730
</t>
27312731
</section>
27322732

2733-
<section title="Keyword Absolute Location">
2733+
<section title="Subschema Absolute Location">
27342734
<t>
2735-
The absolute, dereferenced location of the validating keyword. The value MUST
2735+
The absolute, dereferenced location of the validating subschema. The value MUST
27362736
be expressed as a full IRI using the canonical IRI of the relevant
27372737
schema object, and it MUST NOT include by-reference applicators
2738-
such as "$ref" or "$dynamicRef" as non-terminal path components.
2739-
It MAY end in such keywords if the error or annotation is for that
2740-
keyword, such as an unresolvable reference.
2738+
such as "$ref" or "$dynamicRef" as path components.
27412739
<cref>
27422740
Note that "absolute" here is in the sense of "absolute filesystem path"
27432741
(meaning the complete location) rather than the "absolute-IRI"
@@ -2753,10 +2751,6 @@ https://example.com/schemas/common#/$defs/count/minimum
27532751
]]>
27542752
</artwork>
27552753
</figure>
2756-
<t>
2757-
This information MAY be omitted only if either the dynamic scope did not pass
2758-
over a reference or if the schema does not declare an absolute IRI as its "$id".
2759-
</t>
27602754
<t>
27612755
The JSON key for this information is "schemaLocation".
27622756
</t>
@@ -2772,32 +2766,48 @@ https://example.com/schemas/common#/$defs/count/minimum
27722766
</t>
27732767
</section>
27742768

2775-
<section title="Error or Annotation">
2769+
<section title="Errors">
27762770
<t>
2777-
The error or annotation that is produced by the validation.
2771+
Any errors produced by the validation. This property MUST NOT
2772+
be included if the validation was successful. The value
2773+
for this property is an object where the keys are the names of
2774+
keywords and the values are the error message produced by the
2775+
associated keyword.
27782776
</t>
27792777
<t>
2780-
For errors, the specific wording for the message is not defined by this
2778+
The specific wording for the message is not defined by this
27812779
specification. Implementations will need to provide this.
27822780
</t>
27832781
<t>
2784-
For annotations, each keyword that produces an annotation specifies its
2785-
format. By default, it is the keyword's value.
2782+
The JSON key for this information is "errors".
2783+
</t>
2784+
</section>
2785+
2786+
<section title="Annotations">
2787+
<t>
2788+
Any annotations produced by the validation. This property MUST NOT
2789+
be included if the validation was unsuccessful. The value
2790+
for this property is an object where the keys are the names of
2791+
keywords and the values are the annotations produced by the
2792+
associated keyword.
2793+
</t>
2794+
<t>
2795+
Each keyword defines its own annotation data type (e.g. "properties"
2796+
produces a list of keywords, whereas "$title" produces a string).
27862797
</t>
27872798
<t>
2788-
The JSON key for failed validations is "error"; for successful validations
2789-
it is "annotation".
2799+
The JSON key for this information is "annotations".
27902800
</t>
27912801
</section>
27922802

27932803
<section title="Nested Results">
27942804
<t>
27952805
For "basic", this property will appear only at the root node and will hold
2796-
all errors or annotations in a list.
2806+
all results in a flat list.
27972807
</t>
27982808
<t>
2799-
For "detailed" and "verbose", this property will hold nested errors
2800-
and annotations in a tree structure, mimicking that of the schema.
2809+
For "detailed" and "verbose", this property will hold nested results
2810+
in a tree structure, mimicking that of the schema.
28012811
</t>
28022812
<t>
28032813
The JSON key for nested results is "nested".
@@ -2817,67 +2827,145 @@ https://example.com/schemas/common#/$defs/count/minimum
28172827
failure
28182828
</t>
28192829
<t>
2820-
"nested" - the collection of errors or annotations produced by a keyword
2830+
"nested" - the collection of errors or annotations produced by a subschema
28212831
</t>
28222832
</list>
2823-
For these examples, the following schema and instance will be used.
2833+
For these examples, the following schema and instances will be used.
28242834
</t>
28252835
<figure>
28262836
<artwork>
28272837
<![CDATA[
2838+
// schema
28282839
{
2829-
"$id": "https://example.com/polygon",
28302840
"$schema": "https://json-schema.org/draft/next/schema",
2831-
"$defs": {
2832-
"point": {
2841+
"$id": "https://json-schema.org/schemas/example",
2842+
"type": "object",
2843+
"title": "root",
2844+
"properties": {
2845+
"foo": {
28332846
"type": "object",
2847+
"title": "foo-title",
28342848
"properties": {
2835-
"x": { "type": "number" },
2836-
"y": { "type": "number" }
2837-
},
2838-
"additionalProperties": false,
2839-
"required": [ "x", "y" ]
2849+
"foo-prop": {
2850+
"const": 1,
2851+
"title": "foo-prop-title"
2852+
}
2853+
}
2854+
},
2855+
"bar": {
2856+
"$ref": "#/$defs/bar"
28402857
}
28412858
},
2842-
"type": "array",
2843-
"items": { "$ref": "#/$defs/point" },
2844-
"minItems": 3
2859+
"$defs": {
2860+
"bar": {
2861+
"type": "object",
2862+
"title": "bar-title",
2863+
"properties": {
2864+
"bar-prop": {
2865+
"type": "integer",
2866+
"minimum": 10,
2867+
"title": "bar-prop-title"
2868+
}
2869+
}
2870+
}
2871+
}
28452872
}
28462873
2847-
[
2848-
{
2849-
"x": 2.5,
2850-
"y": 1.3
2851-
},
2852-
{
2853-
"x": 1,
2854-
"z": 6.7
2855-
}
2856-
]
2874+
// failing instance
2875+
{
2876+
"foo": {"foo-prop": "not 1"},
2877+
"bar": {"bar-prop": 2}
2878+
}
2879+
2880+
// passing instance
2881+
{
2882+
"foo": {"foo-prop": 1},
2883+
"bar": {"bar-prop": 20}
2884+
}
28572885
]]>
28582886
</artwork>
28592887
</figure>
28602888
<t>
2861-
This instance will fail validation and produce errors, but it's trivial to deduce
2862-
examples for passing schemas that produce annotations.
2889+
The failing instance will produce the following errors:
2890+
<list>
2891+
<t>
2892+
The value at "/foo/foo-prop"
2893+
validated at "/properties/foo/properties/foo-prop"
2894+
by following the path "/properties/foo/properties/foo-prop"
2895+
by the "const" keyword
2896+
is not the constant value 1.
2897+
</t>
2898+
<t>
2899+
The value at "/bar/bar-prop"
2900+
validated at "/$defs/bar/properties/bar-prop"
2901+
by following the path "/properties/bar/$ref/properties/bar-prop"
2902+
by the "type" keyword
2903+
is not a number.
2904+
</t>
2905+
</list>
2906+
<cref>
2907+
"minimum" doesn't produce an error because it only operates on
2908+
instances that are numbers.
2909+
</cref>
2910+
<cref>
2911+
Note that the error message wording as depicted in the examples below is not a
2912+
requirement of this specification. Implementations SHOULD craft error messages
2913+
tailored for their audience or provide a templating mechanism that allows their
2914+
users to craft their own messages.
2915+
</cref>
28632916
</t>
28642917
<t>
2865-
Specifically, the errors it will produce are:
2918+
The passing instance will produce the following annotations:
28662919
<list>
28672920
<t>
2868-
The second object is missing a "y" property.
2921+
The keyword "title"
2922+
validated at ""
2923+
by following the path ""
2924+
will produce "root".
2925+
</t>
2926+
<t>
2927+
The keyword "properties"
2928+
validated at ""
2929+
by following the path ""
2930+
will produce "["foo", "bar"]".
2931+
</t>
2932+
<t>
2933+
The keyword "title"
2934+
validated at "/properties/foo"
2935+
by following the path "/properties/foo"
2936+
will produce "foo-title".
2937+
</t>
2938+
<t>
2939+
The keyword "properties"
2940+
validated at "/properties/foo"
2941+
by following the path "/properties/foo"
2942+
will produce "["foo-prop"]".
2943+
</t>
2944+
<t>
2945+
The keyword "title"
2946+
validated at "/properties/foo/properties/foo-prop"
2947+
by following the path "/properties/foo/properties/foo-prop"
2948+
will produce "foo-prop-title".
2949+
</t>
2950+
<t>
2951+
The keyword "title"
2952+
validated at "/$defs/bar"
2953+
by following the path "/properties/bar/$ref"
2954+
will produce "bar-title".
28692955
</t>
28702956
<t>
2871-
The second object has a disallowed "z" property.
2957+
The keyword "properties"
2958+
validated at "/$defs/bar"
2959+
by following the path "/properties/var/$ref"
2960+
will produce "["bar-prop"]".
28722961
</t>
28732962
<t>
2874-
There are only two objects, but three are required.
2963+
The keyword "title"
2964+
validated at "/$defs/bar/properties/bar-prop"
2965+
by following the path "/properties/bar/$ref/properties/bar-prop"
2966+
will produce "bar-prop-title".
28752967
</t>
28762968
</list>
2877-
Note that the error message wording as depicted in these examples is not a
2878-
requirement of this specification. Implementations SHOULD craft error messages
2879-
tailored for their audience or provide a templating mechanism that allows their
2880-
users to craft their own messages.
28812969
</t>
28822970

28832971
<section title="Flag">

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /