OpenAPI Path Parameters

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 (opens in a new tab) specification. Reserved characters are percent-encoded (for example, ? becomes %3F).

By default, path parameters are serialized using style: simple and explode: false but there are a number of different serialization options available:

• style: simple - Simple style serialization is the default serialization for path parameters, using commas (,) to separate multiple values. Defined by RFC 6570 (opens in a new tab).
• style: label - Label-style serialization uses dots (.) to separate multiple values. Defined by RFC 6570 (opens in a new tab).
• style: matrix - Matrix-style serialization uses semicolons (;) to separate multiple values. Defined by RFC 6570 (opens in a new tab).

Primitive Types As Path Parameters in OpenAPI

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

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}.

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}.

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}.

Complex Objects and Arrays As Path Parameters in OpenAPI

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

For example, to serialize using JSON, the following:

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

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

The characters :/?#[]@!$&'()*+,;= are encoded by default when present in the value of a path parameter. Those characters can be rendered unencoded in a request url via the x-speakeasy-param-encoding-override: allowReserved extension (docs).