Split `items` into `items` and `tupleItems`

[jdesrosiers]

The items keyword has an object form and an array form. The object form is used for constraining the items in an array while the array form is for constraining an array that is used like a tuple. This is something that trips up people new to JSON Schema.

It also causes confusion with the additionalItems keyword. additionalItems is only defined for use with the array form of items, but I often see people throwing in "additionalItems": false when they are using the object form. I'm not sure what they think that means, but it's not uncommon to see.

Proposal

• Redefine the items keyword to only support the current object form behaviour
• Introduce the tupleItems keyword that supports the current array form of items
• Rename additionalItems to additionalTupleItems to make it clear that it works with the tupleItems keyword not the items keyword.
• Rename unevaluatedItems to unevaluatedTupleItems to make it clear that it works with the tupleItems keyword not the items keyword.

Pros

• Less confusing for JSON Schema noobs and veterans alike
• Better errors. If you try to use an array for items when you meant the object form (and vis versa) meta-schema validation will fail making it more clear where your problem is.

Cons

• Redefining an existing keyword is a backwards incompatible change
• OAS is skeptical of additional changes at this stage

[handrews]

This was previously discussed in #209 specifically starting at #209 (comment)

I'm obviously not personally dead-set against it as I brought it up last time, but it did not gather support.

This would also be something where I'd want input from the OpenAPI folks (@webron @darrelmiller @MikeRalphson) because it impacts them as of OAS 3.1. Since OAS 3.0 doesn't allow tuple items to begin with, it would probably be good to put this into 2020-03 if we want it so that the change doesn't show up in OAS 3 at all. On the other hand, the OAS folks have been skeptical of additional changes at this stage.

[handrews]

Paging @darrelmiller again as I misspelled his id at first in the previous comment and I'm not sure GitHub emails people if you tag them in a comment edit

[jdesrosiers]

I didn't realize it had come up before. I'll read through that issue.

Sounds like an ideal change for better OAS integration. That way they don't have to redefine items, they just need drop support for tupleItems.

[darrelmiller]

As someone who has never seen Items used as an array, I would not be particularly concerned about a change like this. Obviously getting this in before OAS 3.1 takes a dependency on the updated JSON Schema would be a good thing. Having said this, I'm not a heavy enough JSON Schema user to have too much weight in this conversation.

[webron]

While generally not a fan of creating more keywords, @handrews is correct that in this case it looks like this is not going to break anything.

I imagine that if both items and tupleItems are defined, they both need to be validated.

Not a huge fan of shoving tupleto all the new keywords as it just makes them longer, but I can't think of a better way of doing it.

[awwright]

I would think if we want to remain analogous to properties/additionalProperties, we should deprecate the object form of "items". This seems more straightforward to me:

• items: accepts an array that applies the _n_th schema to the _n_th item in the instance, if it exists
• additionalItems: accepts an object that applies to each item in the instance except for the first n items defined by "items"

Is this any less sufficient?

[MikeRalphson]

Possibly use tuples alone in place of tupleItems in the keywords, but otherwise I'm neutral on this. (Not dropping / deprecating the object form of items, that seems like it would break OAS 3.0 to 3.1 compatibility).

[darrelmiller]

@awwright I'm not sure that the symmetry of that approach outweighs breaking 90% of the current usages of items.

[handrews]

My preference would be to add tupleItems that behaves exactly like the array form and leave the others unchanged.

In my view, as long as we keep "Items" in tupleItems, the names of the other keywords work fine, and I prefer minimizing the thrash on those keyword names. I'm not dead set on this but that is the direction in which I would lean.

Regarding @awwright 's suggestion, it would be more symmetric but I think I'm with @darrelmiller on the fact that items with a schema is the only form of these keywords that is really widely used, and it's the only form that has long been supported in OAS. The idea here is to maybe break some obscure compatibility in JSON Schema, but not break compatibility for OAS.

@Relequestual @gregsdennis @Julian @johandorland thoughts on this?

[jdesrosiers]

I prefer minimizing the thrash on those keyword names

The keyword thrash is unfortunate, but if we don't change it, people are going to continue to use additionalItems incorrectly.

[karenetheridge]

I like the idea of splitting the keywords, but "tuple" is unintuitive. I don't want to bikeshed the wording, but what about "itemElements" for the array form?

[notEthan]

splitting items is good. it makes more sense to me as a schema author and implementer of schema tooling to have separate keywords for the significantly different behaviors.

adding tupleItems makes sense to me, keeping items as one schema for all array items. I do see @awwright's point that array items + schema additionalItems is a closer parallel to the handling of properties/additionalProperties. but in practice, people mostly use arrays of the same sort of item, rather than tuples, and having this more common use case on the items keyword makes more intuitive sense to me, and also will break everybody's schemas less.

for additionalItems, I'm not certain the benefit of a rename; tupleItems + additionalItems + unevaluatedItems seems sufficient to me. it's a little weird that the plain items has no interaction with any of these other Items suffixed keywords, but I think it's okay.

I'm not as fond of the itemElements name suggestion - 'items' and 'elements' seem like synonyms to me. tuple is a good description of the data structure the array form expresses. as for tuples, I'd say keeping the Items suffix helps keep it in line with additionalItems (I don't think additionalTuples makes sense; not sure what else you might call items beyond tuples).

[gregsdennis]

I'm with @karenetheridge in that "tuple" is unintuitive. If you don't have the history of why the array format was created, it makes no sense. I think there are use cases for this form outside of tuples, and we shouldn't pigeon-hole the keyword to a single use case.

If itemElements is unsuitable, something else should be suggested. Maybe sequencedItems.