How to describe urls with ordered indexed array?

[denisvmedia]

Here is an example url that I tried to describe with OpenAPI, but failed:

http://example.com/api/items?filter[0][field]=value1&filter[0][type]=gte&filter[0][x]=490&filter[1][field]=value2&filter[1][type]=lte&filter[1][x]=200&filter[2][field]=value3&filter[2][type]=between&filter[2][x]=100&filter[2][y]=300

Some additional notes: we have an array of filters that should accept some values. The parameters can be represented in JSON like this:

[
 {
 "field": "value1",
 "type": "gte",
 "x": 490
 },
 {
 "field": "value2",
 "type": "lte",
 "x": 200
 },
 {
 "field": "value3",
 "type": "between",
 "x": 100,
 "y": 300
 }
]

With this type of query parameters indexing we get natural arrays in PHP without any additional "movements" using something like this:

parse_str('filter[0][field]=value1&filter[0][type]=gte&filter[0][x]=490&filter[1][field]=value2&filter[1][type]=lte&filter[1][x]=200&filter[2][field]=value3&filter[2][type]=between&filter[2][x]=100&filter[2][y]=300', $result);
var_dump($result);
/** output:
array(1) {
 ["filter"]=>
 array(3) {
 [0]=>
 array(3) {
 ["field"]=>
 string(6) "value1"
 ["type"]=>
 string(3) "gte"
 ["x"]=>
 string(3) "490"
 }
 [1]=>
 array(3) {
 ["field"]=>
 string(6) "value2"
 ["type"]=>
 string(3) "lte"
 ["x"]=>
 string(3) "200"
 }
 [2]=>
 array(4) {
 ["field"]=>
 string(6) "value3"
 ["type"]=>
 string(7) "between"
 ["x"]=>
 string(3) "100"
 ["y"]=>
 string(3) "300"
 }
 }
}
**/

So, this is not something exotic, this is a normal php-style query uri. But unfortunately it seems OpenAPI just doesn't support it.

[mario-d-s]

@denisvmedia can you please clarify what you mean exactly by "OpenAPI just doesn't support it".

OpenAPI itself is just a spec, but your issue seems to be related to a piece of tooling. If that is the case, which tool doesn't work for your use case?

If you're just having trouble to describe your endpoint operation in your OpenAPI document, can you at least include what you have tried, and what you need more help with?

[denisvmedia]

OK, in other words, the spec doesn't take care of this case. So, it's not about the tool. And sorry, but I can't tell you what I tried, just because I don't know how to do that according to the spec.

[handrews]

@denisvmedia you are saying that you want OpenAPI to describe taking that blob of JSON and producing that query string with the square brackets and stuff?

Alternatively, what part of the OpenAPI spec do you think should be helping you with this but does not?

[denisvmedia]

@handrews I'm saying I'm trying to describe the query arguments. JSON stuff was an example how the arguments should have been treated. As of the part of the OpenAPI spec, I think it's data formats section.

[handrews]

With PR #4590 and the new media types registry, it is possible to define new ways to structure the query string, and that is now the recommended approach to try out complex formats such as this.