Support deep objects for query parameters with deepObject style #1385

bajtos · 2018-09-13T13:26:12Z

Content & configuration

Swagger/OpenAPI definition:

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

Swagger-Client usage:

SwaggerClient({
  // no special configuration is needed
})

Is your feature request related to a problem?

Many applications expect deeply nested objects in input parameters, see the discussion in swagger-ui starting from this comment: swagger-api/swagger-ui#4064 (comment) In LoopBack, we are running into this problem too, see loopbackio/loopback-next#1679.

Consider the filter parameter described above (in:query style:deepObject explode:true).

Let's say the user provides 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, swagger-js (and swagger-ui) silently ignores the value, produces an empty query and does not even let the user know that something went wrong.

Describe the solution you'd like

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

filter[name]=ivan&filter[birth-date][qte]=1970-01-01

Describe alternatives you've considered

There are no alternatives as far as I can tell.

In the past, when Swagger 2.x did not support deepObject style, we were describing our filter argument as string and allowing clients to send the deep object in a JSON string. This was our custom extension that was of course not supported by swagger-js and swagger-ui, creating a suboptimal user experience.

Additional context

We are using [email protected], which is the latest version published to npm. Unfortunately I am not able to tell which version of swagger-js is used by this version of swagger-ui-dist :(

The proposed serialization style is supported by https://www.npmjs.com/package/qs, which is used by http://expressjs.com as the default query parser, which means that a vast number of Node.js API servers are already expecting this serialization style.

I found the following two older comments that may be relevant:

#1140

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

#1140 (comment)

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

@shockey @webron What's your opinion on this? If we contributed a patch to swagger-js that will serialize deeply-nested properties using the style described above, would you accept such change, despite the fact that OpenAPI specification does not explicitly describe how to serialize deeply-nested properties?

The text was updated successfully, but these errors were encountered:

webron · 2018-09-22T19:38:12Z

@bajtos 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'. If you're looking for supporting that use case, it needs to be addressed by the spec first.

bajtos · 2018-09-25T13:26:22Z

@webron thank you for the response.

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'.

Fair enough. Can swagger-js reject deeply nested objects with a descriptive error then? Right now, swagger-ui is silently ignoring parameter values set to a deep object. I'd like it to display an error explaining the problem to the user.

Would you accept a patch adding such validation logic?

If you're looking for supporting that use case, it needs to be addressed by the spec first.

Makes sense. I have very little experience with the standardization process. What is your opinion - how likely will such proposal get accepted? How long would the process take? Is it a matter of weeks, months or years?

webron · 2018-09-27T16:56:21Z

Providing a descriptive error makes sense to me, and we'd appreciate a patch for that logic.

To start a process with affecting the spec, you can file a ticket at https://github.com/OAI/OpenAPI-Specification/ with the details. Releases of the spec are not frequent, so it can take some time. Assuming it's a non-breaking change, it can get into a minor version (but cannot get into a patch version) - that would be a few months.

bajtos · 2018-10-11T13:05:22Z

Thank you @webron. I opened a new ticket to enhance the spec, see OAI/OpenAPI-Specification#1706.

I'll try to find some time to fix swagger-js in the next few weeks.

BREAKING CHANGE: This fix has modified the Open-API definition of the decorator 'param.query.object', to support url-encoded format for json query parameters. Previously, such parameters were described with `exploded: true` and `style: deepObject` which turned out to be problematic, as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for json query params if the payload was simple as below, but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix modifies the definition of JSON query params from `exploded` and `deep-object` style to the `url-encoded` style described in Open-API spec. The 'style' and 'explode' fields are removed. The 'schema' field is moved under 'content[application/json]' (`url-encoded` style) as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` for example, to filter api results with the following condition, ```json { "include": [ { "relation": "todo" } ] } ``` the following url-encoded query parameter is used. ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. LoopBack framework supported receiving `url-encoded` payload for `exploded`, `deep object style` query params on the server side even before this fix, even though the Open-API spec has very clear demarcations for both the styles. In effect, this fix only clarifies the schema contract as per Open-API spec. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted. The impact is only on the open api specifications generated from LoopBack APIs. All consumers of LoopBack APIs may need to regenerate the api specifications, if their API clients or client tools (like swagger-ui or LoopBack's api explorer) necessiate adhering to Open-API's url-encoded query parameter definition to use url-encoding. Otherwise there wouldnt be any significant impact on API consumers.

BREAKING CHANGE: This fix has modified the schema described by the decorator 'param.query.object', to support Open-API specification's url-encoded format for json query parameters. Previously, such parameters were described with `exploded: true`, `style: deepObject` which turned out to be problematic, as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for json query params if the payload was simple as below, but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix modifies the definition of JSON query params from `exploded` and `deep-object` style to the `url-encoded` style described in Open-API spec. The 'style' and 'explode' fields are removed. The 'schema' field is moved under 'content[application/json]' (`url-encoded` style) as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` for example, to filter api results with the following condition, ```json { "include": [ { "relation": "todo" } ] } ``` the following url-encoded query parameter is used. ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. LoopBack supported receiving `url-encoded` payload for `exploded`, `deep object` style query params on the server side even before this fix, even though the Open-API spec has very clear demarcations for both these styles. In effect, this fix only clarifies the schema contract as per Open-API spec. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted. The impact is only on the open api specifications generated from LoopBack APIs. All consumers of LoopBack APIs may need to regenerate the api specifications, if their API clients or client tools (like swagger-ui or LoopBack's api explorer) necessiate adhering to Open-API's url-encoded query parameter definition to use url-encoding. Otherwise there wouldnt be any significant impact on API consumers.

BREAKING CHANGE: This fix has modified the schema described by the decorator 'param.query.object', to support Open-API specification's url-encoded format for json query parameters. Previously, such parameters were described with `exploded: true`, `style: deepObject` which turned out to be problematic, as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for json query params if the payload was simple as below, but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix modifies the definition of JSON query params from `exploded` and `deep-object` style to the `url-encoded` style described in Open-API spec. The 'style' and 'explode' fields are removed. The 'schema' field is moved under 'content[application/json]' (`url-encoded` style) as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` for example, to filter api results with the following condition, ```json { "include": [ { "relation": "todo" } ] } ``` the following url-encoded query parameter is used. ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. LoopBack supported receiving `url-encoded` payload for `exploded`, `deep object` style query params on the server side even before this fix, even though the Open-API spec has very clear demarcations for both these styles. In effect, this fix only clarifies the schema contract as per Open-API spec. The impact is only on the open api definitions generated from LoopBack APIs. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted. All consumers of LoopBack APIs may need to regenerate api definitions, if their API clients or client tools (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` format to support url-encoding. Otherwise there wouldn't be any significant impact on API consumers.

BREAKING CHANGE: This fix has modified the schema definitions described by the decorator 'param.query.object', to support Open-API's `url-encoded` definition for json query parameters. Previously, such parameters were described with `exploded: true`, `style: deepObject` which turned out to be problematic, as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for json query params if the payload was simple as below but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix modifies the definition of json query params from `exploded` and `deep-object` style to the `url-encoded` style described in Open-API spec. The 'style' and 'explode' fields are removed. The 'schema' field is moved under 'content[application/json]' (`url-encoded` style) as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` for example, to filter api results with the following condition, ```json { "include": [ { "relation": "todo" } ] } ``` the following url-encoded query parameter is used. ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. LoopBack supported receiving `url-encoded` payload for `exploded`, `deep object` style query params on the server side even before this fix, even though the Open-API spec has very clear demarcations for both these styles. In effect, this fix only clarifies the schema contract as per Open-API spec. The impact is only on the open api definitions generated from LoopBack APIs. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted. All consumers of LoopBack APIs may need to regenerate api definitions, if their client libraries (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` format to support url-encoding. Otherwise there wouldn't be any significant impact on API consumers.

BREAKING CHANGE: This fix has modified the schema definitions described by the decorator 'param.query.object', to support Open-API's `url-encoded` definition for json query parameters. Previously, such parameters were described with `exploded: true`, `style: deepObject` which turned out to be problematic as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded style encoding worked if the payload was simple as below but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix modifies the definition of json query params from `exploded` and `deep-object` style to the `url-encoded` style described in Open-API spec. Certain client libraries (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` format to support "sending" url-encoded payload. LoopBack supported "receiving" url-encoded payload for `exploded`, `deep object` style query params on the server side even before this fix, even though the Open-API spec has very clear demarcations for both these styles. In effect, this fix only clarifies the schema contract as per Open-API spec. The impact is only on the open api definitions generated from LoopBack APIs. All consumers of LoopBack APIs may need to regenerate api definitions only if their client libraries require them to do so for url-encoding. Otherwise there wouldn't be any significant impact on API consumers. This fix removes the 'style' and 'explode' fields from the definition of json query params. The 'schema' field is moved under 'content[application/json]' (`url-encoded` style) as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` for example, to filter api results with the following condition, ```json { "include": [ { "relation": "todo" } ] } ``` the following url-encoded query parameter is used. ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted.

BREAKING CHANGE: This fix has modified the schema definitions described by the decorator 'param.query.object', to support Open-API's `url-encoded` definition for json query parameters. Previously, such parameters were described with `exploded: true`, `style: deepObject` which turned out to be problematic as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for simple json objects as below but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix modifies the definition of json query params from `exploded` and `deep-object` style to the `url-encoded` style described in Open-API spec. for example, to filter api results with the following condition, ```json { "include": [ { "relation": "todo" } ] } ``` the following url-encoded query parameter is used, ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` Certain client libraries (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` style definition for json query params to support "sending" url-encoded payload. LoopBack supported "receiving" url-encoded payload for `exploded`, `deep object` style query params on the server side even before this fix, even though the Open-API spec has very clear demarcations for both these styles. In effect, this fix only clarifies the schema contract as per Open-API spec. The impact is only on the open api definitions generated from LoopBack APIs. All consumers of LoopBack APIs may need to regenerate api definitions only if their client libraries require them to do so for url-encoding. Otherwise there wouldn't be any significant impact on API consumers. This fix removes the 'style' and 'explode' fields from the definition of json query params. The 'schema' field is moved under 'content[application/json]' (`url-encoded` style) as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted.

BREAKING CHANGE: This fix has modified the api definitions described by the decorator 'param.query.object', to support Open-API's `url-encoded` style definition for json query parameters. Previously, such parameters were described with `exploded: true` and `style: deepObject` which turned out to be problematic as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for simple json objects as below but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix switches from the `exploded`, `deep-object` style to the `url-encoded` style described in Open-API spec. For instance, to filter api results from the GET '/todo-list' endpoint in the todo-list example with a specific relation , say, { "include": [ { "relation": "todo" } ] }, the following url-encoded query parameter can be used, ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` This fix removes the 'style' and 'explode' fields (`exploded` `deep-object` style) and moves the 'schema' field under 'content[application/json]' (`url-encoded` style) in the Open-API definition as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` Certain client libraries (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` style definition for json query params to support "sending" url-encoded payload. LoopBack supported "receiving" url-encoded payload for `exploded`, `deep object` style query params on the server side even before this fix, even though the Open-API spec has described both these styles with clear demarcations. In effect, this fix only clarifies the schema contract as per Open-API spec. The impact is only on the open api definitions generated from LoopBack APIs. All consumers of LoopBack APIs may need to regenerate api definitions only if their client libraries require them to do so for url-encoding. Otherwise there wouldn't be any significant impact on API consumers. To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted. This fix has also modified the coercion behaviour for `in:query`, `deep-object` query parameters by removing json parsing for them and the expectation is to pass in only string values. But since the `exploded` `deep-object` style definition for query params has been removed, this behaviour remains just an internal source code aspect as of now.

BREAKING CHANGE: This fix has modified the api definitions described by the decorator 'param.query.object', to support Open-API's `url-encoded` definition for json query parameters. Previously, such parameters were described with `exploded: true` and `style: deepObject` which turned out to be problematic as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for simple json objects as below but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix switches definition of json query params from the `exploded`, `deep-object` style to the `url-encoded` style definition in Open-API spec. LoopBack already supports receiving url-encoded payload for json query parameters. For instance, to filter api results from the GET '/todo-list' endpoint in the todo-list example with a specific relation, { "include": [ { "relation": "todo" } ] }, the following url-encoded query parameter can be used, ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` The coercion behavior in LoopBack has always supported receiving url-encoded payload for `exploded`, `deep object` style json query params before this fix. This fix has modified that behavior by removing json parsing for `deep object` json query params. Since the `exploded` `deep-object` definition has been removed from the `param.query.object` decorator, this new behaviour remains just an internal source code aspect as of now. In effect, this fix only clarifies the schema contract as per Open-API spec. The impact is only on the open api definitions generated from LoopBack APIs. This fix removes the 'style' and 'explode' fields from the definition of json query params and moves the 'schema' field under 'content[application/json]'. This is the definition that should support url-encoding as per Open-API spec. ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` Certain client libraries (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` style definition for json query params to support "sending" url-encoded payload. All consumers of LoopBack APIs may need to regenerate api definitions, if their client libraries require them to do so for url-encoding. Otherwise there wouldn't be any significant impact on API consumers. To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work for json query params, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted.

BREAKING CHANGE: This fix has modified the api definitions described by the decorator 'param.query.object', to support Open-API's `url-encoded` definition for json query parameters. Previously, such parameters were described with `exploded: true` and `style: deepObject` which turned out to be problematic as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for simple json objects as below but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix switches definition of json query params from the `exploded`, `deep-object` style to the `url-encoded` style definition in Open-API spec. LoopBack already supports receiving url-encoded payload for json query parameters. For instance, to filter api results from the GET '/todo-list' endpoint in the todo-list example with a specific relation, { "include": [ { "relation": "todo" } ] }, the following url-encoded query parameter can be used, ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` The above was possible because the coercion behavior in LoopBack performed json parsing for `deep object` style json query params before this fix. This fix has modified that behavior by removing json parsing. Since the `exploded` `deep-object` definition has been removed from the `param.query.object` decorator, this new behaviour remains just an internal source code aspect as of now. In effect, this fix only modifies the open api definitions generated from LoopBack APIs. This fix removes the 'style' and 'explode' fields from the definition of json query params and moves the 'schema' field under 'content[application/json]'. This is the definition that supports url-encoding as per Open-API spec. ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` Certain client libraries (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` style definition for json query params to support "sending" url-encoded payload. All consumers of LoopBack APIs may need to regenerate api definitions, if their client libraries require them to do so for url-encoding. Otherwise there wouldn't be any significant impact on API consumers. To preserve compatibility with existing REST API clients, this change is backward compatible. All exploded queries like `?filter[limit]=1` will continue to work for json query params, despite the fact that they are described differently in the OpenAPI spec. Existing api clients will continue to work after an upgrade. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted.

BREAKING CHANGE: This fix has modified the api definitions described by the decorator 'param.query.object', to support Open-API's `url-encoded` definition for json query parameters. Previously, such parameters were described with `exploded: true` and `style: deepObject`, i.e exploded encoding, which turned out to be problematic as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for simple json objects as below but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix switches definition of json query params from the `exploded`, `deep-object` style to the `url-encoded` style definition in Open-API spec. LoopBack already supports receiving url-encoded payload for json query parameters. For instance, to filter api results from the GET '/todo-list' endpoint in the todo-list example with a specific relation, { "include": [ { "relation": "todo" } ] }, the following url-encoded query parameter can be used, ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` The above was possible because the coercion behavior in LoopBack performed json parsing for `deep object` style json query params before this fix. This fix has modified that behavior by removing json parsing. Since the `exploded` `deep-object` definition has been removed from the `param.query.object` decorator, this new behaviour remains just an internal source code aspect as of now. In effect, this fix only modifies the open api definitions generated from LoopBack APIs. The 'style' and 'explode' fields are removed and the 'schema' field is moved under 'content[application/json]'. This is the definition that supports url-encoding as per Open-API spec. ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` Certain client libraries (like swagger-ui or LoopBack's api explorer) necessiate using Open-API's `url-encoded` style definition for json query params to support "sending" url-encoded payload. All consumers of LoopBack APIs may need to regenerate api definitions, if their client libraries require them to do so for url-encoding. Otherwise there wouldn't be any significant impact on API consumers. To preserve compatibility with existing REST API clients, this change is backward compatible. All exploded queries like `?filter[limit]=1` will continue to work for json query params, despite the fact that they are described differently in the OpenAPI spec. Existing api clients will continue to work after an upgrade. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted.

Adhalianna · 2023-07-06T14:18:45Z

Since the discussion on the OAS side seems to have stopped on "use extensions", maybe Swagger could support one that implements this? Some suggestions have been proposed here in the comment under the discussion started by @bajtos .

This was referenced Sep 13, 2018

Sending an object list in the URL swagger-api/swagger-ui#4064

Closed

REST API to find models using a filter loopbackio/loopback-next#1679

Merged

bajtos mentioned this issue Oct 11, 2018

Support deep objects for query parameters with deepObject style OAI/OpenAPI-Specification#1706

Open

bajtos mentioned this issue Oct 15, 2018

[API Explorer] Fields shown but ignored loopbackio/loopback-next#1470

Closed

GuillaumeJasmin mentioned this issue Oct 25, 2018

Include related models in "GET /mymodels" results loopbackio/loopback-next#1889

Closed

2 tasks

bajtos mentioned this issue Jan 10, 2019

API Explorer ignores filter options where, fields, and order loopbackio/loopback-next#2208

Closed

7 tasks

shockey added the type: enhancement label Jan 15, 2019

bajtos mentioned this issue Apr 29, 2019

API Explorer ignores where filter loopbackio/loopback-next#2804

Closed

bajtos mentioned this issue May 30, 2019

docs: clean up WIP sections for sequence page loopbackio/loopback-next#2994

Merged

7 tasks

DarkSorrow mentioned this issue Jul 6, 2019

Adding nested object support for deepObject style #1450

Closed

10 tasks

hkosova mentioned this issue Jan 5, 2022

Clarify deepObject applicability OAI/OpenAPI-Specification#2846

Merged

mficzel mentioned this issue Jun 27, 2024

BUGFIX: The style deepObject together with a json payload confuses some generators and the swagger ui at times sitegeist/Sitegeist.SchemeOnYou#25

Open

mficzel mentioned this issue Jan 29, 2025

Non singleValue value objects as query parameters are not handled correctly yet sitegeist/Sitegeist.SchemeOnYou#11

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support deep objects for query parameters with deepObject style #1385

Support deep objects for query parameters with deepObject style #1385

bajtos commented Sep 13, 2018

webron commented Sep 22, 2018

bajtos commented Sep 25, 2018

webron commented Sep 27, 2018

bajtos commented Oct 11, 2018

Adhalianna commented Jul 6, 2023 •

edited

Loading

Support deep objects for query parameters with deepObject style #1385

Support deep objects for query parameters with deepObject style #1385

Comments

bajtos commented Sep 13, 2018

Content & configuration

Is your feature request related to a problem?

Describe the solution you'd like

Describe alternatives you've considered

Additional context

webron commented Sep 22, 2018

bajtos commented Sep 25, 2018

webron commented Sep 27, 2018

bajtos commented Oct 11, 2018

Adhalianna commented Jul 6, 2023 • edited Loading

Adhalianna commented Jul 6, 2023 •

edited

Loading