What does "annotation result" mean?

[meowsbits]

Hey all, I'm trying to wrap my head around the spec (specifically, this section) and I see annotation result used, but I can't find a definition for it. What does it mean?

This issue deals with it too, but I wasn't able to grok a definition there either.

[karenetheridge]

Here's a good place to start: https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.7.7

[meowsbits]

Thanks for that link! I can't believe I missed it 🤦 .

So first a little rehash of what I'm understanding "annotation results" to be. To see if I'm on track.

Annotations are arbitrary keyword/<value> pairs on a JSON Schema. Since JSON Schema allows arbitrary pairs, this is allowed.

eg.

{
  "type": "string",
  "describes": "color" 
}

In this example, "describes" is the annotation, and "color" is the default "annotation result".

Unless otherwise specified, the value of an annotation keyword's annotation is the keyword's value.
https://json-schema.org/draft/2019-09/json-schema-core.html#annotations

Another example, from the spec:

{
    "title": "Feature list",
    "type": "array",
    "items": [
        {
            "title": "Feature A",
            "properties": {
                "enabled": {
                    "$ref": "#/$defs/enabledToggle",
                    "default": true
                }
            }
        },
        {
            "title": "Feature B",
            "properties": {
                "enabled": {
                    "description": "If set to null, Feature B
                                    inherits the enabled
                                    value from Feature A",
                    "$ref": "#/$defs/enabledToggle"
                }
            }
        }
    ],
    "$defs": {
        "enabledToggle": {
            "title": "Enabled",
            "description": "Whether the feature is enabled (true),
                            disabled (false), or under
                            automatic control (null)",
            "type": ["boolean", "null"],
            "default": null
        }
    }
}

In this case, "default" is the annotation, and true and null are the distinct annotation results, noting that:

The application programmer and the schema author need to agree on the usage. For this example, let's assume that they agree that the most specific "default" value will be used, and any additional, more generic "default" values will be silently ignored.
[...]
Note that there are other reasonable approaches that a different application might take. For example, an application may consider the presence of two different values for "default" to be an error, regardless of their schema locations.
https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.7.7.1.1

So, if I'm correct so far (and please correct me if I'm not), if annotation results behavior definitions (used presumably interchangeably with annotation data) fall into the purview of arbitrary negotiation between application designers and Schema designers, as:

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.
https://json-schema.org/draft/2019-09/json-schema-core.html#annotations

If this is indeed the case, then I'm confused about the spec's apparent concrete use of the annotation result as an element establishing definition in the spec:

The behavior of this keyword ["additionalItems"] depends on the presence and annotation result of "items" within the same schema object. If "items" is present, and its annotation result is a number, validation succeeds if every instance element at an index greater than that number validates against "additionalItems".
https://json-schema.org/draft/2019-09/json-schema-core.html#additionalItems

It would seem that the spec defines the validation of a keyword (additionalItems) in way that necessitates and defines use of the annotation result. But aren't annotation results (and their behavior) negotiable and arbitrary?

[handrews]

@meowsbits "annotation results" in the sense of "data produced by an annotation keyword and returned to the application that ran the JSON Schema implementation" are not negotiable or arbitrary. readOnly produces a boolean that always means the same thing with respect to the annotated location (that you cannot change it in some sense). title always produces a string.

"annotations results" in the sense of "the application-level effect of processing annotations" is negotiable and therefore somewhat arbitrary. The application has to determine what sort of change readOnly is forbidding. It could mean that this is data that gets sent to a server which will reject or ignore a change. It could mean that trying to change it in memory will cause some sort of problem. It could be entirely advisory, for human documentation, with no enforcement at code level. We don't know or care. The application really ought not to do anything weird like inverting readOnly to mean writeOnly, or overloading it with some other purpose, but that's a vague "ought not" and not a specification-level SHOULD NOT.

Does this help?

[Relequestual]

/remind me to close this issue if there's no reply in 28 days

[reminders]

@Relequestual set a reminder for Oct 16th 2020