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:

openapi: 3.0.3

Update it to:

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.

# OpenAPI 3.0
type: string
nullable: true

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

# OpenAPI 3.0
minimum: 7
exclusiveMinimum: true

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

# OpenAPI 3.0
type: string
example: fedora

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

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:

# OpenAPI 3.0
requestBody:
  content:
    application/octet-stream:
      schema:
        type: string
        format: binary

# OpenAPI 3.1
requestBody:
  content:
    application/octet-stream: {}

Base64-encoded uploads:

# OpenAPI 3.0
requestBody:
  content:
    image/png:
      schema:
        type: string
        format: base64

# OpenAPI 3.1
requestBody:
  content:
    image/png:
      schema:
        type: string
        contentEncoding: base64

Multipart file uploads:

# OpenAPI 3.0
requestBody:
  content:
    multipart/form-data:
      schema:
       type: object
       properties:
        orderId:
          type: integer
        fileName:
          type: string
          format: binary

# 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, including “base64” and “base64url”, as well as “quoted-printable” from RFC2045.

Optional Enhancements

$schema declarations

OpenAPI 3.1 supports the $schema keyword within Schema Objects, which explicitly declares the JSON Schema dialect in use. This prevents ambiguity for tools processing multiple schema versions.

{
   "$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 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
  • Validate the updated specification with OpenAPI 3.1 compatible tools
  • Test with your development toolchain
  • Update CI/CD pipelines if needed

Tools and Resources

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.