-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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
Payload specification extensions #709
Comments
I also should add, this would make it much easier for tooling to offer extension points - the tooling can simply offer a map of protocol names to handlers for that protocol. So, a protobuf extension would just have to register itself as the handler for |
I'm not sure if "protocol" is the best name, as this might be misunderstood to refer to the URI scheme part (i.e. HTTP vs. HTTPS vs. whatever else is coming). I don't have a better name proposal, though. |
I'm not sure how the term "protocol" that is being used here is different than media-type/content-type. Doesn't the produces/consumes attributes already define what "formats" the payloads will be using. |
@darrelmiller Basically you are right, the payload format is an important part of the media type. But the media type definition by itself doesn't really tell us how the OpenAPI schema definition is mapped to that payload format (apart from JSON, which belongs to Also, we can have several media types for each format. E.g. in one of my recent APIs I have application/problem+json (for the error responses) as well as application/x.zalando.wholesale.warehouse-list+json (which is a custom media type, effectively defined by its OpenAPI schema definition) for the 200 response. If we want that all "application/*+json" media types are represented using the standard JSON representation of the schemas, then we should do so explicitly in the specification. And if we have e.g. |
This issue is now outdated as Given how old this is an how it's based on an outdated practice, I'm going to close it- if there's something here to consider based on the current state of things (3.1), please open a new issue for it. |
This is a sub issue of #586.
There are a number of proposals for extensions to the payload, sometimes the extension involves JSON, sometimes it's a completely different format. There should be a clear and consistent way for new protocols/payload formats to be defined, whether they end up being specification extensions, or end up being part of the OpenAPI spec.
For example, let's say I wanted to create a protobuf specification extension. A recommendation by one member of the OpenAPI specification was that I define a specification extension for the schema object, eg
x-protobuf
, and put my info in that, which works, however, that's inconsistent with for example the way that arbitrary files are currently distinguished - a file is specified by specifyingtype: file
. Why should afile
payload be specified using thetype: file
property, while a protobuf be specified using anx-protobuf: ...
property?My thoughts are that something should be added to the root of
schema
to indicate the protocol being used, for example,protocol: json
,protocol: file
,protocol: x-protobuf
.protocol: json
could be assumed if noprotocol
property is present, with the provision that iftype: file
is present, then it's file for backwards compatibility reasons, but this should be considered the legacy approach, withprotocol: file
being preferred.By having an explicit protocol property, rather than inferring the protocol based on what extension properties may or may not be present, this also ensures that extensions can't interfere with each other - for example if an extension to the json protocol sees
protocol: something-thats-not-json
, it knows to back off and not try to parse or participate at all in the handling of this schema.The text was updated successfully, but these errors were encountered: