> For the complete documentation index, see [llms.txt](https://eazyapi-1.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eazyapi-1.gitbook.io/docs/open-api-guide/component-section.md).

# Component Section

Often, multiple API operations have some common parameters or return the same response structure. To avoid code duplication, you can place the common definitions in the global `components` section and reference them using [$ref](/docs/open-api-guide/using-usdref.md). In the example below, duplicate definitions of a User object are replaced with a single component and references to that component. Before:

{% code lineNumbers="true" %}

```yaml
paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string
```

{% endcode %}

After:

{% code lineNumbers="true" %}

```yaml
paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
```

{% endcode %}

### Components Structure <a href="#structure" id="structure"></a>

`components` serve as a container for various reusable definitions – schemas (data models), parameters, responses, examples, and others. The definitions in `components` have no direct effect on the API unless you explicitly reference them from somewhere outside the `components`. That is, `components` are not parameters and responses that apply to all operations; they are just pieces of information to be referenced elsewhere. Under `components`, the definitions are grouped by type – `schemas`, `parameters` and so on. The following example lists the available subsections. All subsections are optional.

{% code lineNumbers="true" %}

```yaml
components:
  # Reusable schemas (data models)
  schemas:
    ...
  # Reusable path, query, header and cookie parameters
  parameters:
    ...
  # Security scheme definitions (see Authentication)
  securitySchemes:
    ...
  # Reusable request bodies
  requestBodies:
    ...
  # Reusable responses, such as 401 Unauthorized or 400 Bad Request
  responses:
    ...
  # Reusable response headers
  headers:
    ...
  # Reusable examples
  examples:
    ...
  # Reusable links
  links:
    ...
  # Reusable callbacks
  callbacks:
    ...
```

{% endcode %}

Each subsection contains one or more named components (definitions):

{% code lineNumbers="true" %}

```yaml
components:
  schemas:
    User:
      type: object
      ...
    Pet:
      type: object
      ...
```

{% endcode %}

The component names can consist of the following characters only:

{% code lineNumbers="true" %}

```yaml
A..Z a..z 0..9 . _ -
```

{% endcode %}

Examples of valid names:

{% code lineNumbers="true" %}

```yaml
User
New_User
org.example.User
401-Unauthorized
```

{% endcode %}

The component names are used to reference the components via `$ref` from other parts of the API specification:

{% code lineNumbers="true" %}

```yaml
$ref: '#/components/<type>/<name>'
```

{% endcode %}

For example:

{% code lineNumbers="true" %}

```yaml
$ref: '#/components/schemas/User'
```

{% endcode %}

An exception are definitions in `securitySchemes` which are referenced directly by name (see [Authentication](/docs/open-api-guide/authentication.md)).

### Components Example <a href="#components" id="components"></a>

Below is an example of `components` that contains reusable data schemas, parameters and responses. Other component types (links, examples, and others) are defined similarly.

{% code lineNumbers="true" %}

```yaml
components:
  #-------------------------------
  # Reusable schemas (data models)
  #-------------------------------
  schemas:
    User:             # Can be referenced as '#/components/schemas/User'
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Error:            # Can be referenced as '#/components/schemas/Error'
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  #-------------------------------
  # Reusable operation parameters
  #-------------------------------
  parameters:
    offsetParam:      # Can be referenced via '#/components/parameters/offsetParam'
      name: offset
      in: query
      description: Number of items to skip before returning the results.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 0
        default: 0
    limitParam:       # Can be referenced as '#/components/parameters/limitParam'
      name: limit
      in: query
      description: Maximum number of items to return.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
  #-------------------------------
  # Reusable responses
  #-------------------------------
  responses:
    404NotFound:       # Can be referenced as '#/components/responses/404NotFound'
      description: The specified resource was not found.
    ImageResponse:     # Can be referenced as '#/components/responses/ImageResponse'
      description: An image.
      content:
        image/*:
          schema:
            type: string
            format: binary
    GenericError:      # Can be referenced as '#/components/responses/GenericError'
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
```

{% endcode %}

### Externally Defined Components <a href="#external" id="external"></a>

Individual definitions in `components` can be specified either inline (as in the previous example) or using a `$ref` reference to an external definition:

{% code lineNumbers="true" %}

```yaml
components:
  schemas:
    Pet:
      $ref: '../models/pet.yaml'
      # Can now use use '#/components/schemas/Pet' instead
    User:
      $ref: 'https://api.example.com/v2/openapi.yaml#/components/schemas/User'
      # Can now use '#/components/schemas/User' instead
  responses:
    GenericError:
      $ref: '../template-api.yaml#/components/responses/GenericError'
      # Can now use '#/components/responses/GenericError' instead
```

{% endcode %}

### Differences From OpenAPI 2.0 <a href="#difference" id="difference"></a>

OpenAPI 2.0 had separate sections for reusable components – `definitions`, `parameters`, `responses` and `securityDefinitions`. In OpenAPI 3.0, they all were moved inside `components`. Also, `definitions` were renamed to `schemas` and `securityDefinitions` were renamed to `securitySchemes` (note the different spelling: `schem`*`A`*`s` vs `securitySchem`*`E`*`s`). The references are changed accordingly to reflect the new structure:

{% code lineNumbers="true" %}

```yaml
OpenAPI 2.0                    OpenAPI 3.0
'#/definitions/User'         → '#/components/schemas/User'
'#/parameters/offsetParam'   → '#/components/parameters/offsetParam'
'#/responses/ErrorResponse'  → '#/components/responses/ErrorResponse'
```

{% endcode %}

### References

[Components Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#componentsObject)