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" } } }