reflow; add build

Author: gregsdennis

jsonschema-validation-output-machines.md

@@ -1,24 +1,40 @@
 # A Specification for Machine-Readable Output for JSON Schema Validation and Annotation
 
-JSON Schema is defined to be platform-independent.  As such, to increase compatibility across platforms, implementations SHOULD conform to a standard validation output format.  This section describes the minimum requirements that consumers will need to properly interpret validation results.
+JSON Schema is defined to be platform-independent. As such, to increase
+compatibility across platforms, implementations SHOULD conform to a standard
+validation output format. This specification describes the minimum requirements
+for machine consumers to properly interpret validation results.
+
+## Table of Contents
 
 ## Schema Identifiers
 
-The output defined in this specification requires that the evaluation root be defined with an absolute IRI, i.e. using the `$id` keyword.  In the event an absolute IRI has not been defined, the implementation MUST generate one.
+The output defined in this specification requires that the evaluation root be
+defined with an absolute IRI, i.e. using the `$id` keyword. In the event an
+absolute IRI has not been defined, the implementation MUST generate one.
 
-There are no requirements on the form of IRI itself, except that it MUST be absolute.
+There are no requirements on the form of IRI itself, except that it MUST be
+absolute.
 
 ## Textual Format and Encoding
 
-JSON Schema output is defined using the JSON Schema data instance model as described in [JSON Schema](#json-schema) "Instance Data Model".  Implementations 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.
+JSON Schema output is defined using the JSON Schema data instance model as
+described in [JSON Schema](#json-schema) "Instance Data Model". Implementations
+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
 
-Beyond the simplistic "flag" output, additional information is useful to aid in debugging evaluation of an instance by a schema.
+Beyond the simplistic "flag" output, additional information is useful to aid in
+debugging evaluation of an instance by a schema.
 
-The output of a subschema validation is considered an "output unit."  The contents of each output unit is specified by this section.
+The output of a subschema validation is considered an "output unit." The
+contents of each output unit is specified by this section.
 
-Each output unit MUST contain the [validation result](#validation-result) for the associated subschema as well as the following information defined by [JSON Schema](#json-schema) "Output Formatting":
+Each output unit MUST contain the [validation result](#validation-result) for
+the associated subschema as well as the following information defined by
+[JSON Schema](#json-schema) "Output Formatting":
 
 - Evaluation Path
 - Schema Location
@@ -36,19 +52,28 @@ Implementations MAY elect to provide additional information.
 
 ### Validation Result {#validation-result}
 
-The validation result is a boolean that indicates whether the local instance passed validation by the local subschema.
+The validation result is a boolean that indicates whether the local instance
+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.
+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 "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.
+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 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. -->
 
@@ -58,16 +83,19 @@ 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.
+- **Flag** - A boolean which simply indicates the overall validation result with
+  no further details.
 - **List** - Provides validation information in a flat list structure.
-- **Hierarchical** - Provides validation information in a hierarchical structure that follows the evaluation paths generated while processing the schema.
+- **Hierarchical** - Provides validation information in a hierarchical structure
+  that follows the evaluation paths generated while processing the schema.
 
-An implementation MUST provide the "flag" format and SHOULD provide at least one of the "list" or "hierarchical" formats. Implementations SHOULD specify in their documentation which formats they support.
+An implementation MUST provide the "flag" format and SHOULD provide at least one
+of the "list" or "hierarchical" formats. Implementations SHOULD specify in their
+documentation which formats they support.
 
 For these examples, the following schema and instances will be used.
 
-```jsonc
-// schema
+```jsonschema "schema"
 {
   "$schema": "https://json-schema.org/draft/next/schema",
   "$id": "https://json-schema.org/schemas/example",
@@ -108,23 +136,25 @@ For these examples, the following schema and instances will be used.
     }
   }
 }
+```
 
-// failing instance
+```json "failing instance"
 {
   "foo": {"foo-prop": "not 1", "other-prop": false},
   "bar": {"bar-prop": 2}
 }
+```
 
-// passing instance
+```json "passing instance"
 {
   "foo": {
     "foo-prop": 1,
     "unspecified-prop": true
   },
   "bar": {"bar-prop": 20}
 }
-
 ```
+
 The failing instance will produce the following errors:
 
 - The instance value at `/foo`
@@ -191,23 +221,35 @@ 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, merely the boolean result for the `valid` valid property
+needs to be fulfilled. For this format, all other information is explicitly
+omitted.
 
 ```json
 {
   "valid": false
 }
 ```
 
-Because no errors or annotations are returned with this format, it is RECOMMENDED that implementations use short-circuiting logic to return failure or success as soon as the outcome can be determined.  For example, if an `anyOf` keyword contains five subschemas, and the second one passes, there is no need to check the other three.  The logic can simply return with success.
+Because no errors or annotations are returned with this format, it is
+RECOMMENDED that implementations use short-circuiting logic to return failure or
+success as soon as the outcome can be determined. For example, if an `anyOf`
+keyword contains five subschemas, and the second one passes, there is no need to
+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 "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 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.
 
-Output units which do not contain errors or annotations SHOULD be excluded from this format, however implementations MAY choose to include them for
+Output units which do not contain errors or annotations SHOULD be excluded from
+this format, however implementations MAY choose to include them for
 completeness.
 
 ```jsonc
@@ -313,7 +355,10 @@ 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 keywords.
+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
+keywords.
 
 All output units are included in this format.
 
@@ -506,44 +551,69 @@ The location properties of the root output unit MAY be omitted.
 
 ## Output validation schemas
 
-For convenience, JSON Schema has been provided to validate output generated by implementations.  Its IRI is: https://json-schema.org/draft/next/output/schema
+For convenience, JSON Schema has been provided to validate output generated by
+implementations. Its IRI is: <https://json-schema.org/draft/next/output/schema>
 
 ## Filtering
 
-For various reasons, including human readability and performance during evaluation, a user may desire to omit certain details from the output.  To address this, implementations MAY provide filtering output information.
+For various reasons, including human readability and performance during
+evaluation, a user may desire to omit certain details from the output. To
+address this, implementations MAY provide filtering output information.
 
-This section defines several RECOMMENDED approaches to filtering, however implementations MAY choose to provide these features in a way that suits them and their users best.
+This section defines several RECOMMENDED approaches to filtering, however
+implementations MAY choose to provide these features in a way that suits them
+and their users best.
 
-For those implementations which support filtering behaviors, the behaviors MUST be configurable and disabled by default.
+For those implementations which support filtering behaviors, the behaviors MUST
+be configurable and disabled by default.
 
 ### Annotation Filtering
 
-Collecting and storing annotations can require increasing amounts of system resources as evaluation proceeds.  The strain on systems can be reduced by only collecting those annotations which users care about.
+Collecting and storing annotations can require increasing amounts of system
+resources as evaluation proceeds. The strain on systems can be reduced by only
+collecting those annotations which users care about.
 
-For annotation filtering, implementations SHOULD provide a mechanism which allows users to configure either the set annotations they would like to keep or the set they would like to ignore.
+For annotation filtering, implementations SHOULD provide a mechanism which
+allows users to configure either the set annotations they would like to keep or
+the set they would like to ignore.
 
-For a "keep" list, an implementation MUST include in the output only those annotations which are configured.
+For a "keep" list, an implementation MUST include in the output only those
+annotations which are configured.
 
-For an "ignore" list, an implementation MUST NOT include in the output those annotations which are configured.
+For an "ignore" list, an implementation MUST NOT include in the output those
+annotations which are configured.
 
 #### Annotations Required for Evaluation
 
-Some implementations may be annotation-driven.  That is, the evaluation of some keywords depends on the annotation results of other keywords.  For example, which properties are seen by `additionalProperties` can be determined by looking at the annotation results of `properties` and `patternProperties`.
+Some implementations may be annotation-driven. That is, the evaluation of some
+keywords depends on the annotation results of other keywords. For example, which
+properties are seen by `additionalProperties` can be determined by looking at
+the annotation results of `properties` and `patternProperties`.
 
-For these implementations, the annotation results of these dependent keywords must still be collected for proper evaluation.  However, these annotations MUST NOT be included in the output unless they are configured accordingly.
+For these implementations, the annotation results of these dependent keywords
+must still be collected for proper evaluation. However, these annotations MUST
+NOT be included in the output unless they are configured accordingly.
 
 ### Output Unit Pruning
 
-In many cases, the output structures defined herein produce output units for more than is necessary to identify evaluation issues.  Implementations SHOULD provide a mechanism which removes unimportant output units from the final structure in order to highlight those units which impact the final result.
+In many cases, the output structures defined herein produce output units for
+more than is necessary to identify evaluation issues. Implementations SHOULD
+provide a mechanism which removes unimportant output units from the final
+structure in order to highlight those units which impact the final result.
 
 Reasons to omit output units may include, but are not limited to:
 
-- Child output units whose validation result does not impact the validation result of the parent.  For example, a subschema of an `anyOf` which has a false validation result when there exists a sibling subschema with a true validation result.
-- Child output units which have a true validation result but contain no annotations.
+- Child output units whose validation result does not impact the validation
+  result of the parent. For example, a subschema of an `anyOf` which has a false
+  validation result when there exists a sibling subschema with a true validation
+  result.
+- Child output units which have a true validation result but contain no
+  annotations.
 
 Output units which include annotations MUST NOT be pruned.
 
-Implementations which provide this behavior SHOULD provide configuration mechanisms appropriate for their users' needs.
+Implementations which provide this behavior SHOULD provide configuration
+mechanisms appropriate for their users' needs.
 
 ## References
 

package.json

@@ -6,9 +6,10 @@
   "main": "index.js",
   "scripts": {
     "lint": "eslint build/",
-    "build": "npm run build-core && npm run build-validation",
+    "build": "npm run build-core && npm run build-validation && npm run build-output",
     "build-core": "node build/build.js < jsonschema-core.md > jsonschema-core.html",
-    "build-validation": "node build/build.js < jsonschema-validation.md > jsonschema-validation.html"
+    "build-validation": "node build/build.js < jsonschema-validation.md > jsonschema-validation.html",
+    "build-output": "node build/build.js < jsonschema-validation-output-machines.md > jsonschema-validation-output-machines.html"
   },
   "license": "MIT",
   "dependencies": {