Skip to content

Commit 2ad7c4a

Browse files
gregsdennisgregsdennis
committed
removed 'detailed' format; added annotations examples; some rewording and clarifications
1 parent cf13b14 commit 2ad7c4a

File tree

1 file changed

+180
-93
lines changed

1 file changed

+180
-93
lines changed

‎jsonschema-core.xml

+180-93
Original file line numberDiff line numberDiff line change
@@ -2672,18 +2672,18 @@
26722672
Basic - Provides validation information in a flat list structure.
26732673
</t>
26742674
<t>
2675-
Detailed - Provides validation information in a condensed hierarchical
2676-
structure based on the structure of the schema.
2677-
</t>
2678-
<t>
2679-
Verbose - Provides validation information in an uncondensed hierarchical
2680-
structure that matches the exact structure of the schema.
2675+
Hierarchical - Provides validation information in a hierarchical
2676+
structure that mimics the structure of the schema.
2677+
<cref>
2678+
To be precise, this structure follows the paths that a validator
2679+
would traverse while processing the schema, including composition
2680+
via by-reference keywords.
2681+
</cref>
26812682
</t>
26822683
</list>
2683-
An implementation SHOULD provide at least one of the "flag", "basic", or "detailed"
2684-
format and MAY provide the "verbose" format. If it provides one or more of the
2685-
"detailed" or "verbose" formats, it MUST also provide the "flag" format.
2686-
Implementations SHOULD specify in their documentation which formats they support.
2684+
An implementation MUST provide the "flag" format and SHOULD provide at least one
2685+
of the "basic" or "hierarchical" formats. Implementations SHOULD specify in
2686+
their documentation which formats they support.
26872687
</t>
26882688

26892689
</section>
@@ -2770,7 +2770,7 @@ https://example.com/schemas/common#/$defs/count/minimum
27702770
<t>
27712771
Any errors produced by the validation. This property MUST NOT
27722772
be included if the validation was successful. The value
2773-
for this property is an object where the keys are the names of
2773+
for this property MUST be an object where the keys are the names of
27742774
keywords and the values are the error message produced by the
27752775
associated keyword. If the subschema itself is producing the
27762776
error, that error MUST be listed with an empty string key.
@@ -2788,7 +2788,7 @@ https://example.com/schemas/common#/$defs/count/minimum
27882788
<t>
27892789
Any annotations produced by the validation. This property MUST NOT
27902790
be included if the validation was unsuccessful. The value
2791-
for this property is an object where the keys are the names of
2791+
for this property MUST be an object where the keys are the names of
27922792
keywords and the values are the annotations produced by the
27932793
associated keyword.
27942794
</t>
@@ -2802,13 +2802,20 @@ https://example.com/schemas/common#/$defs/count/minimum
28022802
</section>
28032803

28042804
<section title="Nested Results">
2805+
<t>
2806+
Nested results are generated from applicator keywords: keywords with
2807+
subschemas or collections of subschemas as values. Keywords which
2808+
have arrays of subschemas (e.g. "anyOf") will generally generate an output
2809+
unit for each subschema. In order to accommodate potentially multiple
2810+
results, the value of this property MUST be an array of output units.
2811+
</t>
28052812
<t>
28062813
For "basic", this property will appear only at the root output unit
2807-
and will hold all results in a flat list.
2814+
and will hold all output units in a flat list.
28082815
</t>
28092816
<t>
2810-
For "detailed" and "verbose", this property will hold nested results
2811-
in a tree structure, mimicking that of the schema.
2817+
For "hierarchical", this property will hold nested results in a tree
2818+
structure, mimicking that of the schema.
28122819
</t>
28132820
<t>
28142821
The sequence of output units within this list is not specified and
@@ -2962,18 +2969,18 @@ https://example.com/schemas/common#/$defs/count/minimum
29622969
by following the path "/properties/foo/allOf/1"
29632970
will produce <sourcecode>["foo-prop"]</sourcecode>.
29642971
</t>
2965-
<t>
2966-
The keyword "title"
2967-
validated at "/properties/foo/allOf/1/properties/foo-prop"
2968-
by following the path "/properties/foo/allOf/1/properties/foo-prop"
2969-
will produce <sourcecode>"foo-prop-title"</sourcecode>.
2970-
</t>
29712972
<t>
29722973
The keyword "additionalProperties"
29732974
validated at "/properties/foo/allOf/1"
29742975
by following the path "/properties/foo/allOf/1"
29752976
will produce <sourcecode>["unspecified-prop"]</sourcecode>.
29762977
</t>
2978+
<t>
2979+
The keyword "title"
2980+
validated at "/properties/foo/allOf/1/properties/foo-prop"
2981+
by following the path "/properties/foo/allOf/1/properties/foo-prop"
2982+
will produce <sourcecode>"foo-prop-title"</sourcecode>.
2983+
</t>
29772984
<t>
29782985
The keyword "title"
29792986
validated at "/$defs/bar"
@@ -3031,9 +3038,9 @@ https://example.com/schemas/common#/$defs/count/minimum
30313038
omitted from the root output unit.
30323039
</t>
30333040
<t>
3034-
Intermediate output units, which do not themselves produce errors but
3035-
represent subschemas that contain error-producing subschemas, MAY be
3036-
included.
3041+
Output units which do not contain errors or annotations SHOULD be excluded
3042+
from this format, however implementations MAY choose to include them for
3043+
completeness.
30373044
</t>
30383045
<figure>
30393046
<artwork>
@@ -3071,78 +3078,72 @@ https://example.com/schemas/common#/$defs/count/minimum
30713078
}
30723079
]
30733080
}
3074-
]]>
3075-
</artwork>
3076-
</figure>
3077-
</section>
30783081
3079-
<section title="Detailed">
3080-
<t>
3081-
The "Detailed" format is a hierarchical structure based on that of the schema
3082-
and can be more readable for both humans and machines by grouping together
3083-
output units that apply to the same subschemas.
3084-
</t>
3085-
<t>
3086-
The root output unit contains "valid" for the overall result and "nested"
3087-
for the list of specific results. All other information is explicitly
3088-
omitted from the root output unit.
3089-
</t>
3090-
<t>
3091-
The following rules govern the construction of the results object:
3092-
<list>
3093-
<t>
3094-
All applicator keywords ("*Of", "$ref", "if"/"then"/"else", etc.) require
3095-
a output unit.
3096-
</t>
3097-
<t>
3098-
Output units that have no children are removed.
3099-
</t>
3100-
<t>
3101-
Output units that have a single child are replaced by the child.
3102-
</t>
3103-
</list>
3104-
Branch output units do not require an error message or an annotation.
3105-
</t>
3106-
<figure>
3107-
<artwork>
3108-
<![CDATA[
3109-
// failing results
3082+
// passing results
31103083
{
3111-
"valid": false,
3084+
"valid": true,
31123085
"nested": [
31133086
{
3087+
"valid": true,
3088+
"evaluationPath": "",
3089+
"schemaLocation":
3090+
"https://json-schema.org/schemas/example#",
3091+
"instanceLocation": "",
3092+
"annotations": {
3093+
"title": "root",
3094+
"properties": [ "foo", "bar" ]
3095+
}
3096+
},
3097+
{
3098+
"valid": true,
31143099
"evaluationPath": "/properties/foo",
31153100
"schemaLocation":
31163101
"https://json-schema.org/schemas/example#/properties/foo",
31173102
"instanceLocation": "/foo",
3118-
"nested": [
3119-
{
3120-
"evaluationPath": "/properties/foo/allOf/0",
3121-
"schemaLocation":
3122-
"https://json-schema.org/schemas/example#/properties/foo/allOf/0",
3123-
"instanceLocation": "/foo",
3124-
"errors": {
3125-
"type": "Expected the property \"unspecified-prop\"."
3126-
}
3127-
},
3128-
{
3129-
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
3130-
"schemaLocation":
3131-
"https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
3132-
"instanceLocation": "/foo/foo-prop",
3133-
"errors": {
3134-
"type": "Expected the value \"1\"."
3135-
}
3136-
}
3137-
]
3103+
"annotations": {
3104+
"title": "foo-title"
3105+
}
3106+
},
3107+
{
3108+
"valid": true,
3109+
"evaluationPath": "/properties/foo/allOf/1",
3110+
"schemaLocation":
3111+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1",
3112+
"instanceLocation": "/foo/foo-prop",
3113+
"annotations": {
3114+
"properties": [ "foo-prop" ],
3115+
"additionalProperties": [ "unspecified-prop" ]
3116+
}
3117+
},
3118+
{
3119+
"valid": true,
3120+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
3121+
"schemaLocation":
3122+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
3123+
"instanceLocation": "/foo/foo-prop",
3124+
"annotations": {
3125+
"title": "foo-prop-title"
3126+
}
31383127
},
31393128
{
3129+
"valid": true,
3130+
"evaluationPath": "/properties/bar/$ref",
3131+
"schemaLocation":
3132+
"https://json-schema.org/schemas/example#/$defs/bar",
3133+
"instanceLocation": "/bar",
3134+
"annotations": {
3135+
"title": "bar-title",
3136+
"properties": [ "bar-prop" ]
3137+
}
3138+
},
3139+
{
3140+
"valid": true,
31403141
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
31413142
"schemaLocation":
31423143
"https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
31433144
"instanceLocation": "/bar/bar-prop",
3144-
"errors": {
3145-
"type": "Expected a value of type \"integer\"."
3145+
"annotations": {
3146+
"title": "bar-prop-title"
31463147
}
31473148
}
31483149
]
@@ -3152,23 +3153,24 @@ https://example.com/schemas/common#/$defs/count/minimum
31523153
</figure>
31533154
</section>
31543155

3155-
<section title="Verbose">
3156+
<section title="Hierarchical">
3157+
<t>
3158+
The "Hierarchical" structure is a tree structure that follows the
3159+
evaluation path during the validation process. Typically, it will
3160+
resemble the schema as if all referenced schemas were bundled in place
3161+
of their associated by-reference keywords.
3162+
</t>
31563163
<t>
3157-
The "Verbose" structure is a fully realized hierarchy that exactly matches
3158-
that of the schema. This structure has applications in form generation and
3159-
validation where the error's location is important.
3164+
All output units are included in this format.
31603165
</t>
31613166
<t>
3162-
The primary difference between this and the "Detailed" structure is that
3163-
all results are returned. This includes subschema validation results that
3164-
would otherwise be removed (e.g. passing subschemas contained within failing
3165-
subschemas, etc.). Because of this, each output unit MUST also carry a
3166-
"valid" property to indicate its local validation result.
3167+
The location properties of the output unit MAY be omitted from the
3168+
root node.
31673169
</t>
31683170
<figure>
31693171
<artwork>
31703172
<![CDATA[
3171-
// failing results
3173+
// failing results (errors)
31723174
{
31733175
"valid": false,
31743176
"nested": [
@@ -3240,7 +3242,92 @@ https://example.com/schemas/common#/$defs/count/minimum
32403242
}
32413243
]
32423244
}
3243-
]]>
3245+
3246+
// passing results (annotations)
3247+
{
3248+
"valid": true,
3249+
"annotations": {
3250+
"title": "root",
3251+
"properties": [ "foo", "bar" ]
3252+
},
3253+
"nested": [
3254+
{
3255+
"valid": true,
3256+
"evaluationPath": "/properties/foo",
3257+
"schemaLocation":
3258+
"https://json-schema.org/schemas/example#/properties/foo",
3259+
"instanceLocation": "/foo",
3260+
"annotations": {
3261+
"title": "foo-title"
3262+
},
3263+
"nested": [
3264+
{
3265+
"valid": true,
3266+
"evaluationPath": "/properties/foo/allOf/0",
3267+
"schemaLocation":
3268+
"https://json-schema.org/schemas/example#/properties/foo/allOf/0",
3269+
"instanceLocation": "/foo"
3270+
},
3271+
{
3272+
"valid": true,
3273+
"evaluationPath": "/properties/foo/allOf/1",
3274+
"schemaLocation":
3275+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1",
3276+
"instanceLocation": "/foo/foo-prop",
3277+
"annotations": {
3278+
"properties": [ "foo-prop" ],
3279+
"additionalProperties": [ "unspecified-prop" ]
3280+
},
3281+
"nested": [
3282+
{
3283+
"valid": true,
3284+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
3285+
"schemaLocation":
3286+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
3287+
"instanceLocation": "/foo/foo-prop",
3288+
"annotations": {
3289+
"title": "foo-prop-title"
3290+
}
3291+
}
3292+
]
3293+
}
3294+
]
3295+
},
3296+
{
3297+
"valid": true,
3298+
"evaluationPath": "/properties/bar",
3299+
"schemaLocation":
3300+
"https://json-schema.org/schemas/example#/properties/bar",
3301+
"instanceLocation": "/bar",
3302+
"nested": [
3303+
{
3304+
"valid": true,
3305+
"evaluationPath": "/properties/bar/$ref",
3306+
"schemaLocation":
3307+
"https://json-schema.org/schemas/example#/$defs/bar",
3308+
"instanceLocation": "/bar",
3309+
"annotations": {
3310+
"title": "bar-title",
3311+
"properties": [ "bar-prop" ]
3312+
},
3313+
"nested": [
3314+
{
3315+
"valid": true,
3316+
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
3317+
"schemaLocation":
3318+
"https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
3319+
"instanceLocation": "/bar/bar-prop",
3320+
"annotations": {
3321+
"title": "bar-prop-title"
3322+
}
3323+
}
3324+
]
3325+
}
3326+
]
3327+
}
3328+
]
3329+
}
3330+
]]>
32443331
</artwork>
32453332
</figure>
32463333
</section>

0 commit comments

Comments
 (0)