Document our deprecation policy

[Julian]

(I don't see this mentioned elsewhere, but if it is, feel free to redirect).

We now have at least a few examples of explicitly deprecated keywords (or more broadly behavior).

The easiest list of examples are in the current metaschema, and specifically include:

• definitions
• dependencies
• $recursiveAnchor
• $recursiveRef

We don't, as far as I can tell, provide any real information about what downstream users should expect about the length of this deprecation. Other than the metaschema inclusion, their presence is indicated in an appendix to the validation spec.

It says, e.g.:

implementations SHOULD assume that "$defs" and "definitions" have the same behavior when that meta-schema is used

though note similar language isn't present for the other 3 examples (and the recursive* examples aren't even mentioned).

It would be nice to:

1. have an explicit policy, even if we don't necessarily decide on a completely standard time (e.g. "all deprecations last 2 releases" might or might not be unrealistic, but we should at least say "all deprecations indicate some information about their expected length" somewhere, and be collected in some explicit location)
2. ensure we have the agreed-upon info from the policy about each existing deprecation

Note that this issue is not intended to discuss or document any backwards compatibility concerns beyond those that already exist (a la e.g. #1242), or even to discuss the practice of deprecation itself and how often we do it "in abstract". It is strictly about clarifying the policy for those things we now explicitly have deprecated in the specifications, and documenting what expectations downstream implementers and users should have about how long those deprecations will last, as well as then hopefully following the same written policy for future deprecations.

[gregsdennis]

This is also probably tangentially related to https://github.com/orgs/json-schema-org/discussions/192

[jdesrosiers]

Historically, we haven't deprecated keywords, we've removed them. I've never really understood why we have them in the meta-schema. They are expected to not do anything, but enforce that they have the syntax for the keyword that was removed.

The only exception is definitions that (as you quoted) does have deprecated-like behavior.

However, sometime soon we want to commit to only backwards compatible changes which means we will likely want to deprecate keywords in the future and we should define how we want to do that.

[handrews]

@jdesrosiers IIRC, the idea was that we didn't want someone to redefine them as extension keywords in some sort of pathological way. I don't recall the rationale being all that thought-out, but it did give us the option of choosing a compatibility strategy later.

This is distinct from the ideas in #1242, as it only preserved the syntax of removed keywords, and only in the standard meta-schema (not the individual vocabulary schemas, so you could easily assemble a meta-schema without the old keywords. We very intentionally did not preserve past legal syntax of keywords whose syntax had changed (e.g. $id).

But it was more about preserving options than anything else- if we had really wanted people to keep supporting those keywords, we would have made a vocabulary for them (which, of course, someone could do on their own, although why anyone would want to preserve $recursive* is beyond me).

[gregsdennis]

I don't think this is a problem anymore since we've forbidden extra keywords. If someone wanted to re-use one of these, they'd have to define it in a vocabulary, in which case, the keyword is properly defined through the vocab anyway.

Closing this.