Formally define Experimental and Deprecated

[mikeschinkel]

Per discussions on 2025-01-28 we discussed the ideal of adding formal definitions for "Experimental" and "Deprecated". @handrews requested me to post an issue to ensure we discuss and potentially address this moving forward.

[handrews]

@mikeschinkel thanks for filing this!

For "Experimental", I think the main point is to place the feature outside of our compatibility guarantees. An experimental feature in 3.2 is not guaranteed to be compatible with 3.3, while regular features are expected to be strictly compatible from an older to newer minor release (3.0 to 3.1 schema objects are an exception that we do not intend to repeat). This is particularly important for new things like abstraction layers that are a step removed from the syntax, which is usually how we have defined compatibility. The open question is whether there needs to be some level of continuity guarantee. We do want people to feel motivated to implement these things, so we don't want to be too casual about it.

For "Deprecated", I think there are basically two ways to go:

1. it's just a signal to OAD authors that they should prefer the new way if at all possible, but it does not impact implementation compliance requirements at all
2. we could allow implementations that only support the OAS release where the syntax is deprecated (and newer) to not support the old syntax at all (although implementations that support older releases probably MUST continue to support it in new ones)

The rationale for option 2 is to encourage new tools to target the latest version, which would be simpler to implement than supporting full compatibility. This involves a trade-off between a new way to fragment the tooling landscape and the reality that backwards compatibility is a burden that is not relevant to all users.

Our minor release guarantee (again excepting 3.0 to 3.1) is that you can just change the openapi field value to the next minor release an everything will still work. Philosophically, if your tool supports 3.2+ and not 3.1, then an OAD with a 3.1 openapi value never worked in your tool at all, so you're not really breaking anything within that one tool. But you are breaking thing from an ecosystem perspective.

If we do option 2, we need to decide whether deprecating a feature immediately makes it optional for new tools, or whether you can only do that in the next release (e.g. syntax deprecated in 3.2 could only be dropped in tools that only support 3.3+, or could it be dropped in tools that only support 3.2+?)

[mikeschinkel]

Will "Deprecated" ever be used as a signal that something will be removed in the future, and if so will that version be defined, e.g. deprecated in 3.1, removed in 4.0? I ask because I wonder if removing it at some future point would not be needed to motivate people to actually move to the newer approach?

If no, or if not always, maybe other terms are needed to indicate the following for clarity?:

1. Obsoleted w/no plans to remove
2. Obsoleted w/plans to remove at some point, and
3. Obsoleted w/plans to remove at a pre-defined version.

#2 might not be needed, though. IOW, if the plan is to remove it then shouldn't the version of removal of support be predefined?

Regarding your last question, given experience with deprecated features in programming languages, I would say the version a feature is deprecated in — e.g. 3.1 — that would mean the feature does not need to be implemented by any tool that only supports that version moving forward, e.g. 3.1+.

---

After writing the above, it occurs to me that newer tools being able to not support deprecated features may be enough incentive for people to move to the non-deprecated features, but I am leaving what I wrote above so that we can discuss and then explicitly take a position on the topic.

[handrews]

@mikeschinkel Our versioning policy already allows us to break/change/add/remove anything on a major version change, but requires us to preserve compatibility when moving from one minor version to the next. So we already cannot remove something in a minor version, and we already set the expectation that nothing is guaranteed in a migration to a new major version (although we provide tools to assist such migrations). When defining what "deprecated" means we should be clear about how those compatibility rules are involved, but there's no need to add or change anything there.

[mikeschinkel]

@handrews — Sounds good.

[baywet]

notes from the TDC meeting:

• experimental is fairly straight forward to allow us to experiment and gather feedback on designs before any "finalized" release/feature. We wouldn't expect tools to implement support for it to be compliant, but they could opt-in.
• deprecated/obsolete might bring additional challenges to tools authors: if I implement only 3.3, do I need to implement a deprecated feature (which was not in 3.2) ? when are we (spec authors) allowed to remove something deprecated from the spec? Java devs are fairly specific about that, support something deprecated for another major release.
• maybe a solution is to differentiate between obsolete and deprecated where a specific feature stays deprecated for a while, but needs to remain supported by the tool, and after a couple of minor version, becomes obsolete, which means implementers of the new spec version DO NOT need to support it anymore.
• one of a considerations is to account for the separation between the syntax and semantic level (if we move in this direction). It becomes much easier to deprecate/obsolete syntax things while maintaining compatibility on a semantic level.

Next steps:

• define the lifecycle for experimental/obsolete/deprecated and introduce it to the broader group.
• lookup and share precedents for those lifecycle aspects, how they handle it, and share it with the broader group (e.g. ES/TC39, WHATWG, etc...)

[handrews]

Some additional notes from the call and my own thoughts:

• I brought up that we don't want something as complex as TC39, in part because we want to use "experimental" very sparingly. Most things shouldn't go through an experimental phase, in part because we already have a major release on the horizon that will allow us to do a reset. That point seemed to gather agreement, or at least no objections that I recall
• I like the "deprecated means still supported by all, obsolete means it can be dropped if pre-deprecation versions are not supported." I'm not sure what the condition for obsoletion should be, but having that idea means we don't need to decide that just to start marking something deprecated in 3.2 or (more likely) 3.3.

[darrelmiller]

We have x-oai- for experimental stuff.

[handrews]

@darrelmiller this is more for things like introducing concepts around DOM/ADA in 3.x. So there's no specific keyword.

[handrews]

PR #4591 defines a deprecation policy, and the use cases for "experimental" no longer really apply. We can file a new issue for "experimental" if it comes up again.

[handrews]

To @darrelmiller 's concern, the experimental use cases that still apply are addressed by x- fields, but we are no longer putting in anyting that would be experimental and not field-based.