Proposal: dotDelimited style for query serialization.

[maarlo]

Regarding [ and ] must be urlencoded, I propose the usage of dot notation to serialize arrays and objects at query parameters.

Having the following array:

{
  "x": ["b","d","f"]
}

It could be serailized as:

?x.0=b&x.1=d&x.2=f 

Having the following object:

{
  "x": {
    "a": "b",
    "c": "d",
    "e": "f"
  }
}

It could be serailized as

?x.a=b&x.c=d&x.e=f

And mixing both of them:

{
  "x": [
    {
      "a": "b"
    },
    {
      "a": "d"
    }
  ]
}

It could be serailized as

?x.0.a=b&x.1.a=d

[jeremyfiel]

you can find serialization examples here, multiple types are supported

https://spec.openapis.org/oas/v3.0.3#fixed-fields-9

[maarlo]

Yes, but the proposed style is not defined.

[handrews]

@OAI/tsc review request: Can we decide whether to add this or not? My sense is that we don't want to add further serialization options/complexity, but if we do it is straightforward. This issue has been open for a year and a half without attracting further support or examples of usage in existing APIs.

[karenetheridge]

Previous serialization styles have been defined in terms of uri-template syntax (although only the swagger documentation -- https://swagger.io/docs/specification/serialization/ -- explicitly provides those templates - it's not even at https://learn.openapis.org/specification/parameters.html).

If we want to restrict ourselves to this, is it possible to define the newly proposed dotDelimited format in terms of uri-templates?

[maarlo]

I think so, just like happens with deepObject, but instead of using brackets using points, and with the addition of also allowing the serialization of deep objects and arrays.

[ralfhandl]

is it possible to define the newly proposed dotDelimited format in terms of uri-templates?

I couldn't find anything in RFC6570

[handrews]

I'm leaning towards advocating that we support #1502 (Support for arbitrary query strings) in 3.2, which could allow folks to experiment with new/custom serializations without us having to add more complexity to the mandatory options.

[mikekistler]

The sense I have gotten from recent discussions in the TDC meetings is that there is already too much undefined behavior in the query string, and there are efforts to correct this (which I am nominally part of). Doesn't this only make the problem worse?

[handrews]

In today's TDC call, we decided to consider a proposal for #1502, which will allow experimentation in the query string. So it will not solve this but it will allow extensions to try it out.

[davebelais]

Because the NPM package qs uses this format, it's already being used widely, just with no easy way for an OpenAPI schema to describe this. I'd advocate for naming this style "dotObject" rather than "dotDelimited" though, since it's akin to a deepObject and it's not indicated a dot separating values, but instead dot attribution...

[handrews]

@davebelais PR #4590 will allow defining extensions for complex parameter formats. There are far too many widely used packages, each with their own contradictory rules, for us to figure out a way to support them through the limitations of style and explode. We also just don't have the bandwidth to research all the formats. Hopefully, folks will experiment and we can incorporate successful approaches in a future release.

[handrews]

PR #4590 is merged and that's as far as we're going with this.