OpenAPI path/query parameters nested structure serialization

Question

In the OpenAPI docs about parameter serialization there's a short section about how to serialize query, path, header and cookie parameters with different styles. The schema of these parameters are described as OpenAPI flavoured json schema, which allows infinite nesting of objects and arrays. I haven't found any mention about how to deal with these in the docs:

https://swagger.io/docs/specification/serialization/

Let's assume the JSON schema provided for any of the parameters is like this:

{
  "type": "object",
  "properties": {
    "foo": {
      "type": "object",
      "properties": {
        "bar": "string"
      }
    }
  }
}

Meaning it allows structures in JSON such as:

{
  "foo": {
    "bar": "hello"
  }
}

Or similar concept with arrays that are nested:

{
  "type": "array",
  "items": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

Which allows structures like this (at least in JSON):

[["a"], ["b"]]

My question:

1. Is this allowed for path, query, etc parameters according to OpenAPI spec?
2. In case it is, are there any docs on how to serialize these in the different styles the spec allows?
3. In case it is not, is this mentioned anywhere in official docs?

I'm asking this because I'm working on tooling that needs to be compatible with the OpenAPI spec, and I'd like to know what can I expect here as parameter formats. I'm fully aware that having giant nested objects and trying to serialize them in a url is not the smartest idea. However I'm interested in what the OpenAPI spec allows.

Answer 1

Short answer: It's undefined behavior.

Most OpenAPI serialization styles are based on RFC 6570, which provides guidance only for:

• primitive values,
• arrays of primitives,
• simple non-nested objects (with primitive properties).

In case of other types of values (nested objects, objects containing arrays, nested arrays, arrays of objects) the behavior is undefined.

Similarly, OpenAPI's own deepObject style is currently defined only for simple objects but not for arrays or nested objects. Here are some related comments from the OpenAPI Specification authors/maintainers:

By the way, is there a reason we couldn't have deepObject work for arrays too? [...]

Darrel: Supporting arrays as you describe was my intent. I was supposed to find some canonical implementation to use as a guideline for the behavior, but didn't get around to it.

Ron: If we end up supporting the exploded array notation, it needs to be clear that the first index is 0 (or 1, or -1, or whatever).

(source)

Ron: when we defined deepObject in the spec, we explicitly chose to not mention what happens when the object has several levels in it, but in our conversations we went with 'not supported'. ​

(source)

There's an existing feature request to extend deepObject to support arrays and nested structures:
Support deep objects for query parameters with deepObject style

Answer 2

OpenAPI spec 3.0/3.1 supports parameter serialization in JSON format. It's just mentioned at the end of the page you referred.

• Other Serialization Methods
• schema vs content

From OpenAPI spec 3.0.3:

For more complex scenarios, the content property can define the media type and schema of the parameter. A parameter MUST contain either a schema property, or a content property, but not both.

Below OpenAPI snippet shows how to define the query parameters that have the desired structure in the question:

  parameters:
    - name: objParam
      in: query
      content:
        application/json:
          schema:
            type: object
            properties:
              foo:
                type: object
                properties:
                  bar:
                    type: string
    - name: nestedArray
      in: query
      content:
        application/json:
          schema:
            type: array
            items:
              type: array
              items:
                type: string