Keywords for exclusive minimum/maximum

[handrews]

This is somewhat related to the general idea of issue #55 (clearly document validation principles). One such principle is that for the most part, each schema validation keyword can be evaluated against an instance independent of the presence, absence, or value of any other keyword. This is a highly desirable property when refactoring or otherwise reasoning about complex schemas.

More formally, for nearly all validation keywords k1, k2, k3... the following holds true:

{
    "k1": "something",
    "k2": {},
    "k3": ["etc."]
}

is equivalent to

{
    "allOf": [
        {"k1": "something"},
        {"k2": {}},
        {"k3": ["etc."]}
    ]
}

There are only four exceptions:

• minimum is controlled by exclusiveMinimum's value
• maximum is controlled by exclusiveMaximum's value
• additionalItems is controlled by the value of items
• additionalProperties is controlled by the values of properties and patternProperties

The issues around additionalItems and additionalProperties are outside the scope of this issue, but I mention them as they (especially additionalProperties) are more obvious examples of the problems this sort of dependency causes. In particular, the behavior when working with allOf can be counter-intuitive.

Getting back to numeric validation, here is how minimum and maximum behave:

{
    "type": "number",
    "minimum": 0,
    "exclusiveMinimum": true,
    "maximum": 1,
    "exclusiveMaximum": true
}

is equivalent to

{
    "allOf": [
        {"type": "number"},
        {
            "minimum": 0,
            "exclusiveMinimum": true
        },
        {
            "maximum": 1,
            "exclusiveMaximum": true
        }
    ]
}

but cannot be further separated. This is particularly vexing since exclusiveMinimum and exclusiveMaximum could have been defined to take numbers like this:

{
    "type": "number",
    "exclusiveMinimum": 0,
    "exclusiveMaximum": 1
}

which now behaves nicely, being equivalent to this:

{
    "allOf": [
        {"type": "number"},
        {"exclusiveMinimum": 0},
        {"exclusiveMaximum": 1}
    ]
}

I propose that in Draft 06 we either change the value of exclusiveMinimum/exclusiveMaximum or replace them with differently named keywords that take numeric values. Migrating from Draft 05 to Draft 06 for this would be easily scriptable, as the presence of the old exclusiveMinimum or exclusiveMaximum keywords with boolean value true just means to replace the boolean with the value of minimum or maximum respectively, and remove those properties (and change the name of the "exclusive" keywords if we replace them with new names rather than changing their type).

[jdesrosiers]

YES! YES! YES!

This is something that has bugged me for a while. These keywords deviate from the architecture of JSON Schema and there isn't even a reason for it. additionalProperties at least provides something of value (1) but there are always consequences for architectural erosion. I'd be thrilled if we could find some way we could redefine additionalProperties and additionalItems so they fit the architecture as well. minimum and maximum is definitely a good place to start.

(1) I would argue not enough value to be worth using, but that's a whole other discussion.

[awwright]

I've been thinking about having maxExclusive maxInclusive minExclusive minInclusive, or lt lte gt gte, or something like that.

[epoberezkin]

I always question the changes that simply change the syntax without adding any additional functionality. Don't forget that having these keywords separate has its uses - easier to change the schema in code, the value for exclusive can be passed as data using $data reference; now you suggest using another keyword entirely.

What is the value in being able to split all keywords in separate schemas?

[awwright]

@epoberezkin As I just commented in #76, most of the properties are "linear" (for lack of a better term, they don't affect one another; the same way that waves traveling through a medium is said to be linear, or how we have linear algebra).

If we replace the existing keywords, we're not (net) increasing the number of keywords, but we are making more of them linear.

And validators can still simultaneously support the old form at the same time they support the new form, the two versions are distinguishable.

I'm not at all concerned with complexity of implementation, because our job as implementors is to take on that complexity, taking it away from schema authors and people who want to do validation as easily as possible.

[epoberezkin]

@awwright What I meant is not complexity of implementation - linear keywords are easier to implement. I think they are just less useful and less expressive for the end users. The use cases I was referring to are the ways people use sibling keywords. Imagine you have a schema:

var s = { minimum: 1 };

and now you want to make this minimum exclusive based on some checkbox in the form. With exclusiveMinimum you can:

s.exclusiveMinimum = exclusive;

Without you have to:

if (exclusive && s.minimum) {
    s.exMin = s.minimum;
    delete s.minimum;
} else if (!exclusive && s.exMin) {
    s.minimum = s.exMin;
    delete s.exMin;
}

So what you've achieved by replacing the minimum with exclusiveMinimum qualifier with a pair of different keywords, you've made the life of future validators implementers easier, but you've made life of users more difficult (not even mentioning the effort of updating existing implementations).

Seriously, what's the point?

Also how do you validate the schemas that have both minimum and exMin? I guess whatever is bigger will apply, but still... You kind of achieved keywords independence principle, but you've violated orthogonality principle when two different keywords mean similar things.

It seems to me that allowing keyword "qualifiers" and dependent sibling keywords is a very low price for all the additional value they bring.

[awwright]

Iirc, I thought of having four different keywords when I was re-writing the definition and trying to figure out how to phrase it so it makes sense.

I think it's more natural for people to write "lt": 5 rather than breaking it into two separate properties. I have to go through a lot of mental gymnastics just to think about how the edge case is handled. (I had to look up the definition of "maximum" just now to be sure I'm using it right!) And when "exclusiveMaximum" can potentially be at the other end of a document, it's feasible to see someone might mess a difficult-to-detect edge case up.

We're already using different keywords/operators for >= and > in programming, it doesn't seem any different to do the same thing in JSON Schema.

Your point sounds a tiny bit contrived to me... first, this isn't going to be true if the implementation is functional. You're going to have something like this instead:

var schema = {};
// etc...
if(exclusive) schema.minExclusive = minimum;
else schema.minInclusive = minimum;

it's going to be the same number of lines either way.

Further, you can rewrite your example like

delete schema.minExclusive;
delete schema.minInclusive;
if(exclusive) schema.minExclusive = minimum;
else schema.minInclusive = minimum;

which is still worse than 1, but better than 6.

Even with all six lines of code, there's no chance someone is going to misunderstand what's going on.

But most of all, I can't think of a time I've ever needed to ask "Inclusive or exclusive?"

[epoberezkin]

Schema is fundamentally different from code - it is often manipulated and constructed with code. But my main argument against cosmetic changes is that introduces higher cost than benefits to everybody - both users and implementations. I see absolutely no reason to change existing schemas unless it improves the functionality. It is a change based on opinions and preferences; in my opinion :) it is always better to avoid such changes.

The main priority should be the consistency, it helps users to continue using the standard. If you both introduce new valuable features and make changes that require migration effort, then instead of switching to a new version, users can switch to something else completely.

That's exactly the reason why programming languages only extend and almost never change their semantics - it becomes too costly and risky for users to upgrade versions.

We can't really use common sense and analogies with other languages as the main decision criteria - the existing base of users should be the main priority. There are plenty of improvements to make to the standard without changing what works. Why are you so keen to introduce confusion and cause unnecessary efforts to migrate to the next version? What is the value? The fact that somebody is confused with the way it is, likes it more etc. are not strong enough arguments for a change I think.

Also, bear in mind, that by changing existing semantics you invalidate all the existing manuals, documentations, etc., so you complicate not only migration but also the adoption of the standard. There were quite a few promising technologies over the past 40 years that died exactly because people who were pushing their development at some point decided that they "knew better" and instead of evolving and extending started to redefine things. The result was always the same - people switch to a different technology, that has no past baggage. One of the latest casualty of "knowing better" is probably Angular web framework. To me, the choice is simple, you either redefine something from scratch, in which case you may or may not get a sufficient user base for a new thing, or you fully respect the baggage you have and live with it, apart from cases when the change brings some serious improvement. I completely fail to see what this serious improvement is in this and some other similar proposed changes.

[awwright]

Understood.

Even if the present keywords were to be removed entirely, there's nothing that should suddenly cause existing schemas to stop working. Implementations are fully allowed to support multiple versions simultaneously, as they're are allowed to recognize unknown keywords. And this has been done before (especially the change from "required" from a boolean to an array, many implementations support both, regardless of which "$schema" is selected).

[epoberezkin]

The change to required was justified by the fact that it went against a very important JSON schema design principle - keywords are only applied if the data exists at the current data level. Old required: true was an exclusion from this rule - it had to be invoked for a missing piece of data. New required: [...] is applied to the object, it won't require anything if the object is missing.

I keep thinking that even postulating JSON-schema principles and values and having some discussion about them before incorporating them into the standard would help making the decisions about changes.

• "independence" of keywords from anything but sibling keywords
• "orthogonality" - avoiding overlap in keywords purpose (patternGroups kind of violates it...)
• "applicability" - keywords only apply to the existing data of a certain type (or all types in case of logical/compound keywords), can't apply to multiple types (in this way I would restrict "format" to strings only).
• "statelessness" - independent of previous validation results ("switch" violates it, I'd rather redefine it to depend on some data value, like JS switch, than on the process).
• "backward compatibility" - avoiding semantic changes without sufficiently strong reasons.

If community could agree on the importance of following these or some similar design principles it would simplify decisions about current and many future proposed changes.

@awwright What do you think? Want to make it a separate issue for discussion?

[handrews]

@epoberezkin

If community could agree on the importance of following these or some similar design principles it would simplify decisions about current and many future proposed changes.

See issue #55

Having skimmed through this, I'm still in favor of the change here for all of the same reasons. Maintaining compatibility is not compelling when it violates a higher principle and it's trivial to convert a schema from old to new format. As @awwright notes you can keep supporting Draft 04 and its meta-schema will continue to be a valid option.