From dea83444ca59cd6aa2d2460c4062781c6fdcd038 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 28 Aug 2023 14:12:03 +1200 Subject: [PATCH 01/16] remove specific output formats from core spec; defer to other specs --- jsonschema-core.md | 599 +++------------------------------------------ 1 file changed, 32 insertions(+), 567 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index d47d1618..4c2fa1d6 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -2071,67 +2071,31 @@ Omitting this keyword has the same assertion behavior as an empty schema. ## Output Formatting {#output} -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. +In order to foster increased usability and interoperability, implementations SHOULD adhere to well-defined output formats. -### Format +Because JSON Schema has multiple uses cases, and those uses cases have different intended consumers, this specification defers the details of any output formats to other documents. Implementations are encouraged to support multiple output formats as required by their target user base. -JSON Schema output is defined using the JSON Schema data instance model as -described in [Instance Data Model](#data-model). Implementations MAY deviate -from this 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. +The scope of this section, therefore, is limited to defining common terms that SHOULD be used in JSON Schema output specifications in order to align the vernacular across differing formats. Output specifications which use this information MUST use this terminology to describe it. Conversely, output specifications which use these terms MUST maintain their meaning. -### Output Formats +### Evaluation path -This specification defines three output formats. See the "Output Structure" -section for the requirements of each format. - -- *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. - -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. - -### Minimum Information - -Beyond the simplistic "flag" output, additional information is useful to aid in -debugging a schema or instance. Each sub-result SHOULD contain the information -contained within this section at a minimum. - -A single object that contains all of these components is considered an output -unit. - -Implementations MAY elect to provide additional information. - -#### Evaluation path - -The evaluation path to the schema object that produced the output unit. The -value MUST be expressed as a JSON Pointer, and it MUST include any by-reference -applicators such as `$ref` or `$dynamicRef`.[^13] - -[^13]: The schema may not actually have a value at the location indicated by -this pointer. It is provided as an indication of the traversal path only. +The evaluation path is the set of keys, starting from the schema root, through which evaluation passes to reach the schema object that produced a specific result. +The value MUST be expressed as a JSON Pointer, and it MUST include any by-reference +applicators such as `$ref` or `$dynamicRef`. ``` /properties/width/$ref/allOf/1 ``` -Note that this pointer may not be resolvable by the normal JSON Pointer process -due to the inclusion of these by-reference applicator keywords. +Note that this pointer may not be resolvable on the root schema by the normal JSON Pointer process. +It is intended as an indication of the traversal path only. -The JSON key for this information is "evaluationPath". +When represented in JSON, the key for this information MUST be "evaluationPath". -#### Schema Location +### Schema Location -The absolute, dereferenced location of the schema object that produced the -output unit. The value MUST be expressed using the canonical IRI of the relevant +The schema location is the absolute, dereferenced location of the schema object that produced a result. +The value MUST be expressed using the canonical IRI of the relevant schema resource plus a JSON Pointer fragment that indicates the schema object that produced the output. It MUST NOT include by-reference applicators such as `$ref` or `$dynamicRef`.[^14] @@ -2145,539 +2109,40 @@ a fragment in order to identify the specific schema object. https://example.com/schemas/common#/$defs/allOf/1 ``` -The JSON key for this information is "schemaLocation". +When represented in JSON, the key for this information MUST be "schemaLocation". -#### Instance Location +### Instance Location -The location of the JSON value within the instance being validated. The value -MUST be expressed as a JSON Pointer. +The instance location is the location of the JSON value within the root instance being validated. +The value MUST be expressed as a JSON Pointer. -The JSON key for this information is "instanceLocation". +When represented in JSON, the key for this information MUST be "instanceLocation". -#### Errors +### Errors -Any errors produced by the validation. This property MUST NOT be included if the -validation was successful. The value for this property MUST be an object where -the keys are the names of keywords and the values are the error message produced -by the associated keyword. +Errors are textual representations of individual validation failures, often intended for human consumers. This specification contains no requirements for the content of these errors. -If the subschema itself is producing the error, that error MUST be listed with -an empty string key.[^15] +When represented in JSON, the key for this information MUST be "errors". -[^15]: Although there may be other cases where a subschema can produce an error, -the most common case is the `false` schema. In cases like these, there is no -keyword that produces the error, so there is nothing to use as a key. Thus the -empty string is used instead. +### Annotations -The specific wording for the message is not defined by this specification. -Implementations will need to provide this. +Many keywords are defined to produce annotations, whether intended for inter-keyword communication (e.g. between `properties` and `unevaluatedProperties`) or for application consumption (e.g. `title` or `readOnly`). Annotation values may be of any type and are defined by the keywords that produced them. -The JSON key for this information is "errors". +When represented in JSON, the key for this information MUST be "annotations". -#### Annotations +### Dropped Annotations -Any annotations produced by the evaluation. This property MUST NOT be included -if the validation result of the containing subschema was unsuccessful. - -The value for this property MUST be an object where the keys are the names of -keywords and the values are the annotations produced by the associated keyword. - -Each keyword defines its own annotation data type (e.g. `properties` produces a -list of keywords, whereas `title` produces a string). - -The JSON key for this information is "annotations". - -#### Dropped Annotations - -Any annotations produced and subsequently dropped by the evaluation due to an -unsuccessful validation result of the containing subschema. This property MAY be -included if the validation result of the containing subschema was unsuccessful. +A dropped annotation is any annotation produced and subsequently dropped by the evaluation due to an +unsuccessful validation result of the containing subschema. +This information MAY be included if the validation result of the containing subschema was unsuccessful. It MUST NOT be included if the local validation result of the containing subschema was successful. -Implementations that wish to provide these annotations MUST NOT provide them as -their default behavior. These annotations MUST only be included by explicitly -configuring the implementation to do so. - -The value for this property MUST be an object where the keys are the names of -keywords and the values are the annotations produced by the associated keyword. - -Each keyword defines its own annotation data type (e.g. `properties` produces a -list of keywords, whereas `title` produces a string). - -The JSON key for this information is "droppedAnnotations". - -#### 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 - -The output MUST be an object containing a boolean property named "valid". When -additional information about the result is required, the output MUST also -contain "details" as described below. - -valid: a boolean value indicating the overall validation success or failure - -details: the collection of results produced by subschemas - -For these examples, the following schema and instances will be used. - -```jsonschema -{ - "$schema": "https://json-schema.org/draft/next/schema", - "$id": "https://json-schema.org/schemas/example", - "type": "object", - "title": "root", - "properties": { - "foo": { - "allOf": [ - { "required": [ "unspecified-prop" ] }, - { - "type": "object", - "title": "foo-title", - "properties": { - "foo-prop": { - "const": 1, - "title": "foo-prop-title" - } - }, - "additionalProperties": { "type": "boolean" } - } - ] - }, - "bar": { - "$ref": "#/$defs/bar" - } - }, - "$defs": { - "bar": { - "type": "object", - "title": "bar-title", - "properties": { - "bar-prop": { - "type": "integer", - "minimum": 10, - "title": "bar-prop-title" - } - } - } - } -} -``` - -```json "Failing instance" -{ - "foo": {"foo-prop": "not 1", "other-prop": false}, - "bar": {"bar-prop": 2} -} -``` - -```json "Passing instance" -{ - "foo": { - "foo-prop": 1, - "unspecified-prop": true - }, - "bar": {"bar-prop": 20} -} -``` - -The failing instance will produce the following errors: - -- The value at `/foo` evaluated at `/properties/foo/allOf/0` by following the - path `/properties/foo/allOf/0` by the `required` keyword is missing the - property `unspecified-prop`. -- The value at `/foo/foo-prop` evaluated at - `/properties/foo/allOf/1/properties/foo-prop` by following the path - `/properties/foo/allOf/1/properties/foo-prop` by the `const` keyword is not - the constant value 1. -- The value at `/bar/bar-prop` evaluated at `/$defs/bar/properties/bar-prop` by - following the path `/properties/bar/$ref/properties/bar-prop` by the `type` - keyword is not a number.[^16][^17] - -[^16]: `minimum` doesn't produce an error because it only operates on instances -that are numbers. - -[^17]: Note that the error message wording as depicted in the examples below is -not a requirement of this specification. Implementations SHOULD craft error -messages tailored for their audience or provide a templating mechanism that -allows their users to craft their own messages. - -The passing instance will produce the following annotations: - -- The keyword `title` evaluated at the instance root by the root schema will produce - `"root"`. -- The keyword `properties` evaluated at instance root by the root schema will produce - `["foo", "bar"]`. -- The keyword `title` evaluated at `/properties/foo` by following the path - `/properties/foo` will produce `"foo-title"`. -- The keyword `properties` evaluated at `/properties/foo/allOf/1` by following - the path `/properties/foo/allOf/1` will produce `["foo-prop"]`. -- The keyword `additionalProperties` evaluated at `/properties/foo/allOf/1` by - following the path `/properties/foo/allOf/1` will produce - `["unspecified-prop"]`. -- The keyword `title` evaluated at `/properties/foo/allOf/1/properties/foo-prop` - by following the path `/properties/foo/allOf/1/properties/foo-prop` will - produce `"foo-prop-title"`. -- The keyword `title` evaluated at `/$defs/bar` by following the path - `/properties/bar/$ref` will produce `"bar-title"`. -- The keyword `properties` evaluated at `/$defs/bar` by following the path - `/properties/var/$ref` will produce `["bar-prop"]`. -- The keyword `title` evaluated at `/$defs/bar/properties/bar-prop` by following - the path `/properties/bar/$ref/properties/bar-prop` will produce - `"bar-prop-title"`. - -#### 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. - -```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. - -#### 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. - -Output units which do not contain errors or annotations SHOULD be excluded from -this format, however implementations MAY choose to include them for -completeness. - -```json "Failing results" -{ - "valid": false, - "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/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/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" - } - } - ] -} -``` - -```json "Passing results" -{ - "valid": true, - "details": [ - { - "valid": true, - "evaluationPath": "", - "schemaLocation": "https://json-schema.org/schemas/example#", - "instanceLocation": "", - "annotations": { - "title": "root", - "properties": [ - "foo", - "bar" - ] - } - }, - { - "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" - ] - } - }, - { - "valid": true, - "evaluationPath": "/properties/bar/$ref", - "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar", - "instanceLocation": "/bar", - "annotations": { - "title": "bar-title", - "properties": [ - "bar-prop" - ] - } - }, - { - "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/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" - } - } - ] -} -``` - -#### 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. - -All output units are included in this format. - -The location properties of the root output unit MAY be omitted. - -```json "Failing results (errors)" -{ - "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": "/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" - } - }, - { - "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" - } - } - ] - } - ] - } - ] -} -``` - -```json "Passing results (annotations)" -{ - "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" - } - ] - } - ] - }, - { - "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" - } - } - ] - } - ] - } - ] -} -``` - -#### Output validation schemas +Implementations that wish to provide dropped annotations MUST NOT provide them as +their default behavior. Dropped annotations MUST only be included when the +implementations is explicitly configured to do so. -For convenience, JSON Schema has been provided to validate output generated by -implementations. Its IRI is: . +When represented in JSON, the key for this information MUST be "droppedAnnotations". ## Security Considerations {#security} From fc59a3e58edf282f1b9af4a42deea9302d5ebf40 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 28 Aug 2023 15:53:46 +1200 Subject: [PATCH 02/16] import output spec from #1385 --- jsonschema-machine-output.md | 605 +++++++++++++++++++++++++++++++++++ 1 file changed, 605 insertions(+) create mode 100644 jsonschema-machine-output.md diff --git a/jsonschema-machine-output.md b/jsonschema-machine-output.md new file mode 100644 index 00000000..346ec572 --- /dev/null +++ b/jsonschema-machine-output.md @@ -0,0 +1,605 @@ +# A Specification for Machine-Readable JSON Schema Output + +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. + +## Schema Identifiers + +The output defined in this specification requires that the evaluation root be defined with an absolute IRI. 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. + +## Textual Format and Encoding + +JSON Schema output is defined using the JSON Schema data instance model as described in [JSON Schema, section 4.2.1](). Implementations MAY deviate from this 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. + +## Output Formats + +This specification defines three output formats. See the "Output Structure" section for the requirements of each format. + +- **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. + +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. + +## Minimum Information + +Beyond the simplistic "flag" output, additional information is useful to aid in debugging a schema or instance. Each sub-result MUST contain the information contained within this section at a minimum, unless otherwise specified. + +A single object that contains all of these components is considered an "output unit." + +Implementations MAY elect to provide additional information. + +### Evaluation path + +The evaluation path to the schema object that produced the output unit. The value MUST be expressed as a JSON Pointer, and it MUST include any by-reference applicators such as `$ref` or `$dynamicRef`. + + + +``` +/properties/width/$ref/allOf/1 +``` + +Note that this pointer may not be resolvable by the normal JSON Pointer process due to the inclusion of these by-reference applicator keywords. + +The JSON key for this information is `evaluationPath`. + +### Schema Location + +The absolute, dereferenced location of the schema object that produced the output unit. The value MUST be expressed using the canonical IRI of the relevant schema resource plus a JSON Pointer fragment that indicates the schema object that produced the output. It MUST NOT include by-reference applicators such as `$ref` or `$dynamicRef`. + + + +``` +https://example.com/schemas/common#/$defs/allOf/1 +``` + +The JSON key for this information is `schemaLocation`. + +### Instance Location + +The location of the JSON value within the instance being validated. The value MUST be expressed as a JSON Pointer. + +The JSON key for this information is `instanceLocation`. + +### Errors + +Any errors produced by the validation. This property MUST NOT be included if the validation was successful. The value +for this property MUST be an object where the keys are the names of keywords and the values are the error message produced by the associated keyword. + +If the subschema itself is producing the error, that error MUST be listed with an empty string key. + + + +The specific wording for the message is not defined by this specification. Implementations will need to provide this. + +The JSON key for this information is `errors`. + +### Annotations + +Any annotations produced by the evaluation. This property MUST NOT be included if the validation result of the containing subschema was unsuccessful. + +The value for this property MUST be an object where the keys are the names of keywords and the values are the annotations +produced by the associated keyword. + +Each keyword defines its own annotation data type (e.g. `properties` produces a list of object keys, whereas `title` produces a string). + +The JSON key for this information is `annotations`. + +### Dropped Annotations + +Any annotations produced and subsequently dropped by the evaluation due to an unsuccessful validation result of the containing subschema. This property MAY be included if the validation result of the containing subschema was unsuccessful. It MUST NOT be included if the local validation result of the containing subschema was successful. + +Implementations that wish to provide these annotations MUST NOT provide them as their default behavior. These annotations MUST only be included by explicitly configuring the implementation to do so. + +The value for this property MUST be an object where the keys are the names of keywords and the values are the annotations produced by the associated keyword. + +Each keyword defines its own annotation data type (e.g. `properties` produces a list of object keys, whereas `title` produces a string). + +The JSON key for this information is `droppedAnnotations`. + +### 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 + +The output MUST be an object containing a boolean property named `valid`. When additional information about the result is required, the output MUST also contain `details` as described below. + +- `valid` - a boolean value indicating the overall validation success or failure +- `details` - the collection of results produced by subschemas + +For these examples, the following schema and instances will be used. + +```jsonc +// schema +{ + "$schema": "https://json-schema.org/draft/next/schema", + "$id": "https://json-schema.org/schemas/example", + "type": "object", + "title": "root", + "properties": { + "foo": { + "allOf": [ + { "required": [ "unspecified-prop" ] }, + { + "type": "object", + "title": "foo-title", + "properties": { + "foo-prop": { + "const": 1, + "title": "foo-prop-title" + } + }, + "additionalProperties": { "type": "boolean" } + } + ] + }, + "bar": { + "$ref": "#/$defs/bar" + } + }, + "$defs": { + "bar": { + "type": "object", + "title": "bar-title", + "properties": { + "bar-prop": { + "type": "integer", + "minimum": 10, + "title": "bar-prop-title" + } + } + } + } +} + +// failing instance +{ + "foo": {"foo-prop": "not 1", "other-prop": false}, + "bar": {"bar-prop": 2} +} + +// 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` + evaluated at `/properties/foo/allOf/0` + by following the path `/properties/foo/allOf/0` + by the `required` keyword + is missing the property `unspecified-prop`. +- The value at `/foo/foo-prop` + evaluated at `/properties/foo/allOf/1/properties/foo-prop` + by following the path `/properties/foo/allOf/1/properties/foo-prop` + by the `const` keyword + is not the constant value 1. +- The value at `/bar/bar-prop` + evaluated at `/$defs/bar/properties/bar-prop` + by following the path `/properties/bar/$ref/properties/bar-prop` + by the `type` keyword + is not a number. + + + + +The passing instance will produce the following annotations: + +- The keyword `title` + evaluated at `` + by following the path `` + will produce `"root"`. +- The keyword `properties` + evaluated at `` + by following the path `` + will produce `["foo", "bar"]`. +- The keyword `title` + evaluated at `/properties/foo` + by following the path `/properties/foo` + will produce `"foo-title"`. +- The keyword `properties` + evaluated at `/properties/foo/allOf/1` + by following the path `/properties/foo/allOf/1` + will produce `["foo-prop"]`. +- The keyword `additionalProperties` + evaluated at `/properties/foo/allOf/1` + by following the path `/properties/foo/allOf/1` + will produce `["unspecified-prop"]`. +- The keyword `title` + evaluated at `/properties/foo/allOf/1/properties/foo-prop` + by following the path `/properties/foo/allOf/1/properties/foo-prop` + will produce `"foo-prop-title"`. +- The keyword `title` + evaluated at `/$defs/bar` + by following the path `/properties/bar/$ref` + will produce `"bar-title"`. +- The keyword `properties` + evaluated at `/$defs/bar` + by following the path `/properties/var/$ref` + will produce `["bar-prop"]`. +- The keyword `title` + evaluated at `/$defs/bar/properties/bar-prop` + by following the path `/properties/bar/$ref/properties/bar-prop` + will produce `"bar-prop-title"`. + +### 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. + +```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. + +### 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. + +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 +// failing results +{ + "valid": false, + "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/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/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" + } + } + ] +} + +// passing results +{ + "valid": true, + "details": [ + { + "valid": true, + "evaluationPath": "", + "schemaLocation": "https://json-schema.org/schemas/example#", + "instanceLocation": "", + "annotations": { + "title": "root", + "properties": [ + "foo", + "bar" + ] + } + }, + { + "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" + ] + } + }, + { + "valid": true, + "evaluationPath": "/properties/bar/$ref", + "schemaLocation": "https://json-schema.org/schemas/example#/$defs/bar", + "instanceLocation": "/bar", + "annotations": { + "title": "bar-title", + "properties": [ + "bar-prop" + ] + } + }, + { + "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/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" + } + } + ] +} +``` + +### 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. + +All output units are included in this format. + +The location properties of the root output unit MAY be omitted. + +```jsonc +// failing results (errors) +{ + "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": "/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" + } + }, + { + "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" + } + } + ] + } + ] + } + ] +} + +// passing results (annotations) +{ + "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" + } + ] + } + ] + }, + { + "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" + } + } + ] + } + ] + } + ] +} +``` + +## 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 + +## 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. + +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. + +### 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. + +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 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`. + +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. + +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. + +Output units which include annotations MUST NOT be pruned. + +Implementations which provide this behavior SHOULD provide configuration mechanisms appropriate for their users' needs. From 4e9e93bd37d8de20c1bb92391bdb1944f79a0136 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 28 Aug 2023 16:20:54 +1200 Subject: [PATCH 03/16] some properties are defined in core --- ...> jsonschema-validation-output-machines.md | 131 ++++++++---------- 1 file changed, 54 insertions(+), 77 deletions(-) rename jsonschema-machine-output.md => jsonschema-validation-output-machines.md (80%) diff --git a/jsonschema-machine-output.md b/jsonschema-validation-output-machines.md similarity index 80% rename from jsonschema-machine-output.md rename to jsonschema-validation-output-machines.md index 346ec572..938396ef 100644 --- a/jsonschema-machine-output.md +++ b/jsonschema-validation-output-machines.md @@ -1,20 +1,20 @@ -# A Specification for Machine-Readable JSON Schema Output +# 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. ## Schema Identifiers -The output defined in this specification requires that the evaluation root be defined with an absolute IRI. 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. ## Textual Format and Encoding -JSON Schema output is defined using the JSON Schema data instance model as described in [JSON Schema, section 4.2.1](). Implementations MAY deviate from this 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. ## Output Formats -This specification defines three output formats. See the "Output Structure" section for the requirements of each format. +This specification defines three output formats. See [Output Structure]{#output-structure} for the requirements of each format. - **Flag** - A boolean which simply indicates the overall validation result with no further details. - **List** - Provides validation information in a flat list structure. @@ -24,85 +24,21 @@ An implementation MUST provide the "flag" format and SHOULD provide at least one ## Minimum Information -Beyond the simplistic "flag" output, additional information is useful to aid in debugging a schema or instance. Each sub-result MUST contain the information contained within this section at a minimum, unless otherwise specified. +Beyond the simplistic "flag" output, additional information is useful to aid in debugging evaluation of an instance by a schema. Each sub-result 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 +- Instance Location A single object that contains all of these components is considered an "output unit." Implementations MAY elect to provide additional information. -### Evaluation path - -The evaluation path to the schema object that produced the output unit. The value MUST be expressed as a JSON Pointer, and it MUST include any by-reference applicators such as `$ref` or `$dynamicRef`. - - - -``` -/properties/width/$ref/allOf/1 -``` - -Note that this pointer may not be resolvable by the normal JSON Pointer process due to the inclusion of these by-reference applicator keywords. - -The JSON key for this information is `evaluationPath`. - -### Schema Location +### Validation Result {#validation-result} -The absolute, dereferenced location of the schema object that produced the output unit. The value MUST be expressed using the canonical IRI of the relevant schema resource plus a JSON Pointer fragment that indicates the schema object that produced the output. It MUST NOT include by-reference applicators such as `$ref` or `$dynamicRef`. - - - -``` -https://example.com/schemas/common#/$defs/allOf/1 -``` - -The JSON key for this information is `schemaLocation`. - -### Instance Location - -The location of the JSON value within the instance being validated. The value MUST be expressed as a JSON Pointer. - -The JSON key for this information is `instanceLocation`. - -### Errors - -Any errors produced by the validation. This property MUST NOT be included if the validation was successful. The value -for this property MUST be an object where the keys are the names of keywords and the values are the error message produced by the associated keyword. - -If the subschema itself is producing the error, that error MUST be listed with an empty string key. - - +The validation result is a boolean that indicates whether the local instance passed validation by the local subschema. -The specific wording for the message is not defined by this specification. Implementations will need to provide this. - -The JSON key for this information is `errors`. - -### Annotations - -Any annotations produced by the evaluation. This property MUST NOT be included if the validation result of the containing subschema was unsuccessful. - -The value for this property MUST be an object where the keys are the names of keywords and the values are the annotations -produced by the associated keyword. - -Each keyword defines its own annotation data type (e.g. `properties` produces a list of object keys, whereas `title` produces a string). - -The JSON key for this information is `annotations`. - -### Dropped Annotations - -Any annotations produced and subsequently dropped by the evaluation due to an unsuccessful validation result of the containing subschema. This property MAY be included if the validation result of the containing subschema was unsuccessful. It MUST NOT be included if the local validation result of the containing subschema was successful. - -Implementations that wish to provide these annotations MUST NOT provide them as their default behavior. These annotations MUST only be included by explicitly configuring the implementation to do so. - -The value for this property MUST be an object where the keys are the names of keywords and the values are the annotations produced by the associated keyword. - -Each keyword defines its own annotation data type (e.g. `properties` produces a list of object keys, whereas `title` produces a string). - -The JSON key for this information is `droppedAnnotations`. +The JSON key for these additional results is `valid`. ### Results from Subschemas @@ -116,7 +52,7 @@ The sequence of output units within this list is not specified and MAY be determ The JSON key for these additional results is `details`. -## Output Structure +## Output Structure {#output-structure} The output MUST be an object containing a boolean property named `valid`. When additional information about the result is required, the output MUST also contain `details` as described below. @@ -603,3 +539,44 @@ Reasons to omit output units may include, but are not limited to: Output units which include annotations MUST NOT be pruned. Implementations which provide this behavior SHOULD provide configuration mechanisms appropriate for their users' needs. + +## References + +### Normative References + +#### [RFC2119] {#rfc2119} + +Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, +RFC 2119, DOI 10.17487/RFC2119, March 1997, +<>. + +#### [RFC3986] {#rfc3986} + +Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier +(URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, +<>. + +#### [RFC3987] {#rfc3987} + +Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC +3987, DOI 10.17487/RFC3987, January 2005, +<>. + +#### [RFC6901] {#rfc6901} + +Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation +(JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, +<>. + +#### [RFC8259] {#rfc8259} + +Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", +STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, +<>. + +#### [json-schema] {#json-schema} + +Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON Schema: A Media Type +for Describing JSON Documents", Work in Progress, Internet-Draft, +draft-bhutton-json-schema-01, June 2022, +<>. From db1d0bc7162be0eca2b8646ec79c466e01244000 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 28 Aug 2023 16:44:49 +1200 Subject: [PATCH 04/16] combine 'output formats' and 'output structure' sections; add conditionally available properties --- jsonschema-validation-output-machines.md | 33 ++++++++++++++---------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index 938396ef..cd382062 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -12,25 +12,25 @@ There are no requirements on the form of IRI itself, except that it MUST be abso 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. -## Output Formats - -This specification defines three output formats. See [Output Structure]{#output-structure} for the requirements of each format. - -- **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. +## Minimum Information -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. +Beyond the simplistic "flag" output, additional information is useful to aid in debugging evaluation of an instance by a schema. -## Minimum Information +The output of a subschema validation is considered an "output unit." The contents of each output unit is specified by this section. -Beyond the simplistic "flag" output, additional information is useful to aid in debugging evaluation of an instance by a schema. Each sub-result 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 - Instance Location -A single object that contains all of these components is considered an "output unit." +The following information MAY be included conditionally: + +- When subschema validation has succeeded + - Annotations +- When subschema validation has failed + - Errors + - Dropped Annotations Implementations MAY elect to provide additional information. @@ -50,14 +50,19 @@ For "hierarchical", this property will contain results in a tree structure where 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} -The output MUST be an object containing a boolean property named `valid`. When additional information about the result is required, the output MUST also contain `details` as described below. +This specification defines three output formats. -- `valid` - a boolean value indicating the overall validation success or failure -- `details` - the collection of results produced by subschemas +- **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. + +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. From 39ebe11bc9f2b11c8036b5451d6d0f13119614b4 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 1 Sep 2023 14:00:38 +1200 Subject: [PATCH 05/16] reflow; add build --- jsonschema-validation-output-machines.md | 150 +++++++++++++++++------ package.json | 5 +- 2 files changed, 113 insertions(+), 42 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index cd382062..b2dbb5c1 100644 --- a/jsonschema-validation-output-machines.md +++ b/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. @@ -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,14 +136,16 @@ 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, @@ -123,8 +153,8 @@ For these examples, the following schema and instances will be used. }, "bar": {"bar-prop": 20} } - ``` + The failing instance will produce the following errors: - The instance value at `/foo` @@ -191,7 +221,9 @@ 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 { @@ -199,15 +231,25 @@ In the simplest case, merely the boolean result for the `valid` valid property n } ``` -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: ## 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 diff --git a/package.json b/package.json index 3e806283..e5e2a18f 100644 --- a/package.json +++ b/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": { From d0e00c1f07adc7d3cdb0548bc8ce16877a0d13ab Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 1 Sep 2023 13:45:56 +1200 Subject: [PATCH 06/16] json conventions Co-authored-by: Jason Desrosiers --- jsonschema-validation-output-machines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index b2dbb5c1..02073740 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -104,7 +104,7 @@ For these examples, the following schema and instances will be used. "properties": { "foo": { "allOf": [ - { "required": [ "unspecified-prop" ] }, + { "required": ["unspecified-prop"] }, { "type": "object", "title": "foo-title", From b9b984827aeffc3459f40211a7052e20ed8d322e Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 1 Sep 2023 13:46:08 +1200 Subject: [PATCH 07/16] json conventions Co-authored-by: Jason Desrosiers --- jsonschema-validation-output-machines.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index 02073740..8479f97c 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -118,9 +118,7 @@ For these examples, the following schema and instances will be used. } ] }, - "bar": { - "$ref": "#/$defs/bar" - } + "bar": { "$ref": "#/$defs/bar" } }, "$defs": { "bar": { From 33f84c566c00d0e735dc445bf4b5c00f13f3c95a Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 1 Sep 2023 13:46:18 +1200 Subject: [PATCH 08/16] json conventions Co-authored-by: Jason Desrosiers --- jsonschema-validation-output-machines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index 8479f97c..4a813706 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -138,8 +138,8 @@ For these examples, the following schema and instances will be used. ```json "failing instance" { - "foo": {"foo-prop": "not 1", "other-prop": false}, - "bar": {"bar-prop": 2} + "foo": { "foo-prop": "not 1", "other-prop": false }, + "bar": { "bar-prop": 2 } } ``` From 076790d1c2f0aad526060cc0f88320993c2876f2 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 1 Sep 2023 13:46:25 +1200 Subject: [PATCH 09/16] json conventions Co-authored-by: Jason Desrosiers --- jsonschema-validation-output-machines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index 4a813706..ab1128e6 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -149,7 +149,7 @@ For these examples, the following schema and instances will be used. "foo-prop": 1, "unspecified-prop": true }, - "bar": {"bar-prop": 20} + "bar": { "bar-prop": 20 } } ``` From 4e7be40fb06e591c9101f4e4640d1ef813ceb13c Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 1 Sep 2023 14:04:31 +1200 Subject: [PATCH 10/16] reflow core --- jsonschema-core.md | 70 +++++++++++++++++++++++++++++----------------- 1 file changed, 44 insertions(+), 26 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 4c2fa1d6..72333401 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -2071,34 +2071,44 @@ Omitting this keyword has the same assertion behavior as an empty schema. ## Output Formatting {#output} -In order to foster increased usability and interoperability, implementations SHOULD adhere to well-defined output formats. +In order to foster increased usability and interoperability, implementations +SHOULD adhere to well-defined output formats. -Because JSON Schema has multiple uses cases, and those uses cases have different intended consumers, this specification defers the details of any output formats to other documents. Implementations are encouraged to support multiple output formats as required by their target user base. +Because JSON Schema has multiple uses cases, and those uses cases have different +intended consumers, this specification defers the details of any output formats +to other documents. Implementations are encouraged to support multiple output +formats as required by their target user base. -The scope of this section, therefore, is limited to defining common terms that SHOULD be used in JSON Schema output specifications in order to align the vernacular across differing formats. Output specifications which use this information MUST use this terminology to describe it. Conversely, output specifications which use these terms MUST maintain their meaning. +The scope of this section, therefore, is limited to defining common terms that +SHOULD be used in JSON Schema output specifications in order to align the +vernacular across differing formats. Output specifications which use this +information MUST use this terminology to describe it. Conversely, output +specifications which use these terms MUST maintain their meaning. ### Evaluation path -The evaluation path is the set of keys, starting from the schema root, through which evaluation passes to reach the schema object that produced a specific result. -The value MUST be expressed as a JSON Pointer, and it MUST include any by-reference -applicators such as `$ref` or `$dynamicRef`. +The evaluation path is the set of keys, starting from the schema root, through +which evaluation passes to reach the schema object that produced a specific +result. The value MUST be expressed as a JSON Pointer, and it MUST include any +by-reference applicators such as `$ref` or `$dynamicRef`. ``` /properties/width/$ref/allOf/1 ``` -Note that this pointer may not be resolvable on the root schema by the normal JSON Pointer process. -It is intended as an indication of the traversal path only. +Note that this pointer may not be resolvable on the root schema by the normal +JSON Pointer process. It is intended as an indication of the traversal path +only. When represented in JSON, the key for this information MUST be "evaluationPath". ### Schema Location -The schema location is the absolute, dereferenced location of the schema object that produced a result. -The value MUST be expressed using the canonical IRI of the relevant -schema resource plus a JSON Pointer fragment that indicates the schema object -that produced the output. It MUST NOT include by-reference applicators such as -`$ref` or `$dynamicRef`.[^14] +The schema location is the absolute, dereferenced location of the schema object +that produced a result. The value MUST be expressed using the canonical IRI of +the relevant schema resource plus a JSON Pointer fragment that indicates the +schema object that produced the output. It MUST NOT include by-reference +applicators such as `$ref` or `$dynamicRef`.[^14] [^14]: Note that "absolute" here is in the sense of "absolute filesystem path" (meaning the complete location) rather than the "absolute-IRI" terminology from @@ -2113,36 +2123,44 @@ When represented in JSON, the key for this information MUST be "schemaLocation". ### Instance Location -The instance location is the location of the JSON value within the root instance being validated. -The value MUST be expressed as a JSON Pointer. +The instance location is the location of the JSON value within the root instance +being validated. The value MUST be expressed as a JSON Pointer. -When represented in JSON, the key for this information MUST be "instanceLocation". +When represented in JSON, the key for this information MUST be +"instanceLocation". ### Errors -Errors are textual representations of individual validation failures, often intended for human consumers. This specification contains no requirements for the content of these errors. +Errors are textual representations of individual validation failures, often +intended for human consumers. This specification contains no requirements for +the content of these errors. When represented in JSON, the key for this information MUST be "errors". ### Annotations -Many keywords are defined to produce annotations, whether intended for inter-keyword communication (e.g. between `properties` and `unevaluatedProperties`) or for application consumption (e.g. `title` or `readOnly`). Annotation values may be of any type and are defined by the keywords that produced them. +Many keywords are defined to produce annotations, whether intended for +inter-keyword communication (e.g. between `properties` and +`unevaluatedProperties`) or for application consumption (e.g. `title` or +`readOnly`). Annotation values may be of any type and are defined by the +keywords that produced them. When represented in JSON, the key for this information MUST be "annotations". ### Dropped Annotations -A dropped annotation is any annotation produced and subsequently dropped by the evaluation due to an -unsuccessful validation result of the containing subschema. -This information MAY be included if the validation result of the containing subschema was unsuccessful. -It MUST NOT be included if the local validation result of the containing -subschema was successful. +A dropped annotation is any annotation produced and subsequently dropped by the +evaluation due to an unsuccessful validation result of the containing subschema. +This information MAY be included if the validation result of the containing +subschema was unsuccessful. It MUST NOT be included if the local validation +result of the containing subschema was successful. -Implementations that wish to provide dropped annotations MUST NOT provide them as -their default behavior. Dropped annotations MUST only be included when the +Implementations that wish to provide dropped annotations MUST NOT provide them +as their default behavior. Dropped annotations MUST only be included when the implementations is explicitly configured to do so. -When represented in JSON, the key for this information MUST be "droppedAnnotations". +When represented in JSON, the key for this information MUST be +"droppedAnnotations". ## Security Considerations {#security} From ef14ca7bfced70e8fd4d389dd5507608cae0737d Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 13 Sep 2023 11:55:35 +1200 Subject: [PATCH 11/16] restate requirements for scheam location; remove note --- jsonschema-core.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 72333401..61da331e 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -2104,16 +2104,10 @@ When represented in JSON, the key for this information MUST be "evaluationPath". ### Schema Location -The schema location is the absolute, dereferenced location of the schema object -that produced a result. The value MUST be expressed using the canonical IRI of -the relevant schema resource plus a JSON Pointer fragment that indicates the -schema object that produced the output. It MUST NOT include by-reference -applicators such as `$ref` or `$dynamicRef`.[^14] - -[^14]: Note that "absolute" here is in the sense of "absolute filesystem path" -(meaning the complete location) rather than the "absolute-IRI" terminology from -RFC 3987 (meaning with scheme and without fragment). Schema locations will have -a fragment in order to identify the specific schema object. +The schema location is the canonical URI of the schema object plus a JSON +Pointer fragment indicating the subschema that produced a result. In contrast +with the evaluation path, the schema location MUST NOT include by-reference +applicators such as `$ref` or `$dynamicRef`. ``` https://example.com/schemas/common#/$defs/allOf/1 From 1d83efbf987df881062c04076e228fc3889053d9 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 13 Sep 2023 12:02:14 +1200 Subject: [PATCH 12/16] address dropped annotations requirements; remove JSON key name requirements --- jsonschema-core.md | 20 +++++--------------- 1 file changed, 5 insertions(+), 15 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index 61da331e..aa94bd06 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -2113,24 +2113,17 @@ applicators such as `$ref` or `$dynamicRef`. https://example.com/schemas/common#/$defs/allOf/1 ``` -When represented in JSON, the key for this information MUST be "schemaLocation". - ### Instance Location The instance location is the location of the JSON value within the root instance being validated. The value MUST be expressed as a JSON Pointer. -When represented in JSON, the key for this information MUST be -"instanceLocation". - ### Errors Errors are textual representations of individual validation failures, often intended for human consumers. This specification contains no requirements for the content of these errors. -When represented in JSON, the key for this information MUST be "errors". - ### Annotations Many keywords are defined to produce annotations, whether intended for @@ -2139,8 +2132,6 @@ inter-keyword communication (e.g. between `properties` and `readOnly`). Annotation values may be of any type and are defined by the keywords that produced them. -When represented in JSON, the key for this information MUST be "annotations". - ### Dropped Annotations A dropped annotation is any annotation produced and subsequently dropped by the @@ -2149,12 +2140,11 @@ This information MAY be included if the validation result of the containing subschema was unsuccessful. It MUST NOT be included if the local validation result of the containing subschema was successful. -Implementations that wish to provide dropped annotations MUST NOT provide them -as their default behavior. Dropped annotations MUST only be included when the -implementations is explicitly configured to do so. - -When represented in JSON, the key for this information MUST be -"droppedAnnotations". +As the intended purpose for including these annotations is debugging, +implementations that wish to provide dropped annotations SHOULD NOT provide them +as their default behavior. Dropped annotations SHOULD only be included when the +implementation is explicitly configured to do so or if the implementation is +specifically intended to be used as a debugging tool. ## Security Considerations {#security} From 3e81674eace8eba04a845fc59f291f46e5dc4352 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Wed, 13 Sep 2023 12:12:24 +1200 Subject: [PATCH 13/16] link to annotation requirements; add requirements of output specs to include details for errors and annotations --- jsonschema-core.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/jsonschema-core.md b/jsonschema-core.md index aa94bd06..bf08f59d 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -2124,6 +2124,10 @@ Errors are textual representations of individual validation failures, often intended for human consumers. This specification contains no requirements for the content of these errors. +Output specifications which include errors SHOULD be written such that the +sources (schema and instance) of a given error is easily identifiable and SHOULD +use the terms defined by this document to do so. + ### Annotations Many keywords are defined to produce annotations, whether intended for @@ -2132,6 +2136,10 @@ inter-keyword communication (e.g. between `properties` and `readOnly`). Annotation values may be of any type and are defined by the keywords that produced them. +Output specifications which include annotations SHOULD be written such that they +can be easily associated with the data defined in {{collect}} and SHOULD use the +terms defined by this document to do so. + ### Dropped Annotations A dropped annotation is any annotation produced and subsequently dropped by the @@ -2146,6 +2154,10 @@ as their default behavior. Dropped annotations SHOULD only be included when the implementation is explicitly configured to do so or if the implementation is specifically intended to be used as a debugging tool. +Output specifications which include dropped annotations SHOULD be written such +that they can be easily associated with the data defined in {{collect}} and +SHOULD use the terms defined by this document to do so. + ## Security Considerations {#security} Both schemas and instances are JSON values. As such, all security considerations From 2a0d4c788f02cdb6ede75ef3bea1d6a1c240cae9 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 14 Sep 2023 08:26:31 +1200 Subject: [PATCH 14/16] update hierarchical examples to have code block titles --- jsonschema-validation-output-machines.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index ab1128e6..a411a317 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -250,8 +250,7 @@ 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 -// failing results +```json "Failing Results" { "valid": false, "details": [ @@ -284,8 +283,9 @@ completeness. } ] } +``` -// passing results +```json "Passing Results" { "valid": true, "details": [ @@ -362,8 +362,7 @@ All output units are included in this format. The location properties of the root output unit MAY be omitted. -```jsonc -// failing results (errors) +```json "failing Results { "valid": false, "evaluationPath": "", @@ -451,8 +450,9 @@ The location properties of the root output unit MAY be omitted. } ] } +``` -// passing results (annotations) +```json "Passing Results { "valid": true, "evaluationPath": "", From 8270653a9f59fadd2df0d789f22d486254505bbe Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 14 Sep 2023 08:28:32 +1200 Subject: [PATCH 15/16] fix casing of setup code block titles --- jsonschema-validation-output-machines.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/jsonschema-validation-output-machines.md b/jsonschema-validation-output-machines.md index a411a317..398162bb 100644 --- a/jsonschema-validation-output-machines.md +++ b/jsonschema-validation-output-machines.md @@ -95,7 +95,7 @@ documentation which formats they support. For these examples, the following schema and instances will be used. -```jsonschema "schema" +```jsonschema "Example Schema" { "$schema": "https://json-schema.org/draft/next/schema", "$id": "https://json-schema.org/schemas/example", @@ -136,14 +136,14 @@ For these examples, the following schema and instances will be used. } ``` -```json "failing instance" +```json "Failing Instance" { "foo": { "foo-prop": "not 1", "other-prop": false }, "bar": { "bar-prop": 2 } } ``` -```json "passing instance" +```json "Passing Instance" { "foo": { "foo-prop": 1, @@ -223,7 +223,7 @@ 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 +```json "Flag Results" { "valid": false } From 69711aacc94bffdd316de22859b588463612aac2 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Mon, 18 Sep 2023 11:33:44 +1200 Subject: [PATCH 16/16] adjust mention of output formats in intro section --- jsonschema-core.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.md b/jsonschema-core.md index bf08f59d..26045426 100644 --- a/jsonschema-core.md +++ b/jsonschema-core.md @@ -30,10 +30,11 @@ and interaction control of JSON data. This specification defines JSON Schema core terminology and mechanisms, including pointing to another JSON Schema by reference, dereferencing a JSON Schema reference, specifying the dialect being used, specifying a dialect's -vocabulary requirements, and defining the expected output. +vocabulary requirements, and defining terms. Other specifications define the vocabularies that perform assertions about -validation, linking, annotation, navigation, and interaction. +validation, linking, annotation, navigation, and interaction as well as output +formats. ## Conventions and Terminology