Payload specification extensions

[jroper]

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 specifying type: file. Why should a file payload be specified using the type: file property, while a protobuf be specified using an x-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 no protocol property is present, with the provision that if type: file is present, then it's file for backwards compatibility reasons, but this should be considered the legacy approach, with protocol: 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.

[jroper]

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 x-protobuf protocols, and when the tooling saw x-protobuf, let's say this was a code generator, it would invoke the protobuf extension which would generate the protobuf models. Otherwise, tooling would have to provide an extension point that would pass the schema object to many different protocol handlers, and ask them "do you know how to handle this?"

[fehguy]

@jroper good ideas on this. Linking to parent issue #586

[ePaul]

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.

[darrelmiller]

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.

[ePaul]

@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 application/json and lots of application/*+json media types, and maybe XML, i.e. all application/xml and application/*+xml media types).

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. text/csv, how would that be mapped from a OpenAPI schema?

[handrews]

This issue is now outdated as type: file was removed back in OAS 3.0. application/*+json media types can already be modeled by JSON Schema. The +json means "you can safely treat this as plain JSON, it just has extra meaning on top of that", so there's no need for us to say so ourselves.

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.