Clarify the meaning of info.version

[dret]

Looking around a little bit and conducting a LinkedIn poll (not very scientific, I agree, but still interesting), it seems that few people understand what info.version is for.

https://www.linkedin.com/feed/update/urn:li:activity:7202896718634315776/

Almost nobody knows the right answer (11% right now but the poll is still open), and there are many documents/tutorials out there that explicitly say that it's the API version (which 56% think is the correct answer).

The current spec text is less than clear. There are two general ways to go:

• Make the text more clear and live with the fact that a good amount of guidance and usage out there is not following the spec.
• Adjust to reality which technically would be a breaking change but since arguably most usage out there is "wrong", it would actually un-break things in a semantically weird but pragmatically interesting way.

[handrews]

@dret I think the best we can do here is clarify in 3.0.4/3.1.1, and maybe in 3.2 we could make this field not required and add an apiVersion field alongside it?

[dret]

On 2024-06-02 16:51, Henry Andrews wrote: @dret <https://github.com/dret> I think the best we can do here is clarify in 3.0.4/3.1.1, and maybe in 3.2 we could make this field not required and add an |apiVersion| field alongside it?

that sounds like a good plan. given that (too) many people take `version` to mean `apiVersion` it might make sense to put an explicit note in there that this is not what it is doing. adding a new field sounds like a good idea to me and would also make it very clear what `version` really is about and where API version information should go.

[handrews]

@dret as noted in discussion with @darrelmiller it really seems like version is the version of the specific OpenAPI Description document, not the entire description. This is because an OpenAPI 3.1 document that is a syntactically complete document (includes an OpenAPI Object at the root) but only has components (not paths or webhooks) will still have a required info field with an Info Object, which will have its own required version field. Such a components-only document is expected to be shared by multiple APIs, each of which would have its Info Object and version field in its own entry document.

So I think that's what we need to clarify. I don't see how any other definition of the version field can work in 3.1. Once we accept either PR #3823 or PR #3855, it should also be a bit more clear how to handle document versioning and documents that are not complete.

[dret]

On 2024-06-03 17:46, Henry Andrews wrote: @dret <https://github.com/dret> as noted in discussion with @darrelmiller <https://github.com/darrelmiller> it really seems like |version| is the version of the specific OpenAPI Description /document/, not the entire description. This is because an OpenAPI 3.1 document that is a /complete/ document (includes an OpenAPI Object at the root) but only has |components| (not |paths| or |webhooks|) will still have a required |info| field with an Info Object, which will have its own required |version| field. Such a |components|-only document is expected to be shared by multiple APIs, each of which would have its Info Object and |version| field in its own /entry/ document.

to be perfectly honest, i'd say that 98% of OpenAPI users out there don't care as much about the finer points of whether info.version applies to a physical or logical document. but i absolutely agree that the spec should be clear about this and it clearly isn't right now. but, given that those 98% (i am exaggerating here for dramatic effect) currently do believe that info.version is for the API version, the more relevant work item may be to say that info.version is *not* that. i do know that it feels odd to say what something is not (because there is not shortage of those things), but given the multitude of incorrect reading and guidance out there, i think in that case we should be clear. where to put API version information is a different issue and there probably should by some place, because people clearly and understandably want to do this.

[handrews]

@dret I'm just not sure how to say that it's not the API version any more clearly than we already do:

The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

[dret]

On 2024-06-04 23:03, Henry Andrews wrote: @dret <https://github.com/dret> I'm just not sure how to say that it's not the API version any more clearly than we already do: The version of the OpenAPI document (which is distinct from the OpenAPI Specification version <#oasVersion> or the API implementation version).

maybe its nitpicking but "API implementation version" to me (and i am suspecting a good number of others) sounds more like the version of the code implementing the API and not so much the version of the API itself. can we remove "implementation" to reduce potential for being misread?

[dret]

For anybody interested in the final results of the poll, here they are:

[karenetheridge]

/info/version is a valuable field for the implementation to know what version of the spec the document is written to adhere to, so it can know how to parse it. This is important to know as there are syntactic and behavioural differences between 3.0.x and 3.1.x, and these differences will grow over time with future revisions.

An implementation needs to know what assumptions the document author made when writing it, and to know how to parse the document. Removing it or making it optional allows implementations to give ambiguous or incorrect behaviour.

(edit: I mistakenly said /api/version in the copy of this that went to email.)

[dret]

On 2024-06-05 17:51, Karen Etheridge wrote: |/api/version| is a valuable field for the implementation to know what version of the spec the document is written to adhere to, so it can know how to parse it. This is important to know as there are syntactic and behavioural differences between 3.0.x and 3.1.x, and these differences will grow over time with future revisions. An implementation needs to know what assumptions the document author made when writing it, and to know how to parse the document. Removing it or making it optional allows implementations to give ambiguous or incorrect behaviour.

All very true but the discussion is about `info.version`, i.e. not the top-level version indicator for the OpenAPI version itself that you are referring to.

[handrews]

@karenetheridge I think you're mixing #/openapi (the version of OAS) and #/info/version (the version of the document, which is meaningless to tools).

[handrews]

Note that as far as API versioning goes, it's a complex topic with several issues open, mostly around the granularity of versioning.

[handrews]

@dret I've updated PR #3861 with a fix removing "implementation" and rewording things a bit.

[dret]

I've updated PR #3861 with a fix removing "implementation" and rewording things a bit.

Sounds perfect to me! Let's see what others think! Thanks!

[miqui]

Closing this issue since PR #3861 has been merged (i.e., a decision on the clarification was reached)

[handrews]

@miqui I've generally been keeping issues open until the PRs have been merged for at least both 3.0.4 and 3.1.1. I had been holding things open until 3.2 was merged as well but I'm holding off on porting some things to 3.2 until after the patch releases are done so I'd say issues don't have to wait for PRs for that release.