Parameter Serialization

Serialization means translating data structures or object state into a format that can be transmitted and reconstructed later. OpenAPI 3.0 supports arrays and objects in operation parameters (path, query, header, and cookie) and lets you specify how these parameters should be serialized. The serialization method is defined by the style and explode keywords:


    style

defines how multiple values are delimited. Possible styles depend on the parameter location – path , query , header or cookie .


    explode

(true/false) specifies whether arrays and objects should generate separate parameters for each array item or object property.

OpenAPI serialization rules are based on a subset of URI template patterns defined by RFC 6570 . Tool implementers can use existing URI template libraries to handle the serialization, as explained below .

Path Parameters

Path parameters support the following style values:

simple – (default) comma-separated values. Corresponds to the


    {param_name}

URI template.

label – dot-prefixed values, also known as label expansion. Corresponds to the


    {.param_name}

URI template.

matrix – semicolon-prefixed values, also known as path-style expansion. Corresponds to the


    {;param_name}

URI template.

The default serialization method is style: simple and explode: false . Given the path /users/{id} , the path parameter id is serialized as follows:

^* Default serialization method

The label and matrix styles are sometimes used with partial path parameters, such as /users{id} , because the parameter values get prefixed.

Query Parameters

Query parameters support the following style values:

form – (default) ampersand-separated values, also known as form-style query expansion. Corresponds to the


    {?param_name}

URI template.

spaceDelimited – space-separated array values. Same as


    collectionFormat: ssv

in OpenAPI 2.0. Has effect only for non-exploded arrays (


    explode: false

), that is, the space separates the array values if the array is a single parameter , as in


    arr=a b c

pipeDelimited – pipeline-separated array values. Same as


    collectionFormat: pipes

in OpenAPI 2.0. Has effect only for non-exploded arrays (


    explode: false

), that is, the pipe separates the array values if the array is a single parameter , as in


    arr=a|b|c

deepObject – simple non-nested objects are serialized as


    paramName[prop1]=value1&paramName[prop2]=value2&...

. The behavior for nested objects and arrays is undefined.

The default serialization method is style: form and explode: true . This corresponds to collectionFormat: multi from OpenAPI 2.0. Given the path /users with a query parameter id , the query string is serialized as follows:

^* Default serialization method

Additionally, the allowReserved keyword specifies whether the reserved characters :/?#[]@!$&'()*+,;= in parameter values are allowed to be sent as they are, or should be percent-encoded. By default, allowReserved is false , and reserved characters are percent-encoded. For example, / is encoded as %2F (or %2f ), so that the parameter value quotes/h2g2.txt will be sent as quotes%2Fh2g2.txt

Header parameters always use the simple style, that is, comma-separated values. This corresponds to the {param_name} URI template. An optional explode keyword controls the object serialization. Given the request header named X-MyHeader , the header value is serialized as follows:

Serialization and RFC 6570

OpenAPI serialization rules are based on a subset of URI templates defined by RFC 6570 . Tool implementers can use existing URI template libraries to handle the serialization. You will need to construct the URI template based on the path and parameter definitions. The following table shows how OpenAPI keywords are mapped to the URI Template modifiers.


   style: pipeDelimited

prefix (depending on the parameter position in the query string) – but using pipes

instead of commas

to join the array values


   style: spaceDelimited

prefix (depending on the parameter position in the query string) – but using spaces instead of commas

to join the array values


   explode: false


   explode: true

suffix


   allowReserved: false


   allowReserved: true

prefix

For example, consider the path /users{id} with a query parameter metadata , defined like so:


   paths:
  # /users;id=3;id=4?metadata=true
  /users{id}:
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: array
            items:
              type: integer
            minItems: 1
          style: matrix
          explode: true
        - in: query
          name: metadata
          schema:
            type: boolean
          # Using the default serialization for query parameters:
          # style=form, explode=false, allowReserved=false
      responses:
        '200':
          description: A list of users

The path parameter id uses the matrix style with the explode modifier, which corresponds to the {;id*} template. The query parameter metadata uses the default form style, which corresponds to the {?metadata} template. The complete URI template would look like:


   /users{;id*}{?metadata}

A client application can then use an URI template library to generate the request URL based on this template and specific parameter values.

Other Serialization Methods

style and explode cover the most common serialization methods, but not all. For more complex scenarios (for example, a JSON-formatted object in the query string), you can use the content keyword and specify the media type that defines the serialization format. For more information, see schema vs content .

Did not find what you were looking for? Ask the community
Found a mistake? Let us know