Rename post-split "dependencies" to "schemaDependencies"

[handrews]

Previously, we split the old dependencies keyword in two:

• requiredDependencies is an assertion in the validation vocabulary, and behaves the same as the old string array form of dependencies
• dependencies is an applicator in the core spec's applicator vocabulary, and only supports the old schema form

This makes dependencies incompatible from draft-07 to draft-08: anything using the string form is now incorrect and will not work. This is also confusing for schema authors migrating to draft-08: there is a non-obvious change and they need to change how they think about this keyword.

Instead, let's do a true split, and make the schema case schemaDependencies. This does two things:

1. It makes the behavior clear from the name, in a way that is consistent with requiredDependencies
2. It allows schema authors to continue using dependencies with its pre-draft-08 semantics as an extension keyword

The second point is particularly compelling. It also gives implementors the ability to continue to support the existing dependencies behavior with draft-08 (presumably as an opt-in, or even better with a custom meta-schema using the new vocabulary support allowing schema authors to declare dependencies as an extension- we could even offer a "draft-08-transitional" meta-schema that provides this).

I've been worried about breaking the dependencies keyword in this draft, and I think this is a much better solution for both clarity and migration support.

Thoughts? Paging some folks who weighed in on other dependencies issues: @erayd @markchart @pipobscure

[awwright]

We had properties and additionalProperties before, would the same critique apply to that, even if we didn't have requiredProperties?

[handrews]

@awwright

We had properties and additionalProperties before, would the same critique apply to that, even if we didn't have requiredProperties?

I don't follow. This is about a single keyword being split into two keywords, and the best way to name them while avoiding breaking existing implementations. What does that have to do with properties or additionalProperties? Yes, it's true that properties and required are single words that could be two-word keywords matching the form of other *Properties.

But the point here is not that dependencies is somehow bad because it's one word. The problem is that changing the behavior of dependencies breaks things for people moving from an earlier draft to draft-08. Replacing it with two new keywords allows for compatibility. The symmetry of the resulting keywords is nice but only in the sense of "hey we can allow for compatibility and still make sense", not "we need to make everything a two-word keywords".

[awwright]

You figured it out, I'm questioning if we need keywords to all be two words just for the sake of being the same number of words. I don't see why.

Now if it's a change in behavior, then I see that. Do you have a simple example that demonstrates the change, to make sure I'm understanding it right?

[handrews]

@awwright yeah, that's a reasonable question. The fact that it goes from one word to two is coincidental.

draft-07:

{
    "dependencies": {
        "foo": ["bar", "baz"],
        "biz": {
            "maxProperties": 10
        }
    }
}

We decided in #528 (comment) to split dependencies, keeping the original keyword as the schema form only, with the string array form becoming `requiredDependencies. This was done in PR #573, resulting in:

{
    "requiredDependencies": {
        "foo": ["bar", "baz"]
    },
    "dependencies": {
        "biz": {
            "maxProperties": 10
        }
    }
}

The problem here is that now dependencies has shrunk in functionality. It looks like the same keyword, but it's really not. That' sub-par UX for people migrating from older drafts. And as it turns out, a number of implementations do not switch on draft number, really, but have logic that handles draft changes on a per-keyword basis. So keeping dependencies as the same keyword with different behavior complicates that. And even when you do switch globally on draft version, it's annoying. And there's no sensible way to implement some sort of transitional/compatibility mode.

These are things that are not compelling on their own, but they add up and slow adoption.

So what I would like for draft-08 to look like is:

{
    "requiredDependencies": {
        "foo": ["bar", "baz"]
    },
    "schemaDependencies": {
        "biz": {
            "maxProperties": 10
        }
    }
}

There is no chance of mistaking either of those keywords for the old dual-function dependencies. And it would allow continuing to support the old dependencies syntax simultaneously if people want to do that.

So, to summarize:

• We've already done the split, which is the change in behavior
• We haven't locked in the new names (Move "dependencies" to applicability group #528 (comment) even notes that we'll quite likely rename them further as we think about it more)
• Splitting the old keyword into two new keywords, instead of splitting off a new keyword and changing the old keyword, is a much better migration story.

[handrews]

Since I can't get anyone to comment further on this despite reaching out in several forums, I'm moving to a PR.

[erayd]

I missed emails on this sorry - will comment on it tonight.

[handrews]

Thanks, @erayd. See also PR #614, feel free to comment wherever seems most useful.

Having a PR doesn't make this inevitable.

[erayd]

@handrews
My preference would be to keep things as dependencies and requiredDependencies. I don't really want requiredDependencies to exist at all (although I can understand why people might desire it) - the entire purpose of having requiredDependencies at all is just a giant UX kludge to support the following:

{
    "dependencies": {
        "foo": {"required": ["bar", "baz"]}
    }
}

---

To me, this change really looks like a behavioral change in dependencies that simplifies its definition (from schema | array to schema only), but keeps the same behavior. That should not IMO result in a keyword change.

The problem here is that now dependencies has shrunk in functionality. It looks like the same keyword, but it's really not.

How is it not the same? It looks the same to me, the only change is removing a syntactic shortcut.

It also gives implementors the ability to continue to support the existing dependencies behavior with draft-08 (presumably as an opt-in, or even better with a custom meta-schema using the new vocabulary support allowing schema authors to declare dependencies as an extension- we could even offer a "draft-08-transitional" meta-schema that provides this).

Why does it need renaming for this though? There's nothing stopping implementations from continuing support for pre-draft-08 syntax; it's just a simple type switch (i.e. if the value is an array, either warn / error or provide deprecated support).

I agree that UX should be a priority, however I think that the eventual UX of the final standard is more important than the UX of migrating from one draft to another. dependencies is a much more obvious keyword than schemaDependencies, and I'm very reluctant to discard it just to handle an edge-case when migrating between two pre-release drafts of the standard.

As far as moving between drafts goes, making $schema mandatory would go a long way towards improving this, as it would require schema authors to declare the version they are using, rather than possibly requiring the implementation to guess or make assumptions if $schema is absent.

As it turns out, a number of implementations do not switch on draft number, really, but have logic that handles draft changes on a per-keyword basis. So keeping dependencies as the same keyword with different behavior complicates that. And even when you do switch globally on draft version, it's annoying. And there's no sensible way to implement some sort of transitional/compatibility mode.

Could you expand on this a bit? I really don't see how this is complicated from an implementation perspective. The backwards-compatibility logic is easy - if definitions is an array, and using deprecated features is allowed, then rewrite it to {"required": $array}. Done. And that could be either on-demand or in preprocessing; there's nothing tying that logic into the actual keyword implementation.

[handrews]

I don't really want requiredDependencies to exist at all

We already lost that argument a long time ago, no point in revisiting.

There's nothing stopping implementations from continuing support for pre-draft-08 syntax; it's just a simple type switch (i.e. if the value is an array, either warn / error or provide deprecated support).

In everything I've ever implemented (an assortment of bits and pieces, most not public), dependencies is always the ugliest mess in the code, so I disagree with your dismissal of this concern.

dependencies is a much more obvious keyword than schemaDependencies

I strongly dispute this. In my experience, dependencies has always been very confusing for people. And even more importantly, I would be willing to bet a lot that most preferences for dependencies can be explained by preferring what is familiar over what is new.

I really don't see how this is complicated from an implementation perspective.

It's complicated compared to other keywords. The original dependencies is a horrible mess from my point of view because it conflates assertions and applicators, and I want to remove any vestige of that.

Also, implementing exclusiveMinimum and exclusiveMaximum across multiple drafts is really annoying.

Your objections seem to boil down to not liking change, but the whole point of being in pre-release drafts is to facilitate change. I try to avoid it as much as possible (goodness knows there are other things I'd personally like to tweak), but when we have decided to make a change (as we have here), I want to make the change clear and obvious, and facilitate migrations as much as possible.

What I'm looking for here is an affirmative argument for keeping it as dependencies: Something compelling that is far better with dependencies and far worse with schemaDependencies. I'm not hearing that. If the discussion is personal preference, or some people thinking that the code is easy and others thinking that it's hard, I'm going to go with the easier option.