Compose all component types, not just schemas

[k98kurz]

The current state of affairs is that responses can be defined as components and referenced with the "$ref":"{uri}" syntax, but these cannot be composed using the allOf directive. Trying to do so results in an error. Adding sibling properties also results in an error. So there is currently no way to define a response with a general schema and then add endpoint-specific models or examples. This seems like a gross oversight and major limitation.

For example, let's say that there are multiple endpoints that return lists of models following a standard response format, but each endpoint returns different models. It would be ideal to keep the reusable format of the response in a response component and compose it with the specific model under the path definition.

Without this functionality, the only options are to have invalid documents or abandon the use of response components.

[darrelmiller]

This was not an oversight. It is an intentional design choice based on years of conversations on how to resolve the semantics of merging one or more objects together. JSON Schema is able to support constructions of all of by categorizing members into either annotations, whose behavior is application defined, or validators that are independent constructs that return a boolean value which can be safely merged for an aggregate result.
OpenAPI concepts such as Response Objects are not so easily aggregated.
I have yet to see an example of a polymorphic response that could not be efficiently described with a single response object and a flexible schema.

[k98kurz]

... I have yet to see an example of a polymorphic response that could not be efficiently described with a single response object and a flexible schema.

@darrelmiller How? What am I missing?

[faelin]

@k98kurz – To facilitate communication, could you provide a counter-argument describing a response object that would be hard to describe using "a single response object and a flexible schema"?

(to be clear, I am not challenging the possibility of such an issue, but I wish to facilitate clear conversation)

[handrews]

@k98kurz you might be interested in the referencing proposals that are just getting started right now. The JRI proposal grapples with the problem of composing references (which it calls "keyword semantics") vs references that just replace the object containing $ref (which it calls "object semantics").

it is a difficult topic that poses challenges for generic tooling.