Oct 5, 2023 · Aug 28, 2023 · Aug 28, 2023 · Aug 28, 2023 · Aug 28, 2023 · Sep 1, 2023
diff --git a/jsonschema-core.md b/jsonschema-core.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
gregsdennis marked this conversation as resolved. Outdated Show resolved Hide resolved
	that produced a result. The value MUST be expressed using the canonical IRI of
gregsdennis marked this conversation as resolved. Outdated Show resolved Hide resolved
	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]
Copy link Member @jdesrosiers jdesrosiers Sep 8, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. Saying that it MUST NOT include `$ref` is, I think, a little more restrictive than is intended. It makes sense for the pointer to include a `$ref`, but only as the terminating value. Since 2019-09, `$ref` is a normal keyword and it make sense for schema location to point to that keyword as much as any other. Copy link Member Author @gregsdennis gregsdennis Sep 9, 2023 • edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. There's not a schema at a `$ref`, only a string (URI). { "type": "array", "items": { "$ref": "foo.json" } } The schema location indicates the schema object that produced the output. There are only two schema objects here: the root the `items` subschema If an evaluation result comes from inside the `$ref`, then the schema location is `foo.json` or some subschema contained by it (unless another `$ref` was followed). Thus, "schema location" never contains a reference keyword. Really, this is a "by definition" requirement, but it felt helpful to state it explicitly. Copy link Member @jdesrosiers jdesrosiers Sep 11, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. I was thinking that "schema location" meant the location in the schema rather than the location of a schema, but reading more carefully, I see I had that wrong. However, if this section is intended to be a set of universal concepts output format authors can use when creating custom output formats, it seems a bit limiting to not provide a concept that allows them to point to a keyword. I won't hold up this PR for that. It can be worked out later if necessary. Copy link Member Author @gregsdennis gregsdennis Sep 11, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. Yeah, the concepts currently listed are the ones that are currently used by the (now split) output spec. I don't mind additional things being added, but I think I'd want to see them being used first. You know, see the term in another output spec, and then import it into this spec to standardize it so that other output specs can use the same term. jdesrosiers reacted with thumbs up emoji

		[^14]: Note that "absolute" here is in the sense of "absolute filesystem path"
		(meaning the complete location) rather than the "absolute-IRI" terminology from
gregsdennis marked this conversation as resolved. Outdated Show resolved Hide resolved
Expand All		@@ -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.
jdesrosiers marked this conversation as resolved. Show resolved Hide resolved

	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.
Comment on lines +2134 to +2138 Copy link Member @jdesrosiers jdesrosiers Sep 8, 2023 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others. Learn more. It might be useful to have a link in here somewhere to the section that defines annotations. gregsdennis reacted with thumbs up emoji

		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}

Expand Down