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 e4eff10

Browse files
gregsdennisgregsdennis
committedNov 8, 2024
add a root object to the output
1 parent 4b21ddd commit e4eff10

File tree

2 files changed

+207
-183
lines changed

2 files changed

+207
-183
lines changed
 

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

Lines changed: 187 additions & 157 deletions
Original file line numberDiff line numberDiff line change
@@ -3,74 +3,88 @@
33

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

99
## Table of Contents
1010

1111
## Schema Identifiers
1212

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

2018
## Textual Format and Encoding
2119

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

28-
## Minimum Information
41+
For the "list" and "hierarchical" formats, the following is also required:
2942

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

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

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

40-
- Evaluation Path
41-
- Schema Location
42-
- Instance Location
53+
- Evaluation Path (as `evaluationPath`)
54+
- Schema Location (as `schemaLocation`)
55+
- Instance Location (as `instanceLocation`)
4356

4457
The following information MAY be included conditionally:
4558

4659
- When subschema validation has succeeded
47-
- Annotations
60+
- Annotations (as `annotations`)
4861
- When subschema validation has failed
49-
- Errors
50-
- Dropped Annotations
62+
- Errors (as `errors`)
63+
- Dropped Annotations (as `droppedAnnotations`)
64+
65+
When including this information, the indicated property names MUST be used.
5166

5267
Implementations MAY elect to provide additional information.
5368

54-
### Validation Result {#validation-result}
69+
#### Validation Result {#validation-result}
5570

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

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

61-
### Results from Subschemas
76+
#### Results from Subschemas
6277

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

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

7589
The sequence of output units within this list is not specified and MAY be
7690
determined by the implementation. Sets of output units are considered equivalent
@@ -230,6 +244,8 @@ omitted.
230244

231245
```json "Flag Results"
232246
{
247+
"dialect": "https://json-schema.org/draft/next/schema",
248+
"schema": "https://json-schema.org/schemas/example",
233249
"valid": false
234250
}
235251
```
@@ -242,21 +258,17 @@ check the other three. The logic can simply return with success.
242258

243259
### List
244260

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

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

258268
```json "Failing Results"
259269
{
270+
"dialect": "https://json-schema.org/draft/next/schema",
271+
"schema": "https://json-schema.org/schemas/example",
260272
"valid": false,
261273
"details": [
262274
{
@@ -292,6 +304,8 @@ completeness.
292304

293305
```json "Passing Results"
294306
{
307+
"dialect": "https://json-schema.org/draft/next/schema",
308+
"schema": "https://json-schema.org/schemas/example",
295309
"valid": true,
296310
"details": [
297311
{
@@ -369,180 +383,195 @@ The location properties of the root output unit MAY be omitted.
369383

370384
```json "failing Results
371385
{
386+
"dialect": "https://json-schema.org/draft/next/schema",
387+
"schema": "https://json-schema.org/schemas/example",
372388
"valid": false,
373-
"evaluationPath": "",
374-
"schemaLocation": "https://json-schema.org/schemas/example#",
375-
"instanceLocation": "",
376389
"details": [
377390
{
378391
"valid": false,
379-
"evaluationPath": "/properties/foo",
380-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
381-
"instanceLocation": "/foo",
392+
"evaluationPath": "",
393+
"schemaLocation": "https://json-schema.org/schemas/example#",
394+
"instanceLocation": "",
382395
"details": [
383396
{
384397
"valid": false,
385-
"evaluationPath": "/properties/foo/allOf/0",
386-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
398+
"evaluationPath": "/properties/foo",
399+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
387400
"instanceLocation": "/foo",
388-
"errors": {
389-
"required": "Required properties [\"unspecified-prop\"] were not present"
390-
}
391-
},
392-
{
393-
"valid": false,
394-
"evaluationPath": "/properties/foo/allOf/1",
395-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
396-
"instanceLocation": "/foo",
397-
"droppedAnnotations": {
398-
"properties": [ "foo-prop" ],
399-
"title": "foo-title"
400-
},
401401
"details": [
402402
{
403403
"valid": false,
404-
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
405-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
406-
"instanceLocation": "/foo/foo-prop",
404+
"evaluationPath": "/properties/foo/allOf/0",
405+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
406+
"instanceLocation": "/foo",
407407
"errors": {
408-
"const": "Expected \"1\""
409-
},
410-
"droppedAnnotations": {
411-
"title": "foo-prop-title"
408+
"required": "Required properties [\"unspecified-prop\"] were not present"
412409
}
413410
},
414411
{
415-
"valid": true,
416-
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
417-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
418-
"instanceLocation": "/foo/other-prop"
412+
"valid": false,
413+
"evaluationPath": "/properties/foo/allOf/1",
414+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
415+
"instanceLocation": "/foo",
416+
"droppedAnnotations": {
417+
"properties": [ "foo-prop" ],
418+
"title": "foo-title"
419+
},
420+
"details": [
421+
{
422+
"valid": false,
423+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
424+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
425+
"instanceLocation": "/foo/foo-prop",
426+
"errors": {
427+
"const": "Expected \"1\""
428+
},
429+
"droppedAnnotations": {
430+
"title": "foo-prop-title"
431+
}
432+
},
433+
{
434+
"valid": true,
435+
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
436+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
437+
"instanceLocation": "/foo/other-prop"
438+
}
439+
]
419440
}
420441
]
421-
}
422-
]
423-
},
424-
{
425-
"valid": false,
426-
"evaluationPath": "/properties/bar",
427-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
428-
"instanceLocation": "/bar",
429-
"details": [
442+
},
430443
{
431444
"valid": false,
432-
"evaluationPath": "/properties/bar/$ref",
433-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
445+
"evaluationPath": "/properties/bar",
446+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
434447
"instanceLocation": "/bar",
435-
"droppedAnnotations": {
436-
"properties": [ "bar-prop" ],
437-
"title": "bar-title"
438-
},
439448
"details": [
440449
{
441450
"valid": false,
442-
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
443-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
444-
"instanceLocation": "/bar/bar-prop",
445-
"errors": {
446-
"minimum": "2 is less than or equal to 10"
447-
},
451+
"evaluationPath": "/properties/bar/$ref",
452+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
453+
"instanceLocation": "/bar",
448454
"droppedAnnotations": {
449-
"title": "bar-prop-title"
450-
}
455+
"properties": [ "bar-prop" ],
456+
"title": "bar-title"
457+
},
458+
"details": [
459+
{
460+
"valid": false,
461+
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
462+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
463+
"instanceLocation": "/bar/bar-prop",
464+
"errors": {
465+
"minimum": "2 is less than or equal to 10"
466+
},
467+
"droppedAnnotations": {
468+
"title": "bar-prop-title"
469+
}
470+
}
471+
]
451472
}
452473
]
453474
}
454475
]
455476
}
456477
]
457478
}
479+
458480
```
459481

460482
```json "Passing Results
461483
{
462-
"valid": true,
463-
"evaluationPath": "",
464-
"schemaLocation": "https://json-schema.org/schemas/example#",
465-
"instanceLocation": "",
466-
"annotations": {
467-
"title": "root",
468-
"properties": [
469-
"foo",
470-
"bar"
471-
]
472-
},
484+
"dialect": "https://json-schema.org/draft/next/schema",
485+
"schema": "https://json-schema.org/schemas/example",
486+
"valid": false,
473487
"details": [
474488
{
475489
"valid": true,
476-
"evaluationPath": "/properties/foo",
477-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
478-
"instanceLocation": "/foo",
490+
"evaluationPath": "",
491+
"schemaLocation": "https://json-schema.org/schemas/example#",
492+
"instanceLocation": "",
493+
"annotations": {
494+
"title": "root",
495+
"properties": [
496+
"foo",
497+
"bar"
498+
]
499+
},
479500
"details": [
480501
{
481502
"valid": true,
482-
"evaluationPath": "/properties/foo/allOf/0",
483-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
484-
"instanceLocation": "/foo"
485-
},
486-
{
487-
"valid": true,
488-
"evaluationPath": "/properties/foo/allOf/1",
489-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
503+
"evaluationPath": "/properties/foo",
504+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo",
490505
"instanceLocation": "/foo",
491-
"annotations": {
492-
"title": "foo-title",
493-
"properties": [
494-
"foo-prop"
495-
],
496-
"additionalProperties": [
497-
"unspecified-prop"
498-
]
499-
},
500506
"details": [
501507
{
502508
"valid": true,
503-
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
504-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
505-
"instanceLocation": "/foo/foo-prop",
506-
"annotations": {
507-
"title": "foo-prop-title"
508-
}
509+
"evaluationPath": "/properties/foo/allOf/0",
510+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0",
511+
"instanceLocation": "/foo"
509512
},
510513
{
511514
"valid": true,
512-
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
513-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
514-
"instanceLocation": "/foo/unspecified-prop"
515+
"evaluationPath": "/properties/foo/allOf/1",
516+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1",
517+
"instanceLocation": "/foo",
518+
"annotations": {
519+
"title": "foo-title",
520+
"properties": [
521+
"foo-prop"
522+
],
523+
"additionalProperties": [
524+
"unspecified-prop"
525+
]
526+
},
527+
"details": [
528+
{
529+
"valid": true,
530+
"evaluationPath": "/properties/foo/allOf/1/properties/foo-prop",
531+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop",
532+
"instanceLocation": "/foo/foo-prop",
533+
"annotations": {
534+
"title": "foo-prop-title"
535+
}
536+
},
537+
{
538+
"valid": true,
539+
"evaluationPath": "/properties/foo/allOf/1/additionalProperties",
540+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties",
541+
"instanceLocation": "/foo/unspecified-prop"
542+
}
543+
]
515544
}
516545
]
517-
}
518-
]
519-
},
520-
{
521-
"valid": true,
522-
"evaluationPath": "/properties/bar",
523-
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
524-
"instanceLocation": "/bar",
525-
"details": [
546+
},
526547
{
527548
"valid": true,
528-
"evaluationPath": "/properties/bar/$ref",
529-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
549+
"evaluationPath": "/properties/bar",
550+
"schemaLocation": "https://json-schema.org/schemas/example#/properties/bar",
530551
"instanceLocation": "/bar",
531-
"annotations": {
532-
"title": "bar-title",
533-
"properties": [
534-
"bar-prop"
535-
]
536-
},
537552
"details": [
538553
{
539554
"valid": true,
540-
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
541-
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
542-
"instanceLocation": "/bar/bar-prop",
555+
"evaluationPath": "/properties/bar/$ref",
556+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar",
557+
"instanceLocation": "/bar",
543558
"annotations": {
544-
"title": "bar-prop-title"
545-
}
559+
"title": "bar-title",
560+
"properties": [
561+
"bar-prop"
562+
]
563+
},
564+
"details": [
565+
{
566+
"valid": true,
567+
"evaluationPath": "/properties/bar/$ref/properties/bar-prop",
568+
"schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop",
569+
"instanceLocation": "/bar/bar-prop",
570+
"annotations": {
571+
"title": "bar-prop-title"
572+
}
573+
}
574+
]
546575
}
547576
]
548577
}
@@ -556,6 +585,7 @@ The location properties of the root output unit MAY be omitted.
556585

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

560590
## Filtering
561591

‎specs/output/schema.json

Lines changed: 20 additions & 26 deletions
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.