Parsing of "in: query" parameters not clearly described

[karenetheridge]

In https://spec.openapis.org/oas/latest#parameter-locations, it is stated that the serialized form of an in: query parameter is appended to the URL; however it does not state how this appending is done, nor how multiple query parameters of distinct styles should be combined.

RFC6570 is referenced in an appendix with a caution to not use the & form of uri templating and to append the query string manually, but again the use of combining multiple styles together is not clearly referenced.

Can we explicitly reference that all query parameters are expected to be serialized as in the application/x-www-form-urlencoded media-type? This is not an extra serialization pass however, but rather an overlapping one -- e.g. for deepObject and for some other style/explode/type combinations the individual key name(s) is/are not the parameter name itself but may be something else or even omitted entirely.

I think WHATWG is probably the best thing to reference here, but I'm not entirely sure.

We can also clarify (e.g. in one of the appendices that already talks about parameter decoding) that for in: query, it is always correct to use the application/x-www-form-urlencoded media type decoding to parse out the full list of keys/values from the query string (but not to treat this as an object as there may be duplicate keys, which may be used or ignored depending on the individual style and explode settings).

[handrews]

@karenetheridge

query string manually, but again the use of combining multiple styles together is not clearly referenced.

Multiple name=value pairs are always separated by & (and the whole query string is separated from the path by ?). The reason we don't specifically say application/x-www-form-urlencoded is that its percent-encoding rules and RFC6570's differ.

But if we don't explicitly say "join them using &" and you want to put that somewhere for clarity, that would still work.

Can we explicitly reference that all query parameters are expected to be serialized as in the application/x-www-form-urlencoded media-type?

This is addressed in Appendix E.5. It is, sadly, not that simple because of variationsi in how space and + are handled. 😢 It almost always works, but if you used allowReserved to sneak in an un-percent-encoded + that does not represent a space character, then you will break application/x-www-form-urlencoded decoders. RFC6570 actually does not allow this to happen, but we circumvented their restriction.

Anything that can improve clarity would be welcome, though.

[handrews]

Arguably, doing that thing with + is pathological, and perhaps we should more clearly advise against it rather than accommodating it with more complex decoding guidance?

[karenetheridge]

Actually it looks like I already patched this in my PR #5122:

query - Parameters that are appended to the URL with the ? character (or to existing query parameters with the & character), as described by RFC3986 section 3.4 ...

..except I'm wrong to refer to RFC3986 there, as it says no such thing about how query strings are formatted or delimited.

[karenetheridge]

I think this is better (I'll add this to that PR):

• query - Parameters that are appended to the URL with the ? character (or for subsequent query parameters, with the & character); MUST NOT appear in the same operation (or in the operation's path-item) as an in: "querystring" parameter.

This clarifies the delimiters used in the query string which are always used, and removes the example that is specific to only a certain style/explode/schema type combination.

[handrews]

[NOTE: never mind, apparently I was hallucinating. I'm not an LLM! I swear!]

@karenetheridge the way I read what you wrote it implies that you can, under some circumstances, mix in: query and in: querystring, but what we say is:

> [An in: query parameter] MUST NOT appear in the same operation (or in the operation’s path-item) as an in: "querystring" parameter.

~~and ~~

> [An in: querystring parameter] MUST NOT appear in the same operation (or in the operation’s path-item) as any in: "query" parameters.

It is (intentionally) not specific to the names of the parameters involved. You just can't mix them at all.

[karenetheridge]

It is (intentionally) not specific to the names of the parameters involved.

I don't understand. I didn't mention parameter names anywhere?

The change I am making is to repeat here the restriction that the query/querystring exclusivity is not just within a set of path-item parameters or operation parameters but in the union of all parameters from both locations.

[handrews]

I don't understand. I didn't mention parameter names anywhere?

I... (looks suspiciously at tea mug but it's just Darjeeling...) have no idea how I hallucinated that? And I am quite certain I looked at it a few times because I'm trying to get better about not replying too quickly. I do apologize. Really, I could have sworn it said something different but clearly does not.