v3.3: replace "array schema" with clearer definition

[karenetheridge]

• no schema changes are needed for this pull request

[handrews]

This was intentional, as prior OAS versions literally required type: array to be present. But really, if the data is an array and is validated by the schema, it doesn't matter if there is a type keyword at all. That's what "array schema" is meant to convey.

[karenetheridge]

The thing is, once we're validating the data it's too late to transform it, so I want to be sure what to look for. We've been good about sticking to the JSON Schema principle of "just because you see an array-requiring keyword like items doesn't mean it has to be an array", and instead only looking for type (or const or enum which also implicitly require a type(s)).

There have been a few places when parsing the partly-decoded content while walking down the encoding and schema trees that I've not been sure where a keyword dictates a behaviour, vs "disregard this if it doesn't match". I think for schemas, we should stick to the same logic as we use for style decoding (which is described in one of the appendices).

[handrews]

@karenetheridge At this point requiringtype: array would arguably be a breaking change. I suppose someone can argue that "array schema" means the same thing, but as I noted, I specifically did not mean type: array at the time.

I agree that there's a bit of a chicken and egg problem, but I'm not sure we can go back and add requirements on type. If we hadn't shipped it yet we would have more options (and I'd be more inclined to go with this).

I'm not 100% sure on all this, I'll need to go through and read all of the text closely and think on it more deeply.

[karenetheridge]

I would just like to fix the wording to whatever is actually intended, because "array schema" is not clear.

[handrews]

@karenetheridge

I would just like to fix the wording to whatever is actually intended, because "array schema" is not clear.

Yeah, that's fair! I'm trying to figure out what I meant here. I have two options:

1. We want to see either itemSchema or (if using schema), prefixItems and/or items, to ensure that there is something in the schema with which prefixEncoding and itemEncoding can be correlated.
2. We just want an array instance, and the actual schema details aren't important- "array schema" was just a proxy for "we want to make sure only arrays are valid."

Option 2 is definitely something we can do in a patch release.

Option 1... I think it hinges on this wording:

These fields are analogous to the prefixItems and items JSON Schema keywords,

I'm hesitant to say that we can make these fields required in the schema, because that could technically be a breaking change. But we could say something about how these keywords are used to correlate with prefixEncoding and itemEncoding, and therefore not having them makes such correlations more difficult. But not impossible- really, if you know you have an array instance, prefixEncoding and itemEncoding could be arranged differently from prefixItems and items. I don't know why you'd do that, but there's no reason you couldn't.

I think I'm leaning towards option 2, but I am open to other arguments.

I agree with you that this needs improvement.

[karenetheridge]

@ralfhandl why all the merges of the parent branch into these PRs? It doesn't do anything except add more clutter to the main branch when it's eventually merged.

[ralfhandl]

We merged a fix for the failing link check into v3.3-dev, and this fix needs to be in your PR branch.

[karenetheridge]

That markdown check still fails.

[karenetheridge]

@handrews I think the wording in the latest diff is the best I can do. Specifically -- when deserializing, we're starting with a string: we have no way of knowing what type is actually expected other than inspecting the schema (or perhaps the encoding object, but we've already made it clear elsewhere that the schema is the source of truth here and if the schema doesn't agree, then the encoding object doesn't apply). "But really, if the data is an array and is validated by the schema, it doesn't matter if there is a type keyword at all. " only works for serialization, not deserialization.

This is also consistent with the spec's discussion elsewhere of type coercion when considering style deserialization: the type keyword (or a const or enum unambiguously indicating a type) is all we rely on to determine the preferred type to use for deserialization.

[karenetheridge]

rebased.