unevaluatedProperties: consider renaming to 'unspecified...' or 'unmatched...'

[tedepstein]

I read through parts of #515 flexible re-use: deferred keywords vs schema transforms, and I'm very happy with unevaluatedProperties as a solution. And while I have only read through some of the arguments advocating for limited forms of schema transformation, I can say that I'm much more comfortable with deferred keywords.

My only suggestion is to consider alternatives to the name unevaluatedProperties.

(Apologies if naming has already been fully discussed someplace else. In that case, please point me in the right direction...)

Going back to the definition:

We can define unevaluatedProperties to be a deferred assertion analogous to additionalProperties. Its value is a schema that is applied to all properties that are not addressed by the union over all relevant schemas of properties and patternProperties.

I find the term "unevaluated" a bit confusing.

First, as a user of JSON Schema (as opposed to an implementor of a JSON Schema processor), the whole idea of "evaluation" isn't a verb that comes prominently to mind as having any particular meaning. I have to think about it to understand what "unevaluated" might refer to.

Second, when I do get to thinking about it, I find two possible meanings:

1. Property names will be evaluated for applicability against each of the properties and patternProperties keywords in the relevant scope. This is not the evaluation you're referring to.
2. The property value will be evaluated for validity against each applicable schema, if any. I think this is the intended meaning of 'evaluated' in the proposed keyword.

The first meaning is a bit more intuitive to me, though "matching" is the first word that comes to mind.

The second meaning is what I think of as "validation," and maybe that strong word association is what made "evaluation" so foreign.

But the bigger point is really the first one. It's the difference between a static perspective vs. a processing perspective. As a user, I'm working with the schema, so the static perspective is more natural to me. Either of the following seems like seems like natural terminology:

• Does the property match any of the in-scope properties or patternProperties keywords?
• Is the expected value of this property specified by any of the in-scope properties or patternProperties keywords?

To understand 'unevaluated', I have to switch from a static, schema-focused perspective to a dynamic, processing model-focused perspective, and I have to disambiguate as noted above.

So that's my long-winded case for unmatchedProperties or unspecifiedProperties. I don't have a strong preference for either one of these over the other. I'd be happier with either of them.

[handrews]

First, as a user of JSON Schema (as opposed to an implementor of a JSON Schema processor), the whole idea of "evaluation" isn't a verb that comes prominently to mind as having any particular meaning. I have to think about it to understand what "unevaluated" might refer to.

This is somewhat intentional. Draft-08 will specifically define a schema evaluation process.

The first meaning is a bit more intuitive to me, though "matching" is the first word that comes to mind.

"Matching" usually means regular expressions, which is not relevant here.

As a user, I'm working with the schema, so the static perspective is more natural to me.

You simply cannot meet the requirements for all of the use cases with a static feature. I'm not going to re-cap 515 here. You can read the summary at #556 which is the current issue tracking unevaluatedProperties. Since 515 went pretty far off the rails.

The name got kicked around a lot. I still prefer unevaluated to either of the above. Please read #556 and see how you feel about it, and please also consider keeping an eye out for PRs and see if the actual spec motivates the terminology better.

We definitely will not use unmatched because of the regular expression thing.

I'd prefer not to use unspecified because it feels static and the outcome of 515 (after 230+ comments) was that the solution must be dynamic.

This is my feeling today, although I'm certainly not the only person whose opinion matters. However, I'm going to close this because the proposal is tracked in #556 and we should keep the discussion there rather than spread it out over numerous issues.

Do be aware that everyone involved is very fatigued after the 515 experience and no one is going to be really enthusiastic about debating names right now. I don't plan to come back to 556 for PRs for several weeks so it's not super-urgent.

[tedepstein]

Thanks for providing the additional context here, @handrews. I'll read through #556, and will provide feedback there, if I have any. But this is not a something I feel that strongly about. What unevaluatedProperties does for JSON Schema is much more important than what it's named.