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.

[karenetheridge]

I've written quite a lot of words that oppose this plan, with the reasons why, at #4147. The point release is relevant, and it could be made even more relevant and useful still, with no changes at all to the specification or the schema (only release procedures would change).

[earth2marsh]

@rmannibucau it feels like people might be talking past each other. Long back-and-forths like this about specific points can be exhausting for everyone involved.

If you still want to push for a specific change here, I recommend restating your thoughts into a single, clear case with specific examples. As volunteers, the maintainers want to make the best decision for the spec, and a focused proposal is the most effective way to help us do that. I cannot promise you'll get the outcome you want, but the best way to create change is to explain clearly why it should happen (ideally including an explanation of the opposite position).

[rmannibucau]

Hmm, seems github collapsed too much message, missed #4233 (reply in thread)

The "missing" piece is that this is not promotion friendly and only works (current state) with a jsonschema registry which is abig drawback since technically openapi gives a version which should be sufficient since once the spec has a version then it is not supposed to change.

The issue with index.json is the requirement to do a local copy, then you are off the synchronization and get "hey it works for me", "not for me" cause people do not rely on the same schema based on the same assumption - openapi value.

Fixing it would avoid to 1. have to copy the schema everywhere and not be future proof, 2. to have this issue ^ ^ and 3. to be outdated (taking oldest schema since it is the only strategy today without shared persistence/copy).

[karenetheridge]

FWIW I'm not bothered by the mechanics of detecting schema updates and downloading them -- I've automated that sufficiently for my implementation here: https://github.com/karenetheridge/OpenAPI-Modern/blob/v0.095/update-schemas#L42-L62

[ralfhandl]

@karenetheridge Would you find an oas/index.json more helpful than scraping the HTML page?

If yes, which structure should it have? What needs to be changed in the proposal https://ralfhandl.github.io/OpenAPI-Specification/oas/index.json?

[karenetheridge]

I think an index.json page would be more useful for users. I don't think we should be optimizing for my needs because I already know what the schemas are for, how to use them and how to find new ones. I'm more concerned with drive-by OpenAPI users who barely know what a schema is, let alone how it fits in with the rest of the ecosystem. I'd like everything to be as easy to use as possible for the users we're trying to draw in.

[rmannibucau]

Hi,

I think it is good for everyone not automating much around openapi and not harnessing it nor using it at runtime (i'm thinking to all openapi intended to be used for dev purposes like swagger-ui and friends) but for any tool and end users using it at runtime (think gateway using it to generate routes for examples) then you can accept to use a random schema even if there is a promise to be backward compatible. Human error happens so there should be a pure immutability in the versioning and 1-1 mapping with the schema IMHO.

So while the relax is good it doesn't solve the mapping issue to a fixed schema IMHO.

[ralfhandl]

Hi @rmannibucau,

Would in an index.json file like this one solve the mapping issue?

• https://ralfhandl.github.io/OpenAPI-Specification/oas/index.json

This file could be auto-generated when publishing spec versions or schema iterations and located at

• https://spec.openapis.org/oas/index.json

[rmannibucau]

it can work only if the date is a timestamp (to be honest i do not care of the "second" but the jour is key), this way the soft can easily know its build time and compare to it to take the "latest previous" one.

It is not as nice as being 1-1 with the openapi attribute (and I still fail to see why it cant since the spec says major.minor is important so patch can be used for that) but it would technically work and cover all the cases I do have.

[karenetheridge]

IMO, any sort of value that is increasing (such as a date, or a 3-part point release, or an integer..) is fine for programmatically finding the latest release on a webpage. I've got that automated already -- once a new release appears on the spec page and I run my scraper script, it downloads the new files, replaces the old ones in my implementation, updates checksums, and substitutes all references to it in code with the new URI.

Making this value be the same three-integer release number as the specification has additional benefits, like increased discoverability by users, the ability to make release announcements about schema improvements, and the ability for users to indicate that their OAD requires a schema fix that appeared in a specific version.

[handrews]

@karenetheridge I would like to revisit this:

The point release is relevant, and it could be made even more relevant and useful still

Do you still maintain this? Even though the jsonSchemaDialect and Link Object schema change examples (and indeed most schema changes give the number of schemas vs point releases) do not have a corresponding point release (or any specification text change anywhere)? And if any such point release were made for each schema its text would be completely unchanged except for the patch number itself? And if so why?

I am struggling to understand here, but realize I may still be missing something. Every example seems to point to the opposite conclusion for me: Point/patch releases are irrelevant to schemas. Are there more examples within the current releases/schemas to support tying them together?

[karenetheridge]

Note to everyone not-Henry: if your eyes are glazing over, then please just read the last paragraph (or rather, the bit after the separation line). It is non-technical, I promise.

I think you are putting too much weight on the tying together part.

In today's call you seemed to reject any other option. If you will drop the tying together part, I think it's totally reasonable to discuss an additional field for 3.3.

You took my statement out of context and then made it say something I didn't make it say. I said before, and I will repeat, that just because two changes are released at the same time doesn't mean they are related to each other, and this is a very normal thing. You seemed to be suggesting that a spec change and a schema change released together doesn't make sense, but every release we do is of that nature - a collection of unrelated fixes, clarifications or new features.

But anyway, your interpretation of my usecases don't make sense.

"The "minimum schema" use case, automatic updating"

I don't understand this usecase at all because it presumes a perfect world where the minute spec and/or schema changes are released that they are fully supported and released in my implementation. So any rebuttal to this usecase doesn't really make sense either.

I also don't understand what you mean by "If you are automatically applying updated schemas back to old patch releases" -- there is no such thing as re-releasing an old version of an implementation; I don't have a time machine. If version 0.618 of my parser doesn't support OAS 3.1.2, it never will. 0.619 might, and at that point there is still just one implementation for all of 3.1, covering up to 3.1.2. There's no code that goes "if the OAD only asked for version 3.1.1, then don't allow uri-references in jsonSchemaDialect". It's just uri-references period. ..And since this field doesn't exist in 3.0 at all, there's no need to have a conditional at all on this feature - for 3.0 there is just a single json schema dialect that can't be changed, and 3.2+ isn't changing how jsonSchemaDialect works so for 3.1 it's just a relative uri period.

"The "minimum schema" use case, no automatic updating" - If you are not updating, then you are preventing people with older patch releases in their openapi fields from using URI-references.

How? Are you presuming this would be interpreted as a maximum, not a minimum?

If I am not updating my implementation, then people can't use uri-references period, because 1. the schema would be preventing the use of a uri-reference rather than a uri, and 2. my code wouldn't support it either even if the schema wasn't being used internally for parsing, because actual work needs to be done to resolve a uri-reference against a base. But at least the OAD is indicating that a later release is expected, and the user isn't scratching their head wondering why it doesn't work (either they got a cryptic validation error that makes no sense to them since they're not intimately familiar with the way json schemas work, or simply the wrong identifier would be used which could cause some other seemingly-unrelated error), because they got a clear and sane warning something like "you asked for 3.1.<something>, but we only know the existence of up to 3.1.1". If we'd had full versioning anytime between February and August (more on that below), a bug report could have landed in my inbox saying something like "hey, 3.1.<something> was released but you don't support it yet, get on with it", and then I reply "paypal plz or no bueno" (just kidding, I don't extort money from my users).

"Locking schemas"

I have no idea at all what you mean by this and I don't know where/what I said that prompted this section.

"Clarified semantics" - You mentioned clarified semantics, but these are generally not visible in schemas

jsonSchemaDialect being mistakenly specified as a uri not uri-reference in the schema is a perfect example of this. Because it was not obvious in the spec, it wasn't obvious to the schema author, who made a mistake, and once it was clarified in the spec it was naturally fixed in the schema as well.

Another recent example that I can think of is the confusion between what characters are permitted in path template names vs path template values (and indeed this was asked about on slack just today! suggesting that further clarification is needed) -- we may in the future discover while clarifying this in the spec (perhaps with examples, which I think we've found are always great to have) that a regex restriction in the schema might be too loose, or could be tightened. I'm going to repeat one more time to make sure you understand that I do understand that such a clarification goes all the way back to 3.1.0 no matter whether or not it was in spec 3.1.0 or in the schemas that were released at that time, but the reality of linear time means that implementations written under those versions, through no fault of their own, may not work as we want them to and therefore if those tools written at that time had access to a version number in the OAD they could potentially better advise a user using those tools of the nature of the problem they are experiencing.

Again I will repeat what I found on the github page for releases: "OpenAPI Description writers should mark their OpenAPI Descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible." One would think that this sentence was written with the intention that this version could actually be useful to someone/something -- be it a future editor of the OAD, an implementation that needs to interpret the OAD, etc. What do you think that purpose might be? Is it so bizarre that I am asking for a way to make this field even more useful, by extending that sentence to "...with the version of the OpenAPI specification and schema(s) they used..."

---

final pitch starts here:

The other advantage of consistently versioning schemas together with specifications is something that I don't think you have responded to at all -- the improved ability to telegraph changes. It has been my consistent frustration that schema releases are in no way announced: not with an RSS feed, nor a mailing list announcement, nor a short blog entry, nor a banner line on the openapis.org site, nor an entry on https://github.com/OAI/OpenAPI-Specification/releases. It's only by watching the github feed (which I find so voluminous I can only barely keep up at the best of times) that I even know they happen at all. I didn't sync up with the February revision until August because I didn't see that it had happened, and with annoyance resorted to writing a web scraper to look for updates (but even this isn't automated as it doesn't get run until I make a code release of my own, which is not always frequent).

Release announcements are not only helpful for all that consume the spec or write OADs, but also allow for further elaboration as to the nature of the change and to provide further colour like "this change is only a clarification and should be assumed to apply to the entire 3.1 release line, although tools may need to be updated" (which seems like it would be obvious to us but is not so much to many others). It gives me something to reference when I make my own tooling release announcements. It provides me something to post to linkedin, for $diety's sake! How can this be a bad thing?

[handrews]

@karenetheridge Thanks for persevering. I think I am finally seeing what I have been missing.

TL;DR:

• There is an error reporting use case that I find worth exploring, at least for patch releases.
• Other things make enough sense to me now that I'm happy to leave them to you and the TSC to resolve. Not because I agree, but because I don't feel that I have such a strong stake in it as to need to influence the final decision beyond what I've already said here.

---

If version 0.618 of my parser doesn't support OAS 3.1.2, it never will. 0.619 might, and at that point there is still just one implementation for all of 3.1, covering up to 3.1.2. There's no code that goes "if the OAD only asked for version 3.1.1, then don't allow uri-references in jsonSchemaDialect".

I now see that you are talking about the status of your releases (multiple, in series) in relation to OAS releases and schemas. As opposed to talking about how a single release of your implementation works with different openapi values. That's a key differing assumption (which you may have clearly articulated before, in which case I apologize for missing it).

But at least the OAD is indicating that a later release is expected, and the user isn't scratching their head wondering why it doesn't work (either they got a cryptic validation error that makes no sense to them since they're not intimately familiar with the way json schemas work, or simply the wrong identifier would be used which could cause some other seemingly-unrelated error), because they got a clear and sane warning something like "you asked for 3.1., but we only know the existence of up to 3.1.1".

This reframes things around error reporting, which is a use case I can understand. It's also a reasonable argument for requiring (rather than just allowing) the patch release in openapi and ideally updating the spec to explain what it should and shouldn't (or SHOULD and SHOULD NOT) be used for.

Personally (emphasis, personally), I feel that the implementation documenting what release it supports and saying so in any error messages ought to be sufficient. "I was written based on the 3.1.1 text, are you expecting behavior clarified later?" But in broader terms that's very debatable, which means not a topic to resolve before 3.2 ships.

I am still less sold on tying patch releases and schemas together, which fits with my general sense that it's the implementation that needs to report, rather than the OAD documenting. I would prefer OAD authors not think about the schemas much, and having an implementation say "your OAD failed against the schema with $id: whatever, check spec.openapis.org and if there is a newer version please file an issue" seems sufficient. And also allowing users to specify a schema separate from the OAD, without having to maintain a potentially finicky field in the OAD. But that is another not-before-3.2 discussion.

Fundamentally, I just don't see the uri vs uri-reference thing (which affected quite a few fields, for those who think jsonSchemaDialect is too obscure for them) as a versioning thing in a way that OAD authors should care about. It was a bug, it got fixed. Yes, there's a new release of something for that, but to me it's the schema package and I doubt I will ever agree with tying the things together. It should have about as much impact as a dependabot PR. But I at least understand the discussion well enough now that I'm satisfied leaving it to you, the TSC, and any other interested parties to resolve.

[ralfhandl]

improved ability to telegraph changes. It has been my consistent frustration that schema releases are in no way announced

@karenetheridge We can announce schema releases without changing the schema version naming pattern, for example by using release names X.Y Schemas YYYY-MM-DD and corresponding tags X.Y.schema-YYYY-MM-DD, see https://github.com/ralfhandl/express-experiments/releases for an experiment.

The latest release, whether spec release or schema release, is labeled "Latest" and will appear in the right sidebar of the repo start page.

On the "Releases" page the releases are lexicographically sorted by tag, so with the X.Y. prefix for schema tags the spec releases will be on top in reverse order, then after the X.Y.0 spec the schema releases in reverse order, then the pattern repeats for the preceding MAJOR.MINOR spec and schema releases.

This would be a minimally invasive addition that probably can be automated and added to the schema release workflow.

Would that work for you?

[karenetheridge]

Adding tags for schema releases would be very welcome yes, thank you!

[ralfhandl]

@karenetheridge Created

• Schema Releases #4955

for further discussion.