Request/response correlation

[garyee]

Hello,

first off, thanks for the work you are doing.
This is maybe more of a question than an issue.
Why can't I specify different types of responses for different kinds/values of a parameter?
I am working with the swagger editor and there it is kind of self-evident. See swagger-api/swagger-editor#2046

[MikeRalphson]

Thank you for the kind words.

The simple answer to why you can't do it is that the OAS provides no mechanism currently to describe such correlation.

The longer answer is a) this has come up before, I just need to find and link the existing issues - #1998 and b) no-one has yet as far as I know suggested an elegant syntax for such correlations.

My idle suggestion would be for us to think about extending the discriminator object to include a runtime expression (as per the callback object) which would allow discriminating a oneOf schema keyword based on more than just a simple property in the same response. @OAI/tsc thoughts?

[darrelmiller]

You can correlate request examples and response examples for the benefit of documentation. However, correlating request/response patterns for a single resource is an anti-pattern that introduces out of band client server coupling.

Part of the reason that folks ask for this feature is because they use query parameters to differentiate between resources and we don't allow operations to be distinguished by query parameters. This is the problem we need to fix. That would allow creating different operations and then the request/response would be correlated based on the URL, including the query parameters.

In summary, the solution is not to correlate request/response within an operation, but to allow the full URL to define the operation.

[handrews]

@MikeRalphson please not discriminator, it's a huge mess for JSON Schema and it would be much easier if we found an alternate solution for that problem (both inside and outside of JSON Schema). The concept is fine but the implementation, like nullable, disregards otherwise consistent aspects of JSON Schema's processing model. We talked about deprecating nullable in 3.1 and (I guess?) dropping it in 4.0 in favor of the type array, and I am very much hoping for a similar approach to discriminator (although probably more like deprecation in 3.2, as we'll have more of an idea about how a code gen vocabulary might look then).

[handrews]

This general concept is being addressed in the Moonwalk (OAS 4) project. Specifically, the concept of operation signatures ought to cover this. So I am marking this "moved to moonwalk" and closing it out of this repository.