OAS 3.2: HTTP QUERY, querystring, and Learn OpenAPI links

Author: philsturgeon

src/_guides/openapi/specification/v3.2/advanced/json-streaming.md

@@ -348,4 +348,5 @@ Whatever the schema is, it can be defined using the standard JSON Schema keyword
 
 ## Further Reading
 
-You can find details in the **OpenAPI Specification v3.2.0** under [Media Types Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md#media-type-object) and look for `itemSchema`.
+- [Learn OpenAPI: Sequential Media Types](https://learn.openapis.org/specification/media-types.html)
+- [OpenAPI Specification v3.2.0: Media Types Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md#media-type-object)

src/_guides/openapi/specification/v3.2/understanding-structure/http-requests.md

@@ -8,12 +8,27 @@ date: 2025-07-09
 - TOC
 {:toc}
 
-Any API handling use-cases more advanced that purely fetching data will need to define a HTTP request body. `POST`, `PATCH`, `PUT`, `QUERY`, etc. all allow a HTTP client to send a body: often JSON or XML. This allows for more information to be sent rather than just query string parameters, which have limits.
+HTTP requests are a fundamental part of any API. They allow clients to send data to the server, whether that’s creating new resources, updating existing ones, or performing complex queries.
 
-The request body can be used for:
+OpenAPI 3.x provides a robust way to define these requests, and OpenAPI v3.2 introduces even more capabilities to handle a wider range of scenarios.
+
+Supported HTTP Methods: 
+
+- `GET`
+- `PATCH`
+- `POST`
+- `PUT`
+- `DELETE`
+- `HEAD`
+- `OPTIONS`
+- `TRACE`
+- `QUERY`
+- Additional custom methods via `additionalOperations`
+
+The HTTP request can also include a body: usually JSON or XML. The request body can be used for:
 
 - Creating new resources (e.g.: booking a train ticket)
-- Updating existing resources (e.g.: updating that booking)
+- Updating existing resources (e.g.: updating or cancelling that booking)
 - Uploading files (e.g.: uploading an image to your railcard)
 
 ## Structure of Request Bodies
@@ -63,7 +78,6 @@ paths:
 Here the `requestBody` object defines two important properties:
 
 - `required: true` - indicates that the request body is mandatory for this operation.
-
 - `content` - specifies that the request body should be in `application/json` format with the following `schema`.
 
 The schema defines the structure of the request body, including properties like `passenger_name`, `train_id`, `date`, and `seat_preference`. This can be defined inline like this, or it can use `components` to share an [existing schema](_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md) and reduce repetition.
@@ -104,6 +118,98 @@ The `schema` then defines the structure of the request body, which demonstrates
 
 If multiple properties could be updated, you would define all the properties that could be updated, then show off some [examples](_guides/openapi/specification/v3.2/data-models/examples.md) for common use-cases of things users might want to do.
 
+## Query Requests
+
+OpenAPI 3.2 adds native support for the `QUERY` HTTP method, which is designed to support complex queries that don’t fit neatly in URL query strings.
+
+Prior to the HTTP Query method it was common for people to add infinite query string parameters like  `?origin=london&destination=paris&has_dogs=true`, or to try and create some sort of query syntax using a standard or home-grown DSL like `?filter=origin:london,destination:paris,has_dogs:true`, but these syntaxes struggle when it comes to `is null`, `not null`, or `>=10`. Putting the query into the body allows for more advanced structures using JSON for example.
+
+```yaml
+paths:
+  /products:
+    query:
+      summary: Product search
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                filter:
+                  type: object
+                  required: [field, value]
+                  properties: 
+                    field:
+                      type: string
+                      examples: [id]
+                    value:
+                      type: string
+                      examples: [abc123]
+                    operator:
+                      type: string
+                      example: "!="
+                sort:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '200':
+          description: Search results
+```
+
+Within a simple structure like this, searching and filtering can be handled with a more useful 
+
+```http
+QUERY /feed 
+Content-Type: application/json
+
+{ 
+   "q": "foo", 
+   "limit": 10, 
+   "sort": "-published", 
+   "filter": [
+    {
+      "field": "origin",
+      "value": "london"
+    },
+    { 
+      "field": "destination",
+      "value": "paris"
+    },
+    {
+      "field": "price",
+      "value": "60.00",
+      "operator": "<="
+    }
+}
+```
+
+## Additional HTTP Methods
+
+Use `additionalOperations` for HTTP methods not covered by standard OpenAPI operations. 
+
+For example, maybe an API is using the `PURGE` HTTP method to remove cached resources from the an API behind a cache proxy like [Varnish](https://varnish-cache.org/docs/3.0/tutorial/purging.html).
+
+```yaml
+paths:
+  /tickets/{ticketId}:
+    parameters:
+      - name: ticketId
+        in: path
+        required: true
+        schema:
+          type: string
+    additionalOperations:
+      PURGE:
+        summary: Purge a ticket from the cache
+        responses:
+          '204':
+            description: Ticket purged from cache
+```
+
+This allows for full support of any HTTP method you can think of, allowing OpenAPI v3.2 to go beyond only supporting the core HTTP methods.
+
 ## File Uploads & Multipart Forms
 
 HTTP requests can also cover more advanced scenarios like [file uploads](_guides/openapi/specification/v3.2/advanced/file-uploads.md) and [multipart form data](_guides/openapi/specification/v3.2/advanced/multipart-form-data.md), which have their own guides in the advanced section.

src/_guides/openapi/specification/v3.2/understanding-structure/parameter-serialization.md

@@ -8,7 +8,7 @@ date: 2024-07-04
 - TOC
 {:toc}
 
-[Parameters](_guides/openapi/specification/v3.2/understanding-structure/parameters.md) not only define what inputs your API accepts, they also define the format your API expects to receive them in, i.e. how you would like it serialized.
+[Parameters](_guides/openapi/specification/v3.2/understanding-structure/parameters.md) not only define what inputs your API accepts, they also define the format your API expects to receive them in, i.e. how those parameters should serialized.
 
 There are two keywords concerning serialization:
 
@@ -199,9 +199,9 @@ This conflict is entirely avoided if you explicitly set `explode:false` on param
 
 It's basically identical to `style:form` with `explode:false`. The difference being, the separator used is not a comma, but a percent-encoded space "%20".
 
-You'll notice there are no examples for any `type` that would be a single value. This is because its behaviour is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`.
+You'll notice there are no examples for any `type` that would be a single value. This is because its behavior is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`.
 
-`style:spaceDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behaviour for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default.
+`style:spaceDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behavior for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default.
 
 ### Pipe Delimited
 
@@ -222,13 +222,13 @@ If you still choose to use non-percent-encoded pipes, it would look like this:
 | ?pets=cat\|dog             | ?pets=age\|2\|type\|dog                   |
 | ?pets=cat\|dog&hats=fedora | ?pets=age\|2\|type\|dog&hats=type\|fedora |
 
-You'll notice there are no examples for any `type` that would be a single value. This is because its behaviour is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`.
+You'll notice there are no examples for any `type` that would be a single value. This is because its behavior is undefined for single values. One could assume it would be identical to `style:form`, but if your parameter is going to be a single value, there is no need to explicitly define it as `spaceDelimited`.
 
-`style:pipeDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behaviour for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default.
+`style:pipeDelimited` is not defined by [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750) and there is no defined behavior for `explode:true`. You could assume it would be identical to the well-defined `in:query` default of `style:form` with `explode:true`. That said, if you're making that assumption, you're better off leaving it on the well-defined default.
 
 ### Deep Object
 
-`style:deepObject` is undefined for its default of `explode:false`. You must explicitly specify `explode:true` for any defined behaviour.
+`style:deepObject` is undefined for its default of `explode:false`. You must explicitly specify `explode:true` for any defined behavior.
 
 You may be able to use a normal square brackets "[" and "]" but they are in the list of [RFC3986's Reserved Characters](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2). As such, it may not work in some environments. 
 
@@ -246,9 +246,9 @@ For maximum interoperability it is safer to have them percent-encoded:
 | ?pets%5Bage%5D=2&pets%5Btype%5D=dog                       |
 | ?pets%5Bage%5D=2&pets%5Btype%5D=dog&hats%5Btype%5D=fedora |
 
-Unsurprisingly, it only has defined behaviour for an `object`. This `style` is quite different from any other, even with `explode:true` the `name`, key and value are all specified. This makes it useful for avoiding the potential name conflicts objects could cause with `style:form`, `explode:true`. 
+Unsurprisingly, it only has defined behavior for an `object`. This `style` is quite different from any other, even with `explode:true` the `name`, key and value are all specified. This makes it useful for avoiding the potential name conflicts objects could cause with `style:form`, `explode:true`. 
 
-Just bear in mind the name is misleading, despite being called a `deepObject`, there is no defined behaviour for nested arrays or objects. This is the same for every `style` `in:query`.
+Just bear in mind the name is misleading, despite being called a `deepObject`, there is no defined behavior for nested arrays or objects. This is the same for every `style` `in:query`.
 
 ## Header Parameters
 
@@ -428,8 +428,14 @@ Now our URL will look like this:
 Here I've stated that my `schema` can be `anyOf` the following: an object or a string, in `style:deepObject`. You may have spotted the problem already:
 
 - If our user specifies an object, this works as expected: `/trips?station[preferred]=gatwick&station[fallback]=london`.  
-- What if our user specifies a string? It's undefined, `deepObject` only has defined behaviour for objects.
+- What if our user specifies a string? It's undefined, `deepObject` only has defined behavior for objects.
 
 You cannot apply `style` on a per-`schema` basis. Your `style` needs to work for all possible variations of your parameter.  
 If you intend to use `anyOf`, `allOf` or `oneOf` make doubly sure your choice of `style` works for every option.  
 As always, the best option is to minimise your use of complex parameters, keep it simple.
+
+### Switching DeepObject to Querystring Parameters
+
+In OpenAPI v3.2, a new parameter location was added: `in: querystring` to help avoid complexity in `deepObject` parameters. Instead of trying to fit everything into a single parameter, you can now define multiple parameters in the querystring using the same `schema`, which can even have different content types.
+
+**Learn more about [Querystring Parameters](_guides/openapi/specification/v3.2/understanding-structure/parameters.md#querystring-parameters).**

src/_guides/openapi/specification/v3.2/understanding-structure/parameters.md

@@ -17,13 +17,21 @@ Parameters fall into one of a few types:
 - **Header Parameters:** Included in the request header, e.g., `Acme-Custom-Header: Value`.
 - **Cookie Parameters:** Passed in the request cookies.
 
-> In previous versions of OpenAPI the entire request body and form data would all be sent as parameters, but since OpenAPI v3.0 this has been moved to the content object. Learn more in [HTTP Requests](_guides/openapi/specification/v3.2/understanding-structure/http-requests.md).
-{: .info }
-
 Each parameter in OpenAPI is defined with specific attributes such as `name`, `in` (location), `required`, `description`, and `schema` (for defining data types and validation rules). Defining parameters with these keywords allows documentation to show example how HTTP requests should be constructed making life easier for the client, but also make sure machines know what to do with it, making SDKs and server-side validation a whole lot more powerful.
 
+
 ## Parameter Types
 
+There are four main types of parameters in OpenAPI v3.1, each serving a different purpose in the context of an HTTP request.
+
+- Path Parameters - `in: path`
+- Query Parameters -`in: query`
+- Header Parameters - `in: header`
+- Cookie Parameters - `in: cookie`
+- OpenAPI 3.2 also added Querystring Parameters `in: querystring`
+
+That new addition is a little confusing as the names are so similar, but we'll cover that in a bit.
+
 ### Path Parameters
 
 The first type of parameter to get the hang of is path parameters.
@@ -154,6 +162,71 @@ paths:
             example: 5
 ```
 
+### Querystring Parameters
+
+OpenAPI v3.2 added support for a new type of parameter called `querystring` parameters. These are similar to query parameters, but they allow for more complex structures to be sent in the query string.
+
+Unlike `in: query`, with `in: querystring` the entire query string is treated as a single parameter with complex structure. This means that combinations of query parameters can be expressed using a well-defined Schema object:
+
+```yaml
+paths:
+  /search:
+    get:
+      parameters:
+      - name: advancedQuery
+        in: querystring
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                filters:
+                  type: object
+                sorting:
+                  type: array
+                  items:
+                    type: string
+```
+
+In HTTP that would look like this:
+
+```http
+GET /search?filters[origin]=london&filters[destination]=paris&filters[has_dogs]=true&sorting[]=price&sorting[]=duration
+```
+
+It also allows for JSON encoded query strings:
+
+```yaml
+paths:
+  /search:
+    get:
+      summary: Search for items
+      parameters:
+        - name: filter
+          in: querystring
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  origin:
+                    type: string
+                  destination:
+                    type: string
+                  has_dogs:
+                    type: boolean
+          
+```
+
+In HTTP that would look like this:
+
+```http
+GET /search?filter={"origin":"london","destination":"paris","has_dogs":true}
+```
+
+Handling advanced query strings like this used to rely on trickery with a combination of [parameter serialization](_guides/openapi/specification/v3.2/understanding-structure/parameter-serialization.md) options most users (and tooling) seemed to struggle with. This new `querystring` parameter type makes it much clearer what is going on, and allows for more complex structures to be expressed in a way that is easier to understand.
+
+Thanks to this new approach giving you the full power of the `schema` keyword, you can re-use and combine sets of query parameters with allOf, you can make them conditional and interdependent with `if`/`then`/`else`, and support [polymorphism with `oneOf`/`anyOf`](_guides/openapi/specification/v3.2/data-models/schema-composition.md). You can even forbid unexpected parameters with `additionalProperties: false` if you want to be strict about what is allowed.
 
 ## Defining Parameters for Multiple Operations