Media Types
Media type is a format of a request or response body data. Web service operations can accept and return data in different formats, the most common being JSON, XML and images. You specify the media type in request and response definitions. Here is an example of a response definition:
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # Media type10 schema: # Must-have11 type: object # Data type12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 example: # Sample data20 id: 121 name: Jessica Right22 fullTime: true
Under responses
we have definitions of individual responses. As you can see, each response is defined by its code ('200'
in our example.). The keyword content
below the code corresponds to the response body. One or multiple media types go as child keywords of this content
keyword. Each media type includes a schema
, defining the data type of the message body, and, optionally, one or several examples. For more information on defining body data, see Defining Request Body and Defining Responses.
Media Type Names
The media types listed below the content
field should be compliant with RFC 6838. For example, you can use standard types or vendor-specific types (indicated by .vnd
) –
1application/json2application/xml3application/x-www-form-urlencoded4multipart/form-data5text/plain; charset=utf-86text/html7application/pdf8image/png
1application/vnd.mycompany.myapp.v2+json2application/vnd.ms-excel3application/vnd.openstreetmap.data+xml4application/vnd.github-issue.text+json5application/vnd.github.v3.diff6image/vnd.djvu
Multiple Media Types
You may want to specify multiple media types:
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # One of media types10 schema:11 type: object12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 application/xml: # Another media types20 schema:21 type: object22 properties:23 id:24 type: integer25 name:26 type: string27 fullTime:28 type: boolean
To use the same data format for several media types, define a custom object in the components
section of your spec and then refer to this object in each media type:
1paths:2 /employees:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 application/json: # Media type9 schema:10 $ref: "#/components/schemas/Employee" # Reference to object definition11 application/xml: # Media type12 schema:13 $ref: "#/components/schemas/Employee" # Reference to object definition14components:15 schemas:16 Employee: # Object definition17 type: object18 properties:19 id:20 type: integer21 name:22 type: string23 fullTime:24 type: boolean
To define the same format for multiple media types, you can also use placeholders like */*
, application/*
, image/*
or others:
1paths:2 /info/logo:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 image/*: # Media type9 schema:10 type: string11 format: binary
The value you use as media type – image/*
in our example – is very similar to what you can see in the Accept
or Content-Type
headers of HTTP requests and responses. Do not confuse the placeholder and the actual value of the Accept
or Content-Type
headers. For example, the image/*
placeholder for a response body means that the server will use the same data structure for all the responses that match the placeholder. It does not mean that the string image/* will be specified in the Content-Type
header. The Content-Type
header most likely will have image/png, image/jpeg, or some other similar value.
_Did not find what you were looking for? Ask the community Found a mistake? Let us know_OAS 3 This page is about OpenAPI 3.0. If you use OpenAPI 2.0, see the OpenAPI 2.0 guide.
Media Types
Media type is a format of a request or response body data. Web service operations can accept and return data in different formats, the most common being JSON, XML and images. You specify the media type in request and response definitions. Here is an example of a response definition:
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # Media type10 schema: # Must-have11 type: object # Data type12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 example: # Sample data20 id: 121 name: Jessica Right22 fullTime: true
Under responses
we have definitions of individual responses. As you can see, each response is defined by its code ('200'
in our example.). The keyword content
below the code corresponds to the response body. One or multiple media types go as child keywords of this content
keyword. Each media type includes a schema
, defining the data type of the message body, and, optionally, one or several examples. For more information on defining body data, see Defining Request Body and Defining Responses.
Media Type Names
The media types listed below the content
field should be compliant with RFC 6838. For example, you can use standard types or vendor-specific types (indicated by .vnd
) –
1application/json2application/xml3application/x-www-form-urlencoded4multipart/form-data5text/plain; charset=utf-86text/html7application/pdf8image/png
1application/vnd.mycompany.myapp.v2+json2application/vnd.ms-excel3application/vnd.openstreetmap.data+xml4application/vnd.github-issue.text+json5application/vnd.github.v3.diff6image/vnd.djvu
Multiple Media Types
You may want to specify multiple media types:
1paths:2 /employees:3 get:4 summary: Returns a list of employees.5 responses:6 "200": # Response7 description: OK8 content: # Response body9 application/json: # One of media types10 schema:11 type: object12 properties:13 id:14 type: integer15 name:16 type: string17 fullTime:18 type: boolean19 application/xml: # Another media types20 schema:21 type: object22 properties:23 id:24 type: integer25 name:26 type: string27 fullTime:28 type: boolean
To use the same data format for several media types, define a custom object in the components
section of your spec and then refer to this object in each media type:
1paths:2 /employees:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 application/json: # Media type9 schema:10 $ref: "#/components/schemas/Employee" # Reference to object definition11 application/xml: # Media type12 schema:13 $ref: "#/components/schemas/Employee" # Reference to object definition14components:15 schemas:16 Employee: # Object definition17 type: object18 properties:19 id:20 type: integer21 name:22 type: string23 fullTime:24 type: boolean
To define the same format for multiple media types, you can also use placeholders like */*
, application/*
, image/*
or others:
1paths:2 /info/logo:3 get:4 responses:5 "200": # Response6 description: OK7 content: # Response body8 image/*: # Media type9 schema:10 type: string11 format: binary
The value you use as media type – image/*
in our example – is very similar to what you can see in the Accept
or Content-Type
headers of HTTP requests and responses. Do not confuse the placeholder and the actual value of the Accept
or Content-Type
headers. For example, the image/*
placeholder for a response body means that the server will use the same data structure for all the responses that match the placeholder. It does not mean that the string image/* will be specified in the Content-Type
header. The Content-Type
header most likely will have image/png, image/jpeg, or some other similar value.
Did not find what you were looking for? Ask the community Found a mistake? Let us know