refinements; update output schema

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 |
-
-<!-- Placeholder for other ideas -->
+| `details` | Contains the detailed subschema evaluation results in one of the [formats](#output-structure) below<br> Required only for "list" and "hierarchical" formats |
+<!-- Placeholder for other metadata ideas -->
 
 ## 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.
-
-<!-- Not sure if it's necessary to mention equivalence. -->
-
-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
 {

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