OAI / OAI/OpenAPI-Specification
The Response object's `default` field is confusing and inconsistently interpreted
Nobody has claimed this yet.
- Dominant language
- Markdown
- Stars
- 31.2k
- Forks
- 9.2k
- Avg merge
- 6h 37m
- Merged PRs (30d)
- 27
Description
According both 3.0 and 3.1, in theResponse object there MUST be at least one response code and it SHOULD be the response for a successful operation call. In addition the default describes “responses other than the ones declared for specific HTTP response codes”.
This means that if we had a 200 response and default, the latter would cover everything except for 200. Many seem to interpret default to mean something like response categories not covered by explicit response codes. Consider this example from the OAI org:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
default:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore-expanded.yaml
This implies that default covers error types when in fact it covers non-error responses as well. In fact, the consumer wouldn't necessarily know if the API might reply with another success code such as a 204. A more precise example might look like this:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
4xx:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
5xx:
description: unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
I would suggest the following actions:
- Update the example to interpret the spec more literally
- Clarify
defaultsince this confusion is not limited to this example, but extends to APIs in the wild - Consider in 3.2 or 4.0 eliminating
default - Consider in 3.2 or 4.0 adding a new named
errorcategory that means "both 4xx and 5xx". This could be used in the way thatdefaultis often misused today
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing examples/v3.0/petstore-expanded.yaml and the Response object definitions for OpenAPI 3.0 and 3.1. Compare the documented meaning of default with the example's intended error handling, then identify which clarification or example update is feasible; completion would require an agreed change to the specification or examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100