Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit e1916d9

Browse files
gregsdennisgregsdennis
committedOct 22, 2024·
add a root object to the output
1 parent 08943f7 commit e1916d9

File tree

2 files changed

+207
-183
lines changed

2 files changed

+207
-183
lines changed
 

‎output/jsonschema-validation-output-machines.md

+187-157
Original file line numberDiff line numberDiff line change
@@ -2,74 +2,88 @@
22

33
JSON Schema is defined to be platform-independent. As such, to increase
44
compatibility across platforms, implementations SHOULD conform to a standard
5-
validation output format. This specification describes the minimum requirements
6-
for machine consumers to properly interpret validation results.
5+
validation output format. This specification describes a number of output
6+
formats intended for machine consumers.
77

88
## Table of Contents
99

1010
## Schema Identifiers
1111

12-
The output defined in this specification requires that the evaluation root be
13-
defined with an absolute IRI, i.e. using the `$id` keyword. In the event an
14-
absolute IRI has not been defined, the implementation MUST generate one.
15-
16-
There are no requirements on the form of IRI itself, except that it MUST be
17-
absolute.
12+
The output defined in this specification requires that an initial IRI is defined
13+
per [JSON Schema Core](./json-schema-core#initial-base) "Initial Base IRI" with an
14+
[absolute IRI](#rfc3987). In the event an absolute IRI has not been defined, the
15+
implementation MUST generate one.
1816

1917
## Textual Format and Encoding
2018

2119
JSON Schema output is defined using the JSON Schema data instance model as
22-
described in [JSON Schema](#json-schema) "Instance Data Model". Implementations
23-
MAY deviate from this in their internal modelling, as supported by their
24-
specific languages and platforms, however it is RECOMMENDED that the output be
25-
convertible to the JSON format defined herein via serialization or other means.
20+
described in [JSON Schema Core](./jsonschema-core#data-model) "Instance Data
21+
Model". Implementations MAY deviate from this in their internal modelling, as
22+
supported by their specific languages and platforms, however it is RECOMMENDED
23+
that the output be convertible to the JSON format defined herein via
24+
serialization or other means.
25+
26+
## The Output Object
27+
28+
The output of a subschema validation is a JSON object which contains general
29+
information about the validation as well as a set of
30+
[output units](#output-unit) which contain specifics.
31+
32+
The root object MUST contain the following properties:
33+
34+
| Property | Value |
35+
|:-|:-|
36+
| `dialect` | The `$schema` IRI of the evaluating schema. |
37+
| `schema` | The identifier `$id` or otherwise used to identify the evaluating schema. |
38+
| `valid` | A boolean indicating the overall validation result. |
2639

27-
## Minimum Information
40+
For the "list" and "hierarchical" formats, the following is also required:
2841

29-
Beyond the simplistic "flag" output, additional information is useful to aid in
30-
debugging evaluation of an instance by a schema.
42+
| `details` | A collection of output units to provide additional details. Must be an array, even when containing a single output unit. |
3143

32-
The output of a subschema validation is considered an "output unit." The
33-
contents of each output unit is specified by this section.
44+
### Output Unit
45+
46+
An output unit describes the evaluation of a single subschema against the appropriate instance location.
3447

3548
Each output unit MUST contain the [validation result](#validation-result) for
3649
the associated subschema as well as the following information defined by
37-
[JSON Schema](#json-schema) "Output Formatting":
50+
[JSON Schema](./jsonschema-core#output) "Output Formatting":
3851

39-
- Evaluation Path
40-
- Schema Location
41-
- Instance Location
52+
- Evaluation Path (as `evaluationPath`)
53+
- Schema Location (as `schemaLocation`)
54+
- Instance Location (as `instanceLocation`)
4255

4356
The following information MAY be included conditionally:
4457

4558
- When subschema validation has succeeded
46-
- Annotations
59+
- Annotations (as `annotations`)
4760
- When subschema validation has failed
48-
- Errors
49-
- Dropped Annotations
61+
- Errors (as `errors`)
62+
- Dropped Annotations (as `droppedAnnotations`)
63+
64+
When including this information, the indicated property names MUST be used.
5065

5166
Implementations MAY elect to provide additional information.
5267

53-
### Validation Result {#validation-result}
68+
#### Validation Result {#validation-result}
5469

5570
The validation result is a boolean that indicates whether the local instance
5671
passed validation by the local subschema.
5772

5873
The JSON key for these additional results is `valid`.
5974

60-
### Results from Subschemas
75+
#### Results from Subschemas
6176

62-
Evaluation results generated by applying a subschema to the instance or a child
77+
Similar to the root object's `details` property, this property contains
78+
evaluation results generated by applying a subschema to the instance or a child
6379
of the instance. Keywords which have multiple subschemas (e.g. `anyOf`) will
6480
generally generate an output unit for each subschema. In order to accommodate
6581
potentially multiple results, the value of this property MUST be an array of
6682
output units, even if only a single output unit is produced.
6783

68-
For "list", this property will appear only at the root output unit and will hold
69-
all output units in a flat list.
70-
71-
For "hierarchical", this property will contain results in a tree structure where
72-
each output unit may itself have further nested results.
84+
This property of the output unit is only used for the "hierarchical" format and
85+
will contain results in a tree structure where each output unit may itself have
86+
further nested results.
7387

7488
The sequence of output units within this list is not specified and MAY be
7589
determined by the implementation. Sets of output units are considered equivalent
@@ -229,6 +243,8 @@ omitted.
229243

230244
```json "Flag Results"
231245
{
246+
"dialect": "https://json-schema.org/draft/next/schema",
247+
"schema": "https://json-schema.org/schemas/example",
232248
"valid": false
233249
}
234250
```
@@ -241,21 +257,17 @@ check the other three. The logic can simply return with success.
241257

242258
### List
243259

244-
The "list" structure is a flat list of output units contained within a root
245-
output unit.
246-
247-
The root output unit contains `valid` for the overall result and `details` for
248-
the list of specific results. All other information is explicitly omitted from
249-
the root output unit. If the root schema produces errors or annotations, then
250-
the output node for the root MUST be present within the root output unit's
251-
`details` list with those errors or annotations.
260+
The "list" structure is a flat list of output units contained within the root
261+
object's `details` array.
252262

253263
Output units which do not contain errors or annotations SHOULD be excluded from
254264
this format, however implementations MAY choose to include them for
255265
completeness.
256266

257267
```json "Failing Results"
258268
{
269+
"dialect": "https://json-schema.org/draft/next/schema",
270+
"schema": "https://json-schema.org/schemas/example",
259271
"valid": false,
260272
"details": [
261273
{
@@ -291,6 +303,8 @@ completeness.
291303

292304
```json "Passing Results"
293305
{
306+
"dialect": "https://json-schema.org/draft/next/schema",
307+
"schema": "https://json-schema.org/schemas/example",
294308
"valid": true,
295309
"details": [
296310
{
@@ -368,180 +382,195 @@ The location properties of the root output unit MAY be omitted.
368382

369383
```json "failing Results
370384
{
385+
"dialect": "https://json-schema.org/draft/next/schema",
386+
"schema": "https://json-schema.org/schemas/example",
371387
"valid": false,
372-
"evaluationPath": "",
373-
"schemaLocation": "https://json-schema.org/schemas/example#",
374-
"instanceLocation": "",
375388
"details": [
376389
{
377390
"valid": false,
378-
"evaluationPath": "/properties/foo",
379-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
380-
"instanceLocation": "/foo",
391+
"evaluationPath": "",
392+
"schemaLocation": "https://json-schema.org/schemas/example#",
393+
"instanceLocation": "",
381394
"details": [
382395
{
383396
"valid": false,
384-
"evaluationPath": "/properties/foo/allOf/0",
385-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
397+
"evaluationPath": "/properties/foo",
398+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
386399
"instanceLocation": "/foo",
387-
"errors": {
388-
"required": "Required properties [\"unspecified-prop\"] were not present"
389-
}
390-
},
391-
{
392-
"valid": false,
393-
"evaluationPath": "/properties/foo/allOf/1",
394-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
395-
"instanceLocation": "/foo",
396-
"droppedAnnotations": {
397-
"properties": [ "foo-prop" ],
398-
"title": "foo-title"
399-
},
400400
"details": [
401401
{
402402
"valid": false,
403-
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
404-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
405-
"instanceLocation": "/foo/foo-prop",
403+
"evaluationPath": "/properties/foo/allOf/0",
404+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
405+
"instanceLocation": "/foo",
406406
"errors": {
407-
"const": "Expected \"1\""
408-
},
409-
"droppedAnnotations": {
410-
"title": "foo-prop-title"
407+
"required": "Required properties [\"unspecified-prop\"] were not present"
411408
}
412409
},
413410
{
414-
"valid": true,
415-
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
416-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
417-
"instanceLocation": "/foo/other-prop"
411+
"valid": false,
412+
"evaluationPath": "/properties/foo/allOf/1",
413+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
414+
"instanceLocation": "/foo",
415+
"droppedAnnotations": {
416+
"properties": [ "foo-prop" ],
417+
"title": "foo-title"
418+
},
419+
"details": [
420+
{
421+
"valid": false,
422+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
423+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
424+
"instanceLocation": "/foo/foo-prop",
425+
"errors": {
426+
"const": "Expected \"1\""
427+
},
428+
"droppedAnnotations": {
429+
"title": "foo-prop-title"
430+
}
431+
},
432+
{
433+
"valid": true,
434+
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
435+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
436+
"instanceLocation": "/foo/other-prop"
437+
}
438+
]
418439
}
419440
]
420-
}
421-
]
422-
},
423-
{
424-
"valid": false,
425-
"evaluationPath": "/properties/bar",
426-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
427-
"instanceLocation": "/bar",
428-
"details": [
441+
},
429442
{
430443
"valid": false,
431-
"evaluationPath": "/properties/bar/$ref",
432-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
444+
"evaluationPath": "/properties/bar",
445+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
433446
"instanceLocation": "/bar",
434-
"droppedAnnotations": {
435-
"properties": [ "bar-prop" ],
436-
"title": "bar-title"
437-
},
438447
"details": [
439448
{
440449
"valid": false,
441-
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
442-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
443-
"instanceLocation": "/bar/bar-prop",
444-
"errors": {
445-
"minimum": "2 is less than or equal to 10"
446-
},
450+
"evaluationPath": "/properties/bar/$ref",
451+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
452+
"instanceLocation": "/bar",
447453
"droppedAnnotations": {
448-
"title": "bar-prop-title"
449-
}
454+
"properties": [ "bar-prop" ],
455+
"title": "bar-title"
456+
},
457+
"details": [
458+
{
459+
"valid": false,
460+
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
461+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
462+
"instanceLocation": "/bar/bar-prop",
463+
"errors": {
464+
"minimum": "2 is less than or equal to 10"
465+
},
466+
"droppedAnnotations": {
467+
"title": "bar-prop-title"
468+
}
469+
}
470+
]
450471
}
451472
]
452473
}
453474
]
454475
}
455476
]
456477
}
478+
457479
```
458480

459481
```json "Passing Results
460482
{
461-
"valid": true,
462-
"evaluationPath": "",
463-
"schemaLocation": "https://json-schema.org/schemas/example#",
464-
"instanceLocation": "",
465-
"annotations": {
466-
"title": "root",
467-
"properties": [
468-
"foo",
469-
"bar"
470-
]
471-
},
483+
"dialect": "https://json-schema.org/draft/next/schema",
484+
"schema": "https://json-schema.org/schemas/example",
485+
"valid": false,
472486
"details": [
473487
{
474488
"valid": true,
475-
"evaluationPath": "/properties/foo",
476-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
477-
"instanceLocation": "/foo",
489+
"evaluationPath": "",
490+
"schemaLocation": "https://json-schema.org/schemas/example#",
491+
"instanceLocation": "",
492+
"annotations": {
493+
"title": "root",
494+
"properties": [
495+
"foo",
496+
"bar"
497+
]
498+
},
478499
"details": [
479500
{
480501
"valid": true,
481-
"evaluationPath": "/properties/foo/allOf/0",
482-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
483-
"instanceLocation": "/foo"
484-
},
485-
{
486-
"valid": true,
487-
"evaluationPath": "/properties/foo/allOf/1",
488-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
502+
"evaluationPath": "/properties/foo",
503+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
489504
"instanceLocation": "/foo",
490-
"annotations": {
491-
"title": "foo-title",
492-
"properties": [
493-
"foo-prop"
494-
],
495-
"additionalProperties": [
496-
"unspecified-prop"
497-
]
498-
},
499505
"details": [
500506
{
501507
"valid": true,
502-
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
503-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
504-
"instanceLocation": "/foo/foo-prop",
505-
"annotations": {
506-
"title": "foo-prop-title"
507-
}
508+
"evaluationPath": "/properties/foo/allOf/0",
509+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
510+
"instanceLocation": "/foo"
508511
},
509512
{
510513
"valid": true,
511-
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
512-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
513-
"instanceLocation": "/foo/unspecified-prop"
514+
"evaluationPath": "/properties/foo/allOf/1",
515+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
516+
"instanceLocation": "/foo",
517+
"annotations": {
518+
"title": "foo-title",
519+
"properties": [
520+
"foo-prop"
521+
],
522+
"additionalProperties": [
523+
"unspecified-prop"
524+
]
525+
},
526+
"details": [
527+
{
528+
"valid": true,
529+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
530+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
531+
"instanceLocation": "/foo/foo-prop",
532+
"annotations": {
533+
"title": "foo-prop-title"
534+
}
535+
},
536+
{
537+
"valid": true,
538+
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
539+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
540+
"instanceLocation": "/foo/unspecified-prop"
541+
}
542+
]
514543
}
515544
]
516-
}
517-
]
518-
},
519-
{
520-
"valid": true,
521-
"evaluationPath": "/properties/bar",
522-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
523-
"instanceLocation": "/bar",
524-
"details": [
545+
},
525546
{
526547
"valid": true,
527-
"evaluationPath": "/properties/bar/$ref",
528-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
548+
"evaluationPath": "/properties/bar",
549+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
529550
"instanceLocation": "/bar",
530-
"annotations": {
531-
"title": "bar-title",
532-
"properties": [
533-
"bar-prop"
534-
]
535-
},
536551
"details": [
537552
{
538553
"valid": true,
539-
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
540-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
541-
"instanceLocation": "/bar/bar-prop",
554+
"evaluationPath": "/properties/bar/$ref",
555+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
556+
"instanceLocation": "/bar",
542557
"annotations": {
543-
"title": "bar-prop-title"
544-
}
558+
"title": "bar-title",
559+
"properties": [
560+
"bar-prop"
561+
]
562+
},
563+
"details": [
564+
{
565+
"valid": true,
566+
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
567+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
568+
"instanceLocation": "/bar/bar-prop",
569+
"annotations": {
570+
"title": "bar-prop-title"
571+
}
572+
}
573+
]
545574
}
546575
]
547576
}
@@ -555,6 +584,7 @@ The location properties of the root output unit MAY be omitted.
555584

556585
For convenience, JSON Schema has been provided to validate output generated by
557586
implementations. Its IRI is: <https://json-schema.org/draft/next/output/schema>
587+
and can also be found at this address.
558588

559589
## Filtering
560590

‎output/schema.json

+20-26
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,26 @@
33
"$id": "https://json-schema.org/draft/next/output/schema",
44
"description": "A schema that validates the minimum requirements for validation output",
55

6-
"anyOf": [
7-
{ "$ref": "#/$defs/flag" },
8-
{ "$ref": "#/$defs/list" },
9-
{ "$ref": "#/$defs/hierarchical" }
10-
],
6+
"type": "object",
7+
"properties": {
8+
"dialect": {
9+
"type": "string",
10+
"format": "iri"
11+
},
12+
"schema": {
13+
"type": "string",
14+
"format": "iri"
15+
},
16+
"valid": { "type": "boolean" },
17+
"details": { "$ref": "#/$defs/outputUnitArray" }
18+
},
19+
"required": ["dialect", "schema", "valid"],
20+
1121
"$defs": {
22+
"outputUnitArray": {
23+
"type": "array",
24+
"items": { "$ref": "#/$defs/outputUnit" }
25+
},
1226
"outputUnit":{
1327
"properties": {
1428
"valid": { "type": "boolean" },
@@ -70,26 +84,6 @@
7084
}
7185
}
7286
]
73-
},
74-
"outputUnitArray": {
75-
"type": "array",
76-
"items": { "$ref": "#/$defs/outputUnit" }
77-
},
78-
"flag": {
79-
"properties": {
80-
"valid": { "type": "boolean" }
81-
},
82-
"required": [ "valid" ]
83-
},
84-
"list": {
85-
"properties": {
86-
"valid": { "type": "boolean" },
87-
"details": {
88-
"$ref": "#/$defs/outputUnitArray"
89-
}
90-
},
91-
"required": [ "valid", "details" ]
92-
},
93-
"hierarchical": { "$ref": "#/$defs/outputUnit" }
87+
}
9488
}
9589
}

0 commit comments

Comments
 (0)
Please sign in to comment.