From 77d7f9ec6ca9476355512ff4492348f282e9c9b0 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 22 Aug 2019 22:11:48 -0700 Subject: [PATCH] Improve guidance on annotations and output Remove wording that is no longer meaningful now that we have recommended output formats. Also do not use meta-schema as example for relative and absolute paths because my brain broke trying to figure out what it was doing. --- jsonschema-core.xml | 44 ++++++++++++++++++++++++++------------- jsonschema-validation.xml | 17 ++++++++------- 2 files changed, 38 insertions(+), 23 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 2d91ffe6..3dfce27f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -812,22 +812,26 @@ location, annotation keywords need to specify any unusual handling of multiple applicable occurrences of the keyword with different values. - - The default behavior is simply to collect all values in a list in - indeterminate order. Given the extensibility of keywords, including - applicators, it is not possible to define a universally predictable - order of processing. - Unlike assertion results, annotation data can take a wide variety of forms, which are provided to applications to use as they see fit. JSON Schema implementations are not expected to make use of the collected information on behalf of applications. + + Unless otherwise specified, the value of an annotation keyword's + annotation is the keyword's value. However, other behaviors are possible. + For example, JSON Hyper-Schema's + "links" keyword is a complex annotation that produces a value based + in part on the instance data. + While "short-circuit" evaluation is possible for assertions, collecting annotations requires examining all schemas that apply to an instance location, even if they cannot change the overall assertion result. + The only exception is that subschemas of a schema object that has + failed validation MAY be skipped, as annotations are not retained + for failing schemas.
@@ -863,7 +867,9 @@ If the same keyword attaches values from multiple schema locations to the same instance location, and the annotation defines a process for combining such values, then the combined value MUST also be associated - with the instance location. + with the instance location. The output formats + described in this specification that include annotation information + meet this requirement.
@@ -2649,13 +2655,13 @@
- Note that this pointer may not be resolvable due to the inclusion of these - applicator keywords. + 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 "keywordLocation". @@ -2665,13 +2671,16 @@
The absolute, dereferenced location of the validating keyword. The value MUST - be expressed as an absolute URI, and it MUST NOT include by-reference applicators - such as "$ref" or "$recursiveRef". + be expressed as an absolute URI using the canonical URI of the relevant + schema object, and it MUST NOT include by-reference applicators + such as "$ref" or "$recursiveRef" as non-terminal path components. + It MAY end in such keywords if the error or annotation is for that + keyword, such as an unresolvable reference.
@@ -2687,7 +2696,7 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum
The location of the JSON value within the instance being validated. The - value MUST be expressed as a JSON Pointer. + value MUST be expressed as a URI fragment-encoded JSON Pointer. The JSON key for this information is "instanceLocation". @@ -2702,6 +2711,10 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum For errors, the specific wording for the message is not defined by this specification. Implementations will need to provide this. + + For annotations, each keyword that produces an annotation specifies its + format. By default, it is the keyword's value. + The JSON key for failed validations is "error"; for successful validations it is "annotation". @@ -2715,7 +2728,8 @@ https://json-schema.org/draft/2019-08/schema#/$defs/nonNegativeInteger/minimum The JSON key for nested results in failed validations is "errors"; for - successful validations it is "annotations". + successful validations it is "annotations". Note the plural forms, as + a keyword with nested results can also have a local error or annotation.
diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index f0881992..8ea2d668 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -137,9 +137,10 @@ This specification defines a set of assertion keywords, as well as a small vocabulary of metadata keywords that can be used to annotate the JSON instance with - useful information. The and - keywords are also useful as annotations as well as being optional assertions, - as they convey additional usage guidance for the instance data. + useful information. The keyword is intended primarily + as an annotation, but can optionally be used as an assertion. The + keywords are annotations for working with documents + embedded as JSON strings.
@@ -1157,9 +1158,9 @@
The value of this keyword MUST be a boolean. When multiple occurrences - of this keyword are applicable to a single sub-instance, the resulting - value MUST be true if any occurrence specifies a true value, and MUST - be false otherwise. + of this keyword are applicable to a single sub-instance, applications + SHOULD consider the instance location to be deprecated if any occurrence + specifies a true value. If "deprecated" has a value of boolean true, it indicates that applications @@ -1179,8 +1180,8 @@ The value of these keywords MUST be a boolean. When multiple occurrences of these keywords are applicable to a single sub-instance, the resulting - value MUST be true if any occurrence specifies a true value, and MUST - be false otherwise. + behavior SHOULD be as for a true value if any occurrence specifies a true value, + and SHOULD be as for a false value otherwise. If "readOnly" has a value of boolean true, it indicates that the value