Allow using deprecated: true to tag Response Objects

[DavidBiesack]

The Response Object in OAS 3.2 does not allow the response objects to be marked as deprecated: true.
Please update OAS so that these objects can be marked as deprecated: true.
As with other objects that can be deprecated, if the deprecated field is omitted, the default will be false.

[handrews]

The Security Scheme Object does have a deprecated field in 3.2.

What is the use case for the Response Object? The various deprecated fields are interpreted by clients as "you can do this, but you shouldn't and it might disappear." Responses come from the server, so the server can simply stop using the response, in which case why would it still be documented?

To put it another way, who would be expected to take action if a Response Object has deprecated: true, and what would that action be?

[DavidBiesack]

Thanks, @handrews -- I must have missed that for Security Scheme in 3.2!

Regarding Response Objects: As with any element that is deprecated, additional documentation will instruct consumers what the replacement is and perhaps when (what release or version) the value would no longer be used. For example, perhaps v1 of an API incorrectly used a 422 when it should use a 409, and v2 aims to corrects that for consistency with the rest of the API's operations, rather than let it exist as an inconsistency indefinitely. The accompanying description normally provides details or conditions which cause the service to return 422, and API evolution or external standards may require shifting to another response code; i.e. 409 may be a more "correct" response that matched the true meaning of the problem. Another situation may be changing a 200 response on a DELETE in v1 to return 204 in v2 instead. deprecation informs the consumer of the pending change.

[DavidBiesack]

I've updated the title and description accordingly.

[cuttingclyde]

I would agree with both @handrews question and @DavidBiesack response in the case of an API host publishing an OpenAPI spec for their own APIs. And that is that both:

• As the API host I can stop returning any response so I could omit communicating such an obsolete response in my schemas,
• Yet I might also choose to publish advance notice of my schema changes that said response will be removed in a future implementation, and describe the new or existing response that will be sent instead.

However, our specific use case is that of the publisher of OpenAPI Specs from the banking industry standards body Financial Data Exchange (https://financialdataexchange.org/). In that context, the consumers of our OAS files are primarily the hosts of Open Banking APIs who use our spec to design and build specific versions of the standard APIs which they will then publish and communicate to their partners who will consume those APIs. Being able to publish the standard with deprecated: elements such as responses lets us communicate such subtle changes to both API hosts and consumers in advance of a host electing to implement or convert to a specific minor version. This essentially lets us as the standards body guide future implementations in the manner of the second bullet above.

So to answer @handrews question, current and future API hosts would be expected to take action, and that action is to decide whether they will keep using a deprecated response and align with an earlier minor version of the standard, or migrate to a later minor / major version and stop sending the deprecated response.