A Content Object is an OpenAPI structure that maps media types to descriptions of message content. It appears through the content property in request bodies and responses, making payload formats visible in documentation tools. Each media type can contain a schema describing the data more precisely. section 6.6.2 section 6.9
JSON request body
A product-creation operation can declare JSON input with a minimal Content Object: requestBody: description: Product info content: application/json: schema: {} The media type identifies JSON, while the schema marks where the product fields will be defined. section 6.6.2
Responses use the same pattern. A successful response and error responses may each declare application/json, with schemas carrying descriptions for product or error data. A response without a body, such as HTTP 204, omits content entirely; a response that can contain data, such as HTTP 404, retains it. section 6.8.1 section 6.8.2
Use the Content Object to make payload expectations explicit:
- Choose a media type such as application/json for JSON data. section 6.6.2
- Add a schema when the payload needs fine-grained data description. section 6.9
- Omit content when the response has no body. section 6.8.2
- List several media types when an operation accepts or returns alternatives. section 14.3.4
Listing 14.1 Sending a file in a request body
paths:
/files:
post:
requestBody:
content:
application/pdf: {} #1
image/png: {} #1
image/jpeg: {} #1
responses:
"201": #2
description: File uploaded
Compare a file-upload Content Object with a structured JSON payload: raw files use media types with empty objects, while schemas describe structured data. section 14.3.4
Listing 14.2 Returning a file or metadata
paths:
/files/{fileId}:
parameters: ...
get:
responses:
"200":
description: File content or metadata
content:
application/pdf: {} #1
image/png: {} #1
image/jpeg: {} #1
application/json: #2
schema:
type: object
...
Inspect how one response can offer PDF, PNG, JPEG, or JSON metadata through separate media-type entries. section 14.3.4
