# OpenAPI path parameters
Source: https://speakeasy.com/openapi/requests/parameters/path-parameters

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



Path parameters are serialized at runtime to the path of the URL, meaning they are generally serialized to a string representation and must adhere to the [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) specification. Reserved characters are percent-encoded (for example, `?` becomes `%3F`).

By default, path parameters are serialized using `style: simple` and `explode: false`, but several different serialization options are available:

- `style: simple` - Simple style serialization is the default serialization for path parameters, using commas (`,`) to separate multiple values. Defined by [RFC 6570](https://tools.ietf.org/html/rfc6570#section-3.2.7).
- `style: label` - Label-style serialization uses dots (`.`) to separate multiple values. Defined by [RFC 6570](https://tools.ietf.org/html/rfc6570#section-3.2.6).
- `style: matrix` - Matrix-style serialization uses semicolons (`;`) to separate multiple values. Defined by [RFC 6570](https://tools.ietf.org/html/rfc6570#section-3.2.5).

## Primitive types as path parameters in OpenAPI

Primitive types such as `string`, `number`, `integer`, and `boolean` are serialized as strings. The `style` and `explode` fields generally determine the prefix for the value.

For the examples below, we will use a path parameter named `type` with a value of `cocktail` for a path-templated URL of `/drinks/{type}`.

<Table
  title="Primitive Types Serialization"
  data={[
    {
      style: "`simple`",
      explodeTrue: "/drinks/cocktail",
      explodeFalse: "/drinks/cocktail"
    },
    {
      style: "`label`",
      explodeTrue: "/drinks/.cocktail",
      explodeFalse: "/drinks/.cocktail"
    },
    {
      style: "`matrix`",
      explodeTrue: "/drinks/;type=cocktail",
      explodeFalse: "/drinks/;type=cocktail"
    }
  ]}
  columns={[
    {
      key: "style",
      header: "Style"
    },
    {
      key: "explodeTrue",
      header: "Explode == `true`"
    },
    {
      key: "explodeFalse",
      header: "Explode == `false`"
    }
  ]}
/>

## Simple arrays as path parameters in OpenAPI

For simple arrays of primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `style` and `explode` fields.

For the examples below, we will use a path parameter named `types` with a value of `["gin", "vodka", "rum"]` for a path-templated URL of `/drinks/{types}`.

<Table
  title="Simple Arrays Serialization"
  data={[
    {
      style: "`simple`",
      explodeTrue: "/drinks/gin,vodka,rum",
      explodeFalse: "/drinks/gin,vodka,rum (default)"
    },
    {
      style: "`label`",
      explodeTrue: "/drinks/.gin.vodka.rum",
      explodeFalse: "/drinks/.gin,vodka,rum"
    },
    {
      style: "`matrix`",
      explodeTrue: "/drinks/;types=gin;types=vodka;types=rum",
      explodeFalse: "/drinks/;types=gin,vodka,rum"
    }
  ]}
  columns={[
    {
      key: "style",
      header: "Style"
    },
    {
      key: "explodeTrue",
      header: "Explode == `true`"
    },
    {
      key: "explodeFalse",
      header: "Explode == `false`"
    }
  ]}
/>

## Simple objects as path parameters in OpenAPI

For simple objects whose fields are primitive types such as `string`, `number`, `integer`, and `boolean`, serialization will vary depending on the `style` and `explode` fields.

For the examples below, we will use a path parameter named `filter` with a value of `{"type": "cocktail", "strength": 5}` for a path-templated URL of `/drinks/{filter}`.

<Table
  title="Simple Objects Serialization"
  data={[
    {
      style: "`simple`",
      explodeTrue: "/drinks/type=cocktail,strength=5",
      explodeFalse: "/drinks/type,cocktail,strength,5 (default)"
    },
    {
      style: "`label`",
      explodeTrue: "/drinks/.type=cocktail.strength=5",
      explodeFalse: "/drinks/.type,cocktail,strength,5"
    },
    {
      style: "`matrix`",
      explodeTrue: "/drinks/;type=cocktail;strength=5",
      explodeFalse: "/drinks/;filter=type,cocktail,strength,5"
    }
  ]}
  columns={[
    {
      key: "style",
      header: "Style"
    },
    {
      key: "explodeTrue",
      header: "Explode == `true`"
    },
    {
      key: "explodeFalse",
      header: "Explode == `false`"
    }
  ]}
/>

## Complex objects and arrays as path parameters in OpenAPI

For complex objects and arrays, serialization in a path parameter is only possible using `content` and not any `style` options.

For example, to serialize using JSON, you can define a parameter in the following way:

```yaml
parameters:
  - name: filter
    in: path
    content:
      application/json:
        schema:
          type: object
          properties:
            type:
              type: array
              items:
                type: string
            strength:
              type: array
              items:
                type: integer
```

This configuration would serialize to `/drinks/%7B%22type%22%3A%5B%22cocktail%22%2C%22mocktail%22%5D%2C%22strength%22%3A%5B5%2C10%5D%7D`, which is the equivalent of `/drinks/{"type":["cocktail","mocktail"],"strength":[5,10]}` unencoded.

## How to override path parameter encoding

By default, the characters `:/?#[]@!$&'()*+,;=` are encoded when present in the value of a path parameter. To render these characters unencoded in a request URL, use the `x-speakeasy-param-encoding-override: allowReserved` extension. Read more about parameter encoding in the ([docs](/docs/customize/java/param-encoding)).