Should keywords be renamed? (started as: "rename required to present")

[notEthan]

I will recognize at the outset this is change would be a significant backwards incompatibility. I want to at least bring it for discussion.

I think the keyword "required" has a poor name for its purpose. All of the validation keywords express requirements of one sort or another. required should be named for what it is actually requiring - the presence of the indicated properties. I think "present" is the best keyword to express this. some variant of "properties present" might be an option too.

The current name is okay for positively validating - saying a property is required does imply that its presence is the requirement. That case is natural enough to read and make intuitive sense. But we have all seen the confusion that results when using it in conditional or negated schemas.

if:
  required:
    - foo
  then:
    ...

"If property foo is required, then ..." is how that reads, but what it means is not very intuitive. "If property foo is present" is much more applicable, and reads more naturally from if: {present: ["foo"]}.

Likewise, not: {required: ["foo"]} does not mean "property foo is not required". Multiple properties are worse: not: {required: ["foo", "bar"]} reads like "neither foo nor bar is required". Much improved, not: {present: ["foo", "bar"]} does assert "properties foo and bar are not present" or "must not be present".

I think required made more sense back when it was a boolean keyword of a property schema, but would have been better renamed when it was put in its right place as a sibling of properties. I think the name present is a significant improvement - I'm interested to hear people's opinions.

Of course, there are countless schemas which use required. This would be a widely impactful change, though not the biggest (e.g. smaller than id / $id, I think). There are tools to convert schemas between spec versions, and this would be a trivial conversion to implement. Maybe required could live on for a while as a deprecated alias with the same function as present (though I don't think the spec has ever done that before and that may be a whole other issue to address).

I think in the long run, though this change would have some pain in its transition, it is worth the benefit of more clearly expressing the intent and meaning of the keyword in all the contexts where it is used.

[notEthan]

this would impact dependentRequired as well, and some open proposals regarding required/present property names, including: json-schema-org/json-schema-spec#1144, json-schema-org/json-schema-spec#1112, json-schema-org/json-schema-spec#846

[awwright]

The naming is one of a series of quirks that I don't think can be perfect... we have a few other properties where the name is a bit ambiguous, for example "minimum"... well, minimum what? (scalar value, item count, string length, sort order, ...?)

Sometimes this could have been better thought through: When we were changing how "required" worked, that may have been a good opportunity to name it "requiredProperties" instead. But even in this case it might not matter (it only makes sense to think of properties as being required or not).

However I don't think "present" would have been a better name. The naming scheme for validation keywords follows assertive language. A schema "requires" a property, it doesn't "present" a property.

Likewise, there's other properties that could be confusing: "if minLength: 5 then ..." well hold up, this will evaluate true for all numbers and other non-string types! A better way to explain its behavior might be like this: "If the condition that the property 'foo' is required is valid, then ..." or "If the condition minLength: 5 validates, then ..."

[handrews]

I'd be extremely hesitant to start renaming keywords, since (as @awwright noted) there are several that could probably be better. Most of the keywords were chosen by people who left the project nearly a decade ago or longer, and most of the newer keywords were chosen to align with those.

We have done a few renames:

• $ prefixes to clarify the core vocabn (first $id, then the rest) — we took advantage of this to rename definitions to $defs instead of $definitions, but we would not have done that if we weren't already renaming it
• items and additionalItems got renamed to prefixItems and items, but that was primarily done to eliminate the dual syntax of the old items, and eliminate the confusing duplicate functionality between items and additionalItems. So it wasn't s straight-up rename
• The Hyper-Schema media keyword got broken up into content* when it was moved over to the validation spec, but there were a lot of reasons why that was relatively low-impact: Hyper-Schema was never as broadly implemented, media was not, as far as anyone could tell, widely used in the first place, and it had previously been content* in earlier drafts. That's very different from renaming one of the most commonly used keywords.

Perhaps at some point if we need to do some sort of large-scale breaking change, a holistic rename could be consider. But more likely, it's better to push for $vocabulary support and if you really can't stand the standard names, you can make a vocabulary that just aliases the keywords you don't like.

[notEthan]

A schema "requires" a property, it doesn't "present" a property.

I would describe the real meaning behind this to be that a schema requires the presence of a property. It looks like you're using the verb form, 'to present a property' rather than an adjective, which isn't how I mean it (though that potential ambiguity may be a downside of the name).

The naming scheme for validation keywords follows assertive language

I agree with this; I see the assertion being made to be that the property is present. Asserting a condition and requiring that condition seem synonymous to me.

For minimum it requires the number to be at least the given value; for type it requires the value be of the given type. They all assert requirements. The required keyword doesn't say what requirement it is asserting, and it's only intuitive what that assertion is when positively validating. Asserting that the property is present, using the present keyword to say this, seems clearer to me in all contexts, but especially when schemas are conditional or negated.

[karenetheridge]

I object to the choice of "present" because it's such an overloaded word in english:

• noun the period of time now occurring
• adjective in a particular place
• adjective fully focused on or involved in what one is doing or experiencing
• verb give, or show, or offer...
• verb to introduce someone
• etc etc etc...

If we are in the mood to change the name of this keyword (and personally I am not), I think "mustExist" or "exists" would be clearer than "present".

[notEthan]

extremely hesitant to start renaming keywords [@handrews ]

I do agree. I also agree with all of the naming changes that have been made so far, the ones you've listed, the dependencies split - I don't think there has been a keyword change that has not been an improvement. I think this is an improvement too, and maybe enough of an improvement to implement, if there is positive feedback on this issue.

It may be the case that other keywords could be named better too. And it is always the case that I can take any idea I like and do my own vocabulary that nobody but me will use. That doesn't help improve the clarity of the core validation's required - I think if this is viewed as an improvement (by more people than myself - looking tenuous so far) it shouldn't be discounted because other keywords could be improved, too.

[notEthan]

@karenetheridge I do think exists or some flavor of "these properties exist" may be an improvement at least as good as present.

[handrews]

@notEthan

I do agree. I also agree with all of the naming changes that have been made so far, the ones you've listed, the dependencies split - I don't think there has been a keyword change that has not been an improvement. I think this is an improvement too, and maybe enough of an improvement to implement, if there is positive feedback on this issue.

The critically important difference here is that none of them were renamed just to rename them. The closest would be adding $ to core, but that was to create a general design principle, which happened to involve some renaming. The renaming was the result of a deeper change, not an end in itself.

That is extremely important. We have never renamed a keyword just because we didn't like the name.

No one will ever agree on what names are best. We all have keyword names that we think are unclear or just not ideal.
But changes have their own detractors. @karenetheridge doesn't like present, and I completely agree with her reasoning.

I would strongly prefer not to debate different names because the question that needs to be answered first is "should we be renaming at all?", and I think the answer to that is an emphatic "no."

[handrews]

I broadened the discussion topic, because this is not the sort of thing that should be discussed piecemeal.

When it comes to long-established keywords, it is important to set and meet clear expectations with users. We have not articulated a policy here (and I am not asserting one — such a policy would be the decision of the core team), but there is a de-facto policy that can be inferred.

• We have never renamed keywords just to get a "better" name, only as the result of a deeper issue or design principle
• We have settled on $ as a core vocabulary prefix, and renamed keywords as needed for that
• We have split keywords like dependencies and items that caused problems by having two different syntaxes that did two different things (and the items split made additionalProperties obsolete so it was removed in the process)
• We have replaced recently added keywords with keywords that addressed the same problem in a different way ($recursive* replaced by $dynamic*), which was deemed less problematic than radically changing the syntax and behavior while keeping the same name

I do not think that this discussion should hinge on any argument about required vs some other name. Either we think it is OK to rename keywords to make them "better", by some metric, or we do not. Specific name changes are irrelevant to the general question, and a distraction from it. I can come up with several that I would find more compelling than changing required, but that's not relevant either.

The real question is, any such change would violate the above de-facto policy and expectations. Why would we want to do that? Not in terms of any one keyword, but in general?

What are the costs of renaming?

• More difficult migration
• Increased impression of instability in the project

I find both of these very concerning.

What are the real-world problems that we can observe from not having renamed these?

I am not aware of anything but personal preference here — I would like to see an actual example of measurable impact, or even anecdotal evidence beyond considering certain names sub-optimal or inconsistent. Those are nice theoretical issues, but what are the real effects? and why do they outweigh the above costs?

[notEthan]

real-world problems that we can observe from not having renamed these?

For required, the unintuitive meaning when it's negated or conditional seems to cause confusion quite often. people are probably using it wrong in practice out there, with some cost. And the community is persistently having to clarify its meaning in these contexts. But the community persistently clarifies many keywords, that's part of explaining and helping people to learn the usage.

But I am no longer advocating any change to required. It would be a significant improvement, but that is my opinion and not generally shared (3 against and none but me for is a small sample but sufficient consensus for me). I am glad to have got the idea that's been at the back of my head for quite some time expressed and advocated for - having it roundly shot down is not unexpected and I appreciate the responses.

Either we think it is OK to rename keywords to make them "better", by some metric, or we do not.

I'll comment, but reiterate that I'm not advocating any change. Clearly yes, it's okay to rename keywords when the metric is one that you have listed, conformance to design principle and others. Is clarity of naming, minimizing confusion for readers, a design principle?

Json Schema has changed a lot through its life as a "draft" and, at least to my interpretation, the draft status implies improving it, applying any changes that consensus says are for the better, until it's stable. On that theory, yes, keywords should be renamed if there are better names. But that theory falls down hard on at least two counts. One, the "draft" label has become meaningless, the specification is used in production in countless systems and backwards incompatibilities do have major cost. Two, consensus on what keyword name is better than another is a mythical beast (probably harder than consensus on improving functionality), evidenced by this discussion and many before.

In practice, then, should any keyword (especially long-established) should be renamed? Rarely, to the point that there may be no instances where the answer is yes. I opened this to see if required is a case that applies; it is not. Maybe the answer is not 'rarely' but 'never'.

[jdesrosiers]

I agree with the general consensus here that renaming required is not the right thing to do, but I wonder if it's worth considering allowing keywords to have aliases. There's no precedent for it in JSON Schema, but it should be easy to implement and could help with the readability of schemas in certain situations as @notEthan as pointed out.

[gregsdennis]

There's nothing stopping anyone from creating an alias vocab...

[jdesrosiers]

Good point. Maybe that's all that's really needed.

[Relequestual]

Good idea! This would be a great example of how vocabularies can be used! =]