Parameter encoding

The allowReserved setting

OpenAPI 3.x supports the allowReserved setting, which applies exclusively to query parameters. This allows reserved characters, such as :/?#[]@!$&'()*+,;=, to appear unencoded in request URLs.

OpenAPI 3.x does not support the allowedReserved setting for path parameters, although API owners may occasionally want to model this behavior. Consider a URL with a path parameter item, such as https://stuff.com/store/{item}. The API might be designed to accept values like most-popular or book/most-popular for {item}, where the / character remains unencoded, resulting in a URL like https://stuff.com/store/book/most-popular.

The Speakeasy OpenAPI extension x-speakeasy-param-encoding-override: allowReserved can be applied to a path parameter to allow reserved characters, such as :/?#[]@!$&'()*+,;=, to appear unencoded in the URL.

Here’s an example demonstrating the use of the path parameter encoding extension:

  /store/{item}:
    get:
      operationId: item
      parameters:
        - name: item
          in: path
          schema:
            type: string
            example: most-popular
          required: true
          x-speakeasy-param-encoding-override: allowReserved
      responses:
        "200":
          ...

As of November 2024, the x-speakeasy-param-encoding-override extension is supported for Java. Let us know if you need support in another language.