# Parameters in OpenAPI
Source: https://speakeasy.com/openapi/requests/parameters

import { Table } from "@/mdx/components";



Parameters are used to describe inputs to an operation. Parameters can be defined at the path or operation level and are merged with any duplicates at the operation level, overriding any defined at the path level.

Each parameter needs to be uniquely identified by a combination of its `name` and `in` fields in an [operation](/openapi/paths/operations).

A parameter in the list can either be a [Parameter Object](/openapi/paths/parameters#parameter-object) or a [Reference](/openapi/references) to a [Parameter Object](/openapi/paths/parameters#parameter-object) defined in the [Components Object](/openapi/components) under the `parameters` field.

Parameters can represent a number of different input types, including:

- Path Parameters
- Query Parameters
- Headers
- Cookies

Example:

```yaml
paths:
  /drinks/{type}:
    parameters:
      - name: type
        in: path
        description: The type of drink to filter by.
        required: true
        schema:
          $ref: "#/components/schemas/DrinkType"
      - name: Cache-Control
        in: header
        description: The cache control header.
        required: false
        schema:
          type: string
          enum:
            - no-cache
            - no-store
            - must-revalidate
            - max-age=0
            - max-age=3600
            - max-age=86400
            - max-age=604800
            - max-age=2592000
            - max-age=31536000
    get:
      operationId: listDrinks
      summary: Get a list of drinks.
      description: Get a list of drinks, if authenticated this will include stock levels and product codes otherwise it will only include public information.
      security:
        - {}
      tags:
        - drinks
      parameters:
        - name: limit
          in: query
          description: The maximum number of drinks to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: filter
          in: query
          description: Advanced filter criteria as a JSON object.
          required: false
          content:
            application/json:
              schema:
                type: object
                properties:
                  productCode:
                    type: string
                  inStock:
                    type: boolean
      responses:
        "200":
          description: A list of drinks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
```

## Parameter Object

<Table
  title="Parameter Object Fields"
  data={[
    {
      field: "`name`",
      type: "String",
      required: "✅",
      description: "The **case sensitive** name of the parameter. This **_must_** be unique when combined with the `in` field.\nIf the `in` field is `path`, then this field **_must_** be referenced in the owning path."
    },
    {
      field: "`in`",
      type: "String",
      required: "✅",
      description: "The type or location of the parameter. The available types are:\n- `path` - A templated parameter defined within the path.\n- `query` - A query parameter passed via the URL.\n- `header` - A header parameter passed via HTTP headers.\n- `cookie` - A cookie parameter passed via HTTP cookies."
    },
    {
      field: "`description`",
      type: "String",
      required: "",
      description: "A description of the parameter. This may contain [CommonMark syntax](https://spec.commonmark.org/) to provide a rich description."
    },
    {
      field: "`required`",
      type: "Boolean",
      required: "",
      description: "Whether the parameter is required. If the `in` field is `path`, then this field is **always** required and **_must_** be `true`. Defaults to `false`."
    },
    {
      field: "`deprecated`",
      type: "Boolean",
      required: "",
      description: "Whether the parameter is deprecated. Defaults to `false`."
    },
    {
      field: "`style`",
      type: "String",
      required: "",
      description: "Describes how the parameter value will be serialized depending on the `in` field. The available styles are `matrix`, `label`, `form`, `simple`, `spaceDelimited`, `pipeDelimited`, and `deepObject`.\n\nThe default style depends on the `in` field:\n- `path` - `simple`\n- `query` - `form`\n- `header` - `simple`\n- `cookie` - `form`\n\nSee the [path](https://www.speakeasy.com/openapi/paths/parameters/path-parameters), [header](https://www.speakeasy.com/openapi/paths/parameters/header-parameters), [query](https://www.speakeasy.com/openapi/paths/parameters/query-parameters), and [cookie](https://www.speakeasy.com/openapi/paths/parameters/cookie-parameters) parameter sections for more details."
    },
    {
      field: "`explode`",
      type: "Boolean",
      required: "",
      description: "Whether the parameter value will be exploded, based on the parameter type. Defaults to `true` when `style` is `form`, otherwise `false`.\n\nSee the [path](https://www.speakeasy.com/openapi/paths/parameters/path-parameters), [header](https://www.speakeasy.com/openapi/paths/parameters/header-parameters), [query](https://www.speakeasy.com/openapi/paths/parameters/query-parameters), and [cookie](https://www.speakeasy.com/openapi/paths/parameters/cookie-parameters) parameter sections for more details."
    },
    {
      field: "`schema`",
      type: "[Schema Object](/openapi/schemas)",
      required: "",
      description: "A schema or reference to a schema that defines the type of the parameter. This is **_required_** unless `content` is defined.\n\n**Note: OpenAPI 3.0.x supports [OpenAPI Reference Objects](/openapi/references#openapi-reference-object) here as the value. OpenAPI 3.1.x uses the [JSON Schema Referencing](/openapi/schemas#json-schema--openapi) format.**"
    },
    {
      field: "`content`",
      type: "[Content](/openapi/paths/operations/content)",
      required: "",
      description: "A map of [Media Type Objects](/openapi/paths/operations/content#media-type-object) that defines the possible media types that can be used for the parameter. This is **_required_** unless `schema` is defined."
    },
    {
      field: "`allowEmptyValue`",
      type: "Boolean",
      required: "",
      description: "Whether the parameter value can be empty. Only used if `in` is `query`. Defaults to `false`."
    },
    {
      field: "`allowReserved`",
      type: "Boolean",
      required: "",
      description: "Whether the parameter value can contain reserved characters as defined by [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986). Only used if `in` is `query`. Defaults to `false`."
    },
    {
      field: "`example`",
      type: "Any",
      required: "",
      description: "An example of the parameter's value. This is ignored if the `examples` field is defined."
    },
    {
      field: "`examples`",
      type: "[Examples](/openapi/examples)",
      required: "",
      description: "A map of [Example Objects](/openapi/examples) and/or [OpenAPI Reference Objects](/openapi/references#openapi-reference-object) that define the possible examples of the parameter's value."
    },
    {
      field: "`x-*`",
      type: "[Extensions](/openapi/extensions)",
      required: "",
      description: "Any number of extension fields can be added to the parameter object that can be used by tooling and vendors."
    }
  ]}
  columns={[
    {
      key: "field",
      header: "Field"
    },
    {
      key: "type",
      header: "Type"
    },
    {
      key: "required",
      header: "Required"
    },
    {
      key: "description",
      header: "Description"
    }
  ]}
/>

The order of fields above is recommended for defining fields in the document.

## Parameter Serialization

OpenAPI provides two mutually exclusive ways to describe how parameter values are serialized: using `schema` with `style` and `explode`, or using `content`. You must use one or the other, but not both.

### Schema with Style and Explode (Recommended for Most Cases)

The `schema` approach is the standard way to define parameters and is suitable for most scenarios. It works well for primitive values, arrays, and simple objects that can be serialized into a string.

With this approach, serialization is controlled by:
- **`style`**: Defines the serialization format (e.g., `form`, `simple`, `matrix`, `label`)
- **`explode`**: Controls whether arrays and objects are expanded into separate parameters

Example of array serialization using `schema`:

```yaml
parameters:
  - name: colors
    in: query
    schema:
      type: array
      items:
        type: string
    style: form
    explode: false
```

This serializes as: `?colors=blue,black,brown`

For detailed serialization rules for each parameter type, see the [path](/openapi/requests/parameters/path-parameters), [header](/openapi/requests/parameters/header-parameters), [query](/openapi/requests/parameters/query-parameters), and [cookie](/openapi/requests/parameters/cookie-parameters) parameter documentation.

### Content (For Complex Serialization)

The `content` approach is designed for complex serialization scenarios that cannot be handled by `style` and `explode`. This is particularly useful when you need to send structured data using a specific media type serialization, such as JSON.

Use `content` when you need to:
- Send complex nested objects that require JSON serialization
- Use a specific media type format for the parameter value
- Handle serialization that goes beyond what `style` and `explode` support

Example of JSON-serialized object in a query parameter:

```yaml
parameters:
  - name: filter
    in: query
    description: Filter criteria as a JSON object
    required: false
    content:
      application/json:
        schema:
          type: object
          properties:
            type:
              type: string
              example: t-shirt
            color:
              type: string
              example: blue
            priceRange:
              type: object
              properties:
                min:
                  type: number
                max:
                  type: number
```

This parameter would be sent as a JSON string in the URL:

```
?filter={"type":"t-shirt","color":"blue","priceRange":{"min":10,"max":50}}
```

The `content` field maps media types to schemas, allowing you to specify exactly how the parameter should be serialized and deserialized. While `application/json` is common for complex query parameters, you can use any media type that makes sense for your API.

**Important**: You cannot use `style` and `explode` when using `content`. Choose the approach that best fits your serialization needs.