JSON Schema Core - 9.3.1.3. unevaluatedItems - clarification suggested

[hrennau]

The text of 9.3.1.3. unevaluatedItems uses the term "adjacent keywords", whereas the text 9.3.1.2. additionalItems uses the term "within the same schema object". I suppose that "adjacent" and "within the same schema object" are equivalent, but I am not completely sure.

A second point to clarify. The text says: "Those two annotations, as well as 'unevaluatedItems', can also result from any and all adjacent in-place keywords". I suppose that "resulting from adjacent in-place keywords" means directly or indirectly resulting annotations - e.g. includes the annotations produced by a subschema which is not the value of an adjacent in-place keyword, but the value of a nested in-place keyword contained by the value of the adjacent in-place keyword.

If my understanding is correct, I suggest to change the text slightly,
from
"resulting from adjacent in-place keywords"
to
"resulting from adjacent in-place keywords, either directly or indirectly via nested in-place keywords."

[Relequestual]

"adjacent keywords" and "within the same schema object".
Yes, they do mean the same thing, but the context within which they are used gives different implications.

The behavior of this keyword depends on the presence and annotation result of "items" within the same schema object.

The behavior of this keyword depends on the annotation results of adjacent keywords that apply to the instance location being validated.

The phrasing is different because additionalItems depends on a single keyword in the same schema object, as opposed to multile annotation results, which may originate from nested schema objects (as I think you've correctly identified).

...e.g. includes the annotations produced by a subschema which is not the value of an adjacent in-place keyword, but the value of a nested in-place keyword contained by the value of the adjacent in-place keyword.

I don't think there's such a thing as a subschema which is not the value of an adjacent in-place applicator keyword, because the resulting annotations are collected and effectivly "bubble up" or ...collect (hence "annotation collection")...

https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.7.7.1.3

In addition to possibly defining annotation results of their own, applicator keywords aggregate the annotations collected in their subschema(s) or referenced schema(s).

Let me know if any of that is unclear if you would like additional clarification.

I'm super glad you're digging into the spec to the point where you have these sort of questions! =] Please continue to do so!

[hrennau]

Thank you for these detailed explanations! I understand, and in the meantime I've also understood the logic behind what appeared to me as a somewhat arbitrary distinction between (a) annotations produced by adjacent keywords and (b) possible other annotations from the same keyword and targeting the same instance location, but not stemming from adjacent keywords. I've realized that keyword adjacency defines a horizon of well-defined temporal order - within this horizon, it makes sense to say "after the production of all annotations", outside of it - not. Therefore now I understand why "unevaluatedItems" ignores annotations produced by, for example, "cousin schemas" (e.g. a schema which is sibling to the containing schema, both of them being items in the array of schemas of a "anyOf" keyword). The keyword simply considers as many annotations as it can! Whether there is more meaning to this "set" of annotations (beyond being the largest possible), something those annotations have "in common" - this is something I have not yet realized, and I doubt it is the case.

The idea behind "additionalItems" I now understand as similar to a "default" clause of a switch expression: making sure that to every array item, which has not yet been checked, at least some constraint is applied. (It's also a bit like the idea of test coverage - we want the items to have been inspected, if only in a minimal way, rather than letting them pass through without asking.)

I wonder if there is some document explaining the rationale behind "unevaluated...", e.g. describing use cases.

[handrews]

We should just explain what "adjacent" means in §4.3.1 JSON Schema Objects and Keywords. That would be the logical place to introduce the terminology.

@hrennau the main motivation behind the unevalluated* keywords that match older additional* keywords is that many people, for many years and draft revisions, have expected or wanted additionalProperties to behave the way unevaluatedProperties does. In particular:

{
    "$schema": "http://json-schema.org/draft-07/schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "someSchemaDefiningProperties"
        }
    ],
    "additionalProperties": false
}

It doesn't matter what's in someSchemaDefiningProperties, the "additionalProperties": false can't "see" it, and forbids any and all properties.

However, with unevaluatedProperties (and also the new ability to just put the keyword next to $ref instead of having to wrap with an allOf):

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "type": "object",
    "$ref": "someSchemaDefiningProperties",
    "unevaluatedProperties": false
}

In this case, unevaluatedProperties can "see" into someSchemaDefiningProperties through the annotation mechanism and behaves the way many people always expected additionalProperties to behave.

We did not want to change additionalProperties because its actual behavior does have real use cases. So we added a new keyword. unevaluatedItems was mostly done for symmetry, but we did come up with some use cases. I think around modeling functions with variable-length positional arguments but TBH I don't remember.

For a complex unevaluatedProperties use case, with lots of dynamic runtime determination due to oneOf (which was part of the challenge for this), see this refactor of an early proposed OpenAPI 3.0.x schema. That was earlier on in the unevaluatedProperties proposal process, so some things may be off, and some other schema features it talks about may or may not have made it into the current spec.

You are correct about

The keyword simply considers as many annotations as it can!

There is no particular significance beyond this. JSON Schema evaluation with an instance is expected to essentially do a depth first traverse, gathering annotations at leaf schemas and rolling them up as you walk back out. There's no way to look at cousin or parent schema objects and factor them in. This is, in practice, not much of a problem- you can always push unevaluated* keywords upwards so that they can "see" all appropriate annotations. Although occasionally it requires creative refactoring.

[handrews]

The "directly or indirectly" thing should follow from the annotation collection process but perhaps that can be clarified? I'd like it to be associated with collecting the annotations more than the specifics of using them with each keyword. The general process is not keyword-specific.

[Relequestual]

@hrennau
I feel this is clear. Here's the second p of 9.3.1.3

The behavior of this keyword depends on the annotation results of adjacent keywords that apply to the instance location being validated. Specifically, the annotations from "items" and "additionalItems", which can come from those keywords when they are adjacent to the "unevaluatedItems" keyword. Those two annotations, as well as "unevaluatedItems", can also result from any and all adjacent in-place applicator keywords. This includes but is not limited to the in-place applicators defined in this document.

I can't the exact phrasing you picked up on ("resulting from adjacent in-place keywords").

I considered changing...

The behavior of this keyword depends on the annotation results of adjacent keywords that apply to the instance location being validated.

to

The behavior of this keyword depends on the annotation results of adjacent keywords that apply to the instance location being validated, including in-place applicatior keywords.

But then I feel it's covered by...

Those two annotations, as well as "unevaluatedItems", can also result from any and all adjacent in-place applicator keywords. This includes but is not limited to the in-place applicators defined in this document.

Given the above, what are your thoughts now?
Is there anything unclear after re-reading that section closely?

[epoberezkin]

@Relequestual there is another place in spec that uses "adjacent" to mean "in the same schema object", that is a sibling, another property of the same object.

Given the intention to apply unevaluatedKeyword based on the annotation results of ALL keywords that apply to this instance location (and not only based on the results of adjacent keywords), it is best to avoid using the word "adjacent" - its literal meaning is "preceding or following, next to".

[handrews]

@epoberezkin unevaluatedProperties definitely only takes into account adjacent keywords (and their subschemas).

[handrews]

I meant unevaluatedItems, although of course it's true of both.

[epoberezkin]

ok, got it - it's because they bubble up... Maybe it's worth clarifying.

[Relequestual]

@epoberezkin In retrospect, do you feel this is already covered by paragraph 2 of http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.9.3.2.4 ?

The behavior of this keyword depends on the annotation results of adjacent keywords that apply to the instance location being validated. ...

Those three annotations, as well as "unevaluatedProperties", can also result from any and all adjacent in-place applicator keywords.

If not, would you like to suggest how we could make it clearer? =]