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.