Skip to content

v3.1.2: Clarify how to describe no response content #4611

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: v3.1-dev
Choose a base branch
from
Open

v3.1.2: Clarify how to describe no response content #4611

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eb642cb
Clarify no-content responses.
handrews May 18, 2025
eb100ec
Make the clarification more clear
handrews May 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2079,7 +2079,7 @@ headers:
type: integer
```

Response with no return value:
A response with no return value can be specified by omitting the `content` field, although this technically does not enforce a lack of content, it merely indicates that none is documented:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"no return value" is not very clear (some might say a response's "return value" is its HTTP response code) -- we should say "with no message body", or perhaps "zero length response body".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@karenetheridge good catch- let me think on how to frame this more clearly.


```json
{
Expand All @@ -2091,6 +2091,29 @@ Response with no return value:
description: object created
```

To signal a definitive lack of content, require that the `Content-Length` header, if present, is `0` (note the HTTP specification does not always require `Content-Length`, so this usage is more to set expectations than to guarantee the header's use):

```json
{
"description": "object created",
"headers": {
"Content-Length": {
"schema": {
"const": 0
}
}
}
}
```

```yaml
description: object created
headers:
Content-Length:
schema:
const: 0
```

#### Callback Object

A map of possible out-of band callbacks related to the parent operation.
Expand Down