Spec versioning scheme is not clear

[micovery]

Looking at the history of:

https://github.com/swagger-api/swagger-spec/commits/master/schemas/v2.0/schema.json

As the schema for the spec itself changes, should not the version number change as well?

It's been "2.0" for a while. This is leads to a lot of confusion where multiple products say they support "Swagger 2.0" ... but they are really talking about different specs 😕 !

Take for example this issue:

#452

What used to be valid "Swagger 2.0" ... is not anymore.

If I am third party product, and I want to claim that I am "Swagger 2.0" compliant, what should I be looking at as the source of truth for what "Swagger 2.0" is?

[webron]

The source of truth is the spec itself - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md - and not the schema. The schema is a tool, just like swagger-ui snd so on. The "version" of it is going to stay 2.0 as that's the version of the spec. That said, we have been meaning to include a revision property too in the schema to show internal document versions but haven't gotten around to it. We'll take extra care in the next version of the spec with that regards. So Swagger 2.0 is Swagger 2.0, there are no 'different specs'.

[micovery]

Thanks for clarifying that I should be looking at the MD file as being "the spec".

In that case, should not the "Revision History" section be updated when there are spec changes.

What kind of spec changes warrant a new version being introduced?

Any thoughts on using semantic versioning for the spec itself?

[webron]

The spec updates with clarifications, typo fixes and such, but not with structural changes. 2.0 is the first version of the spec that was written alongside the creation of the spec itself, so the process itself was fairly new. Even though the 1.2 spec exists, it was actually reverse engineered and was written quite some time after the 1.2 version was released.

We're definitely looking to improve the process in future versions (read: minor/major versions, not document updates) and the feedback is welcome. We're considering semver for the spec, although I'm not sure how well it would suit the spec itself.

[fehguy]

See #561