Updates to OpenAPI 3.2 Guide

src/_data/sidebars/guides/openapi/v3-2.yml

@@ -19,7 +19,7 @@ resources:
         link: /understanding-structure/api-servers/
       - label: Paths and Operations
         link: /understanding-structure/paths-operations/
-      - label: Parameters (Path, Query, Header, and Cookie)
+      - label: HTTP Parameters
         link: /understanding-structure/parameters/
       - label: Parameter Serialization
         link: /understanding-structure/parameter-serialization/

src/_guides/openapi/openapi-format-overlays.md

@@ -30,7 +30,7 @@ Figuring out how to do all of this just from staring into an empty text editor c
 
 Copy in some OpenAPI into the box on the left. If you don’t have any handy why not use the [Train Travel API](https://github.com/bump-sh-examples/train-travel-api) by Bump.sh.
 
-![](images/guides/openapi-format-overlays/new-openapi-in-playground.png)
+![](/images/guides/openapi-format-overlays/new-openapi-in-playground.png)
 
 ### Step 2 - Open the Overlay section
 

src/_guides/openapi/specification/v3.1/documentation/grouping-operations-with-tags.md

@@ -152,7 +152,7 @@ When you generate API documentation, you'll notice the documentation orders the
 ![How tags are ordered in generated API documentation](/images/guides/tags_order.png)
 [*See it live*](https://bump.sh/demo/doc/bump)
 
-Note that [Bump.sh helps you order your endpoints and webhooks](/help/specifications-support/openapi-support/name-and-sort-resources/#group-by-tag) using a "Group by tag" operation. It is actually the default behaviour of Bump.sh when you have these tags defined and have not selected an other sorting option for your Bump.sh API documentation.
+Note that [Bump.sh helps you order your endpoints and webhooks](/help/specifications-support/openapi-support/name-and-sort-resources/#group-by-tag) using a "Group by tag" operation. It is actually the default behavior of Bump.sh when you have these tags defined and have not selected an other sorting option for your Bump.sh API documentation.
 
 Now that you understand what tags are and their benefits, you'll see some best practices you should follow when using OpenAPI tags in API contracts.
 

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

@@ -200,9 +200,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
 
@@ -223,13 +223,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. 
 
@@ -247,9 +247,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
 
@@ -429,7 +429,7 @@ 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.  

src/_guides/openapi/specification/v3.2/advanced/callbacks-webhooks.md

@@ -103,7 +103,7 @@ Content-Type: application/json
 }
 ```
 
-The callbackURL could be in headers or could be composed of various other bits of data in the request, take a look at OpenAPI v3.1's [runtime expressions](https://spec.openapis.org/oas/v3.1.0#runtime-expressions) syntax to get more advanced.
+The callbackURL could be in headers or could be composed of various other bits of data in the request, take a look at OpenAPI's [runtime expressions](https://spec.openapis.org/oas/v3.1.0#runtime-expressions) syntax to get more advanced.
 
 Once you've got a callback named and figured out where the URL is going, the rest of the OpenAPI is going to feel very familiar, only it's backwards.
 

src/_guides/openapi/specification/v3.2/advanced/error-formats.md

@@ -1,7 +1,7 @@
 ---
 title: Handling Error Formats
 authors: phil
-excerpt: Describing HTTP errors efficiently in OpenAPI v3.1.
+excerpt: Describing HTTP errors efficiently in OpenAPI v3.2.
 date: 2024-08-07
 ---
 

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/advanced/multipart-form-data.md

@@ -169,7 +169,7 @@ requestBody:
                 type: integer
 ```
 
-Take a look at the OpenAPI v3.1 Specification to learn more about the [Encoding Object](https://spec.openapis.org/oas/v3.1.0#encoding-object), and see how to handle custom headers and even "styles" and "explode" to handle complex data expressed in a string form.
+Take a look at the OpenAPI v3.2 Specification to learn more about the [Encoding Object](https://spec.openapis.org/oas/v3.2.0#encoding-object), and see how to handle custom headers and even "styles" and "explode" to handle complex data expressed in a string form.
 
 > Multipart form data is only one way to handle file uploads, so read the [File Uploads](_guides/openapi/specification/v3.2/advanced/file-uploads.md) guide to see other ways to do it.
 {: .info }

src/_guides/openapi/specification/v3.2/advanced/security.md

@@ -13,7 +13,7 @@ OpenAPI uses the term "security scheme" to cover both authentication and authori
 - **Authentication:** Who is this user, are they who they say they are.
 - **Authorization:** What data can this user see, what actions can they take.
 
-OpenAPI v3.1 lets you describe APIs protected using the following security schemes:
+OpenAPI lets you describe APIs protected using the following security schemes:
 
 - HTTP authentication schemes (anything using the `Authorization` header)
   - Basic
@@ -207,7 +207,7 @@ In this example, the `/bookings` path requires the `OAuth2ReadWrite` security sc
 
 OpenID Connect is an identity layer built on top of OAuth 2.0 that allows clients to verify the identity of end-users based on the authentication performed by an authorization server. It provides a standardized way to authenticate users and obtain their identity information, such as name, email, and profile picture.
 
-In OpenAPI v3.1, you can describe OpenID Connect authentication using the following example:
+In OpenAPI v3.x, you can describe OpenID Connect authentication using the following example:
 
 ```yaml
 OpenIDConnect:
@@ -324,7 +324,7 @@ All other paths will continue to be secured regardless of what order they're in.
 
 You might have noticed the empty array showing up: `HttpBearerToken: []`. This empty array is where "scopes" go.
 
-Scopes allow you to define fine-grained permissions within some types of security schema that support them, and in OpenAPI v3.1 that means OAuth 2 and OpenID Connect. 
+Scopes allow you to define fine-grained permissions within some types of security schema that support them, and in OpenAPI v3.x that means OAuth 2 and OpenID Connect. 
 
 Each security scheme can have its own set of scopes, which can be used to control access to specific resources or actions. 
 

src/_guides/openapi/specification/v3.2/data-models/examples.md

@@ -20,7 +20,7 @@ There are three main types of examples:
 
 ## Schema Examples
 
-The [schema object](_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md) is used all over in OpenAPI, for requests and responses, parameters, and headers. A schema in OpenAPI v3.1 can add an example for an entire schema, part of a schema, or a single specific property, which is either confusing or flexible, depending on how you see the world.
+The [schema object](_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md) is used all over in OpenAPI, for requests and responses, parameters, and headers. A schema in OpenAPI v3.x can add an example for an entire schema, part of a schema, or a single specific property, which is either confusing or flexible, depending on how you see the world.
 
 Here's an example of the `examples` keyword being used for specific properties inside an object.
 
@@ -97,7 +97,7 @@ For more on these schema examples, head over to the [Learn JSON Schema: Examples
 
 ## Media Type Examples
 
-The [Media Type Object](https://spec.openapis.org/oas/v3.1.0#media-type-object) is the same object that defines the request body and each response underneath the `application/json` or whichever other content type is being defined. 
+The [Media Type Object](https://spec.openapis.org/oas/v3.2.0#media-type-object) is the same object that defines the request body and each response underneath the `application/json` or whichever other content type is being defined. 
 
 This type of example allows you to create an entire request or response example, and you have a choice between two two keywords: `example` or `examples`. There is more than just an `s` difference between these keywords, they're different shapes too. `example` is singular example which just contains the actual example value.
 
@@ -176,7 +176,7 @@ The summary name is optional, but is a great place to put human readable names i
 
 ![](/images/changelog/multiple_examples.jpg)
 
-Notice that these examples are all defined _next_ to the `schema` keyword, not _inside_ it. Examples outside the schema object are an object with names, examples inside the schema object are just a list (array) which have no names. For clarity you can check the OpenAPI v3.1 Specification, looking at the [Media Type Object](https://spec.openapis.org/oas/v3.1.0#media-type-object) and the [Schema Object](https://spec.openapis.org/oas/v3.1.0#schema-object).
+Notice that these examples are all defined _next_ to the `schema` keyword, not _inside_ it. Examples outside the schema object are an object with names, examples inside the schema object are just a list (array) which have no names. For clarity you can check the OpenAPI v3.2 Specification, looking at the [Media Type Object](https://spec.openapis.org/oas/v3.2.0#media-type-object) and the [Schema Object](https://spec.openapis.org/oas/v3.2.0#schema-object).
 
 Here's a quick example of all the examples so you know where to start.
 
@@ -200,7 +200,7 @@ requestBody:
 
 ## Parameter Examples
 
-The OpenAPI v3.1 Parameter Object describes path parameters, query parameters, headers, etc. Since OpenAPI v3.0 They can have `examples` or an `example`, which work the same as the media type examples. They can also have a `schema`, which means they can have schema `examples` just like we talked about above.
+The OpenAPI v3.2 Parameter Object describes path parameters, query parameters, headers, etc. Since OpenAPI v3.0 They can have `examples` or an `example`, which work the same as the media type examples. They can also have a `schema`, which means they can have schema `examples` just like we talked about above.
 
 ```yaml
 /params:
@@ -254,7 +254,7 @@ Some mocking tools [like Microcks][microcks] might prefer you use named examples
 
 ## Example of All Examples
 
-Let's go on an adventure through all the types of examples available in OpenAPI v3.1, with a bunch of Adventure Time characters with random coordinates of their last known locations.
+Let's go on an adventure through all the types of examples available in OpenAPI v3.2, with a bunch of Adventure Time characters with random coordinates of their last known locations.
 
 ```yaml
 openapi: 3.2.0
@@ -344,3 +344,7 @@ What are we trying to achieve in doing this? We want the docs and mocks to have
 This lets tools know that false is the default state for this property, which will make documentation more clear, help mock servers act more consistently, and can even make any code generated from OpenAPI work as expected.
 
 The `default` keyword is therefore quite similar to `examples` within a schema object, as it can introduce concrete values into the schema which can be used for all sorts of tooling, but it's more functional.
+
+
+
+<!-- NEW EXAMPLE KEYWORDS -->

src/_guides/openapi/specification/v3.2/data-models/schema-and-data-types.md

@@ -10,7 +10,7 @@ date: 2025-05-16
 
 One of the most important parts of OpenAPI is the `schema` object. Schema objects are used to describe HTTP request and response bodies, parameters, headers, and all sorts of other data, whether its JSON, XML, or primitive types like integers and strings. 
 
-> If you're familiar with JSON Schema, you'll be right at home here, because OpenAPI v3.1 uses JSON Schema (draft 2020-12). For those who have not used JSON Schema before, that's ok, follow along.
+> If you're familiar with JSON Schema, you'll be right at home here, because OpenAPI v3.1 onward is compatible with JSON Schema. For those who have not used JSON Schema before, that's ok, follow along.
 {: .info }
 
 The first thing to learn about a schema is the `type` keyword, which can be one or more of the following types:
@@ -102,7 +102,7 @@ items:
       format: int32
 ```
 
-The full list of formats defined in the JSON Schema Validation that OpenAPI v3.1 relies upon:
+The full list of formats defined in the JSON Schema Validation that OpenAPI v3.2 uses:
 
 - date-time: A string instance is valid against this attribute if it is a valid representation according to the "date-time" production as defined in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339).
 

src/_guides/openapi/specification/v3.2/data-models/schema-composition.md

@@ -8,7 +8,7 @@ date: 2025-07-24
 - TOC
 {:toc}
 
-In OpenAPI v3.1 and JSON Schema, you can use `oneOf`, `allOf`, and `anyOf` keywords to handle composition, which is the concept of combining multiple schemas and subschemas in various ways to handle polymorphism, or "extending" other schemas to add more criteria.
+From OpenAPI v3.1, you can use the JSON Schema keywords `oneOf`, `allOf`, and `anyOf` to handle composition, which is the concept of combining multiple schemas and subschemas in various ways to handle polymorphism, or "extending" other schemas to add more criteria.
 
 ## What are oneOf, anyOf, and allOf?
 
@@ -161,4 +161,4 @@ content:
               $ref: '#/components/schemas/Links-Self'
 ```
 
-These schema composition keywords provide flexibility and allow you to define complex data structures and validation rules in OpenAPI v3.1 and JSON Schema, which becomes more useful as you start to [improve reuse across one or more API](_guides/openapi/specification/v3.2/advanced/splitting-documents-with-ref.md).
+These schema composition keywords provide flexibility and allow you to define complex data structures and validation rules in OpenAPI and JSON Schema, which becomes more useful as you start to [improve reuse across one or more API](_guides/openapi/specification/v3.2/advanced/splitting-documents-with-ref.md).