From de685300c760e095d4cb70f827a8f91d557cd4d1 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Sun, 14 Sep 2025 18:43:55 +0100 Subject: [PATCH 1/5] Add some notes and upgrade pages for the 3.2 release --- examples/index.md | 2 +- overlay/index.md | 2 +- referencing/index.md | 2 +- specification/http-methods.md | 119 +++++++++++++++++++ specification/media-types.md | 72 +++++++++++ specification/parameters.md | 48 ++++++++ specification/paths.md | 2 +- specification/servers.md | 27 +++++ specification/structure.md | 1 + specification/tags.md | 179 ++++++++++++++++++++++++++++ upgrading/index.md | 25 ++++ upgrading/v3.0-to-v3.1.md | 218 ++++++++++++++++++++++++++++++++++ upgrading/v3.1-to-v3.2.md | 193 ++++++++++++++++++++++++++++++ 13 files changed, 886 insertions(+), 4 deletions(-) create mode 100644 specification/http-methods.md create mode 100644 specification/media-types.md create mode 100644 specification/tags.md create mode 100644 upgrading/index.md create mode 100644 upgrading/v3.0-to-v3.1.md create mode 100644 upgrading/v3.1-to-v3.2.md diff --git a/examples/index.md b/examples/index.md index de34a50..032e604 100644 --- a/examples/index.md +++ b/examples/index.md @@ -1,7 +1,7 @@ --- layout: default title: Example API Descriptions -nav_order: 6 +nav_order: 8 has_children: true has_toc: true --- diff --git a/overlay/index.md b/overlay/index.md index d437d80..128549f 100644 --- a/overlay/index.md +++ b/overlay/index.md @@ -1,6 +1,6 @@ --- layout: default -nav_order: 8 +nav_order: 9 title: Overlays has_children: true has_toc: false diff --git a/referencing/index.md b/referencing/index.md index 9c69bc5..e175a58 100644 --- a/referencing/index.md +++ b/referencing/index.md @@ -1,7 +1,7 @@ --- layout: default title: Using References -nav_order: 5 +nav_order: 7 has_children: true has_toc: false --- diff --git a/specification/http-methods.md b/specification/http-methods.md new file mode 100644 index 0000000..f72c8bf --- /dev/null +++ b/specification/http-methods.md @@ -0,0 +1,119 @@ +--- +layout: default +title: HTTP Methods +parent: The OpenAPI Specification Explained +nav_order: 10 +--- + +# HTTP Methods + +OpenAPI supports describing operations using HTTP methods. This page covers the standard HTTP methods available in all OpenAPI versions, and the enhanced method support introduced in OpenAPI 3.2. + +## Standard HTTP Methods (All Versions) + +OpenAPI has always supported standard HTTP methods as operation keys in path items: + +```yaml +paths: + /users: + get: # Retrieve users + summary: List users + responses: + '200': + description: User list + post: # Create user + summary: Create a new user + responses: + '201': + description: User created + put: # Replace user collection + summary: Replace all users + delete: # Delete users + summary: Delete all users + options: # Get allowed methods + summary: Get allowed methods for users endpoint + head: # Get headers only + summary: Get user list headers + patch: # Update users + summary: Update users + trace: # Diagnostic trace + summary: Trace users endpoint +``` + +Each method corresponds to a specific HTTP verb and follows REST conventions for the expected behavior. + +## Enhanced HTTP Method Support in OpenAPI 3.2 + +### QUERY Method Support +{: .d-inline-block } +OpenAPI 3.2+ +{: .label .label-green } + +OpenAPI 3.2 adds native support for the [QUERY HTTP method](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html), designed for complex queries that don't fit in URL query strings. + +### QUERY Method Example + +```yaml +# OpenAPI 3.2 +paths: + /products: + query: + summary: Advanced product search + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + filter: + type: object + sort: + type: array + items: + type: string + responses: + '200': + description: Search results +``` + +### Additional Operations for Custom Methods +{: .d-inline-block } +OpenAPI 3.2+ +{: .label .label-green } + +Use `additionalOperations` for HTTP methods not covered by standard OpenAPI operations: + +### Additional Operations Example + +Add the method names in upper case, any supported HTTP method name can be used. + +```yaml +# OpenAPI 3.2 +paths: + /documents/{id}: + additionalOperations: + LINK: + summary: Link related documents + parameters: + - name: id + in: path + required: true + schema: { type: string } + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + targetDocument: + type: string + relationship: + type: string + responses: + '204': + description: Link created successfully +``` + +This approach makes it easier to adopt new methods as the HTTP landscape evolves. diff --git a/specification/media-types.md b/specification/media-types.md new file mode 100644 index 0000000..2ac5ff4 --- /dev/null +++ b/specification/media-types.md @@ -0,0 +1,72 @@ +--- +layout: default +title: Sequential Media Types +parent: The OpenAPI Specification Explained +nav_order: 11 +--- + +# Sequential Media Types +{: .d-inline-block } +OpenAPI 3.2+ +{: .label .label-green } + +OpenAPI 3.2 introduces support for sequential and streaming media types, enabling description of data streams where individual items arrive over time. + +## New Schema Field: itemSchema + +The key addition is the `itemSchema` field, which describes the structure of a repeated item in a response: + +```yaml +# OpenAPI 3.2 +responses: + '200': + description: Stream of updates + content: + text/event-stream: + itemSchema: + type: object + properties: + id: { type: string } + data: { type: object } +``` + +## Supported Sequential Media Types + +OpenAPI 3.2 adds support for several streaming formats: + +- **Server-Sent Events**: `text/event-stream` +- **JSON Lines**: `application/jsonl` +- **JSON Sequences**: `application/json-seq` +- **Multipart Mixed**: `multipart/mixed` + +## Enhanced Multipart Support + +OpenAPI 3.2 introduces new encoding fields for multipart content: + +### itemEncoding + +Applies encoding to each item in a sequence: + +```yaml +# OpenAPI 3.2 +content: + multipart/form-data: + itemEncoding: + file: + contentType: application/octet-stream +``` + +### prefixEncoding + +Specifies encoding for items by position: + +```yaml +# OpenAPI 3.2 +content: + multipart/mixed: + prefixEncoding: + - contentType: application/json + - contentType: text/html +``` + +Sequential media type support in OpenAPI 3.2 enables documentation of streaming and real-time APIs using the `itemSchema` field to describe individual items in data streams. diff --git a/specification/parameters.md b/specification/parameters.md index 3ff84e9..08c50d0 100644 --- a/specification/parameters.md +++ b/specification/parameters.md @@ -70,8 +70,38 @@ Parameters can reside in different locations, indicated by the `in` field. The m in: query ``` + > **NOTE**: + > If any parameters are `in: query`, then `in: querystring` cannot be used. + +- `querystring` (OpenAPI 3.2+): The entire query string is treated as a single parameter with complex structure: + + ```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 + ``` + + > **NOTE**: + > `in: querystring` cannot be combined with `in:query`. + - `header`: The parameter is sent in a custom HTTP header as part of the request. Header names are **case-insensitive**. +- `cookie`: The parameter is sent in a cookie header as part of the request. + ### Parameter Type Most of the time a parameter's type can be specified by using a [Schema Object](https://spec.openapis.org/oas/v3.1.0#schemaObject) in the `schema` field. Schema objects allow defining primitive or complex types (like arrays or objects) and impose additional restrictions on them. For example: @@ -97,6 +127,24 @@ In more advanced scenarios the `content` field can be used instead. It provides The `style` field describes how a parameter is to be serialized and its effect depends on the **type** of the parameter. The resulting matrix is therefore rather complex and can be consulted in the [Parameter Object](https://spec.openapis.org/oas/v3.1.0#style-examples) specification page. +OpenAPI 3.2 adds the `cookie` style for more accurate cookie parameter descriptions: + +```yaml +# OpenAPI 3.2 +paths: + /dashboard: + get: + parameters: + - name: preferences + in: cookie + style: cookie # New in 3.2 + schema: + type: object + properties: + theme: { type: string } + language: { type: string } +``` + The tables given below exemplify the most common styles `simple`, `form`, `label`, and `matrix`: - **Primitive types**: For example, an integer named `id` with value 1234. diff --git a/specification/paths.md b/specification/paths.md index 86f8104..edf6622 100644 --- a/specification/paths.md +++ b/specification/paths.md @@ -39,7 +39,7 @@ paths: ## The Path Item Object -The [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object) describes the HTTP operations that can be performed on a path with a separate [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object) for each one. Allowed operations match HTTP method names like `get`, `put` or `delete`, to list the most common (find the complete list in the [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object) specification). +The [Path Item Object](https://spec.openapis.org/oas/v3.1.0#path-item-object) describes the HTTP operations that can be performed on a path with a separate [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object) for each one. Allowed operations match HTTP method names like `get`, `put` or `delete`, to list the most common. For complete details about HTTP methods in OpenAPI, see the [HTTP Methods](http-methods) page. This object also accepts common properties for all operations on the path like `summary` or `description`. The details of each operation are given in each child Operation object. diff --git a/specification/servers.md b/specification/servers.md index 7e11484..be8dcad 100644 --- a/specification/servers.md +++ b/specification/servers.md @@ -30,6 +30,33 @@ servers: description: Server located in Shenzhen ``` +## Enhanced Server Fields +{: .d-inline-block } +OpenAPI 3.2+ +{: .label .label-green } + +OpenAPI 3.2 adds a `name` field to Server Objects for easier identification and reference: + +```yaml +servers: +- name: Production + url: https://api.example.com/v1 + description: Production server for live traffic +- name: Staging + url: https://staging-api.example.com/v1 + description: Staging environment for testing +- name: Development + url: http://localhost:3000/v1 + description: Local development server +``` + +The `name` field is particularly useful for: +- **Tool integration** - Development tools can reference servers by name +- **Documentation clarity** - Clear identification in API documentation +- **Environment switching** - Easy server selection in API clients +- **Configuration management** - Named references in deployment scripts + + Individual API endpoints (as specified in the [Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object)) are then appended to this URL to construct the full endpoint URL. For example: ```yaml diff --git a/specification/structure.md b/specification/structure.md index cf87a14..25995fd 100644 --- a/specification/structure.md +++ b/specification/structure.md @@ -80,6 +80,7 @@ The OAS structure is long and complex so this section just describes the minimal The root object in any OpenAPI Description is the [OpenAPI Object](https://spec.openapis.org/oas/v3.1.0#openapi-object), and only two of its fields are mandatory: `openapi` and `info`. Additionally, at least one of `paths`, `components` and `webhooks` is required. * `openapi` (**string**): This indicates the version of the OAS this OAD is using, e.g. "3.1.0". Using this field tools can check that the description correctly adheres to the specification. +* `$self` (**string**, OpenAPI 3.2+): Provides the canonical URI for the document itself, used as the base URI for resolving relative references. This field is optional. * `info` ([Info Object](https://spec.openapis.org/oas/v3.1.0#info-object)): This provides general information about the API (like its description, author and contact information) but the only mandatory fields are `title` and `version`. * `title` (**string**): A human-readable name for the API, like "GitHub REST API", useful to keep API collections organized. * `version` (**string**): Indicates the version **of the API description** (not to be confused with the OAS version above). Tools can use this field to generate code that ensures that clients and servers are interacting through the same version of the API, for example. diff --git a/specification/tags.md b/specification/tags.md new file mode 100644 index 0000000..c72c540 --- /dev/null +++ b/specification/tags.md @@ -0,0 +1,179 @@ +--- +layout: default +title: Enhanced Tags +parent: The OpenAPI Specification Explained +nav_order: 9 +--- + +# Enhanced Tags +{: .d-inline-block } +OpenAPI 3.2+ +{: .label .label-green } + +Tags provide a way to group and organize operations in your API documentation. OpenAPI 3.2 significantly enhances tag functionality with hierarchical organization, classification, and improved display options. + +## Basic Tag Usage (All Versions) + +Tags have been available since OpenAPI 2.0 for basic operation grouping: + +```yaml +openapi: 3.1.0 +tags: + - name: users + description: User management operations + - name: orders + description: Order processing operations + +paths: + /users: + get: + tags: [users] + summary: List users +``` + +## Enhanced Tags in OpenAPI 3.2 + +OpenAPI 3.2 introduces powerful new fields that make tags more useful for API organization and navigation. + +### New Tag Fields + +#### Summary Field + +The `summary` field provides a short display name for tags, useful in navigation and lists. This replaces the need for the `x-displayName` extension: + +```yaml +# OpenAPI 3.2 +tags: + - name: user-management + summary: Users + description: Complete user lifecycle management including registration, authentication, and profile management +``` + +#### Parent Field for Hierarchical Organization + +Create tag hierarchies using the `parent` field, which enables a tag to be nested inside another tag. +If you used the `x-tagGroups` extension in OpenAPI < 3.2, nesting provides a first-class way to build a tags structure. + +```yaml +# OpenAPI 3.2 +tags: + - name: products + summary: Products + description: All product-related operations + + - name: cakes + summary: Cakes + description: Cake catalog and customization + parent: products + + - name: pastries + summary: Pastries + description: Pastries and small baked goods + parent: products + + - name: seasonal-cakes + summary: Seasonal + description: Limited-time seasonal cake offerings + parent: cakes +``` + +#### Kind Field for Tag Classification + +The `kind` field allows you to use different sets of tags for different purposes. +The goal here is to enable arbitrary grouping and labeling of endpoints, for multiple use cases. + +```yaml +# OpenAPI 3.2 +tags: + - name: products + summary: Products + description: Core product operations + kind: nav + + - name: deprecated-v1 + summary: Legacy V1 + description: Deprecated version 1 endpoints + kind: lifecycle + + - name: beta-features + summary: Beta + description: Experimental features + kind: lifecycle + + - name: mobile-optimized + summary: Mobile + description: Mobile-optimized endpoints + kind: device +``` + +See the [Tag Kind Registry](https://spec.openapis.org/registry/tag-kind/index.html) for values commonly used with tags and generally supported by tooling. +However this field is free text, so you can extend its use as you need to. + +### Complete Enhanced Tags Example + +```yaml +openapi: 3.2.0 +info: + title: Bakery API + version: 2.0.0 + +tags: + # Main navigation categories + - name: products + summary: Products + description: All bakery product operations + kind: nav + + - name: orders + summary: Orders + description: Order management and tracking + kind: nav + + # Product subcategories + - name: cakes + summary: Cakes + description: Custom cakes and layer cakes + parent: products + kind: nav + + - name: breads + summary: Breads + description: Artisan breads and rolls + parent: products + kind: nav + + # Special categories + - name: seasonal + summary: Seasonal + description: Limited-time seasonal offerings + kind: badge + externalDocs: + description: Seasonal menu planning + url: https://docs.bakery.com/seasonal + +paths: + /cakes: + get: + tags: [cakes] + summary: List available cakes + + /cakes/seasonal: + get: + tags: [cakes, seasonal] + summary: List seasonal cake offerings + + /orders/wholesale: + post: + tags: [orders, wholesale] + summary: Create wholesale order +``` + +## Best Practices + +1. **Use hierarchical organization** for complex APIs with many operations +2. **Provide summary fields** for all tags to improve navigation clarity +3. **Use consistent kind values** - follow registry conventions +4. **Combine tags thoughtfully** - operations can have multiple tags for cross-cutting concerns +5. **Consider your audience** - use audience-specific tags when serving multiple user types + +Enhanced tags in OpenAPI 3.2 provide powerful tools for creating well-organized, navigable API documentation that scales with your API's complexity. diff --git a/upgrading/index.md b/upgrading/index.md new file mode 100644 index 0000000..321b49d --- /dev/null +++ b/upgrading/index.md @@ -0,0 +1,25 @@ +--- +layout: default +title: Upgrading Between Versions +nav_order: 6 +has_children: true +has_toc: false +--- + +# Upgrading Between Versions + +As the OpenAPI Specification evolves, new versions are released that add features, improve clarity, and enhance functionality. This section provides guidance on upgrading your OpenAPI descriptions between versions. + +Each version upgrade guide covers: +- Key changes and new features introduced +- Breaking changes to be aware of +- Step-by-step migration instructions +- Common migration scenarios and examples +- Tools and resources to help with the upgrade process + +## Available Upgrade Guides + +- [Upgrading from OpenAPI 3.0 to 3.1](v3.0-to-v3.1): Learn about the significant changes and how to migrate your API descriptions. +- [Upgrading from OpenAPI 3.1 to 3.2](v3.1-to-v3.2): Discover the latest features and migration path for the newest version. + +Choose the appropriate guide based on your current OpenAPI version and target version. diff --git a/upgrading/v3.0-to-v3.1.md b/upgrading/v3.0-to-v3.1.md new file mode 100644 index 0000000..b1ee51d --- /dev/null +++ b/upgrading/v3.0-to-v3.1.md @@ -0,0 +1,218 @@ +--- +layout: default +title: Upgrading from OpenAPI 3.0 to 3.1 +parent: Upgrading Between Versions +nav_order: 1 +--- + +# Upgrading from OpenAPI 3.0 to 3.1 + +OpenAPI 3.1 introduces significant new functionality and improvements. This guide covers the changes required to migrate your OpenAPI 3.0 descriptions to version 3.1. + +## Getting Started + +Begin by updating the version number in your OpenAPI document. Locate this line in your JSON or YAML file: + +```yaml +openapi: 3.0.3 +``` + +Update it to: + +```yaml +openapi: 3.1.1 +``` + +*Note: If your document shows `swagger: 2.0`, you must first upgrade to OpenAPI 3.0 before proceeding.* + +While this version change may appear minor, OpenAPI 3.1 does introduce some breaking changes. These changes were necessary to achieve full compatibility with modern JSON Schema, and their scope is limited to the Schema Object. + +## JSON Schema Alignment + +OpenAPI 3.1 achieves full compatibility with JSON Schema Draft 2020-12. Previously, OpenAPI used a modified subset of JSON Schema that added some features while removing others, creating confusion in the community. + +### Background + +OpenAPI 3.0 was based on JSON Schema Draft 05. Since then, JSON Schema has evolved through Draft 06, Draft 07, and Draft 2019-09. OpenAPI 3.1 aligns with the latest JSON Schema Draft 2020-12, which was finalized based on feedback from the OpenAPI community. + +This alignment provides access to modern JSON Schema features, including tuple validation with item arrays and conditional schemas using if/then/else keywords as alternatives to complex nested allOf/oneOf structures. + +## Required Schema Object Changes + +### Replace nullable with type arrays + +JSON Schema supports multiple types through arrays in the `type` keyword. This functionality makes the OpenAPI-specific `nullable` keyword redundant. + +```yaml +# OpenAPI 3.0 +type: string +nullable: true +``` + +```yaml +# OpenAPI 3.1 +type: +- "string" +- "null" +``` + +This change follows JSON Schema's keyword independence principle, where keywords should only add constraints. + +### Update exclusiveMinimum and exclusiveMaximum + +These keywords now accept direct values instead of boolean modifiers for the `minimum` and `maximum` properties. + +```yaml +# OpenAPI 3.0 +minimum: 7 +exclusiveMinimum: true +``` + +```yaml +# OpenAPI 3.1 +exclusiveMinimum: 7 +``` + +### Change schema example to examples + +Schema objects now use the standard JSON Schema `examples` keyword instead of the OpenAPI-specific singular `example`. + +```yaml +# OpenAPI 3.0 +type: string +example: fedora +``` + +```yaml +# OpenAPI 3.1 +type: string +examples: + - fedora +``` + +This change requires converting the single value to an array format. The benefit is easier support for multiple examples: + +```yaml +type: string +examples: + - fedora + - ubuntu +``` + +### Update file upload descriptions + +JSON Schema's `contentEncoding` and `contentMediaType` keywords provide clearer semantics for file uploads than the previous format-based approach. + +**Binary file uploads:** + +```yaml +# OpenAPI 3.0 +requestBody: + content: + application/octet-stream: + schema: + type: string + format: binary +``` + +```yaml +# OpenAPI 3.1 +requestBody: + content: + application/octet-stream: {} +``` + +**Base64-encoded uploads:** + +```yaml +# OpenAPI 3.0 +requestBody: + content: + image/png: + schema: + type: string + format: base64 +``` + +```yaml +# OpenAPI 3.1 +requestBody: + content: + image/png: + schema: + type: string + contentEncoding: base64 +``` + +**Multipart file uploads:** + +```yaml +# OpenAPI 3.0 +requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + orderId: + type: integer + fileName: + type: string + format: binary +``` + +```yaml +# OpenAPI 3.1 +requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + orderId: + type: integer + fileName: + type: string + contentMediaType: application/octet-stream +``` + +The `contentEncoding` keyword supports all encodings defined in [RFC4648](https://tools.ietf.org/html/rfc4648), including "base64" and "base64url", as well as "quoted-printable" from [RFC2045](https://tools.ietf.org/html/rfc2045#section-6.7). + +## Optional Enhancements + +### $schema declarations + +OpenAPI 3.1 supports the `$schema` keyword, which explicitly declares the JSON Schema dialect in use. This prevents ambiguity for tools processing multiple schema versions. + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#" +} +``` + +By default, OpenAPI 3.1 schemas use the `https://spec.openapis.org/oas/3.1/dialect/base` dialect. External schema files can override this by declaring their own `$schema`. + +This explicit declaration eliminates the need for tools to infer schema versions from context, preventing compatibility issues when schemas are referenced across different OpenAPI versions. + +## Migration Checklist + +- [ ] Update `openapi` version to `3.1.1` +- [ ] Replace `nullable: true` with type arrays (`type: ["string", "null"]`) +- [ ] Update `exclusiveMinimum`/`exclusiveMaximum` from boolean modifiers to direct values +- [ ] Change schema `example` to `examples` (as an array) +- [ ] Update file upload descriptions to use `contentEncoding`/`contentMediaType` +- [ ] Consider adding `$schema` declarations for better tool compatibility +- [ ] Validate the updated specification with OpenAPI 3.1 compatible tools +- [ ] Test with your development toolchain +- [ ] Update CI/CD pipelines if needed + +## Tools and Resources + +- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0) +- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/schema) +- [swagger2openapi](https://github.com/Mermade/oas-kit/blob/master/packages/swagger2openapi/README.md) for upgrading from Swagger 2.0 +- OpenAPI 3.1 compatible validators and tooling + +Most OpenAPI 3.0 descriptions require only minimal changes to work with OpenAPI 3.1, making this a manageable upgrade process. + +_This documentation was based on a blog post by Phil Sturgeon: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0 and further edits and improvements are welcome._ diff --git a/upgrading/v3.1-to-v3.2.md b/upgrading/v3.1-to-v3.2.md new file mode 100644 index 0000000..d026c49 --- /dev/null +++ b/upgrading/v3.1-to-v3.2.md @@ -0,0 +1,193 @@ +--- +layout: default +title: Upgrading from OpenAPI 3.1 to 3.2 +parent: Upgrading Between Versions +nav_order: 2 +--- + +# Upgrading from OpenAPI 3.1 to 3.2 + +OpenAPI 3.2 introduces substantial new functionality while maintaining full backward compatibility with OpenAPI 3.1. This guide covers the upgrade process and provides a roadmap for gradually adopting new features. + +## Getting Started + +Begin by updating the version number in your OpenAPI document: + +```yaml +# Before +openapi: 3.1.1 + +# After +openapi: 3.2.0 +``` + +**Key advantage**: Unlike the 3.0 to 3.1 transition, OpenAPI 3.2 does not introduce breaking changes. All existing 3.1 documents will work without modification after updating the version number. + +## What's New in OpenAPI 3.2 + +OpenAPI 3.2 introduces enhancements across several major areas: + +### Enhanced Tag System + +- **Hierarchical organisation** with parent/child relationships +- **Tag classification** with kind field (nav, badge, audience) +- **Improved display** with summary fields +- **Native support** for functionality previously requiring extensions + +#### Migration Examples: From Extensions to Native Tags + +**Basic Migration - x-displayName to summary:** + +```yaml +# Before (OpenAPI 3.1 with extensions) +tags: + - name: user-management + description: User operations + x-displayName: Users + +# After (OpenAPI 3.2) +tags: + - name: user-management + summary: Users + description: User operations +``` + +**Hierarchy Migration - x-tagGroups to parent:** + +```yaml +# Before (OpenAPI 3.1 with extensions) +tags: + - name: products + - name: books + - name: cds + - name: giftcards +x-tagGroups: + - name: Products + tags: [books, cds, giftcards] + +# After (OpenAPI 3.2) +tags: + - name: products + summary: Products + description: All product operations + kind: nav + + - name: books + summary: Books & Literature + description: Book catalog and recommendations + parent: products + kind: nav + + - name: cds + summary: Music CDs + description: Music CD catalog and reviews + parent: products + kind: nav + + - name: giftcards + summary: Gift Cards + description: Digital and physical gift cards + parent: products + kind: nav + + - name: digital-delivery + summary: Digital Delivery + description: Instantly delivered digital products + kind: badge + +paths: + /giftcards: + get: + tags: [giftcards, digital-delivery] + summary: List available gift cards +``` + +**Key Migration Benefits:** + +- Replace `x-displayName` extension with native `summary` field +- Convert `x-tagGroups` extension to hierarchical `parent` relationships +- Add `kind` classification for enhanced organization +- Combine tags for cross-cutting concerns (like delivery methods) + +*See: [Enhanced Tags](../specification/tags) for comprehensive documentation* + +### Advanced HTTP Method Support + +- **QUERY method** for complex filtering with request bodies +- **Custom HTTP methods** via additionalOperations +- **Enhanced parameter handling** including querystring location + +*See: [HTTP Methods](../specification/http-methods) for implementation details* + +### Sequential and Streaming Data + +- **Server-Sent Events** (text/event-stream) +- **JSON streaming** (application/jsonl, application/json-seq) +- **Enhanced multipart** handling +- **itemSchema** field for describing sequential data + +*See: [Sequential Media Types](../specification/media-types) for complete guide* + +### Security Enhancements + +- **OAuth2 Device Authorization** flow for limited-input devices +- **Enhanced metadata** support with oauth2MetadataUrl +- **Deprecation marking** for security schemes +- **URI-based references** for security schemes + +*See: [Security](../specification/security) for updated authentication methods* + +### Better Examples and Documentation + +- **Structured examples** with dataValue field +- **Serialization examples** with serializedValue field +- **Enhanced servers** with name fields +- **Document identity** with $self field + +*See: [Providing Documentation and Examples](../specification/docs) for enhanced example handling* + +## Upgrade Benefits + +## Gradual Enhancement Strategy + +Consider adopting new features incrementally: + +1. **Enhance server descriptions** - Add `name` fields to server objects +2. **Improve examples** - Use `dataValue` and `serializedValue` for clearer examples +3. **Add document identity** - Include `$self` field if URI resolution clarity is needed +1. **Tag enhancements** - Convert `x-displayName` to `summary`, `x-tagGroups` to tag hierarchy +2. **Remove custom extensions** - Replace with native 3.2 functionality where available +1. **New HTTP methods** - Implement QUERY method for complex filtering scenarios +2. **Streaming support** - Add sequential media types for real-time APIs +3. **Enhanced security** - Implement OAuth2 device flow if relevant to your use cases + +## Migration Checklist + +### Essential Steps + +- [ ] Update `openapi` version to `3.2.0` +- [ ] Validate existing specification with OpenAPI 3.2 compatible tools + +### Gradual Enhancements (As Needed) + +- [ ] Replace custom extensions with native 3.2 features +- [ ] Add `name` fields to server objects for better identification +- [ ] Enhance examples with `dataValue`/`serializedValue` fields +- [ ] Consider tag hierarchy for better API organisation +- [ ] Evaluate new HTTP methods for relevant use cases +- [ ] Review security schemes for OAuth2 device flow applicability +- [ ] Consider sequential media types for streaming or real-time APIs + +## Tools and Resources + +- [OpenAPI 3.2 Specification](https://spec.openapis.org/oas/latest) (when available) +- [The OpenAPI Specification Explained](../specification/) - Updated with 3.2 features +- [Media Types Registry](https://spec.openapis.org/registry/media-type/index.html) +- [Tag Kind Registry](https://spec.openapis.org/registry/tag-kind/index.html) +- OpenAPI 3.2 compatible validators and tooling + +## Summary + +OpenAPI 3.2 represents a significant enhancement while maintaining complete backward compatibility. The upgrade of OpenAPI descriptions is low-risk, requiring only a version number change. The real value comes from gradually adopting new features that enhance your API documentation, improve developer experience, and support modern API patterns. + +This approach allows teams to upgrade immediately for compatibility benefits while planning feature adoption based on their specific needs and timeline. From 4d0efaf438eadd56ec841cec573c58016ddd4d7c Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Mon, 15 Sep 2025 17:44:01 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Ralf Handl --- upgrading/v3.0-to-v3.1.md | 8 ++++---- upgrading/v3.1-to-v3.2.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/upgrading/v3.0-to-v3.1.md b/upgrading/v3.0-to-v3.1.md index b1ee51d..b45a327 100644 --- a/upgrading/v3.0-to-v3.1.md +++ b/upgrading/v3.0-to-v3.1.md @@ -29,7 +29,7 @@ While this version change may appear minor, OpenAPI 3.1 does introduce some brea ## JSON Schema Alignment -OpenAPI 3.1 achieves full compatibility with JSON Schema Draft 2020-12. Previously, OpenAPI used a modified subset of JSON Schema that added some features while removing others, creating confusion in the community. +OpenAPI 3.1 achieves full compatibility with [JSON Schema Draft 2020-12](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html). Previously, OpenAPI used a modified subset of JSON Schema that added some features while removing others, creating confusion in the community. ### Background @@ -182,7 +182,7 @@ The `contentEncoding` keyword supports all encodings defined in [RFC4648](https: ### $schema declarations -OpenAPI 3.1 supports the `$schema` keyword, which explicitly declares the JSON Schema dialect in use. This prevents ambiguity for tools processing multiple schema versions. +OpenAPI 3.1 supports the `$schema` keyword within [Schema Objects](https://spec.openapis.org/oas/v3.1.html#schema-object), which explicitly declares the JSON Schema dialect in use. This prevents ambiguity for tools processing multiple schema versions. ```json { @@ -198,7 +198,7 @@ This explicit declaration eliminates the need for tools to infer schema versions - [ ] Update `openapi` version to `3.1.1` - [ ] Replace `nullable: true` with type arrays (`type: ["string", "null"]`) -- [ ] Update `exclusiveMinimum`/`exclusiveMaximum` from boolean modifiers to direct values +- [ ] Update `exclusiveMinimum`/`exclusiveMaximum` from boolean modifiers to direct values and remove sibling `minimum/maximum` - [ ] Change schema `example` to `examples` (as an array) - [ ] Update file upload descriptions to use `contentEncoding`/`contentMediaType` - [ ] Consider adding `$schema` declarations for better tool compatibility @@ -208,7 +208,7 @@ This explicit declaration eliminates the need for tools to infer schema versions ## Tools and Resources -- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0) +- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1) - [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/schema) - [swagger2openapi](https://github.com/Mermade/oas-kit/blob/master/packages/swagger2openapi/README.md) for upgrading from Swagger 2.0 - OpenAPI 3.1 compatible validators and tooling diff --git a/upgrading/v3.1-to-v3.2.md b/upgrading/v3.1-to-v3.2.md index d026c49..cecce2d 100644 --- a/upgrading/v3.1-to-v3.2.md +++ b/upgrading/v3.1-to-v3.2.md @@ -180,7 +180,7 @@ Consider adopting new features incrementally: ## Tools and Resources -- [OpenAPI 3.2 Specification](https://spec.openapis.org/oas/latest) (when available) +- [OpenAPI 3.2 Specification](https://spec.openapis.org/oas/v3.2) (when available) - [The OpenAPI Specification Explained](../specification/) - Updated with 3.2 features - [Media Types Registry](https://spec.openapis.org/registry/media-type/index.html) - [Tag Kind Registry](https://spec.openapis.org/registry/tag-kind/index.html) From bd3c10c398289fbd2d18209463aab259bb25c984 Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 17 Sep 2025 19:32:13 +0100 Subject: [PATCH 3/5] Update specification/parameters.md Co-authored-by: Karen Etheridge --- specification/parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/parameters.md b/specification/parameters.md index 08c50d0..dff33af 100644 --- a/specification/parameters.md +++ b/specification/parameters.md @@ -100,7 +100,7 @@ Parameters can reside in different locations, indicated by the `in` field. The m - `header`: The parameter is sent in a custom HTTP header as part of the request. Header names are **case-insensitive**. -- `cookie`: The parameter is sent in a cookie header as part of the request. +- `cookie`: The parameter is sent in a Cookie header as part of the request. ### Parameter Type From 316b49d96b4ebfbb830a93e808474f0c5008f68c Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 17 Sep 2025 20:15:55 +0100 Subject: [PATCH 4/5] Add discriminator and some other pull request feedback --- specification/parameters.md | 2 +- upgrading/v3.1-to-v3.2.md | 39 ++++++++++++++----------------------- 2 files changed, 16 insertions(+), 25 deletions(-) diff --git a/specification/parameters.md b/specification/parameters.md index dff33af..6609d25 100644 --- a/specification/parameters.md +++ b/specification/parameters.md @@ -73,7 +73,7 @@ Parameters can reside in different locations, indicated by the `in` field. The m > **NOTE**: > If any parameters are `in: query`, then `in: querystring` cannot be used. -- `querystring` (OpenAPI 3.2+): The entire query string is treated as a single parameter with complex structure: +- `querystring` (OpenAPI 3.2+): The entire query string is treated as a single parameter with complex structure, meaning that combinations of query parameters can be expressed using a well-defined Schema object: ```yaml paths: diff --git a/upgrading/v3.1-to-v3.2.md b/upgrading/v3.1-to-v3.2.md index cecce2d..3fa3fa9 100644 --- a/upgrading/v3.1-to-v3.2.md +++ b/upgrading/v3.1-to-v3.2.md @@ -114,8 +114,8 @@ paths: ### Advanced HTTP Method Support - **QUERY method** for complex filtering with request bodies -- **Custom HTTP methods** via additionalOperations -- **Enhanced parameter handling** including querystring location +- **Custom HTTP methods** via `additionalOperations` +- **Enhanced parameter handling** including `in: querystring` location *See: [HTTP Methods](../specification/http-methods) for implementation details* @@ -131,35 +131,25 @@ paths: ### Security Enhancements - **OAuth2 Device Authorization** flow for limited-input devices -- **Enhanced metadata** support with oauth2MetadataUrl +- **Enhanced metadata** support with `oauth2MetadataUrl` - **Deprecation marking** for security schemes - **URI-based references** for security schemes *See: [Security](../specification/security) for updated authentication methods* -### Better Examples and Documentation - -- **Structured examples** with dataValue field -- **Serialization examples** with serializedValue field -- **Enhanced servers** with name fields -- **Document identity** with $self field +### Discriminator Improvements -*See: [Providing Documentation and Examples](../specification/docs) for enhanced example handling* +- **Use an optional value** for `discriminator` +- **Provide fallback** configuration with `defaultMapping` for payloads that don't match the discriminator mapping -## Upgrade Benefits - -## Gradual Enhancement Strategy +### Better Examples and Documentation -Consider adopting new features incrementally: +- **Structured examples** with `dataValue` field +- **Serialization examples** with `serializedValue` field +- **Enhanced servers** with `name` fields +- **Document identity** with `$self` field -1. **Enhance server descriptions** - Add `name` fields to server objects -2. **Improve examples** - Use `dataValue` and `serializedValue` for clearer examples -3. **Add document identity** - Include `$self` field if URI resolution clarity is needed -1. **Tag enhancements** - Convert `x-displayName` to `summary`, `x-tagGroups` to tag hierarchy -2. **Remove custom extensions** - Replace with native 3.2 functionality where available -1. **New HTTP methods** - Implement QUERY method for complex filtering scenarios -2. **Streaming support** - Add sequential media types for real-time APIs -3. **Enhanced security** - Implement OAuth2 device flow if relevant to your use cases +*See: [Providing Documentation and Examples](../specification/docs) for enhanced example handling* ## Migration Checklist @@ -171,9 +161,10 @@ Consider adopting new features incrementally: ### Gradual Enhancements (As Needed) - [ ] Replace custom extensions with native 3.2 features -- [ ] Add `name` fields to server objects for better identification -- [ ] Enhance examples with `dataValue`/`serializedValue` fields - [ ] Consider tag hierarchy for better API organisation +- [ ] Enhance examples with `dataValue`/`serializedValue` fields +- [ ] Add `name` fields to server objects for better identification +- [ ] Set a `defaultMapping` for discriminators to use a default schema rather than trigger an error - [ ] Evaluate new HTTP methods for relevant use cases - [ ] Review security schemes for OAuth2 device flow applicability - [ ] Consider sequential media types for streaming or real-time APIs From 6112d7d5a8478093ee0ffe2f5e2df53e4c5635bc Mon Sep 17 00:00:00 2001 From: Lorna Jane Mitchell Date: Wed, 17 Sep 2025 20:17:13 +0100 Subject: [PATCH 5/5] Update upgrading/v3.0-to-v3.1.md Co-authored-by: Ralf Handl --- upgrading/v3.0-to-v3.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/upgrading/v3.0-to-v3.1.md b/upgrading/v3.0-to-v3.1.md index b45a327..f35ecb3 100644 --- a/upgrading/v3.0-to-v3.1.md +++ b/upgrading/v3.0-to-v3.1.md @@ -198,7 +198,7 @@ This explicit declaration eliminates the need for tools to infer schema versions - [ ] Update `openapi` version to `3.1.1` - [ ] Replace `nullable: true` with type arrays (`type: ["string", "null"]`) -- [ ] Update `exclusiveMinimum`/`exclusiveMaximum` from boolean modifiers to direct values and remove sibling `minimum/maximum` +- [ ] Update `exclusiveMinimum`/`exclusiveMaximum` from boolean modifiers to direct values and remove sibling `minimum`/`maximum` - [ ] Change schema `example` to `examples` (as an array) - [ ] Update file upload descriptions to use `contentEncoding`/`contentMediaType` - [ ] Consider adding `$schema` declarations for better tool compatibility