Convert

Upgrade your OpenAPI 3.0 document to OpenAPI 3.1 or 3.2.

CLI Usage

Terminal

# Convert to OpenAPI 3.1
npx openapi-format openapi.json -o openapi-3.1.json --convertTo "3.1"

# Convert to OpenAPI 3.2
npx openapi-format openapi.json -o openapi-3.2.json --convertTo "3.2"

# Convert without sorting
npx openapi-format openapi.yaml -o openapi-3.1.yaml --no-sort --convertTo "3.1"

Example: 3.0 → 3.1

Before (OpenAPI 3.0)

openapi: 3.0.2
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      nullable: true
      properties:
        name:
          type: string
        tag:
          type: string
          nullable: true

After (OpenAPI 3.1)

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List pets
      responses:
        '200':
          description: A list of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type:
        - object
        - 'null'
      properties:
        name:
          type: string
        tag:
          type:
            - string
            - 'null'

Example: 3.0 → 3.2

Before

{
  "openapi": "3.0.2",
  "info": {
    "title": "Petstore API",
    "version": "1.0.0"
  }
}

After (--convertTo 3.2)

{
  "openapi": "3.2.0",
  "info": {
    "title": "Petstore API",
    "version": "1.0.0"
  }
}

What Changes

3.0 → 3.1: Key transformations include:

nullable: true → type: [original, 'null']
exclusiveMinimum: true → exclusiveMinimum: value
example → examples (array format)

Based on the migration guide from Phil Sturgeon .

3.x → 3.2: Prepares the document for features like hierarchical tags, the QUERY HTTP method, and reusable media types introduced in the 3.2 release .