`prefixItems` doesn't match keyword naming convention

[gregsdennis]

In response to #810 and #925, it seems we need agree on how keywords are named. Since prefixItems is new for the upcoming draft, we should consider fixing this now rather than being stuck with it or introducing another breaking change.

Based on previous conversations, there are two schools of thought, which are defined by two aspects of keywords:

• Function
• Relationship to other keywords

In either case, the other is intended to be declared in the specification.

Although being able to convey both with a name, I prioritize naming by function because it increases readability while authoring schemas.

Another thing to consider is keyword symmetry along:

• array vs object (having similar functionality for both)
• boolean logic (having functionality for AND and OR)

In general, keywords tend toward function or both, but prefixItems deviates from this pattern. Below is an analysis of some existing keywords, followed by a similar analysis of prefixItems:

*Of, not, type, maxLength

These keywords land in the function camp. It's very clear what they do and how they apply.

There's no mention of how they interact with other keywords, if they do at all.

if/then/else

These names actually satisfy both aspects.

Most people are familiar with conditional constructs (dispite the volume of SO questions regarding these keywords), both in regard to what they do as well as how they relate to each other.

items

I think this one is a little vague, but it leans pretty strongly towards "function".

The word "items" suggests that it applies to arrays, but it doesn't convey that all items must match the given subschema. Perhaps a more functionally-oriented name could be allItems.

This opens the opportunity for contains to be renamed to anyItem, which would satisfy boolean symmetry.

additional* & unevaluated*

These also happily have names that both convey the function and relationship. For example, unevaluatedItems is processed like items but after all other array-related keywords have been processed. (Note, however, that unevaluated* doesn't convey that it can peer into sibling applicator keywords. I think that's just matter of terseness.)

prefixItems

This name is relationship-based. It is named such because it should be processed before items is processed. But there's no mention that the subschemas are intended to be applied in order. This is the only keyword that fails to do this.

This keyword is analogous to properties (apply multiple subschemas to multiple sub-instances of the instance passed to it) with one addendum: arrays are considered to be ordered. Since objects aren't ordered, that doesn't apply. However, it does beg the question: If we have an ordered items keyword, should we also have an unordered items keyword (think boolean symmetry again)?

Supposing we have an unordered items keyword, what do we call it? I expect that it should also be applied before items, but prefixItems is already used.

But if we call it orderedItems, that gives us the opportunity to create an unorderedItems without any naming issues.

There is also some additional symmetry created by this:

• items (allItems) and contains (anyitem) (after extensive discussion at "unevaluatedItems" should consider "contains" #810 and some sort of resolution on Split "prefixItems" from "items", drop "additionalItems", make "unevaluatedItems" respect "contains" #925) work together to provide AND/OR functionality respectively for single subschemas.
• orderedItems and unorderedItems would provide that same functionality for multiple subschemas.

[karenetheridge]

This is an excellent summary. Thank you for taking the time to go into the details here!

[karenetheridge]

FWIW - I don't really see arrays as being ordered and objects being unordered -- you could just as easily view objects as being ordered too (where the property names are alphabetically sorted); or conversely, arrays as being unordered objects where the property names are their integer indexes (where we normally omit the indexes for brevity).

With this terrible metaphor established, the keyword that is missing (symmetry-wise) is a keyword that applies subschemas to corresponding non-sequential indexes, for example: "for index 0, apply schema {..}; for index 1, don't do anything; for index 2, apply schema {..}; ...". But we can achieve that by saying [ { schema for index 0 }, true, { schema for index 2 }, ... ]. (except that index 1 now counds as "evaluated", which would affect the behaviour of unevaluatedItems, doh! and that might be important.)

I'm starting to come around to liking the previous keyword choice of "tupleItems". I'm so sorry @handrews. Luckily I'm not in the core team so I have no vote :D :D :D heads to bed

[gregsdennis]

I don't really see arrays as being ordered and objects being unordered -- you could just as easily view objects as being ordered too

JSON defines arrays as ordered and objects as unordered. From json.org:

JSON is built on two structures:

• A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
• An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.

To that end, I have a setting in my library that configures array equality checking as sequence- or content-equality because both make sense for different applications.

That said, it's irrelevant because the unorderedItems is merely a multi-item version of contains, where all of the items must be present within the array, but not necessarily at any particular indices.

The trouble with tupleItems and the specific example you mentioned, is that it's still ordered, even though it's skipping indices. You can do that with orderedItems: [<schema>, true, <schema>] as you mentioned (except the annotations issue you also mentioned, maybe use null instead of true to indicate "don't eval this one."). The check you want is "I give you a collection of things, and you make sure that all the things you need are somewhere in there."

Even that is irrelevant because this issue is about calling prefixItems something else. Something that indicates its function, like all of the other keywords do. tupleItems kinda does that, but it pigeonholes the keyword into being solely intended to validate tuples.

[karenetheridge]

JSON defines arrays as ordered and objects as unordered

Yes, of course, sorry, I chose my words poorly in my exhaustion. What I was trying to say, badly, was that arrays and objects can both be seen as collections of key-value pairs, where the keys are just of a different nature. But because we leave off the keys in arrays and imply them by ordering the values, we limit ourselves more in what we can do, because now we can't express anything to do with the arrays in an unordered way. But that's okay because if we have a collection of data that is more random, we'd choose an object to store it, right? :) So we don't have to have symmetry between keywords that apply to both data types.

[Relequestual]

We've already bikesheeded the change and naming of the new split keyword: #864

I spent hours deliberating over #864 , and ended up greenlighting the issue for PR because I saw consensus.

Consensus does not mean everyone has to agree, but the editors have to feel that everyone who wants to share an opinion has done so, and their point of view has been understood.

This may mean we do something that you don't personally agree with. We do plenty of things that I personally (and others personally), don't agree with, but our job as editors is not to impose what WE believe is the best solution, but to look for the general consensus. This sometimes means it's not the "best" solution, but the solution that's likely to have the least impact or that the most people agree is kinda OK.

Please feel free to DM me if you'd like to chat about this further.

This is by no means a personal snub; you've done plenty of great work on JSON Schema! Long may it continue.

[gregsdennis]

This isn't an issue of consensus or of what I think is "right." It's an issue of consistency. This keyword is the outlier from all of the other keywords. This keyword is named incorrectly, hence the issue.

I was part of #864, and the conversation (and the PR that followed) was more about whether we should split items. The name of the new keyword was discussed, but no definitive conclusion was decided; it just stopped being discussed. @handrews made PR #925 to split the keyword, and this keyword problem needs to be decided as a group with everyone considering the arguments I opened with rather than you just making an executive decision.

I had decided to let the PR go forward rather than undoing @handrews's work on it. I agree that we should split it. That's what the PR did. Now we should consider the naming of the new keyword.

cc: @awwright @jdesrosiers @notEthan @darrelmiller @MikeRalphson @webron @ssilverman

[Relequestual]

I'm sorry you feel I've missread the consensus (please others speak up if you agree).

Looking specifically at #864 (comment) - My understanding from that, and the rest of the thread, that the consensus was prefixItems if we went with only 2 keywords.

If I'm reading your comment, you're just suggesting we call it X rather than Y, not changing the proposed functionality. Is that right?

prefixItems - This name is relationship-based. It is named such because it should be processed before items is processed. But there's no mention that the subschemas are intended to be applied in order. This is the only keyword that fails to do this.

Would you propose we call it sequentiallyPrefixedItems? Given how infrequently we expect it to be used, I don't have a problem with length if you want to try and convey as much as possible by the keyword itself. Or maybe prefixedTupleItems?

The name of the new keyword was discussed, but no definitive conclusion was decided; it just stopped being discussed.

Discussions were had outside of the issue as well as in the issue. Henry asked me to make a call, noting that @webron favoured prefixItems. At this point I asked for further discussion because I didn't see a consensus yet.

@handrews made PR #925 to split the keyword, and this keyword problem needs to be decided as a group with everyone considering the arguments I opened with rather than you just making an executive decision.

I try to avoid making executive decisions, but sometimes it's gotta be done to move forward. I've OFTEN been the tie breaker in decisions where most parties were happy with multiple possible solutions (I'm sure @handrews and @awwright can vouch for that). As I said, I greatly considered the issue, taking several hours over a number of days, including length discussions with most involved.

I had decided to let the PR go forward rather than undoing @handrews's work on it. I agree that we should split it. That's what the PR did. Now we should consider the naming of the new keyword.

If it was simply a matter of the name you dissagereed with, you really should have not given an approving review on the PR. In doing so, you signaled you agreed with or could live with all the changes therein. Coming back AFTER the fact to say your not, is confusing and to be honest a little rude.

---

Further, in the PR itself...

Is the bikeshedding on the "prefixItems" name totally done (vs. alternatives like tupleItems, sequentialItems etc). - @karenetheridge

@karenetheridge yes, the naming is 100000000% final. Please see the issue for that whole saga, but it will not be reopened. Or rather, if you want to re-open it, ask @Relequestual and y'all go off and figure it out and tell me what happens 😛 - @handrews

There was a CLEAR invitation to go discuss it with me right then before the PR is resolved.

There was a follow up in one of your review comments...

@gregsdennis we spent an epic number of comments debating the naming, with participation from the OpenAPI steering committee as well. In the end, @Relequestual made a call and that's what I implemented. - @handrews

Again, this was another invitation to come and talk to me. I try to be open and read to hear all opinions as I possibly can.

This isn't an issue of consensus or of what I think is "right." It's an issue of consistency. This keyword is the outlier from all of the other keywords. This keyword is named incorrectly, hence the issue.

I dissagree with your assessment. You said in the opening comment that one of the approaches we use is Relationship to other keywords, followed by This name is relationship-based.

---

For clarity:

• I was asked to make a decision by one of the core team. I spent hours reading every word, and believed I saw a consensus. My executive decision was in calling that consensus, as is within my role of being in the core team and an editor.
• @handrews made a PR, to which you provided feedback. Part of the feedback included comments about the keyword naming. You approved the PR with the name unchanged.
• I made several open invitations (and some were made on my behalf) to come discuss any issues with the keyword naming. No one has done that.

I still want to hear you out.
Say we went with orderedItems or something that conveyed order only. It would be confusing if you tried to use it with items also.
Say we went with orderedPrefixItems. It comes before items, but items can't be an array? Now we're back to having the same confusion.

this keyword problem needs to be decided as a group with everyone considering the arguments I opened with rather than you just making an executive decision.

My only executive decision was to call the consensus I saw. I don't feel you can reach consensus without giving everyone the chance to consider each argument put forward, which I believe people did (or I would not have called the consnsus).

[handrews]

@Relequestual regarding

If it was simply a matter of the name you dissagereed with, you really should have not given an approving review on the PR. In doing so, you signaled you agreed with or could live with all the changes therein. Coming back AFTER the fact to say your not, is confusing and to be honest a little rude.

I recall having a slack chat with @gregsdennis and asking him to split these topics, so what he did in approving the PR and filing the issue was completely reasonable based on that discussion. Which was not on a public channel so you would not have seen it- sorry about the confusion.

[gregsdennis]

You said in the opening comment that one of the approaches we use is "Relationship to other keywords", followed by "This name is relationship-based".

I never said that this is an approach we use. I said it's a school of thought, specifically the one taken to name this keyword. No other keyword follows this school of thought, so why does this one? As I was composing it, I was going to start classifying all of the keywords into relationship- vs. function-based keywords so that we could decide one way or the other for consistency, and I found that all of them were function based... except this one.

---

You approved the PR with the name unchanged.

I commented that I would open a new issue about the naming, hence this issue. In fact I wrote that comment and immediately started composing this issue.

---

You're also ignoring all of the benefits I mentioned that naming it by function gives us (opens doors for other symmetrically-functioned keywords).

[notEthan]

I appreciate the ping. I think most of what is relevant to say was said on #864 though. I'm content with the outcome of prefixItems, given the consensus on a 2-keyword solution, even though it's not what I advocated over there.

the relationship to items is important. unless the keyword for fixed-sequence-of-items-before-an-items-keyword establishes its relationship to items, it's more likely to confuse anybody reading a schema using both. orderedItems + items does not establish this relationship.

No other keyword follows this [relationship-based] school of thought, so why does [prefixItems]?

what about additionalProperties, additionalItems (formerly), unevaluatedItems, unevaluatedProperties? when keywords interact, it's good to have some indication of their relationship in the keyword name.

[prefixItems] is named such because it should be processed before items is processed. But there's no mention that the subschemas are intended to be applied in order.

I think the name 'prefix', combined with the value being an array, is sufficient for a reader to infer it is a fixed-length sequence. if it's unclear how that applies, that's the point where the reader needs to consult documentation. no keyword of one or two words can intuitively convey the full meaning of this keyword, I think.

prefixItems on its own is harder to make intuitive sense of, being a prefix of nothing. that is a shortcoming of that choice. I don't know that this shortcoming is any greater than what you get with any other keyword name, though (itemsBeginWith? /s).

should we also have an unordered items keyword

unless there's significant demand for this by schema authors, I think this is adequately fulfilled by the structure {allOf: [{contains: ..., contains: ...}]}. that might not quite fit your proposal though - I don't know quite how unorderedItems would interact with items. whether significant demand for this exists, I don't know.

[notEthan]

more broadly, you're proposing a number of backwards-incompatible changes here (items → allItems, contains → anyItem). while I agree, in principle, that certain keywords could have better and more consistent naming, these changes seem unlikely to gain traction due to the schema breakage they will cause.

I think it'd be interesting to work on a new alternative to the core vocabulary for subschema application (and validation as well, probably), unencumbered by previous drafts and picking the best damn names for everything. I know "go make your own vocabulary" is becoming a somewhat unsatisfying form-letter response for anybody with a suggestion about keywords. but, eh, it's what vocabularies are there for.

maybe a new alternative vocabulary becomes popular enough to supplant the existing core applicator vocab by the time this draft spec loses its draft-ness. probably confuse the hell out of everybody reading and writing schemas along the way, but progress can do that for an interim.

[gregsdennis]

@notEthan

what about additionalProperties, additionalItems (formerly), unevaluatedItems, unevaluatedProperties?

I address this in the original post: these follow both ideals. But no keyword only describes its relationship to others.

I think the name 'prefix', combined with the value being an array, is sufficient for a reader to infer it is a fixed-length sequence.

No, "prefix" says nothing about the sequence of the items being important.

the relationship to items is important

I agree, but looking at this same decision applied to the other keywords, it seems that this relationship is less important than the keyword's function.