OpenAPI 3.2: What's New & Migration Guide 2026

Quick clarification: as of March 2026, OpenAPI 4.0 does not exist. The current OpenAPI specification is OpenAPI 3.2.0, released in September 2025. If you've seen mentions of "OpenAPI 4.0" or "Moonwalk," those refer to a future major version still in development. This guide covers what's actually in production: OpenAPI 3.2.0 and what it means for your API documentation and tooling.

TL;DR

• OpenAPI 3.2.0 was released in September 2025 — zero breaking changes from 3.1
• New: hierarchical tags (summary/parent/kind), first-class streaming (SSE, JSON Lines, multipart), custom HTTP methods via additionalOperations
• OAuth 2.0 Device Authorization Flow now in the spec
• All existing 3.1 documents work after updating the version number
• "OpenAPI 4.0" is a planned future major version (codenamed Moonwalk) — not released yet
• Tooling support for 3.2 is maturing rapidly; check your tools' release notes

Key Takeaways

• Migration from 3.1 to 3.2 is trivial — update the version string, review new optional features
• Streaming support is the most impactful new feature for modern API developers
• Hierarchical tags dramatically improve documentation navigation for large APIs
• OpenAPI 3.2 maintains full backward compatibility — no migration pain
• Start using 3.2 features for new APIs; existing 3.1 APIs benefit from migration with zero risk

The Full Story

Clearing Up the OpenAPI 4.0 Confusion

The OpenAPI specification has two distinct tracks in 2026:

Track 1 — OpenAPI 3.x (stable): The specification that everyone uses today. Current stable release: OpenAPI 3.2.0 (September 2025).

Track 2 — OpenAPI 4.0 "Moonwalk" (in development): A planned major version with significant structural changes. As of March 2026, this is still in design phases and is not yet released. No production tooling supports it yet.

All tutorials, tooling, and real-world usage as of 2026 targets OpenAPI 3.x. This guide covers OpenAPI 3.2.

For context on how OpenAPI relates to AsyncAPI for event-driven APIs, see our OpenAPI vs AsyncAPI guide.

What's New in OpenAPI 3.2.0

OpenAPI 3.2.0 adds several high-value features while maintaining complete backward compatibility with 3.1.

1. First-Class Streaming Support

The most significant addition in 3.2 is native streaming support. Before 3.2, documenting streaming responses required hacky workarounds or custom extensions. OpenAPI 3.2 adds formal support for:

Server-Sent Events (SSE):

/events/stream:
  get:
    summary: Subscribe to live events
    responses:
      '200':
        description: SSE stream
        content:
          text/event-stream:
            schema:
              type: object
              properties:
                event:
                  type: string
                data:
                  $ref: '#/components/schemas/Event'

JSON Lines (newline-delimited JSON):

/data/export:
  get:
    responses:
      '200':
        content:
          application/x-ndjson:
            schema:
              $ref: '#/components/schemas/Record'

Multipart streaming for progressive file uploads and chunked responses.

This matters because streaming is now mainstream. AI APIs (text streaming), real-time dashboards, and live data feeds all use streaming responses. Before 3.2, these couldn't be properly documented in OpenAPI without custom extensions.

2. Hierarchical Tags

Before 3.2, OpenAPI tags were a flat list. tags on an operation was just a string category. Large APIs with many operations had flat, unnavigable documentation.

OpenAPI 3.2 introduces hierarchical tags with summary, parent, and kind properties:

tags:
  - name: payments
    summary: Payment operations
    kind: group
  - name: payments/charges
    summary: Charge management
    parent: payments
    kind: resource
  - name: payments/refunds
    summary: Refund operations
    parent: payments
    kind: resource

This enables documentation tools to render API references with proper navigation hierarchies — groups, subgroups, and nested resources — instead of a flat alphabetical list. For large APIs with dozens of resource types, this is a significant quality-of-life improvement.

3. Custom HTTP Methods via additionalOperations

Standard HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE) cover most use cases. But some APIs use non-standard verbs — particularly search APIs that use QUERY (from the in-draft HTTP QUERY method), or custom RPC-style methods.

OpenAPI 3.2 adds additionalOperations at the path level to document non-standard HTTP methods:

/resources/search:
  additionalOperations:
    query:
      summary: Search resources with a request body
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          $ref: '#/components/responses/SearchResults'

This is particularly relevant for teams tracking the evolving HTTP QUERY method specification and for APIs that use custom verbs for internal tooling.

4. OAuth 2.0 Device Authorization Flow

The OAuth 2.0 Device Authorization Flow (formerly Device Code Flow) is used for devices without a browser — smart TVs, CLIs, IoT devices, and developer tools. Before 3.2, this flow couldn't be formally documented in OpenAPI security schemes.

OpenAPI 3.2 adds it to the OAuth2 flows object:

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        deviceAuthorization:
          deviceAuthorizationUrl: https://auth.example.com/device
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access

This enables proper documentation of CLIs and tools that use device authorization, and allows client generation tools to generate correct authorization flows for these environments.

What Didn't Change (3.1 → 3.2)

It's worth being explicit about what stayed the same:

• JSON Schema compatibility: OpenAPI 3.1 introduced full JSON Schema draft 2020-12 compatibility. This is preserved in 3.2.
• $ref behavior: No changes to reference resolution.
• Webhook documentation: Added in 3.1, unchanged in 3.2.
• Path parameters, headers, query parameters: No changes.
• All existing security scheme types: All 3.1 security schemes work identically in 3.2.
• oneOf, anyOf, allOf, not: No changes to composition keywords.

Migrating from OpenAPI 3.1 to 3.2

This is genuinely the easiest major spec migration you'll encounter. Since 3.2 is fully backward-compatible with 3.1, the minimum migration is:

Step 1: Update the openapi field:

# Before
openapi: "3.1.0"

# After
openapi: "3.2.0"

That's it for a minimum migration. Your existing spec is valid 3.2 without any other changes.

Step 2 (optional): Adopt new 3.2 features where they improve your documentation:

Current approach	3.2 improvement
Custom extension for streaming	Use native streaming content types
Flat tag list	Hierarchical tags with parent/kind
Workaround for QUERY method	additionalOperations
Missing Device Auth Flow	Native OAuth2 device authorization

Step 3: Update tooling. Check your OpenAPI tooling (validators, code generators, documentation tools) for 3.2 support. Most major tools released 3.2 support in Q4 2025 or Q1 2026.

Tooling Support in 2026

OpenAPI 3.2 tooling support as of March 2026:

Tool	3.2 Support	Notes
Swagger UI	Yes (5.x)	Full rendering including streaming
Redoc	Yes	Updated for hierarchical tags
Stoplight Studio	Yes	Full 3.2 authoring support
Scalar	Yes	Modern renderer, 3.2 native
OpenAPI Generator	Partial	Most generators updated; verify target language
Spectral	Yes	Updated validation rules
Postman	Partial	Core features supported; some 3.2-specific features in progress
Speakeasy SDK Gen	Yes	Full 3.2 schema support
Fern SDK Gen	Yes	3.2 native

Before migrating, test your specific workflow. Run your spec through your validator and code generator with 3.2 version string and verify the output.

What to Know About OpenAPI 4.0 (Moonwalk)

Since the question comes up frequently: here's the current state of OpenAPI 4.0.

What it is: A planned major version with significant structural changes to how APIs are described. Codenamed "Moonwalk," the design is being driven by the OpenAPI Initiative.

Key design goals (from public TSC discussions):

• Better support for server-driven workflows (not just request/response)
• Improved reusability and composition model
• More natural expression of modern API patterns (streaming-first, event-driven, AI-native)
• Better alignment with the HTTP specification

Current status (March 2026): In design and early draft phase. The TSC has published design proposals but no stable specification. No production tooling supports it. No official release date.

What this means for you: Build on OpenAPI 3.2 now. When OpenAPI 4.0 releases, expect a longer migration period given the structural changes. For current API development, 3.2 is the right target.

For the Arazzo workflow specification (a related OpenAPI Initiative project for API workflows), see our OpenAPI Arazzo Workflow Spec guide.

Practical Recommendations

Starting a new API today: Use OpenAPI 3.2 from the beginning. Take advantage of streaming documentation for any endpoints that return streaming responses.

Existing OpenAPI 3.1 API: Migrate to 3.2 when you have a documentation update cycle. The change is trivial (version string bump). Opportunistically adopt hierarchical tags if your API has more than 20–30 operations.

Existing OpenAPI 3.0 API: Consider migrating to 3.1 or 3.2. The 3.0 → 3.1 migration is the meaningful step (JSON Schema compatibility changes), and 3.1 → 3.2 is trivial afterward.

Team tooling: Verify that your whole toolchain (linting, code generation, documentation, testing) supports 3.2. Run a test migration in a branch before committing.

Methodology

This guide draws on the official OpenAPI 3.2.0 specification (openapis.org), release notes from Speakeasy's OpenAPI Release Notes tracker, APIDog's three-way comparison of OpenAPI 3.0/3.1/3.2, and the official OpenAPI Initiative migration guide (learn.openapis.org). "OpenAPI 4.0" status reflects publicly available OpenAPI TSC meeting notes and design proposals as of March 2026. Tooling support status reflects vendor documentation and community reports from March 2026.