Remove swagger: 2.0 from spec

[fehguy]

The current OpenAPI spec has "swagger": "2.0" in it. Since it's no longer called the swagger spec, this should go away.

I do believe we should continue to declare the version in the specification though, to make tooling more tolerant. Some points about that.

• One major issue with the Swagger 2.0 tooling was that it was looking for the "2.0" version in the spec itself. That meant, a "2.0.1" spec--even if structurally compatible--would not work. We should advise all tooling vendors as to versioning process and how they should detect versions inside the spec. Reference the concerns in Clarify release procedure for Swagger spec v 2.0 #107. In a couple cases we probably should have bumped the spec version in 2.0 to 2.0.1, etc. Let's not make that mistake again
• Declaring a semver approach for the spec makes sense. We don't need to go too far into the details in this ticket as to what constitutes a major, minor, patch version, but in general, if we put a version in the next spec version (which I advocate), it should be in the x.y.z format.
• Making it "2.0" as a string vs. number was dumb. The above point solves that.

[fehguy]

parent issue: #560

[dolmen]

Spec versionning could instead be specified using the existing feature of JSON Schema: the $schema property. See #496.

[jpstrikesback]

Agree @dolmen

[ePaul]

@dolmen If I understand correctly, JSON schema alone is not enough to completely validate an OpenAPI document (at least in version 2.0), thus some additional OpenAPI specific logic is necessary anyways.

(Of course that logic could be coded to recognize a specific hard-coded JSON schema URI instead of "swagger": "2.0".)

[webron]

$schema has nothing to do with it. $schema would refer to the version of the JSON Schema, not the specification. It's indeed a feature of JSON Schema. The OpenAPI spec is not JSON Schema. It uses it to describe input/output, it provides it as a limited form of validation, but it is not the same.

[jpstrikesback]

@webron, indeed that is the case within a JSON Schema. Perhaps simply pointing to it at /schema for tooling is fair game:

{
  "schema": {"$ref": "http://openapis.org/schema/v2.0/schema.json"}
}

About versions, I agree with the OP, and it needs to live somewhere, but living in a URI is a bit opaque. I would still like the ability to extend and validate by specifying a schema property, but perhaps depending on a path component for a version is unnecessarily terse.

{
  "schema": {"$ref": "http://openapis.org/schema/v2.0.0/schema.json"},
  "version": "x.y.z"
}

[webron]

All @fehguy was trying to say is is it should change from:
swagger: "2.0"
to something like
openapi: 3.0.0
(if we go with semver). Not really sure why this was taken to more complicated realms.

[jpstrikesback]

Apologies :) I am guilty of a bit of a co-opting/hope of omnibus above, after arriving here from #496

[dolmen]

In semver, the third part is about backwards-compatible bug fixes. A bug fix resolves a problem of implementation. But here, we are speaking about versioning of a specification, not the versioning of an implementation. Semver could be used in a version field of the JSON Schema for OpenAPI or in a version field of the documentation of the OpenAPI specification (the document itself is versioned and may evolve to add clarification of the specification, without changing the meaning) but not in the OpenAPI specification itself.
So I don't think that the 3-parts SemVer is applicable here.

@webron
My point about $schema is that an URI could be enough to tell a version. That's how HTML and XML specification versioning works. And that's also how JSON Schema versioning works with the $schema.

[webron]

@dolmen that's a separate issue. This ticket is about the version field of the spec which is currently represented by the swagger property (used to be swaggerVersion in older versions). This is about the spec, not the JSON Schema representing the spec. That's why the $schema is unrelated to this discussion.

As for whether we use semver or not, that's definitely part of the discussion here. Personally, I don't have a strong opinion here. In my experience we've made different types of changes to the document since it was officially released. I can bring some of those here so we can discuss what kind of version changes those would potentially require, if anything at all.

[fehguy]

Here is my proposal for addressing this.

Options:

• We can use the schema namespace instead of a OAI version
• We can use a oas attribute for the version

Pros:

• schema URL is more flexible.
• oas is more tooling friendly. Most tools cannot do much with a new version of the schema

Cons:

• schema url is very long. Useful for validation, not for interpretation
• oas as a numeric version has the same issue as swagger: "2.0"

Recommendation:

• use the oas specifier with semver semantics:

oas: 3.0.0-alpha

which will eventually be released as:

oas: 3.0.0

The multiple . will avoid the string/number issue from swagger: 2.0

• introduce an optional schema URL which can be used for validation. If absent, the tooling will choose the appropriate OAS schema.

• Tooling will be responsible for parsing with semver compatibilty:

  Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.
  • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format

example:

oas: 3.0.0
schema: https://openapis.org/schemas/v3.0.0.json

[IvanGoncharov]

@whitlockjc @fehguy How this will correlate with schema versioning?
For example, right now if some schema changes make old specs fail during validation.
And it's very important from tooling perspective to track such changes.

For example, some user creates his spec inside swagger-editor and it passed validation.
Then he open his spec in a few days and see it became invalid.

I propose to include all schema changes as PATCH changes.
Since they fix discrepancies between schema and specification itself.

In this case, tooling can notify users that spec was fixed and he need to fix his OAI spec.
Real life example would be MIME types in Swagger 2.0
Any string was treated as valid MIME than it was constrained by RegExp.
And after one more change, everything was reverted back to no constraints on MIME types.
That's all without changes in version so right know many tools using old schema.
So we in a situation when all tools with 2.0 support bisect by the fact whenever they support certain MIME types.

[fehguy]

No, these are quite different considerations.

1. The OAI has a version associated with what it encompasses
2. The OAI has a schema which is used by tooling to enforce the intent of item 1.
3. The tooling may or may not use a JSON schema for internal use

That said, using a schema to point to the OAI specification version doesn't make sense. That's because the source of truth is the document itself, not the JSON Schema. I do believe that we can and will become better about making changes (and therefore versioning) the JSON Schema but that is entirely differently.

Point being, the JSON schema is not the source of truth for the OAI spec. Recall too that it is up to the tooling to use a schema or not, so we cannot blame the specification for how the tooling uses it.

[whitlockjc]

I never thought about it like that @fehguy, I'm glad you brought that up. Tooling authors using JSON Schema is a choice, not a requirement. That definitely helps me look at some of these requests a little differently.

[IvanGoncharov]

@fehguy In that case, I suggest to change $schema: https://openapis.org/schemas/v3.0.0.json into $schema: https://openapis.org/version/v3.0.0/schemas/latest.json.
In this case latest is alias for the lastest version of schema corresponding to OAI v3.0.0.
But if you want to be precise you can set it to:
$schema: https://openapis.org/version/v3.0.0/schemas/v1.0.1.json
Which will point to v1.0.1 of the schema for OAI v3.0.0.

Aliasing isn't a problem since Git support symlinks.