Map vs list in responses (and in general)

[arno-di-loreto]

Thinking aloud about responses being a map vs a list.

Unless I missed something, the reusable part of a response is what is inside the key.
That means :

• The response key is redefined each time a reusable response is used
• It may request users one info unnecessarily (what's the use of this information vs a summary or a description stored in the response? do all responses would benefit of it?)
• It may lead to inconsistency (different keys used for the same kind of response)
• But that also allows to locally state something (a kind of name/summary specific to the use of the response)
• Also (maybe?) when reading the file in a code editor, a map is more readable than a list, all sub-level can be closed leaving the keys visible. (but is that consideration to take into account?)

If responses is a list:

• There's one info less to provide
• If it's valuable in some use cases, it can be stored (or not) in a summary (or a name if really needed) inside the response object and then be overridden (or defined) by providing the adequate property near the ref.
• The responses property may be less readable in a code editor when all its elements are closed (no info visible)

In that case (list), I wonder if sets of responses couldn't be defined. When a $ref is used, it could be a reference to a single response or a set of responses (defined in components.responsesSets) (but that's another story).

This question is also a general concern: Are some guidelines defined to help choose one or another in OpenAPI v4 design?
For instance, having headers as a map in v3 led to some issues (losing header names in components.headers). The same goes for examples being a map, the extra key level was finally redundant with the info of the example.

Responses as a map:

paths:
  "/path":
        responses:
          ok:
            $ref: "#/components/responses/FooCreated"
  "/another/path":
        responses:
          created:
            $ref: "#/components/responses/FooCreated"
components:
  responses:
     FooCreated:
        status: 201
        contentType: application/json
        contentSchema:
          $ref: "#/components/schemas/foo"

Responses as a list

paths:
  "/path":
        responses:
            - $ref: "#/components/responses/FooCreated"
  "/another/path":
        responses:
            - $ref: "#/components/responses/FooCreated"
              summary: created
components:
  responses:
     FooCreated:
        status: 201
        summary: ok # (or a specific name property if absolutely needed)
        contentType: application/json
        contentSchema:
          $ref: "#/components/schemas/foo"

[ralfhandl]

One of the design goals is

• Reduce nested structures to improve readability and editability

so I'd prefer lists over maps.

@darrelmiller writes

I encourage people to explore complete API design languages that will optimize for the types of APIs being built but compile into an interoperable standard like OpenAPI

Compiling into Moonwalk is easier if the compiler doesn't have to invent map keys.

[kevinswiber]

Oops. Didn't see this one before submitting a recent proposal. @arno-di-loreto Should we merge these or do you want to keep this separate? My proposal suggests changing a lot more than just responses, so I'm not against keeping them separate. #32

[arno-di-loreto]

Same topic! The "responses" case is just one case among others. @kevinswiber, is there a way to move the messages from this discussion to the more generic one?

[kevinswiber]

I'm not really sure, as I don't have a lot of experience with Discussions. I'll defer to @darrelmiller as steward of the repo to advise.

[handrews]

I've consolidated this at #32 (comment) by copying this original post and the (non-logistical) reply into a comment thread, so let's close this discussion