OpenAPI Parameter Serialization

Parameter Serialization

How Parameters Are Encoded

OpenAPI defines how arrays and objects are serialized in URLs and headers. Understanding these styles ensures your API clients send parameters in the format your server expects.

Key Concepts

• style - How values are delimited (comma, pipe, space, etc.)
• explode - Whether to repeat key names for arrays
• allowReserved - Whether to encode reserved characters

Tigrister Automatic Serialization

When you define style and explode in your OpenAPI spec, Tigrister automatically applies the correct serialization when sending requests. Just enter your values normally - Tigrister handles the encoding based on your spec.

Serialization Styles

Style	Location	Array Example	Default For
simple	path, header	blue,black,brown	path, header
form	query, cookie	?color=blue,black,brown	query, cookie
spaceDelimited	query	?color=blue%20black%20brown	-
pipeDelimited	query	?color=blue\|black\|brown	-
deepObject	query	?filter[status]=active	-
matrix	path	;color=blue,black,brown	-
label	path	.blue.black.brown	-

form Style

Query Default

The default style for query and cookie parameters. Behavior changes based on explode.

explode: false

# Input: colors = ["blue", "black", "brown"]

?colors=blue,black,brown

style: form

explode: false

explode: true(default)

# Input: colors = ["blue", "black", "brown"]

?colors=blue&colors=black&colors=brown

style: form

explode: true

Objects with form Style

explode: false

# Input: {R: 100, G: 200, B: 150}

?color=R,100,G,200,B,150

explode: true

# Input: {R: 100, G: 200, B: 150}

?R=100&G=200&B=150

simple Style

Path/Header Default

Comma-separated values without the parameter name. Used for path and header parameters.

Examples

Primitive

# /users/{id}

/users/5

Array

# /items/{ids}

/items/1,2,3

Object (explode: false)

# /color/{rgb}

/color/R,100,G,200,B,150

spaceDelimited & pipeDelimited

Alternative delimiters for query parameters. Useful when commas might appear in values.

spaceDelimited

# Input: ["blue", "black", "brown"]

?colors=blue%20black%20brown

Space character is URL-encoded as %20

pipeDelimited

# Input: ["blue", "black", "brown"]

?colors=blue|black|brown

Useful for values that may contain commas

deepObject Style

Objects Only

Renders object properties as separate parameters with bracket notation. Only works with explode: true (the only valid option).

Nested Object Example

Input Object

{
  "filter": {
    "status": "active",
    "category": "electronics"
  }
}

Output URL

?filter[status]=active

&filter[category]=electronics

Spec Definition

parameters:

- name: filter

in: query

style: deepObject

explode: true

schema:

type: object

properties:

status:

type: string

category:

type: string

Arrays in deepObject

Tigrister also supports arrays within deepObject. Each array element gets an index:

Input Object

{
  "filter": {
    "tags": ["electronics", "sale"],
    "price": { "min": 10, "max": 100 }
  }
}

Output URL

?filter[tags][0]=electronics

&filter[tags][1]=sale

&filter[price][min]=10

&filter[price][max]=100

matrix Style

Path Only

Uses semicolon-prefixed notation (RFC 6570). Less common but useful for complex path parameters.

explode: false

# Primitive

;color=blue

# Array

;colors=blue,black,brown

# Object

;color=R,100,G,200,B,150

explode: true

# Primitive

;color=blue

# Array

;colors=blue;colors=black;colors=brown

# Object

;R=100;G=200;B=150

label Style

Path Only

Dot-prefixed notation (RFC 6570). Values are separated by dots.

explode: false

# Primitive

.blue

# Array

.blue,black,brown

# Object

.R.100.G.200.B.150

explode: true

# Primitive

.blue

# Array

.blue.black.brown

# Object

.R=100.G=200.B=150

allowReserved Option

Controls whether reserved characters (:/?#[]@!$'()*+,;=) are URL-encoded or passed through as-is. Only applies to query parameters.

allowReserved: false(default)

# Input: "users/list"

?path=users%2Flist

Slash (/) is encoded as %2F

allowReserved: true

# Input: "users/list"

?path=users/list

Slash passes through unencoded

Caution

Use allowReserved: true carefully. Unencoded special characters can cause parsing ambiguity. Only use when the server specifically requires it.

Quick Reference: Defaults by Location

Parameter Location	Default Style	Default Explode
path	simple	false
query	form	true
header	simple	false
cookie	form	false

Tip

If you don't specify style or explode, these defaults are used. Most servers expect the defaults - only override when necessary.

Schema Composition External References