Repository navigation
Are indexes in the query parameter array representable? #1501
Description
I understand how to represent in 2.0 and 3.0 these query parameters with OpenAPI:
?list=x&list=y
But I can't understand if it is possible or not (so I imagine, not?) to represent this:
?list[0]=x&list[1]=y
or this:
?obj[x][0]=a&obj[x][1]=b
We use indexes so we can mix arrays and maps with the same notation, i.e. we would also have:
?map[x]=1&map[y]=2
Is this even representable today? Any hack around it if not?
Activity
jcarres-mdsol commentedon Mar 3, 2018
@webron, I think you originally added collectionFormat and style so probably you have given this some thought
hkosova commentedon Mar 5, 2018
Your last example
?map[x]=1&map[y]=2can be defined an an object parameter withstyle: deepObject:or
Not sure about other examples though.
harvzor commentedon Aug 16, 2021
.NET uses the
?list=x&list=yformat for simple nested objects which currently works fine with Swagger/OpenAPI.However, when .NET has to pass an array of objects, it switches to the
?list[0]=x&list[1]=yformat, which is incorrectly parsed by Swagger because OpenAPI has no way of describing how it should be serialized.This issue is better documented here: domaindrivendev/Swashbuckle.AspNetCore#1832
DSchougaard commentedon Mar 23, 2022
I've just recently encountered this issue myself. Has anything new happened?
septatrix commentedon Jul 8, 2022
This notation is also commonly used in PHP
OleksiiBulba commentedon Jun 20, 2024
I have a question about the workaround: is it legit to name the parameter with brackets. E.g. for the author example it would be
list[]. At least it solves the issue for just indexed query but not for maps.handrews commentedon Jun 20, 2024
@OleksiiBulba the OpenAPI parameter name syntax allows it. Although the question of whether non-percent-encoded
[]is valid in a URL query string is complex (see Appendix E in the work-in-progress 3.0.4 and 3.1.1 specs, which are on their own branches). But if it's working for you in practice, then you're probably fine (I can't tell whether that PHP framework is encoding/decoding behind the scenes or if it's just relying on the interoperability problems of[and]in URLs being very rare).OleksiiBulba commentedon Jun 20, 2024
@handrews thanks for your prompt response!
Actually, I've already tried it with
nelmio/api-doc-bundle(for Symfony) and it works absolutely ok.P.S. For anyone who would find this comment: if your property is required, don't forget to add
[]to the property name in required list, it will save you ~20 mins of life :Dhandrews commentedon Aug 19, 2025
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.