3.2: allow openapi field to just specify MAJOR.MINOR and omit the PATCH number

[ralfhandl]

Requiring openapi: MAJOR.MINOR.PATCH and then stating in the spec that PATCH actually is meaningless is confusing.

Better allow (or require?) to write openapi: MAJOR.MINOR.

[handrews]

We could relax this requirement and allow 3.2 (etc.) but we can't outright forbid the patch version due to compatibility issues. At least not for 3.1.x and 3.0.x. I suppose we coudl say "X.Y.Z" if Y <=1, "X.Y" if Y>=2.

[mikekistler]

I think allowing just major and minor would be a great improvement. Or do we think that's already allowed? It's not clear to me from reading the 3.1.1 spec.

[LasneF]

as it is written The patch version SHOULD NOT ... it means that the patch version is still there in a way for 3.1. at least

i would agree with @handrews statement meaning that we are 3.0.X , 3.1.X and could be just 3.2

still btw the presence of a 3.1.1 show case that patch was used it , as well as 3.0.4 for minor changes toward the 3.1.0 or 3.0.0

that said having update on 3.2 and future for typos , i would say brings unecessary complexity for low benefits (traceability)

so far it would requires that all changes in a 3.2 once settle are very very minor (gatekeeping ) , otherwise will go to 3.3

[lornajane]

There's clear consensus that we should allow the openapi: string value to be MAJOR.MINOR, so from 3.2 onwards, you would simply use 3.2 or 3.3, etc. For YAML, those values should be quoted to avoid them being parsed as numbers (which the three-segment version number aren't subject to).

There is a lively discussion on whether the patch value should be forbidden or optional.

[handrews]

@lornajane I'd like to think about the goals around this so we can find the best path forward to satisfy all of the goals. I do not think that allowing the patch version is the best solution.

• Compliance tools need to test adherence to 3.2 regardless of patch version, and both tool developers and OAD authors need to unambiguously see that this is the behavior
• OAD authors need to be confident that their OAD will be interpreted the same way by all tools
• You've brought up possible misinterpretations and ambiguities that would need to be detected, and you have tied that to the patch release number; while I think we are in a better position to correct such misinterpretations before they become entrenched, it is indeed always possible that something goes off the rails
• The problem with tying this to the patch version is that one tool's patch-specific misinterpretation is not the same as another's; for a use case where an OAD is passed to multiple tools, it may be the case that the 3.2.0-specific behavior of one tool is desired, while the 3.2.0-specific behavior of another is not desired.

The problem here is that different tooling vendors may misinterpret different things based on patch-release-specific language. Or they might misinterpret different things in conflicting ways that cannot be reconciled (we have seen this repeatedly with certain parsing/resolving behaviors).

We should have a mechanism for OAD authors to indicate that they want to stick with an "incorrect" tool-specific interpretation. But this should be of the correct granularity to help users navigate the complex and inconsistent tooling landscape.

My preference would be to allow vendors to define their own flags to control behavior that is outside of the specification. At most, we might designate a special field under which such flags appear.

Note that this is different from "feature flags", a concept which I have opposed elsewhere: Feature flags create a complex matrix of interoperability requirements that everyone must follow. Tool-specific variation flags are not expected to be used by anyone but the tool to which they are scoped.

Our biggest problem for large-scale use is the lack of interoperability. We need to put the tightest guard rails possible on any non-interoperable behavior to make it clear that tools cannot change what the spec means by mistake. If they want to keep a mistake, they need to do that explicitly so that people who write "normal" OADs have the maximum chance of interoperability.

[lornajane]

I have no need to discuss this further. I completely agree that the patch number should never be used by tooling and the wording in the specification also already makes that clear. However, as a person who works with a lot of OpenAPI descriptions, the "vintage" is sometimes useful contextual information to understand their status. The change to major/minor only seems good, but strictly forbidding anyone to include the patch number seems like a more closed approach than we usually take.

[handrews]

@lornajane my point here is that we can capture the "vintage" information some other way that does not make the other goals more difficult.

strictly forbidding anyone to include the patch number seems like a more closed approach than we usually take.

Our tendency to have non-strict semi-requirements is part of why the tooling landscape is so fractured and non-interoperable today. The point of a spec is interoperability. We need to tighten up our requirements so they are clear, testable, and dependable.

I'm trying to find a way to meet both goals: Capture "vintage" information that can be used outside of what the specification says while still locking down the correct behavior so users can depend on it.

[ralfhandl]

I'm in favor of not allowing 3.2.0 etc. and requiring 3.2 etc.

There are consuming tools relying on the PATCH part of the 3.0.x version, and I had to add options to my generating tools for setting a particular PATCH version expected by these consuming tools.

All optional features will be used in all allowed ways, and then some creative ways, too.

[handrews]

@ralfhandl @lornajane last call on this for 3.2- will it be "3.2" or "3.2.0" in the version field? Or will we allow both? It's a trivial change to make now, but will set the pattern for 3.2.x patch releases.

[ralfhandl]

I'd only allow "3.2" etc. going forward.

If someone has concerns, I'd be fine with allowing both "3.2" and "3.2.0" etc.

[handrews]

@ralfhandl @lornajane I'll point out that this is now causing confusion with the IETF HTTP APIs media type working group that is trying to register application/openapi+json and application/openapi+yaml, with a version parameter. There is now debate over whether the patch number should be allowed in content-negotiation, and due to the unresolved state of this conversation the best I could come up with was "allow but discourage" which is not very satisfactory.

[lornajane]

I've nothing to add here.

[handrews]

@lornajane @ralfhandl I think everyone has all of the necessary info about this, so I'll leave you and the rest of @OAI/tsc to decide. I think we should pick an answer (whether that's 3.2, 3.2.0 or allow either) and resolve this discussion rather than leaving it open, but I'll work with any resolution y'all choose.