NOTE: This is primarily relevant if #5320 is accepted, as it dramatically widens the scope of potential interactions by allowing global parameters. If #5320 is rejected, this can probably just be closed wontfix.
To keep things simple with in: querystring, we added two restrictions, which apply across both the Operation and Path Item level:
- There can only be one
in: querystring parameter
- If there is an
in: querystring parameter, there cannot be any in: query parameters
We missed a querystring option elsewhere
However, we did overlook that the type: apiKey, in: query Security Scheme effectively adds an in: query parameter which we did not explicitly forbid (and I do not consider the current wording to implicitly forbid it, as "parameter" was intended to mean Parameter Object).
Technically, there isn't a problem here: You can just tack the API key parameter onto the query string on either end, and as long as you remove it first when parsing, there's no ambiguity.
None of the potential problems are new
- Ambiguous groups of object-property-name-defined query paramters already occur with
in: query, explode: true
- As noted (and warned against) in Appendix E, with very particular use of
allowReserved: true with minimal percent-encoding (and no form-urlencoded-specific escaping), plus use of a form-urlencoded parser, it is possible to misinterpret a + as an escaped space when it was serialized as a literal +. This requires the user to make an effort to work around the typical behavior, and we already warn that it will cause a bug if the user does so.
We can make the ambiguity better, and the escaping/encoding issue is not worse
We could also improve the situation with in: querystring by mandating its position relative to other query parameters (whether in: querystring or in: query). For example:
- when multiple
in: querystring paramters are present, the global ones MUST be serialized first (directly after the ?), in the order they appear in the global array, then the path item ones, then the operation ones
- when
in: querystring paramters are present, they MUST all appear before any in: query or security scheme parameters (or MUST all appear after, it doesn't matter as long as it is consistent)
This would substantially reduce the number of possible ways to parse the resulting URL when it is recieved.
We could also make corresponding SHOULD recommendations regarding in: query (and other) parameter ordering, we just can't make it a MUST because of compatibility. In fact, without this SHOULD, the behavior is already inherently implementation-defined.
(paging @karenetheridge for implementor feedback)
NOTE: This is primarily relevant if #5320 is accepted, as it dramatically widens the scope of potential interactions by allowing global parameters. If #5320 is rejected, this can probably just be closed wontfix.
To keep things simple with
in: querystring, we added two restrictions, which apply across both the Operation and Path Item level:in: querystringparameterin: querystringparameter, there cannot be anyin: queryparametersWe missed a querystring option elsewhere
However, we did overlook that the
type: apiKey, in: querySecurity Scheme effectively adds anin: queryparameter which we did not explicitly forbid (and I do not consider the current wording to implicitly forbid it, as "parameter" was intended to mean Parameter Object).Technically, there isn't a problem here: You can just tack the API key parameter onto the query string on either end, and as long as you remove it first when parsing, there's no ambiguity.
None of the potential problems are new
in: query, explode: trueallowReserved: truewith minimal percent-encoding (and noform-urlencoded-specific escaping), plus use of aform-urlencodedparser, it is possible to misinterpret a+as an escaped space when it was serialized as a literal+. This requires the user to make an effort to work around the typical behavior, and we already warn that it will cause a bug if the user does so.We can make the ambiguity better, and the escaping/encoding issue is not worse
We could also improve the situation with
in: querystringby mandating its position relative to other query parameters (whetherin: querystringorin: query). For example:in: querystringparamters are present, the global ones MUST be serialized first (directly after the?), in the order they appear in the global array, then the path item ones, then the operation onesin: querystringparamters are present, they MUST all appear before anyin: queryor security scheme parameters (or MUST all appear after, it doesn't matter as long as it is consistent)This would substantially reduce the number of possible ways to parse the resulting URL when it is recieved.
We could also make corresponding SHOULD recommendations regarding
in: query(and other) parameter ordering, we just can't make it a MUST because of compatibility. In fact, without this SHOULD, the behavior is already inherently implementation-defined.(paging @karenetheridge for implementor feedback)