Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Support deep objects for query parameters with deepObject style

See original GitHub issue


Many applications expect deeply nested objects in input parameters, see the discussion in swagger-ui starting from this comment: In LoopBack, we are running into this problem too, see

Consider a filter parameter defined as follows:

   in: query
   name: filter
     type: object
   style: deepObject
   explode: true
   description: Options for filtering the results
   required: false

Let’s say the user wants to provide the following value, for example by entering a JSON into the text area rendered by swagger-ui:

  "name": "ivan",
  "birth-date": {
    "gte": "1970-01-01"

At the moment, the OpenAPI Specification v3 does not describe how to encode such value in a query string. As a result, OpenAPI clients like swagger-ui don’t know how to handle this input - see the discussion in for an example.


The following query string should be created by swagger-js client for the input value shown above.


The proposed serialization style is supported by, which is used by as the default query parser, which means that a vast number of Node.js API servers are already expecting this serialization style.

I am not sure if there is any existing formal specification of this format, I am happy to look into that once my proposal gets considered as acceptable in principle.

Additional information

Existing issues that are touching a similar topic:

  • style: form + object looses the parameter name? #1006
  • Are indexes in the query parameter array representable? #1501

Two older comments from swagger-js that may be relevant:

Limitations: deepObject does not handle nested objects. The specification and documentation does not provide an example for serializing deep objects. Flat objects will be serialized into the deepObject style just fine.

As for deepObject and nested objects - that was explicitly left out of the spec, and it’s ok to just Not Support It™.

Issue Analytics

  • State:open
  • Created 5 years ago
  • Reactions:197
  • Comments:50 (9 by maintainers)

github_iconTop GitHub Comments

benhaynescommented, Jan 18, 2019

Hey @earth2marsh and @darrelmiller … We (Directus team) have been trying to use OpenAPI 3.0 for a while now, but the lack of support for nested deepObjects has kept us from using this spec. We have a dynamic API that allows for relatively complex filtering, for example: filter[<field-name>][<operator>]=<value>

GET /items/users?filter[category][eq]=vip

Our API Reference for this filtering

Is there any hope for this being supported in the future or should we “move on”?

ElectroBuddhacommented, May 18, 2022

Five years later, this feature request is still relevant. Any news on this ?

Read more comments on GitHub >

github_iconTop Results From Across the Web

Parameter Serialization - Swagger
OpenAPI 3.0 supports arrays and objects in operation parameters (path, query, header, ... Possible styles depend on the parameter location – path, query, ......
Read more >
How to define parameters with square brackets in OpenAPI ...
The sort parameter can be defined an an object with the name and age properties. The parameter serialization method should be style: deepObject...
Read more >
Parsing requests | LoopBack Documentation
LoopBack has switched the definition of json query params from the exploded , deep-object style to the url-encoded style definition in Open API...
Read more >
Creating a parameter - IBM
Parameters define variable elements of a URL path, query parameters, headers, ... deepObject: Provides a simple way of rendering nested objects using form ......
Read more >
OpenAPI Specification v3.1.0 | Introduction, Definitions, & More
Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1. ... a simple way of rendering nested objects using form parameters....
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found