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

Define formal media type (MIME type) for Swagger Object #110

Open
philipashlock opened this Issue Sep 15, 2014 · 61 comments

Comments

Projects
None yet
@philipashlock
Copy link

philipashlock commented Sep 15, 2014

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

This comment has been minimized.

Copy link

philipashlock commented Jan 29, 2015

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

This comment has been minimized.

Copy link
Member

webron commented Jan 29, 2015

👍

@olensmar

This comment has been minimized.

Copy link

olensmar commented Apr 30, 2015

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

This comment has been minimized.

Copy link
Contributor

dilipkrish commented Apr 30, 2015

@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 swagger-api/swagger-ui#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

This comment has been minimized.

Copy link

olensmar commented Apr 30, 2015

@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

@tomchristie

This comment has been minimized.

Copy link

tomchristie commented Jan 24, 2016

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

This comment has been minimized.

Copy link
Contributor

fehguy commented Jan 24, 2016

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

@cabbonizio

This comment has been minimized.

Copy link

cabbonizio commented Jan 24, 2016

+1

1 similar comment
@jharmn

This comment has been minimized.

Copy link
Contributor

jharmn commented Feb 5, 2016

+1

@tomchristie

This comment has been minimized.

Copy link

tomchristie commented Feb 8, 2016

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

@webron

This comment has been minimized.

Copy link
Member

webron commented Feb 8, 2016

Done.

@cdivilly

This comment has been minimized.

Copy link

cdivilly commented Feb 16, 2016

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

This comment has been minimized.

Copy link
Contributor

jharmn commented Feb 16, 2016

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

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 16, 2016

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

@tomchristie

This comment has been minimized.

Copy link

tomchristie commented Feb 18, 2016

@darrelmiller 👍 Good stuff.

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Mar 8, 2016

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

@fehguy

This comment has been minimized.

Copy link
Contributor

fehguy commented Mar 9, 2016

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

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Mar 10, 2016

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

This comment has been minimized.

Copy link

cdivilly commented Mar 11, 2016

@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

This comment has been minimized.

Copy link
Contributor

ralfhandl commented Mar 18, 2016

+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

This comment has been minimized.

Copy link
Contributor

ralfhandl commented Mar 18, 2016

+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

This comment has been minimized.

Copy link
Member

darrelmiller commented Mar 18, 2016

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

@fehguy

This comment has been minimized.

Copy link
Contributor

fehguy commented Feb 14, 2017

Hey @dilipkrish I'm not @darrelmiller but I believe he can't register it until we release the spec. So it'll happen when released.

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 14, 2017

Technically, we could register it based on the V2 spec. This is simply procrastination on my part.

@dilipkrish

This comment has been minimized.

Copy link
Contributor

dilipkrish commented Feb 14, 2017

No hurry... prompted by requests to support rendering the spec in yaml and I'd rather use the media type as a negotiating instrument than something in the url or a file extension like we usually do.

@BigBlueHat

This comment has been minimized.

Copy link

BigBlueHat commented Jul 7, 2017

/me pokes 👉 👉 👉 @darrelmiller

Stop procrastinating, friend. I need this, k?! 😁

❤️,
🎩

@jameswatts

This comment has been minimized.

Copy link
Contributor

jameswatts commented Aug 8, 2017

@webron @darrelmiller @fehguy just checking in on this, with the 3.0 spec now released, is there any update on the IANA registration and the formal definition of the type?

My understanding from this comment was that application/openapi+json;version=#.# would be the proposed type to use, is that still the case?

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Aug 8, 2017

Yes, that's still the case. I still haven't done the registration. I still need to do it.

@DavidBiesack

This comment has been minimized.

Copy link
Contributor

DavidBiesack commented Oct 6, 2017

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 9, 2018

So, in light of recent developments, I am bringing this issue back to life. There are ongoing discussions in the OpenAPI Initiative about possibly increasing the scope of the OAI and it may arise that other specifications will fall under the OAI umbrella.

I would like to propose an alternate media type identifier that would remove some of the road blocks that were previously preventing this registration from happening and also accommodate the possibility of identifying other related specifications in a consistent manner.

I suggest that we register:

application/vnd.oai.openapi

with an optional version parameter. By moving our registration to the vendor subtree, the process becomes as simple as filling a web form with some fields. To be in the standards tree we would need to go through IETF expert review and have a stable copy of the the specification registered with a recognized standards organization.

This identifier makes the naming process easier for future specs managed by the OAI.

Finally, I am proposing that we drop the +json suffix. We will not be able to have a properly registered +yaml suffix because yaml is not an IANA registered media type. I would prefer to have the simpler identifier than only support just one.

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 9, 2018

Following TSC conversation, here is our latest proposal,

application/vnd.oai.openapi (YAML variant)
application/vnd.oai.openapi+json (JSON only variant) 

Optional version parameter:

 application/vnd.oai.openapi;version=2.0
@usarid

This comment has been minimized.

Copy link
Contributor

usarid commented Feb 12, 2018

Hmm, I'm not understanding how application/vnd.oai.openapi makes it easier to have other specs under the OAI umbrella. It seems, if anything, it would make it harder, as it would attach "OpenAPI" to one specific spec.

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 12, 2018

@usarid Well assuming it was decided to adopt asyncapi as is, then we could registerapplication/vnd.oai.asyncapi

If we decided to adopt a variant of apis.json as a discovery document then it could become application/vnd.oai.apisjson

My perspective is that OpenAPI already is associated to one spec. OAI is the organization that could manage other specs.

@usarid

This comment has been minimized.

Copy link
Contributor

usarid commented Feb 12, 2018

I don’t think people will understand the subtlety that “OpenAPI” is just one of the specs managed by the OAI (OpenAPI Initiative). But maybe we should first progress the scope discussion and then get back to this.

@tomchristie

This comment has been minimized.

Copy link

tomchristie commented Feb 15, 2018

Heya. Good work on progressing this.

Just to clarify on "Finally, I am proposing that we drop the +json suffix." is that a typo that meant to say "Finally, I am proposing that we drop the +yaml suffix." (Which the later comment suggests?)

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 15, 2018

@tomchristie My initial plan was to drop both, with the argument that if I can't support one, then let's not confuse the issue by only supporting +JSON. But on the TSC call @MikeRalphson suggested letting the one without the suffix be YAML by default. Which is extra convenient because JSON is actually valid YAML also. Which leaves us in the awesome position of tools that support YAML or JSON get the clean suffixless version and JSON only tools need the +json. It's like having your cake and eating it too.

@tomchristie

This comment has been minimized.

Copy link

tomchristie commented Feb 15, 2018

Great thanks @darrelmiller - that makes sense. 😄

@pratikpparikh

This comment has been minimized.

Copy link

pratikpparikh commented Feb 22, 2018

@darrelmiller is this the final with an optional variant of version? Sorry, the above thread does not clearly tell me what is the final. what is the whole conversation around asyncapi?

application/vnd.oai.openapi (YAML variant)
application/vnd.oai.openapi+json (JSON only variant)

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 23, 2018

@pratikpparikh No final decision has been made. The two options you mention were my latest suggestion. https://www.asyncapi.com is another specification that is very similar to OAS but for message based protocols. There is conversations going on about possibly bringing that specification under the OAI organization.

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Feb 23, 2018

@usarid I think that regardless of how we end up incorporating AsyncAPI features into the OAI, whether it is with a distinct spec or just extensions to the existing specification, I still think there is value in calling out the fact that OpenAPI is part of the OAI. It fits nicely into the vendor extension model and leaves the possibility of extensions in the future even if we don't use it.

Personally, I think I have dragged this issue out long enough and would really like to see some closure here. If eventually we decide to propose OpenAPI as a full on IETF standard we can always register a new standards track media type at a later date.

@darrelmiller

This comment has been minimized.

Copy link
Member

darrelmiller commented Jul 2, 2018

@OAI/tsc APPROVED 🎉

@DavidBiesack

This comment has been minimized.

Copy link
Contributor

DavidBiesack commented Aug 16, 2018

Please publish the final approved media types on https://github.com/OAI/OpenAPI-Specification (no need to update the published specification documents, but in the future I would like to see it in the spec itself).

Also, please clarify if we should use ;version=3.0 for 3.0.*, as implied by https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#versions

@lashchev

This comment has been minimized.

Copy link

lashchev commented Sep 12, 2018

@darrelmiller When should we expect these media types to appear in the registry at https://www.iana.org/assignments/media-types/media-types.xhtml?

@DavidBiesack

This comment has been minimized.

Copy link
Contributor

DavidBiesack commented Sep 25, 2018

Please consider resolving/closing #110 for OAS 3.0.2, with clarification on exactly what the TSC approved, and what ;version= values/mapping are allowed

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