Consider keeping semver for *future* 3.x releases

[pimterry]

I think I understand the v3.1 vs v4.0 decision, and while I don't love it, I'm taking that as a given.

However, I don't see that that necessitates the current versioning text in the 3.1.0 RC spec. Is there any flexibility to provide more guarantees there? I'm talking about this paragraph specifically:

Occasionally, non-backwards compatible changes may be made in minor versions of the OAS where impact is believed to be low relative to the benefit provided.

As a developer building on top of OpenAPI, this means today I cannot write code that accepts any OAS spec inputs with versions >3.1. All code & libraries written today must reject those as incompatible, because they're defined as being potentially incompatible in all possible ways.

I suspect that's suboptimal, because it seems very likely that a hypothetical v3.2, 3.3, 3.4... and other future specs will be exciting feature releases, backwards compatible with 3.1, rather than a series of new breaking changes.

It would be unfortunate if OpenAPI's versioning system unnecessarily made adoption of these future specifications more difficult by forcing today's tools and libraries to reject these compatible specifications out of hand.

I'm proposing that this paragraph could instead say something along the lines of:

This specification breaks compatibility with previous 3.0.x specifications, in some specific cases with minimal impact and high benefit. This is intended to be a one-off occurrence. Future 3.x.x specifications MUST remain backwards compatible with this specification (v3.1.0) and tools MAY assume that future 3.x.x specifications are fully backwards compatible.

I.e. don't drop semver entirely, and instead say "just this one time, we're bending the rules".

This has a few benefits:

• Code that consumes OpenAPI specs today can make useful assumptions about more future spec versions.
• OpenAPI releases will be able to easily communicate both size and compatibility of future specifications just through the version number. Right now that's not possible (is 3.2 a shiny new feature set, or an incompatible change? Is 3.1.1 a typo fix, or a big-but-compatible change?).
• It provides clearer documentation of the current decision and intent within the spec itself.
• It provides future pressure to either a) stay backwards compatible or b) more clearly communicate breaking changes with a version bump. Staying backwards compatible where possible is clearly valuable. While I'm aware that a v4 bump was undesirable, if there will be more breaking changes in future, doing the bump and matching standard versioning expectations will eventually be preferable.

Of course, if the real expectation is that a hypothetical v3.2 is actually very likely to be incompatible, then this is all wrong! In that case tools really should reject future spec versions. Imo given that it would be better to either start major bumps or pick a versioning system that clearly communicates this, and make that likelihood clearer in this text too. As a very quick fix, I'd suggest maybe 3.1-0, as a minimal change that'll jump out to everybody as not-semver. For now I'm going to assume that that's not the intent here though.

[pimterry]

Conclusion after the TSC call, as I understand it:

• It is probable that future OpenAPI minor versions will often be incompatible, at least in some sense. That's beneficial: not being able to release changes due to compatibility has significantly slowed past progress (JSON schema compatibility being just one example).
• It's not possible to provide any stricter guarantees about the type of incompatible changes that might appear in a minor version. The definition used in 3.0.3 specifically would not work, as it's a tighter constraint than the guarantees provided by JSON Schema, so would block updates there.
• For marketing and adoption reasons, it's not acceptable to have repeated major version bumps.
• Given that, we can't realistically do semver at all. The plan for now is to evaluate the impact of this from community feedback when releasing 3.1, and to reconsider versioning strategies based on that experience for future releases.

From my POV that's not exactly what I was looking for, but given the need for regular breaking changes it's unavoidable, so I'll close this for now.