Define formal media type (MIME type) for Swagger Object

[philipashlock]

A media type of application/swagger+json has been suggested on the mailing list before. I would recommend formally declaring this as part of the spec.

RAML defines its media type as application/raml+yaml

API Blueprint defines its base media type as application/vnd.apiblueprint.ast plus similar ones for other serializations

[philipashlock]

For what it's worth, the White House open data policy is currently documenting application/swagger+json for metadata provided by federal agencies: https://project-open-data.cio.gov/v1.1/api/

If this should be changed, please flag it is an issue on https://github.com/project-open-data/project-open-data.github.io/issues

[webron]

:+1:

[olensmar]

I'm all for it and would like to go so far and suggest different mime-types for different encodings and Swagger versions

application/swagger-v20+json application/swagger-v20+yaml application/swagger-v12+json application/swagger-v12+xml

(not really sure we need to add xml for 1.2 but it was in the spec as far as I can remember)

since Swagger 1.2 has separate files for resource listings and api declarations I suggest we make the api declaration implicit and have a separate mime-type for the resource listing

application/swagger-v12-resource-listing+json application/swagger-v12-resource-listing+xml

or alternatively we make both the api declaration and resource listing explicit;

application/swagger-v12-resource-listing+json application/swagger-v12-api-declaration+json application/swagger-v12-resource-listing+xml application/swagger-v12-api-declaration+xml

If we're aligned I can submit this to IANA... let me know your thoughts

/Ole

[dilipkrish]

@olensmar Not really sure we need to separate resource listing and api declaration. Its implicit by definition that if its application/swagger-v12+json we're going to get a document that conforms to the swagger12 spec. likewise for swagger2 also. Its no different that today where application/json covers both documents (files). In the case of swagger 1.2 the protocol to access the resource listing to get to the api declarations is a shared understanding described by the spec.

As an aside, related to https://github.com/swagger-api/swagger-ui/issues/708 would you be able to assist/ hand-hold so I could also register

application/swagger-v20+hal+json

I'm starting to experiment with a few ideas with swagger and hypermedia support. The thinking is that if we could combine HAL with swagger it would give a rich interactive experience. An on-demand swagger-ui if you will, similar to hal browser. I have very rough ideas that I hope to formalize soon. Initially trying to prototype it in spring using springfox.

[olensmar]

@dilipkrish thanks! I'd love to talk about hypermedia support in swagger, it's getting asked for in every talk I've done on swagger over the last weeks. I personally think that using the extension mechanism is a good starting point; if we can agree on a set of extensions that add hypermedia-related constructs to a Swagger definition those can be used by related tools without having to change the spec itself - and if they gain a lot of traction we could discuss putting it in the next major revision of the spec.

Regarding the mime-type - I still think there are use-cases where it might be good to be able to differ between resource listings and api declarations - but those might be very application-specific so we can leave them out for now. In that case I suggest we just go with:

application/swagger-v20+json application/swagger-v20+yaml application/swagger-v12+json application/swagger-v12+xml

what about also having

application/swagger+json application/swagger+yaml

as aliases for the latest version of the spec? (2.0) Or is that some kind of anti-pattern that I'm not aware of?

/Ole

[lovelydinosaur]

Is there any formal progress on a "application/swagger+json" media type? I'm working on generic client tooling right now, and the lack of a media type for swagger is a minor point of awkwardness there (eg can interact with other schema and hypermedia types without having to explicitly specify what type of media they should be interpreted as, but not so with swagger)

[fehguy]

I think this is a very good idea to add in the next spec version

[cabbonizio]

+1

[jharmn]

+1

[lovelydinosaur]

Is this worth the OpenAPI.Next Proposal tag, to ensure it gets consideration?

[webron]

Done.

[cdivilly]

The lack of a registered Media Type for Open API resources is a hindrance so it would be great to get this resolved.

Whatever Media Type name is chosen, it should be registered in the IANA Media Types Registry.

Versioning information should not appear in the Media Type, the version information is present in the resource representation. The vast majority of Media Types in the IANA registry do not transport any version information. You don't want to have to go through the Media Type registration process each time a new version is minted.

Note that the IANA Media Types registry is partitioned into namespaces, it won't be possible to register application/swagger+json, or application/~anything~+json, as they fall in the Standards Tree namespace, which requires a corresponding IETF (or other recognized standards body) specification.

Registration in the Vendor Tree should be fine, so I would recommend:

application/vnd.open-api+json for the JSON representation, and application/vnd.open-api+yaml for the YAML representation.

Note that RFC 6839 Section 3.1 formalizes the +json suffix convention. There is no registered Media Type for YAML, and therefore no formalization of the +yaml suffix convention, both these issues may be an obstacle to registration of a Media Type for the YAML representation.

[jharmn]

@darrelmiller I see RFC, IANA and vnd a lot here...chances are you have thoughts.

[darrelmiller]

@jasonh-n-austin Just pinged someone to find out the right place to get some of the uncertainties ironed out. In theory I don't think we have to be on the vnd tree and I believe recent specs have formalized the suffix issue, but I want to confirm before making a submission.

[lovelydinosaur]

@darrelmiller :+1: Good stuff.

[darrelmiller]

Asked the questions to the people who hold the keys to the registry https://mailarchive.ietf.org/arch/msg/media-types/_ijxSwBDdS6MF-sECqhxN1jkXzs

[fehguy]

Thanks @darrelmiller. Did you manage to find "the form"?

[darrelmiller]

I know where the submission form is :-). I was hoping I could get a registration in the standards tree without having to submit a spec document to IETF. However, I don't believe the Linux Foundation is considered a "Standards Development Organization" so, our choices are either live with the "vnd" or submit an IETF compliant version of the spec to them when we release new versions. I did at least get confirmation that it could be "Informational" and therefore not require any IETF WG input/consensus.

[cdivilly]

@darrelmiller Happy to help with drafting the informational RFC if needed, have done some draft RFCs before. The other message I took from that email thread was the case for approving the RFCs for application/openapi+json & application/openapi+yaml would be made stronger by going ahead and using those media types, did I interpret that correctly? Is there agreement within OpenAPI that those are the exact media types that should be registered?

[ralfhandl]

+1 for registering these as the "latest version" media types. +1 for also registering version-specific media types as proposed by @olensmar application/openapi-v20+json or application/openapi-v3_0+json (no dots allowed in standards-tree subtypes)

[ralfhandl]

+1 for submitting OpenAPI as an IETF RFC as we want to base the JSON dialect of OData's Metadata Format on OpenAPI, so the OpenAPI specification would be a normative reference.

[darrelmiller]

@cdivilly Thanks for the offer to help. Regarding the deploy first register later, the challenge is if we do something informally, the worst thing that could happen is people start using different approaches. e.g. with/without version number. I'm currently just trying to gather information and get the opinions out in the open, so that when we do make a registration, all the opinions have been heard.

@ralfhandl Can you make your case for including the version? I would prefer not to include the version and just encourage people who are writing OpenAPI parsers to handle the differences internally. Yes, having OpenAPI as an RFC would definitely make it easier to reference from other RFCs. It would be interesting to investigate what it would take to automate the creation of a mirror spec. The spec is already in markdown, so perhaps it could just be inserted into a kramdown-rfc2629 template.

[ralfhandl]

@darrelmiller Assuming that OpenAPI 3.0 isn't the end of the road we'll need a mechanism for version negotiation. This could be a separate set of headers, or it could be rolled into the media type, i.e. be part of the content negotiation:

Accept: application/openapi-v3_1+json, application/openapi-v3_0+json;q=0.2

or with separate headers

Accept: application/openapi+json
OpenAPI-MinVersion: 3.0
OpenAPI-MaxVersion: 3.1

Making it part of the media type is two request headers less, and in addition I can give a weight to the acceptable versions.

My assumption (and use case :-)) is that the OpenAPI document is not a static resource but an integral part of my service/API, in case of OData it will be the /$metadata resource.

[akuckartz]

@ralfhandl That is not best practice. HTML for example uses text/html since ages without a version number.

[darrelmiller]

@akuckartz I'd prefer if we don't try and resolve this by appealing to "best practices". The best solution to a particular problem is usually fairly context sensitive and there are too many varying opinions about what are the best practices.

However, the text/html media type is a good example of a media type that has gone through numerous versions and has kept the same media type identifier. I would prefer if OpenAPI tried to follow this model.

@ralfhandl Having version specific media types isn't the only way that we can deal with future versions of the OpenAPI spec. The previous specification had the foresight to include version identifiers within the document so a parser can fairly easily identify which specification version is applicable.

It is true that without a version specific media type intermediaries will need to parse the body, but I am struggling to think of scenarios where they would want to differentiate. Perhaps you are aware of some? I would think it is more likely that intermediaries would prefer not to have to be updated when a new OpenApi version is released and they can identify all versions of the spec as an "OpenAPI" document.

The one scenario that is more challenging with just a single media type for all versions, is when a client wishes a server would return it a down-revision instance of the specification. The question that comes to mind, is it really better to conneg for that, or should the OpenApi3 and OpenApi4 document simply be exposed as two different URLs? Considering spec documents are fairly static documents, being able to cache them is handy and the support for using vary to cache multiple variants based on media type is quite poor, I think having separate URLs might be wise.

Are there other scenarios I am not considering where version specific media types are useful?

[ePaul]

As an example, the TWINTIP API crawler currently expects just one API definition file referred from well-known URI (with its format – e.g. swagger-2.0 – specified in a type attribute). Though there is a feature request for allowing multiple ones, and then it might also be possible to mention different formats of the same specification there, so this is not really an argument for or against having different formats at the same or at different URIs.

[cdivilly]

@ralfhandl Embedding version information in the media type would require a new media-type registration on each spec revision. In theory the version information could be transported as a media type parameter (like the charset parameter for text media types), but I'm not sure how well that would be supported, it's not something I've seen in the wild (I know I've written code that would fail to handle a parameterized media type in an Accept header correctly). So I wouldn't encourage this approach.

Instead of the client trying to negotiate a representation, how about if the server tells the client about alternative representations. I think this is something that is probably needed anyways, for example to point to the Open API YAML representation from the JSON representation and vice versa. Something like the links element from JSON Hyper Schema, e.g.:

swagger: "4.0"
links: 
  - 
    href: /open-api/3.0/myapi.yaml
    mediaType: application/openapi+yaml
    rel: alternate
    spec-version: "3.0"
  - 
    href: /open-api/4.0/myapi.json
    mediaType: application/openapi+json
    rel: alternate
    spec-version: "4.0"  
info:
  title: My API
...

• A way to discriminate between Open API representation versions is needed for the hyperlinks, I'm not sure of the best way to represent this (again it could be a media type parameter), as a strawman I've minted a new attribute: spec-version to represent this value.

With this approach it is always apparent what older spec versions a server supports, versus the negotiation approach, which requires the client constructing a more complicated request to find out if the server supports the representation it requires.

[ralfhandl]

@darrelmiller My goal is using OpenAPI as an alternative standard format for OData Metadata Documents, hence my desire for an IETF RFC for the OpenAPI Specification.

The metadata document of an OData service defines and describes the data structures and resource paths of that service, which OpenAPI also does, so this seems to be a good fit.

The metadata document is part of the service and resides at <service-root>/$metadata. It may be a static resource, but typically it is dynamically derived from the underlying API, and it is supposed to support content negotiation and language negotiation via the Accept and Accept-Language headers.

OData defines protocol-version negotiation, so a client can specify a range of acceptable OData versions, and we could tie the OpenAPI version to the OData version. But given that OData and OpenAPI are independent standards and will probably evolve at different speeds this feels undesirable.

@cdivilly I very much like the idea of having a links section pointing to alternate representations of the OpenAPI document. This would also be the natural place for a rel: latest-version that would allow an API advertising its successor.

[darrelmiller]

@ralfhandl That's quite a challenging goal you have set for yourself there. I would have thought it easier to just link to an OpenAPI document from the OData metadata rather than trying to replace the entire thing. But that's another matter and I don't want to derail this thread.

I am reluctant to support versioning the Open API media types just because OData chose to try and standardize a resource identifier ($metadata) despite the guidance against doing that. This is the same situation that @ePaul mentions about the use of a .well-known identifier to point to OpenAPI descriptions.

However, it is important to realize that well-known URIs were formalized to resolve only a small subset of situations where all other options were not possible.

well-known URIs are not intended for general information retrieval or establishment of large URI namespaces on the Web. Rather, they are designed to facilitate discovery of information on a site when it isn't practical to use other mechanisms; for example, when discovering policy that needs to be evaluated before a resource is accessed, or when using multiple round-trips is judged detrimental to performance From https://tools.ietf.org/html/rfc5785

There are much better ways for API consumers to discover description documents. For example using http://apisjson.org/

The parameterization of the version in the media type @cdivilly is certainly a way to avoid the re-registration problem, but like him I haven't seen very much use of this in the wild. We should consider it and perhaps it is something that someone on the IETF mailing list might weigh in on. Maybe if we made version parameter optional to allow those who want to explicitly set it do so and those who don't can just ignore it.

[DavidBiesack]

@cdivilly Please use type, not mediaType, as per RFC 4287 3.1.1.1 The "type" Attribute.