Define formal media type (MIME type) for Swagger Object #110
Comments
Adding Uber as a sample
|
For what it's worth, the White House open data policy is currently documenting If this should be changed, please flag it is an issue on https://github.com/project-open-data/project-open-data.github.io/issues |
|
👍 |
|
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 (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 or alternatively we make both the api declaration and resource listing explicit; application/swagger-v12-resource-listing+json If we're aligned I can submit this to IANA... let me know your thoughts /Ole |
|
@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 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. |
|
@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 what about also having application/swagger+json 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 |
|
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) |
|
I think this is a very good idea to add in the next spec version |
|
+1 |
1 similar comment
|
+1 |
|
Is this worth the |
|
Done. |
|
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 Registration in the Vendor Tree should be fine, so I would recommend:
Note that RFC 6839 Section 3.1 formalizes the |
|
@darrelmiller I see |
|
@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. |
|
@darrelmiller 👍 Good stuff. |
|
Asked the questions to the people who hold the keys to the registry https://mailarchive.ietf.org/arch/msg/media-types/_ijxSwBDdS6MF-sECqhxN1jkXzs |
|
Thanks @darrelmiller. Did you manage to find "the form"? |
|
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. |
|
@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 |
|
+1 for registering these as the "latest version" media types. |
|
+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. |
|
@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. |
|
@DavidBiesack OK so your version of "profile" is separate from the media type parameter JSON Schema adds the At this point idk what JSON Schema will do in the next draft (the one that will align with OAS 3.1 final) but I'm hoping that the people who keep disagreeing with each other will work it out because it's frustrating to be criticized for every possible decision by different people who are each trying to advocate for or discourage the use of their own projects. I tried to get around it by coming up with our own thing, but people don't like that either, so I've more or less given up on the topic.
No, it's been effectively a running joke for years that it will never get a proper media type, and it's annoying AF. This is part of why OpenAPI declared their own media type, with an optional
@Relequestual @awwright @philsturgeon here's something to consider for the next JSON Schema draft I guess. |
|
hello all.
On 2020-08-28 18:11, Henry Andrews wrote:
JSON Schema adds the |application/schema-instance| media type
specifically so we could use a |profile=| or |schema=| media type
parameter legally (and use JSON Pointers for fragments legally). Several
drafts ago we were using |profile=| but @dret objected
<json-schema-org/json-schema-spec#222 (comment)>
so we switched to |schema=|, although @dret <https://github.com/dret>
seems to have since given up trying to enforce that
<json-schema-org/json-schema-spec#833 (comment)>.
i cannot "enforce" everything. i simply have tried to explain to people
that a profile is not what they think it is when they are referring to
the RFC *and* actually talk about applying schemas to data models.
but yes, i have given up on this one. and i don't "own" the concept of a
profile, i simply had something specific in mind when i wrote the RFC
and that was different from what some people apparently want it to be.
such is life. time to move on. keep up the good fight, henry!
…--
erik wilde | mailto:erik.wilde@dret.net |
| http://dret.net/netdret |
| http://twitter.com/dret |
|
|
@dret I'm sorry that this keeps coming up, I think it's more that we're looking for consensus from the broader community, and I saw you disagree that a schema can be a profile, but I don't understand why. I would like to understand why, though. I'm not sure about OpenAPI, but at least as far as JSON Schema defines it, a schema seems like a kind of profile:
✅ JSON Schema adds constraints to documents, and allows additional information to be read out of a JSON document; but it does not alter the JSON semantics.
✅ e.g. an intermediate HTTP node (that does not understand profiles or JSON Schema) could add or remove whitespace without affecting a JSON Schema aware processor.
✅ Multiple JSON Schema documents may be applied, forming a logical intersection
✅ JSON Schemas are identified by URI
✅ JSON Schemas are not (necessarily) available over the network, and most applications expected to work without ever dereferencing a profile URI (unlike a DTD).
✅ JSON Schema does permit this, but downloadable representations are retrieved by following the "describedBy" link relation.
✅ We suggest doing this for the benefit of human debugging If any of this doesn't seem correct, I'm very curious to hear your take, @dret. @larsgsvensson wrote:
I think this is the only issue here, if you mean something that can be downloaded, then another link relation would be appropriate. |
|
On 2020-08-30 02:11, Austin Wright wrote:
I'm not sure about OpenAPI, but at least as far as JSON Schema defines
it, a schema seems like a kind of profile:
a bit of history: RFC 6906 is based on "profile" as used in the HTML
spec (it's deprecated by now, so linking to good old HTML4):
https://www.w3.org/TR/html40/struct/global.html#profiles
you can simply use this concept to understand what RFC 6906 is defining.
HTML is not a profile of SGML/XML. but you can use profiles to indicate
that your HTML is based on a certain way of using HTML. you can still
understand HTML as HTML even when you're not knowing the profile.
or to give a more real-life example:
- a letter is something written on paper. a letter is a way of using
paper and it's defining a new layer of meaning. a letter *isn't* paper,
it's *a way of using paper*.
- a "profile of paper" would be something like square paper: it's still
just paper, but with an additional constraint.
- a "profile of a letter" would be an invitation letter: it's still just
a letter, but one with additional constraints.
that's really all i can say. if you think that *a letter is paper*, then
in my mind you're mixing categories, but you're of course free to do it.
…--
erik wilde | mailto:erik.wilde@dret.net |
| http://dret.net/netdret |
| http://twitter.com/dret |
|
|
@dret I don't understand how @awwright would be arguing that *a letter is paper*. He provided a very clear breakdown of how he thinks JSON Schema meets each condition in the specification. Could you please let us know which of his points is incorrect? From my perspective, square paper is a subset of paper. Given a schema language for paper dimensions it could be expressed as something like A JSON Schema similarly defines the subset of JSON documents that are acceptable. The schema identifier may (as in "people probably do" not as in RFC 2119 "MAY") in practice be overloaded to indicate further semantics (e.g. this is a "letter"), but that is not part of the JSON Schema specification, and other link relation types are more appropriate for that. In an API, I would not use a schema to indicate that a document is a letter (or a car, or a planet, or anything else). Because the schema describes the representation syntax, not the semantic usage. The semantic usage should be stable across the lifetime of the API. Some uses may or may not be implemented at different times, but they are still semantically valid. However, the syntax is expected to fluctuate across time. Ideally it wouldn't but we all know that's not how it works. So I read your explanation and @awwright's detailed examination of the requirements and cannot see a contradiction. Could you please point it out in plain terms, using @awwright's example? |
|
On 2020-08-31 20:37, Henry Andrews wrote:
Could you please let us know which of his points is incorrect? From my
perspective, square paper is a subset of paper. Given a schema language
for paper dimensions it could be expressed as something like |"xyRatio":
"1:1"|. There are endless possible sizes and ratios of paper, but this
constrains the set to those where the X and Y dimensions are the same.
yes, you can implement a profile using a schema language. but we're not
arguing over implementations here but over what the two terms mean (the
concept of a profile and the concept of a schema).
all i can say is that in my experience in a variety of fields, people
use these terms for different concepts. a schema establishes a new
interpretation; a profile augments an interpretation. think along the
lines of HTML (a schema) and the good old STRICT and LOOSE profiles of
it (two ways to constrain the HTML schema).
clearly you want to use these terms in a different way, and that's your
right. i happen to think that this is not very helpful, but that's just
me having a different opinion.
but we're getting into a wittgenstein loop here. if you want to use the
term "profile" the way you want to use it, then this is what it means
for you. i cannot point you to a definition that categorically disallows
your use. all i can do is say that this is not how i use it, how i see
it being used, and that this is not what was intended in the RFC.
…--
erik wilde | mailto:erik.wilde@dret.net |
| http://dret.net/netdret |
| http://twitter.com/dret |
|
Besides the fact HTML is a separate media type, is there any reason this should be the case? An XML processor can read an It seems the issue is XML semantics are so generic, there's not much else you can do with it. But suppose I know the XML document is HTML, then there's more I can do with it. And suppose I know the HTML document is hCard, or RDFa. Then there's even more I can do with it. Being able to express this seems to be the primary benefit of profiles.
So you consider a DTD to be a kind of profile? Isn't a DTD a kind of schema? |
@dret, i'm pretty distressed by this accusation. Several years ago, we stopped using In the intervening years, other things have happened with "profile", and you yourself have indicated some sort of shift in views (as noted and linked to above). @awwright raised the idea that maybe given how things have changed, we should check in and align with the overall community meaning of "profile", whatever that happens to be now. All we want is to be aligned with the common accepted usage. We don't want to be a weird outlier to an established pattern. We don't want to be that one project abusing an otherwise well-defined term, and we don't want to be that one project that re-invented the wheel (e.g. by replacing "profile" with "schema" for both media type parameters and link relation types, if it turns out that "profile" is the industry-wide consensus. Which we are not assuming). I am bothered that you are ascribing ill will to us here.
That's not what we asked, and we're not trying to argue with you. We're trying to understand, but instead of giving a clear answer in terms of the concrete example, you criticize us and give oblique arguments that don't clearly relate to what we need to understand. @awwright and I are both trying our best to figure this out and we cannot. There is a simple question on the table. You should be able to tell us which of those seven points is wrong. Or if it's not outright wrong (is that what you mean by "yes you can implement a schema..."?), then clearly something is at least bothering you about at least one of those seven points. Which point is it, and what is the problem? Don't point to other media types or create new examples. There's a seven-point attempt to meet your own definition. Where did we go wrong? |
|
On 2020-09-01 22:14, Austin Wright wrote:
think along the lines of HTML (a schema) and the good old STRICT and
LOOSE profiles of it (two ways to constrain the HTML schema).
So you consider a DTD to be a kind of profile? Isn't a DTD a kind of schema?
we're definitely going in circles by now.
a DTD is tech. schemas and profiles are concepts. most people probably
would put DTD in the schema bucket, but as i said, you can implement
profiles in many ways, including a DTD.
if that helps you: HTML is a model that can be (and in fact has been,
look at HTML and XHTML) based on different foundations. for somebody
just interested in HTML semantics, that actually doesn't matter, it's
HTML semantics in both cases. because all you do is operate at the
semantic level of HTML.
profiles do not establish this new level. they constrain the existing
level. i still need to understand HTML in order to understand a profile
of HTML. i do not need to understand SGML in order to understand HTML.
really, i have no idea how to explain this any better. and it doesn't
seem to me like we're making any progress here.
…--
erik wilde | mailto:erik.wilde@dret.net |
| http://dret.net/netdret |
| http://twitter.com/dret |
|
|
On 2020-09-01 23:35, Henry Andrews wrote:
All we /*want*/ is to be aligned with the common accepted usage. We
don't want to be a weird outlier to an established pattern. We don't
want to be that one project abusing an otherwise well-defined term,
/*and*/ we don't want to be that one project that re-invented the wheel
(e.g. by replacing "profile" with "schema" for both media type
parameters and link relation types, if it turns out that "profile" is
the industry-wide consensus. Which we are not assuming).
i am not the arbiter of what *common accepted usage* is, and it probably
very much differs depending on the community. if you talk to people with
a more XMLish background you will find rather different ideas than you
would find in a sample with a more RDFish slant.
all i can do is tell you what *my* view of the matter is, and i think
that really hasn't changed much over the years. but to say it one last
time: i have no control over how people use terminology or specs, and i
have no special say in this either. concepts are fuzzy, people have
opinions and preferences, and you may have to simply accept that.
|
|
Why can't you just answer the question? |
|
@dret this is maddening. Just tell us 1, 2, 3, 4, 5, 6, 7 which point(s) are wrong? |
|
Ok, I gather that it's entirely possible to use a JSON Schema to define profiles of an Before we get too far off topic, I think the question becomes, can we use profiles to distinguish version? If a profile is required to correctly interpret an OpenAPI media type, we don't gain anything over just using |
Why do you think we don't? I'm not asking you for a certificate of compliance to wave at other people. I'm just asking, in your own personal opinion, which of the seven points is incorrect? You have indicated that you do not agree with our interpretation, therefore one of those steps must be a problem in your own opinion, which we promise not to use to bludgeon anyone else or whatever it is you think we're doing. I am begging you to tell us which one. |
|
Is this effectively resolved by https://datatracker.ietf.org/doc/html/draft-polli-rest-api-mediatypes? |
|
Not solved yet, but we started working on https://datatracker.ietf.org/doc/draft-ietf-httpapi-rest-api-mediatypes/ |
|
Is this dead? |
|
On 2023-09-20 09:06, Michal Landsman wrote:
Is this dead?
hopefully not!
|
|
Dear all, the work on this is ongoing. Yet, laying down something meaningful is not easy as it seems. People interested in contributing to this issue can spend some time reading and providing feedback here https://github.com/ietf-wg-httpapi/mediatypes/labels/rest-api Have a nice day, |
and others
A media type of
application/swagger+jsonhas 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+yamlAPI Blueprint defines its base media type as
application/vnd.apiblueprint.astplus similar ones for other serializationsThe text was updated successfully, but these errors were encountered: