OpenAPI query string parameter with list of objects

Question

I am trying to document with OpenAPI a query string which look like

filtered[0][id]=code&filtered[0][value]=12345

and contains a list of object with properties id and value.

My yaml documentation looks like the following

parameters:
    - name: filtered
      in: query
      description: filters to be applied
      explode: true
      style: deepObject
      schema:
        type: array
        items:
          properties:
            id:
              description: name of the field to be filtered
              type: string
            value:
              description: value of the filter
          type: object

The problem is the following: it looks like the style: deepObject option works only for one level, and not at the second level where my objects actually are. That is, it expects a query string like

?sorted[0]=%7B%0A%20%20%22id%22%3A%20%22string%22%2C%0A%20%20%22value%22%3A%20true%0A%7D

with the object not serialized as an array with id and value keys.

Is there a way to solve this?

deepobject is still not native jason just enumeration of all object properties or elements — Serge
@serge i would like to encode my query string as filtered[0][id]=code&filtered[0][value]=12345 — marcosh
Well by name deep object aplies to objects. Is it an option to put your list inside an object — Serge
no, it is not an option. The frontend is using a library (react-table) which uses that format. That is what I need to document, I can't change it — marcosh

Helen Helen · Accepted Answer · 2018-10-19T14:13:21

This is not possible as of OpenAPI 3.1

OpenAPI 3.0/3.1 Specifications currently defines the deepObject behavior only for simple objects (with primitive properties) such as

{
  "id": 5,
  "name": "Bob"
}

but not for arrays and not for nested objects.

Since the behavior for arrays and nested objects is not defined, there's really no way to describe your query string. Technically, the only way would be to define filtered[0][id], filtered[0][value], etc. as individual query parameters.

OpenAPI query string parameter with list of objects

2 Answers