New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove swagger: 2.0 from spec #561

Closed
fehguy opened this Issue Feb 10, 2016 · 15 comments

Comments

Projects
None yet
7 participants
@fehguy
Contributor

fehguy commented Feb 10, 2016

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

This comment has been minimized.

Show comment
Hide comment
@fehguy

fehguy Feb 10, 2016

Contributor

parent issue: #560

Contributor

fehguy commented Feb 10, 2016

parent issue: #560

@dolmen

This comment has been minimized.

Show comment
Hide comment
@dolmen

dolmen Feb 29, 2016

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

dolmen commented Feb 29, 2016

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

@jpstrikesback

This comment has been minimized.

Show comment
Hide comment
@jpstrikesback

jpstrikesback commented Feb 29, 2016

Agree @dolmen

@ePaul

This comment has been minimized.

Show comment
Hide comment
@ePaul

ePaul Feb 29, 2016

Contributor

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

Contributor

ePaul commented Feb 29, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@webron

webron Feb 29, 2016

Member

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

Member

webron commented Feb 29, 2016

$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

This comment has been minimized.

Show comment
Hide comment
@jpstrikesback

jpstrikesback Feb 29, 2016

@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"
}

jpstrikesback commented Feb 29, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@webron

webron Feb 29, 2016

Member

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.

Member

webron commented Feb 29, 2016

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

This comment has been minimized.

Show comment
Hide comment
@jpstrikesback

jpstrikesback Mar 1, 2016

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

jpstrikesback commented Mar 1, 2016

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

@dolmen

This comment has been minimized.

Show comment
Hide comment
@dolmen

dolmen Mar 1, 2016

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.

dolmen commented Mar 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@webron

webron Mar 1, 2016

Member

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

Member

webron commented Mar 1, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@fehguy

fehguy Mar 14, 2016

Contributor

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
Contributor

fehguy commented Mar 14, 2016

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

This comment has been minimized.

Show comment
Hide comment
@IvanGoncharov

IvanGoncharov Mar 14, 2016

Contributor

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

Contributor

IvanGoncharov commented Mar 14, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@fehguy

fehguy Mar 14, 2016

Contributor

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.

Contributor

fehguy commented Mar 14, 2016

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

This comment has been minimized.

Show comment
Hide comment
@whitlockjc

whitlockjc Mar 14, 2016

Member

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.

Member

whitlockjc commented Mar 14, 2016

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

This comment has been minimized.

Show comment
Hide comment
@IvanGoncharov

IvanGoncharov Mar 14, 2016

Contributor

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

Contributor

IvanGoncharov commented Mar 14, 2016

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

fehguy added a commit that referenced this issue Apr 8, 2016

@fehguy fehguy closed this Apr 14, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment