Version parts

[aowss]

Are all parts of the openapi field mandatory or can i have a value that is just 3.1?

[MikeRalphson]

The major, minor and patch numbers of the openapi field are mandatory (the value is a semantic version number, not a semver matching expression), but the patch version SHOULD be ignored by tooling, so 3.1.0, 3.1.1 and 3.1.999 are treated equivalently.

You can also have pre-release information following a dash, such as 3.2.0-rc0. This is obviously optional.

[MikeRalphson]

@char0n sure, back at my laptop now rather than on my phone so finding links is easier. The openapi field value is a normal version number according to the semver spec, so MUST contain all three components (major,minor,patch).

By "semver matching expression" I meant something like npmjs's "ranges". Here "3.1" would be treated as an "X-Range" - so drawing the distinction that "3.1" would NOT be a valid value for the openapi field.

[char0n]

Thank for explanation! Though the openapi field format is compliant with semver spec, the actual meaning of the number is IMHO not. As OAS 3.1.0 technically contains multiple breaking changes we would be in OAS 4.0.0 instead of OAS 3.1.0.

[MikeRalphson]

@char0n you are absolutely right, we did drop semver in v3.1.0 and I should have made that clear. We still subscribe to the definitions of major, minor, and patch versions/releases, but we class some theoretically-breaking changes as minor, because of their limited impact.

[aowss]

thanks for your prompt and detailed version.
Should a link to normal version number be added to the spec to make that clearer ?

[MikeRalphson]

@aowss Probably because semver was officially dropped in v3.1, linking to parts of that spec again might be confusing. I think we'd totally welcome a PR to the spec. clarifying that the major, minor and patch numbers of the openapi field are all mandatory and that there is the optional pre-release information, as we do seem to have lost that specific guidance.

[handrews]

Since we are sorting out our release scale policies in the following issues, I'm going to close this discussion in favor of them:

• 3.x.y patch release approach #3528
• 3.x minor release approach #3529