3.3: 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.

[whitlockjc]

...

• 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

This is not a guarantee that a spec can offer, nor does this change help or hinder things. Tool developers and OAD authors all go based on their comprehension of the spec and there are no guarantees that any/all of them will have the same interpretation for the grey areas. In fact, some tools even go so far as enforcing their own rules (requiring operationId for example) and so I'm not sure this is a valid supporting reason.

• OAD authors need to be confident that their OAD will be interpreted the same way by all tools

Same as my comment above, [dis]allowing patch doesn't have a direct impact on this.

• 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

My concern here is that it becomes much harder to know what changes were made to correct things if we lose the patch number.

• 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.

Again, see above. This concern/situation isn't addressed or fixed by dropping patches, in fact I might even say it's harder to detect situations like this. Let's say 3.2.0 drops, tooling author supports 3.2.0 completely and now 3.2.1 drops. There is a clear understanding that this tool supports 3.2.0, and the tooling author can tell what went into 3.2.1 to adapt (should they choose to).

Now let's use this same scenario with 3.2, how does the tooling author know that since the original release when they wrote their tool support that things have in fact changed and they may have an impact on their tooling's support? Sure, we can use a date/errata in the spec, but aren't these analogous to a patch version but with more work required by tooling authors and users to comply?

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).

[Dis]allowing patch DOES NOT affect this.

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.

Aren't tooling authors already able to do this?

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.

I agree, anything above and beyond (including going against the spec) should be configurable.

...
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.

Again, I don't see how [dis]allowing patch addresses this in any way, and my personal opinion is that it actually might make things harder.

[karenetheridge]

There is a clear understanding that this tool supports 3.2.0, and the tooling author can tell what went into 3.2.1 to adapt (should they choose to). ... Now let's use this same scenario with 3.2, how does the tooling author know that since the original release when they wrote their tool support that things have in fact changed and they may have an impact on their tooling's support?

Can you clarify what you mean by this? Are you suggesting that the tooling author would accept documents with "openapi":"3.2.0" but reject ones with "openapi":"3.2.1" because they don't know if there were changes that they aren't yet dealing with? And if the document only says "3.2" that the tooling author can't do something different? But what different actions are you expecting the tool to take, when we explicitly say that patch releases are fully compatible?

[rmannibucau]

But what different actions are you expecting the tool to take, when we explicitly say that patch releases are fully compatible?

even a rephrasing of a description is not compat for a tool if the descriptions are modified somehow so until schemas are exactly the same and the 1-1 mapping is just convenient, then it is required

[handrews]

@whitlockjc I just want to get clarity on something (I am not making further points on the actual question at hand, just the context):

There is a clear understanding that this tool supports 3.2.0, and the tooling author can tell what went into 3.2.1 to adapt (should they choose to).

since the original release when they wrote their tool support that things have in fact changed and they may have an impact on their tooling's support?

Is it or is it not our policy that patch releases SHOULD NOT change tooling behavior?

• If not, what do you think the policy is and where is it documented?
• If so, are you making the argument that we need to handle people that disregard the SHOULD NOT? And if that is the case, how does that fit with how we handle SHOULD/SHOULD NOT in general? These constructs are usually used in the sense that if you disregard them, you are at least somewhat on your own.

[handrews]

Add-on for those who read emai notifications: I correct the previous comment from "SHOULD NOT change behavior" to "SHOULD NOT change tooling behavior".

[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.

[whitlockjc]

We've got a year worth of back and forth, anyone got a TL;DR for the reasons supporting this change, and those opposing it? I responded here but I feel like there is more going on. Also, last I saw @karenetheridge said the patch/point release is significant, and I would agree with that (voted up, but easy to miss).

[whitlockjc]

But, I do understand that if we're running the project properly, while the spec's content COULD change between patch versions, the associated JSON Schema SHOULD NOT.

[rmannibucau]

Should but can. A common exemple is a description change for ex. As an integrators you want the schema matching the doc version even if runtime wide it doesn't change - doc can be shown in the ui for ex.

So a 1-1 mapping is really desired whatever good intents are.

[handrews]

@whitlockjc

Schemas change within a minor release line, they just don't change due to patch release changes. Patch releases fix spec language, schema iterations improve the schema with respect to the overall minor release line.

We just had an extremely extensive debate on this topic which resolved as stated above, which we then documented on the spec site. This is our actual hard-won policy, please do not re-open it when we just put so much work into settling it a few months ago.

Our official policy: The latest schema iteration in a minor release line is the most correct, and applies to all patch releases in the minor release line. We have further considered not using dates in the schema iteration ids to prevent people from trying to correlate schema iteration dates and patch release dates which they should not do.

[karenetheridge]

Also, last I saw @karenetheridge said the patch/point release is significant

Well actually... I've been thinking about this a lot, and re-reading all the arguments in this thread and in the other threads, and I think I've been convinced to go the other way. While it may be useful for the OAD author to indicate the OAS patch version under which they wrote the document, I no longer think that this should be in the openapi field, as I don't think the tooling should in any way be able to programmatically act on this information (and I have failed to come up with any usecases where this is a good idea, other than simply using this information to provide better diagnostic messages).

I might go further in depth with my thoughts later, but for now the tldr is: I am now fully on board with not just allowing the openapi field to drop the patch value, but outright forbidding its use.

[karenetheridge]

while the spec's content COULD change between patch versions, the associated JSON Schema SHOULD NOT

No -- the associated schema for the OAD certainly can, and does, change in between minor releases. In the past year we have seen several changes, both to correct errors (a typo in one property name that no one noticed: body -> server in the link object), to optimize conditions or to add additional constraints that could have been there but were not (removing redundant declarations, moving things out of an allOf that didn't need to be there, fixing the format of some things from uri to uri-reference).

To reiterate Henry's point above -- in all cases, the latest schema revision within a minor version is considered to be the most correct -- there is absolutely zero reason to ever use an older version of a schema for a given minor revision (and ideally we should delete them from the website and never mention them again -- but we can't do that because something might still be referencing them). If a tool is knowingly and willfully using an older version of a schema for a given minor release, that is a bug.