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:

# 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:

# 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:

# 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 for comprehensive documentation

Advanced HTTP Method Support

  • QUERY method for complex filtering with request bodies
  • Custom HTTP methods via additionalOperations
  • Enhanced parameter handling including in: querystring location

See: 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 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 for updated authentication methods

Discriminator Improvements

  • Use an optional value for discriminator
  • Provide fallback configuration with defaultMapping for payloads that don’t match the discriminator mapping

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 for enhanced example handling

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
  • 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

Tools and Resources

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.