From cd0326f79daf5a6b679419d51c14a4549b723590 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 9 Feb 2024 11:30:32 +1300 Subject: [PATCH 1/6] add overview block to output to contain metadata --- jsonschema-validation-output-machines.md | 372 ++++++++++++----------- 1 file changed, 202 insertions(+), 170 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index 398162bb..81bf9b0b 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -24,7 +24,24 @@ MAY deviate from this in their internal modelling, as supported by their specific languages and platforms, however it is RECOMMENDED that the output be convertible to the JSON format defined herein via serialization or other means. -## Minimum Information +## Applicability + +The formats described in this document apply only for a successful evaluation. If the implementation encounters a scenario for which JSON Schema requires that evaluation halt, the requirements herein do not apply, and the implementation SHOULD react as appropriate for its language/environment. + +## Overview + +The root of JSON Schema output MUST be a JSON object. This object MUST contain the following metadata regarding the validation: + +| JSON Property Name | Description | +|:-:|:-| +| `dialect` | Schema dialect (`$schema` value) | +| `baseUri` | Schema base URI (`$id` value) | +| `valid` | Boolean containing the overall validation result | +| `details` | Contains the detailed subschema evaluation results in one of the [formats](#output-structure) below | + + + +## Minimum Information for Subschema Validation and Annotation Beyond the simplistic "flag" output, additional information is useful to aid in debugging evaluation of an instance by a schema. @@ -83,9 +100,8 @@ The JSON key for these additional results is `details`. This specification defines three output formats. -- **Flag** - A boolean which simply indicates the overall validation result with - no further details. -- **List** - Provides validation information in a flat list structure. +- **Flag** - Only the top-level overview needs to be populated; `details` is omitted. +- **List** - Provides all subschema results in a flat array. - **Hierarchical** - Provides validation information in a hierarchical structure that follows the evaluation paths generated while processing the schema. @@ -225,7 +241,9 @@ omitted. ```json "Flag Results" { - "valid": false + "dialect": "https://json-schema.org/draft/next/schema", + "baseUri": "https://json-schema.org/schemas/example", + "results": false } ``` @@ -252,6 +270,8 @@ completeness. ```json "Failing Results" { + "dialect": "https://json-schema.org/draft/next/schema", + "baseUri": "https://json-schema.org/schemas/example", "valid": false, "details": [ { @@ -287,6 +307,8 @@ completeness. ```json "Passing Results" { + "dialect": "https://json-schema.org/draft/next/schema", + "baseUri": "https://json-schema.org/schemas/example", "valid": true, "details": [ { @@ -364,186 +386,196 @@ The location properties of the root output unit MAY be omitted. ```json "failing Results { + "dialect": "https://json-schema.org/draft/next/schema", + "baseUri": "https://json-schema.org/schemas/example", "valid": false, - "evaluationPath": "", - "schemaLocation": "https://json-schema.org/schemas/example#", - "instanceLocation": "", - "details": [ - { - "valid": false, - "evaluationPath": "/properties/foo", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo", - "instanceLocation": "/foo", - "details": [ - { - "valid": false, - "evaluationPath": "/properties/foo/allOf/0", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0", - "instanceLocation": "/foo", - "errors": { - "required": "Required properties [\"unspecified-prop\"] were not present" - } - }, - { - "valid": false, - "evaluationPath": "/properties/foo/allOf/1", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1", - "instanceLocation": "/foo", - "droppedAnnotations": { - "properties": [ "foo-prop" ], - "title": "foo-title" + "details": { + "valid": false, + "evaluationPath": "", + "schemaLocation": "https://json-schema.org/schemas/example#", + "instanceLocation": "", + "details": [ + { + "valid": false, + "evaluationPath": "/properties/foo", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo", + "instanceLocation": "/foo", + "details": [ + { + "valid": false, + "evaluationPath": "/properties/foo/allOf/0", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0", + "instanceLocation": "/foo", + "errors": { + "required": "Required properties [\"unspecified-prop\"] were not present" + } }, - "details": [ - { - "valid": false, - "evaluationPath": "/properties/foo/allOf/1/properties/foo-prop", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop", - "instanceLocation": "/foo/foo-prop", - "errors": { - "const": "Expected \"1\"" + { + "valid": false, + "evaluationPath": "/properties/foo/allOf/1", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1", + "instanceLocation": "/foo", + "droppedAnnotations": { + "properties": [ "foo-prop" ], + "title": "foo-title" + }, + "details": [ + { + "valid": false, + "evaluationPath": "/properties/foo/allOf/1/properties/foo-prop", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop", + "instanceLocation": "/foo/foo-prop", + "errors": { + "const": "Expected \"1\"" + }, + "droppedAnnotations": { + "title": "foo-prop-title" + } }, - "droppedAnnotations": { - "title": "foo-prop-title" + { + "valid": true, + "evaluationPath": "/properties/foo/allOf/1/additionalProperties", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties", + "instanceLocation": "/foo/other-prop" } + ] + } + ] + }, + { + "valid": false, + "evaluationPath": "/properties/bar", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/bar", + "instanceLocation": "/bar", + "details": [ + { + "valid": false, + "evaluationPath": "/properties/bar/$ref", + "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar", + "instanceLocation": "/bar", + "droppedAnnotations": { + "properties": [ "bar-prop" ], + "title": "bar-title" }, - { - "valid": true, - "evaluationPath": "/properties/foo/allOf/1/additionalProperties", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties", - "instanceLocation": "/foo/other-prop" - } - ] - } - ] - }, - { - "valid": false, - "evaluationPath": "/properties/bar", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/bar", - "instanceLocation": "/bar", - "details": [ - { - "valid": false, - "evaluationPath": "/properties/bar/$ref", - "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar", - "instanceLocation": "/bar", - "droppedAnnotations": { - "properties": [ "bar-prop" ], - "title": "bar-title" - }, - "details": [ - { - "valid": false, - "evaluationPath": "/properties/bar/$ref/properties/bar-prop", - "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop", - "instanceLocation": "/bar/bar-prop", - "errors": { - "minimum": "2 is less than or equal to 10" - }, - "droppedAnnotations": { - "title": "bar-prop-title" + "details": [ + { + "valid": false, + "evaluationPath": "/properties/bar/$ref/properties/bar-prop", + "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop", + "instanceLocation": "/bar/bar-prop", + "errors": { + "minimum": "2 is less than or equal to 10" + }, + "droppedAnnotations": { + "title": "bar-prop-title" + } } - } - ] - } - ] - } - ] + ] + } + ] + } + ] + } } ``` ```json "Passing Results { - "valid": true, - "evaluationPath": "", - "schemaLocation": "https://json-schema.org/schemas/example#", - "instanceLocation": "", - "annotations": { - "title": "root", - "properties": [ - "foo", - "bar" - ] - }, - "details": [ - { - "valid": true, - "evaluationPath": "/properties/foo", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo", - "instanceLocation": "/foo", - "details": [ - { - "valid": true, - "evaluationPath": "/properties/foo/allOf/0", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0", - "instanceLocation": "/foo" - }, - { - "valid": true, - "evaluationPath": "/properties/foo/allOf/1", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1", - "instanceLocation": "/foo", - "annotations": { - "title": "foo-title", - "properties": [ - "foo-prop" - ], - "additionalProperties": [ - "unspecified-prop" - ] - }, - "details": [ - { - "valid": true, - "evaluationPath": "/properties/foo/allOf/1/properties/foo-prop", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop", - "instanceLocation": "/foo/foo-prop", - "annotations": { - "title": "foo-prop-title" - } - }, - { - "valid": true, - "evaluationPath": "/properties/foo/allOf/1/additionalProperties", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties", - "instanceLocation": "/foo/unspecified-prop" - } - ] - } + "dialect": "https://json-schema.org/draft/next/schema", + "baseUri": "https://json-schema.org/schemas/example", + "valid": false, + "details": { + "valid": true, + "evaluationPath": "", + "schemaLocation": "https://json-schema.org/schemas/example#", + "instanceLocation": "", + "annotations": { + "title": "root", + "properties": [ + "foo", + "bar" ] }, - { - "valid": true, - "evaluationPath": "/properties/bar", - "schemaLocation": "https://json-schema.org/schemas/example#/properties/bar", - "instanceLocation": "/bar", - "details": [ - { - "valid": true, - "evaluationPath": "/properties/bar/$ref", - "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar", - "instanceLocation": "/bar", - "annotations": { - "title": "bar-title", - "properties": [ - "bar-prop" - ] + "details": [ + { + "valid": true, + "evaluationPath": "/properties/foo", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo", + "instanceLocation": "/foo", + "details": [ + { + "valid": true, + "evaluationPath": "/properties/foo/allOf/0", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/0", + "instanceLocation": "/foo" }, - "details": [ - { - "valid": true, - "evaluationPath": "/properties/bar/$ref/properties/bar-prop", - "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop", - "instanceLocation": "/bar/bar-prop", - "annotations": { - "title": "bar-prop-title" + { + "valid": true, + "evaluationPath": "/properties/foo/allOf/1", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1", + "instanceLocation": "/foo", + "annotations": { + "title": "foo-title", + "properties": [ + "foo-prop" + ], + "additionalProperties": [ + "unspecified-prop" + ] + }, + "details": [ + { + "valid": true, + "evaluationPath": "/properties/foo/allOf/1/properties/foo-prop", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop", + "instanceLocation": "/foo/foo-prop", + "annotations": { + "title": "foo-prop-title" + } + }, + { + "valid": true, + "evaluationPath": "/properties/foo/allOf/1/additionalProperties", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/foo/allOf/1/additionalProperties", + "instanceLocation": "/foo/unspecified-prop" } - } - ] - } - ] - } - ] + ] + } + ] + }, + { + "valid": true, + "evaluationPath": "/properties/bar", + "schemaLocation": "https://json-schema.org/schemas/example#/properties/bar", + "instanceLocation": "/bar", + "details": [ + { + "valid": true, + "evaluationPath": "/properties/bar/$ref", + "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar", + "instanceLocation": "/bar", + "annotations": { + "title": "bar-title", + "properties": [ + "bar-prop" + ] + }, + "details": [ + { + "valid": true, + "evaluationPath": "/properties/bar/$ref/properties/bar-prop", + "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop", + "instanceLocation": "/bar/bar-prop", + "annotations": { + "title": "bar-prop-title" + } + } + ] + } + ] + } + ] + } } ``` From e90d18d9a08887f0c81b40639eef75d15b3386f3 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 9 Feb 2024 12:19:03 +1300 Subject: [PATCH 2/6] refinements; update output schema --- jsonschema-validation-output-machines.md | 66 +++++++++--------------- output/schema.json | 42 +++++++-------- 2 files changed, 44 insertions(+), 64 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index 81bf9b0b..4239ffa0 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -26,20 +26,24 @@ convertible to the JSON format defined herein via serialization or other means. ## Applicability -The formats described in this document apply only for a successful evaluation. If the implementation encounters a scenario for which JSON Schema requires that evaluation halt, the requirements herein do not apply, and the implementation SHOULD react as appropriate for its language/environment. +The formats described in this document apply only for a successful evaluation, +irrespective of whether validation passes or fails. If the implementation +encounters a scenario for which JSON Schema requires that evaluation halts, the +requirements herein do not apply, and the implementation SHOULD react as +appropriate for its language/environment. ## Overview -The root of JSON Schema output MUST be a JSON object. This object MUST contain the following metadata regarding the validation: +The root of JSON Schema output MUST be a JSON object. This object MUST contain +the following metadata regarding the validation: | JSON Property Name | Description | |:-:|:-| | `dialect` | Schema dialect (`$schema` value) | | `baseUri` | Schema base URI (`$id` value) | | `valid` | Boolean containing the overall validation result | -| `details` | Contains the detailed subschema evaluation results in one of the [formats](#output-structure) below | - - +| `details` | Contains the detailed subschema evaluation results in one of the [formats](#output-structure) below
Required only for "list" and "hierarchical" formats | + ## Minimum Information for Subschema Validation and Annotation @@ -74,28 +78,6 @@ passed validation by the local subschema. The JSON key for these additional results is `valid`. -### Results from Subschemas - -Evaluation results generated by applying a subschema to the instance or a child -of the instance. Keywords which have multiple subschemas (e.g. `anyOf`) will -generally generate an output unit for each subschema. In order to accommodate -potentially multiple results, the value of this property MUST be an array of -output units, even if only a single output unit is produced. - -For "list", this property will appear only at the root output unit and will hold -all output units in a flat list. - -For "hierarchical", this property will contain results in a tree structure where -each output unit may itself have further nested results. - -The sequence of output units within this list is not specified and MAY be -determined by the implementation. Sets of output units are considered equivalent -if they contain the same units, in any order. - - - -The JSON key for these additional results is `details`. - ## Output Structure {#output-structure} This specification defines three output formats. @@ -235,9 +217,8 @@ The passing instance will produce the following annotations: ### Flag -In the simplest case, merely the boolean result for the `valid` valid property -needs to be fulfilled. For this format, all other information is explicitly -omitted. +In the simplest case, only the overview needs to be fulfilled. For the "flag" +format, all other information is explicitly omitted. ```json "Flag Results" { @@ -255,14 +236,8 @@ check the other three. The logic can simply return with success. ### List -The "list" structure is a flat list of output units contained within a root -output unit. - -The root output unit contains `valid` for the overall result and `details` for -the list of specific results. All other information is explicitly omitted from -the root output unit. If the root schema produces errors or annotations, then -the output node for the root MUST be present within the root output unit's -`details` list with those errors or annotations. +The "list" format is a flat list of output units contained within a root output +unit. Output units which do not contain errors or annotations SHOULD be excluded from this format, however implementations MAY choose to include them for @@ -375,14 +350,19 @@ completeness. ### Hierarchical -The "Hierarchical" structure is a tree structure that follows the evaluation -path during the validation process. Typically, it will resemble the schema as if -all referenced schemas were inlined in place of their associated by-reference +The "hierarchical" format is a tree structure that follows the evaluation path +during the validation process. Typically, it will resemble the schema as if all +referenced schemas were inlined in place of their associated by-reference keywords. -All output units are included in this format. +For each output unit, evaluation results generated by any subschemas are +provided under a `details` property, and each such subschema will generate an +output unit. In order to accommodate keywords with multiple subschemas, the +value of this property MUST be an array of output units, even if only a single +output unit is produced. The sequence of output units within this list is not +specified and MAY be determined by the implementation. -The location properties of the root output unit MAY be omitted. +All output units are included in this format. ```json "failing Results { diff --git a/output/schema.json b/output/schema.json index 8487a290..d31eebae 100644 --- a/output/schema.json +++ b/output/schema.json @@ -3,11 +3,25 @@ "$id": "https://json-schema.org/draft/next/output/schema", "description": "A schema that validates the minimum requirements for validation output", - "anyOf": [ - { "$ref": "#/$defs/flag" }, - { "$ref": "#/$defs/list" }, - { "$ref": "#/$defs/hierarchical" } - ], + "properties": { + "dialect": { + "type": "string", + "format": "iri" + }, + "baseUri": { + "type": "string", + "format": "iri" + }, + "valid": { "type": "boolean" }, + "details": { + "anyOf": [ + { "$ref": "#/$defs/list" }, + { "$ref": "#/$defs/hierarchical" } + ] + } + }, + "requires": [ "dialect", "baseUri", "valid" ], + "$defs": { "outputUnit":{ "properties": { @@ -18,7 +32,7 @@ }, "schemaLocation": { "type": "string", - "format": "uri" + "format": "iri" }, "instanceLocation": { "type": "string", @@ -75,21 +89,7 @@ "type": "array", "items": { "$ref": "#/$defs/outputUnit" } }, - "flag": { - "properties": { - "valid": { "type": "boolean" } - }, - "required": [ "valid" ] - }, - "list": { - "properties": { - "valid": { "type": "boolean" }, - "nested": { - "$ref": "#/$defs/outputUnitArray" - } - }, - "required": [ "valid", "nested" ] - }, + "list": { "$ref": "#/$defs/outputUnitArray" }, "hierarchical": { "$ref": "#/$defs/outputUnit" } } } From d6797708273057a111adcba107d16947d5763798 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 14 Feb 2024 09:53:25 +1300 Subject: [PATCH 3/6] remove dialect from overview block --- jsonschema-validation-output-machines.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index 4239ffa0..d94f3a27 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -39,8 +39,7 @@ the following metadata regarding the validation: | JSON Property Name | Description | |:-:|:-| -| `dialect` | Schema dialect (`$schema` value) | -| `baseUri` | Schema base URI (`$id` value) | +| `baseUri` | Evaluation root base URI (`$id` value) | | `valid` | Boolean containing the overall validation result | | `details` | Contains the detailed subschema evaluation results in one of the [formats](#output-structure) below
Required only for "list" and "hierarchical" formats | @@ -245,7 +244,6 @@ completeness. ```json "Failing Results" { - "dialect": "https://json-schema.org/draft/next/schema", "baseUri": "https://json-schema.org/schemas/example", "valid": false, "details": [ @@ -282,7 +280,6 @@ completeness. ```json "Passing Results" { - "dialect": "https://json-schema.org/draft/next/schema", "baseUri": "https://json-schema.org/schemas/example", "valid": true, "details": [ @@ -366,7 +363,6 @@ All output units are included in this format. ```json "failing Results { - "dialect": "https://json-schema.org/draft/next/schema", "baseUri": "https://json-schema.org/schemas/example", "valid": false, "details": { @@ -461,7 +457,6 @@ All output units are included in this format. ```json "Passing Results { - "dialect": "https://json-schema.org/draft/next/schema", "baseUri": "https://json-schema.org/schemas/example", "valid": false, "details": { From 0e7b1edb58cd8a2b4b9d56830bcce2ee29eee82d Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 16 Feb 2024 09:50:24 +1300 Subject: [PATCH 4/6] Update output/schema.json Co-authored-by: Jason Desrosiers --- output/schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/output/schema.json b/output/schema.json index d31eebae..19db3f26 100644 --- a/output/schema.json +++ b/output/schema.json @@ -20,7 +20,7 @@ ] } }, - "requires": [ "dialect", "baseUri", "valid" ], + "requires": [ "baseUri", "valid" ], "$defs": { "outputUnit":{ From 55a631bd4ded169e3b1d1bd5eb4da6a2db15382f Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 16 Feb 2024 09:50:41 +1300 Subject: [PATCH 5/6] Update jsonschema-validation-output-machines.md Co-authored-by: Jason Desrosiers --- jsonschema-validation-output-machines.md | 1 - 1 file changed, 1 deletion(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index d94f3a27..e297fb9c 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -221,7 +221,6 @@ format, all other information is explicitly omitted. ```json "Flag Results" { - "dialect": "https://json-schema.org/draft/next/schema", "baseUri": "https://json-schema.org/schemas/example", "results": false } From 91fd38cd5eff47ea40c3fdddf2469f78fd327520 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 16 Feb 2024 09:50:48 +1300 Subject: [PATCH 6/6] Update output/schema.json Co-authored-by: Jason Desrosiers --- output/schema.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/output/schema.json b/output/schema.json index 19db3f26..0761f9e0 100644 --- a/output/schema.json +++ b/output/schema.json @@ -4,10 +4,6 @@ "description": "A schema that validates the minimum requirements for validation output", "properties": { - "dialect": { - "type": "string", - "format": "iri" - }, "baseUri": { "type": "string", "format": "iri"