"The Responses Object MUST contain at least one response code"

[karenetheridge]

https://spec.openapis.org/oas/v3.1.0#responses-object

[karenetheridge]

Unfortunately JSON Schema doesn't have a "contains"-like operation for objects, which would let us say "there must be at least one property matching '^[1-5](?:[0-9]{2}|XX)$'" (i.e. not 'default'). But this is still better than nothing.

edit: I thought of a way of checking this! added as a second commit.

[hkosova]

Wait, is the "MUST contain at least one response code" requirement meant to not count default? I've always interpreted the spec to mean that default is sort of also a "response code" (the catch-all code), just like OAS considers 2XX a response code despite the string 2XX itself not being an actual HTTP status code. 😕

Perhaps the spec itself could also use a clarification.

[karenetheridge]

Good question! I always interpreted it as "must contain at least one, other than default" but I can see how it could be interpreted the other way too.

I wonder if there is much of a desire to declare a responses object with just default under it? It's too bad we don't have a way of searching what everyone is currently doing.

[hkosova]

Some examples of default-only responses from the openapi-directory:

https://github.com/APIs-guru/openapi-directory/blob/main/APIs/worldtimeapi.org/20210108/openapi.yaml#L60-L70
https://github.com/APIs-guru/openapi-directory/blob/main/APIs/reverb.com/3.0/openapi.yaml#L61
https://github.com/APIs-guru/openapi-directory/blob/main/APIs/adobe.com/aem/3.5.0-pre.0/openapi.yaml#L42-L44

Search query (might include false positives)

[karenetheridge]

It might be good to discuss this at the next community meeting -- how do people interpret this section of the spec? is interpreting it one way obviously superior to the other option?

[darrelmiller]

In my opinion, having a single default response is valid. default can be used to describe successful responses and having a successful response is not a MUST. My understanding was the constraint was there just so that docs generators could at least show something relating to the response.

It could be argued that this constraint is moot now that the responses property in Operation Object is not required. Forcing the Responses Object to contain something is not actually guaranteeing anything.