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:

1
paths:
2
  /employees:
3
    get:
4
      summary: Returns a list of employees.
5
      responses:
6
        "200": # Response
7
          description: OK
8
          content: # Response body
9
            application/json: # Media type
10
              schema: # Must-have
11
                type: object # Data type
12
                properties:
13
                  id:
14
                    type: integer
15
                  name:
16
                    type: string
17
                  fullTime:
18
                    type: boolean
19
                example: # Sample data
20
                  id: 1
21
                  name: Jessica Right
22
                  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) –

1
application/json
2
application/xml
3
application/x-www-form-urlencoded
4
multipart/form-data
5
text/plain; charset=utf-8
6
text/html
7
application/pdf
8
image/png

1
application/vnd.mycompany.myapp.v2+json
2
application/vnd.ms-excel
3
application/vnd.openstreetmap.data+xml
4
application/vnd.github-issue.text+json
5
application/vnd.github.v3.diff
6
image/vnd.djvu

Multiple Media Types

You may want to specify multiple media types:

1
paths:
2
  /employees:
3
    get:
4
      summary: Returns a list of employees.
5
      responses:
6
        "200": # Response
7
          description: OK
8
          content: # Response body
9
            application/json: # One of media types
10
              schema:
11
                type: object
12
                properties:
13
                  id:
14
                    type: integer
15
                  name:
16
                    type: string
17
                  fullTime:
18
                    type: boolean
19
            application/xml: # Another media types
20
              schema:
21
                type: object
22
                properties:
23
                  id:
24
                    type: integer
25
                  name:
26
                    type: string
27
                  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:

1
paths:
2
  /employees:
3
    get:
4
      responses:
5
        "200": # Response
6
          description: OK
7
          content: # Response body
8
            application/json: # Media type
9
              schema:
10
                $ref: "#/components/schemas/Employee" # Reference to object definition
11
            application/xml: # Media type
12
              schema:
13
                $ref: "#/components/schemas/Employee" # Reference to object definition
14
components:
15
  schemas:
16
    Employee: # Object definition
17
      type: object
18
      properties:
19
        id:
20
          type: integer
21
        name:
22
          type: string
23
        fullTime:
24
          type: boolean

To define the same format for multiple media types, you can also use placeholders like */*, application/*, image/* or others:

1
paths:
2
  /info/logo:
3
    get:
4
      responses:
5
        "200": # Response
6
          description: OK
7
          content: # Response body
8
            image/*: # Media type
9
              schema:
10
                type: string
11
                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.