json - 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