OAS 3.2: querystring

[philsturgeon]

Explain what querystring is about, why its different from query, and how it works.

Adapt understanding-structure/parameter-serialization.md and make it all make sense in a 3.2 world.

[philsturgeon]

Notes written by Henry Andrews in OpenAPI Slack chat.

in: querystring lets you model the URL's query string the same way you model an application/x-www-form-urlencoded request body.

That's it. That's all it is. It does this by letting you use the content field to apply a Media Type Object (and optional Encoding Objects) to the whole query string at once.

The reason to do that is that now you can model the whole query string with one schema. You can re-use and combine sets of query parameters with allOf. you can make them conditional with if/then/else or oneOf etc. You can forbid unexpected parameters with additionalProperties: false (although the wisdom of doing so has been hotly debated).

In terms of implementations, there is very little to it- if you already support application/x-www-form-urlencoded request bodies under a Request Body Object, you just apply that to a Parameter Object. You are not allowed to use both in: querystring and in: query at the same time, and in: querystring only works with content to avoid having two layers of style/explode in play at once. It's literally "take your form request body implementation and put it in the URI." (edited)

This also means that you can define your own media type. So all of the people with extremely complicated "deep object"-esque ways of mapping data structures can make up a media type and define how it works and register it, and if any become really popular we can add them to a future OAS version. For example, I know there's one based on jq that at least one major vendor has implemented.