Skip to content

Commit b4ff06e

Browse files
gregsdennisgregsdennis
committed
removed 'detailed' format; added annotations examples; some rewording and clarifications
1 parent 8a73d7b commit b4ff06e

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
@@ -2726,18 +2726,18 @@
27262726
Basic - Provides validation information in a flat list structure.
27272727
</t>
27282728
<t>
2729-
Detailed - Provides validation information in a condensed hierarchical
2730-
structure based on the structure of the schema.
2731-
</t>
2732-
<t>
2733-
Verbose - Provides validation information in an uncondensed hierarchical
2734-
structure that matches the exact structure of the schema.
2729+
Hierarchical - Provides validation information in a hierarchical
2730+
structure that mimics the structure of the schema.
2731+
<cref>
2732+
To be precise, this structure follows the paths that a validator
2733+
would traverse while processing the schema, including composition
2734+
via by-reference keywords.
2735+
</cref>
27352736
</t>
27362737
</list>
2737-
An implementation SHOULD provide at least one of the "flag", "basic", or "detailed"
2738-
format and MAY provide the "verbose" format. If it provides one or more of the
2739-
"detailed" or "verbose" formats, it MUST also provide the "flag" format.
2740-
Implementations SHOULD specify in their documentation which formats they support.
2738+
An implementation MUST provide the "flag" format and SHOULD provide at least one
2739+
of the "basic" or "hierarchical" formats. Implementations SHOULD specify in
2740+
their documentation which formats they support.
27412741
</t>
27422742

27432743
</section>
@@ -2824,7 +2824,7 @@ https://example.com/schemas/common#/$defs/count/minimum
28242824
<t>
28252825
Any errors produced by the validation. This property MUST NOT
28262826
be included if the validation was successful. The value
2827-
for this property is an object where the keys are the names of
2827+
for this property MUST be an object where the keys are the names of
28282828
keywords and the values are the error message produced by the
28292829
associated keyword. If the subschema itself is producing the
28302830
error, that error MUST be listed with an empty string key.
@@ -2842,7 +2842,7 @@ https://example.com/schemas/common#/$defs/count/minimum
28422842
<t>
28432843
Any annotations produced by the validation. This property MUST NOT
28442844
be included if the validation was unsuccessful. The value
2845-
for this property is an object where the keys are the names of
2845+
for this property MUST be an object where the keys are the names of
28462846
keywords and the values are the annotations produced by the
28472847
associated keyword.
28482848
</t>
@@ -2856,13 +2856,20 @@ https://example.com/schemas/common#/$defs/count/minimum
28562856
</section>
28572857

28582858
<section title="Nested Results">
2859+
<t>
2860+
Nested results are generated from applicator keywords: keywords with
2861+
subschemas or collections of subschemas as values. Keywords which
2862+
have arrays of subschemas (e.g. "anyOf") will generally generate an output
2863+
unit for each subschema. In order to accommodate potentially multiple
2864+
results, the value of this property MUST be an array of output units.
2865+
</t>
28592866
<t>
28602867
For "basic", this property will appear only at the root output unit
2861-
and will hold all results in a flat list.
2868+
and will hold all output units in a flat list.
28622869
</t>
28632870
<t>
2864-
For "detailed" and "verbose", this property will hold nested results
2865-
in a tree structure, mimicking that of the schema.
2871+
For "hierarchical", this property will hold nested results in a tree
2872+
structure, mimicking that of the schema.
28662873
</t>
28672874
<t>
28682875
The sequence of output units within this list is not specified and
@@ -3016,18 +3023,18 @@ https://example.com/schemas/common#/$defs/count/minimum
30163023
by following the path "/properties/foo/allOf/1"
30173024
will produce <sourcecode>["foo-prop"]</sourcecode>.
30183025
</t>
3019-
<t>
3020-
The keyword "title"
3021-
validated at "/properties/foo/allOf/1/properties/foo-prop"
3022-
by following the path "/properties/foo/allOf/1/properties/foo-prop"
3023-
will produce <sourcecode>"foo-prop-title"</sourcecode>.
3024-
</t>
30253026
<t>
30263027
The keyword "additionalProperties"
30273028
validated at "/properties/foo/allOf/1"
30283029
by following the path "/properties/foo/allOf/1"
30293030
will produce <sourcecode>["unspecified-prop"]</sourcecode>.
30303031
</t>
3032+
<t>
3033+
The keyword "title"
3034+
validated at "/properties/foo/allOf/1/properties/foo-prop"
3035+
by following the path "/properties/foo/allOf/1/properties/foo-prop"
3036+
will produce <sourcecode>"foo-prop-title"</sourcecode>.
3037+
</t>
30313038
<t>
30323039
The keyword "title"
30333040
validated at "/$defs/bar"
@@ -3085,9 +3092,9 @@ https://example.com/schemas/common#/$defs/count/minimum
30853092
omitted from the root output unit.
30863093
</t>
30873094
<t>
3088-
Intermediate output units, which do not themselves produce errors but
3089-
represent subschemas that contain error-producing subschemas, MAY be
3090-
included.
3095+
Output units which do not contain errors or annotations SHOULD be excluded
3096+
from this format, however implementations MAY choose to include them for
3097+
completeness.
30913098
</t>
30923099
<figure>
30933100
<artwork>
@@ -3125,78 +3132,72 @@ https://example.com/schemas/common#/$defs/count/minimum
31253132
}
31263133
]
31273134
}
3128-
]]>
3129-
</artwork>
3130-
</figure>
3131-
</section>
31323135
3133-
<section title="Detailed">
3134-
<t>
3135-
The "Detailed" format is a hierarchical structure based on that of the schema
3136-
and can be more readable for both humans and machines by grouping together
3137-
output units that apply to the same subschemas.
3138-
</t>
3139-
<t>
3140-
The root output unit contains "valid" for the overall result and "nested"
3141-
for the list of specific results. All other information is explicitly
3142-
omitted from the root output unit.
3143-
</t>
3144-
<t>
3145-
The following rules govern the construction of the results object:
3146-
<list>
3147-
<t>
3148-
All applicator keywords ("*Of", "$ref", "if"/"then"/"else", etc.) require
3149-
a output unit.
3150-
</t>
3151-
<t>
3152-
Output units that have no children are removed.
3153-
</t>
3154-
<t>
3155-
Output units that have a single child are replaced by the child.
3156-
</t>
3157-
</list>
3158-
Branch output units do not require an error message or an annotation.
3159-
</t>
3160-
<figure>
3161-
<artwork>
3162-
<![CDATA[
3163-
// failing results
3136+
// passing results
31643137
{
3165-
"valid": false,
3138+
"valid": true,
31663139
"nested": [
31673140
{
3141+
"valid": true,
3142+
"evaluationPath": "",
3143+
"schemaLocation":
3144+
"https://json-schema.org/schemas/example#",
3145+
"instanceLocation": "",
3146+
"annotations": {
3147+
"title": "root",
3148+
"properties": [ "foo", "bar" ]
3149+
}
3150+
},
3151+
{
3152+
"valid": true,
31683153
"evaluationPath": "/properties/foo",
31693154
"schemaLocation":
31703155
"https://json-schema.org/schemas/example#/properties/foo",
31713156
"instanceLocation": "/foo",
3172-
"nested": [
3173-
{
3174-
"evaluationPath": "/properties/foo/allOf/0",
3175-
"schemaLocation":
3176-
"https://json-schema.org/schemas/example#/properties/foo/allOf/0",
3177-
"instanceLocation": "/foo",
3178-
"errors": {
3179-
"type": "Expected the property \"unspecified-prop\"."
3180-
}
3181-
},
3182-
{
3183-
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
3184-
"schemaLocation":
3185-
"https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
3186-
"instanceLocation": "/foo/foo-prop",
3187-
"errors": {
3188-
"type": "Expected the value \"1\"."
3189-
}
3190-
}
3191-
]
3157+
"annotations": {
3158+
"title": "foo-title"
3159+
}
3160+
},
3161+
{
3162+
"valid": true,
3163+
"evaluationPath": "/properties/foo/allOf/1",
3164+
"schemaLocation":
3165+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1",
3166+
"instanceLocation": "/foo/foo-prop",
3167+
"annotations": {
3168+
"properties": [ "foo-prop" ],
3169+
"additionalProperties": [ "unspecified-prop" ]
3170+
}
3171+
},
3172+
{
3173+
"valid": true,
3174+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
3175+
"schemaLocation":
3176+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
3177+
"instanceLocation": "/foo/foo-prop",
3178+
"annotations": {
3179+
"title": "foo-prop-title"
3180+
}
31923181
},
31933182
{
3183+
"valid": true,
3184+
"evaluationPath": "/properties/bar/$ref",
3185+
"schemaLocation":
3186+
"https://json-schema.org/schemas/example#/$defs/bar",
3187+
"instanceLocation": "/bar",
3188+
"annotations": {
3189+
"title": "bar-title",
3190+
"properties": [ "bar-prop" ]
3191+
}
3192+
},
3193+
{
3194+
"valid": true,
31943195
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
31953196
"schemaLocation":
31963197
"https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
31973198
"instanceLocation": "/bar/bar-prop",
3198-
"errors": {
3199-
"type": "Expected a value of type \"integer\"."
3199+
"annotations": {
3200+
"title": "bar-prop-title"
32003201
}
32013202
}
32023203
]
@@ -3206,23 +3207,24 @@ https://example.com/schemas/common#/$defs/count/minimum
32063207
</figure>
32073208
</section>
32083209

3209-
<section title="Verbose">
3210+
<section title="Hierarchical">
3211+
<t>
3212+
The "Hierarchical" structure is a tree structure that follows the
3213+
evaluation path during the validation process. Typically, it will
3214+
resemble the schema as if all referenced schemas were bundled in place
3215+
of their associated by-reference keywords.
3216+
</t>
32103217
<t>
3211-
The "Verbose" structure is a fully realized hierarchy that exactly matches
3212-
that of the schema. This structure has applications in form generation and
3213-
validation where the error's location is important.
3218+
All output units are included in this format.
32143219
</t>
32153220
<t>
3216-
The primary difference between this and the "Detailed" structure is that
3217-
all results are returned. This includes subschema validation results that
3218-
would otherwise be removed (e.g. passing subschemas contained within failing
3219-
subschemas, etc.). Because of this, each output unit MUST also carry a
3220-
"valid" property to indicate its local validation result.
3221+
The location properties of the output unit MAY be omitted from the
3222+
root node.
32213223
</t>
32223224
<figure>
32233225
<artwork>
32243226
<![CDATA[
3225-
// failing results
3227+
// failing results (errors)
32263228
{
32273229
"valid": false,
32283230
"nested": [
@@ -3294,7 +3296,92 @@ https://example.com/schemas/common#/$defs/count/minimum
32943296
}
32953297
]
32963298
}
3297-
]]>
3299+
3300+
// passing results (annotations)
3301+
{
3302+
"valid": true,
3303+
"annotations": {
3304+
"title": "root",
3305+
"properties": [ "foo", "bar" ]
3306+
},
3307+
"nested": [
3308+
{
3309+
"valid": true,
3310+
"evaluationPath": "/properties/foo",
3311+
"schemaLocation":
3312+
"https://json-schema.org/schemas/example#/properties/foo",
3313+
"instanceLocation": "/foo",
3314+
"annotations": {
3315+
"title": "foo-title"
3316+
},
3317+
"nested": [
3318+
{
3319+
"valid": true,
3320+
"evaluationPath": "/properties/foo/allOf/0",
3321+
"schemaLocation":
3322+
"https://json-schema.org/schemas/example#/properties/foo/allOf/0",
3323+
"instanceLocation": "/foo"
3324+
},
3325+
{
3326+
"valid": true,
3327+
"evaluationPath": "/properties/foo/allOf/1",
3328+
"schemaLocation":
3329+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1",
3330+
"instanceLocation": "/foo/foo-prop",
3331+
"annotations": {
3332+
"properties": [ "foo-prop" ],
3333+
"additionalProperties": [ "unspecified-prop" ]
3334+
},
3335+
"nested": [
3336+
{
3337+
"valid": true,
3338+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
3339+
"schemaLocation":
3340+
"https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
3341+
"instanceLocation": "/foo/foo-prop",
3342+
"annotations": {
3343+
"title": "foo-prop-title"
3344+
}
3345+
}
3346+
]
3347+
}
3348+
]
3349+
},
3350+
{
3351+
"valid": true,
3352+
"evaluationPath": "/properties/bar",
3353+
"schemaLocation":
3354+
"https://json-schema.org/schemas/example#/properties/bar",
3355+
"instanceLocation": "/bar",
3356+
"nested": [
3357+
{
3358+
"valid": true,
3359+
"evaluationPath": "/properties/bar/$ref",
3360+
"schemaLocation":
3361+
"https://json-schema.org/schemas/example#/$defs/bar",
3362+
"instanceLocation": "/bar",
3363+
"annotations": {
3364+
"title": "bar-title",
3365+
"properties": [ "bar-prop" ]
3366+
},
3367+
"nested": [
3368+
{
3369+
"valid": true,
3370+
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
3371+
"schemaLocation":
3372+
"https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
3373+
"instanceLocation": "/bar/bar-prop",
3374+
"annotations": {
3375+
"title": "bar-prop-title"
3376+
}
3377+
}
3378+
]
3379+
}
3380+
]
3381+
}
3382+
]
3383+
}
3384+
]]>
32983385
</artwork>
32993386
</figure>
33003387
</section>

0 commit comments

Comments
 (0)