Meta Description: OpenAPI 3.2 brings JSON Schema 2020-12, webhooks, and improved reusability. Learn what changed from 3.0 and 3.1 and how to upgrade.
Keywords: openapi 3.2, swagger specification, api documentation, openapi upgrade, json schema, api spec
Word Count: ~2,300 words
You're using OpenAPI 3.0 to document your API. It works fine. Should you upgrade to 3.1 or 3.2?
The short answer: yes. Each version adds features that make your API documentation more accurate, maintainable, and powerful.
Let's break down what changed and why it matters.
Each version is backward compatible within the 3.x line, but 3.0 → 3.1 has breaking changes.
OpenAPI 3.0 was a major rewrite from 2.0. Key improvements:
2.0 had single host:
host: api.petstore.com
basePath: /v1
schemes:
- https
3.0 supports multiple servers:
servers:
- url: https://api.petstore.com/v1
description: Production
- url: https://staging.petstore.com/v1
description: Staging
- url: http://localhost:3000/v1
description: Local development
This is useful for testing against different environments.
2.0 mixed parameters and body:
parameters:
- in: body
name: body
schema:
$ref: '#/definitions/Pet'
3.0 separates request body:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
This makes it clearer and supports multiple content types.
2.0 had scattered reusable objects:
definitions:
Pet: {...}
parameters:
petId: {...}
responses:
NotFound: {...}
3.0 groups them under components:
components:
schemas:
Pet: {...}
parameters:
petId: {...}
responses:
NotFound: {...}
securitySchemes:
bearerAuth: {...}
Better organization and more reusable component types.
3.0 added callback documentation for webhooks:
callbacks:
petStatusChanged:
'{$request.body#/callbackUrl}':
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PetStatusEvent'
This documents what your API sends to client webhooks.
OpenAPI 3.1 aligned with JSON Schema, fixing years of divergence.
3.0 used a subset of JSON Schema Draft 5 with custom extensions.
3.1 uses JSON Schema 2020-12 (Draft 2020-12) with full compatibility.
This means you can use any valid JSON Schema in OpenAPI 3.1:
components:
schemas:
Pet:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 100
age:
type: integer
minimum: 0
maximum: 30
tags:
type: array
items:
type: string
uniqueItems: true
minItems: 1
required:
- name
# JSON Schema 2020-12 features
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://petstoreapi.com/schemas/pet"
3.0 had nullable:
type: string
nullable: true
3.1 uses JSON Schema's null type:
type: [string, "null"]
Or with anyOf:
anyOf:
- type: string
- type: "null"
This is more consistent with JSON Schema.
3.0 had both example and examples:
schema:
type: string
example: "Max"
examples:
dog:
value: "Max"
cat:
value: "Whiskers"
3.1 clarifies their usage and makes them consistent with JSON Schema.
3.1 improved discriminator mapping:
components:
schemas:
Pet:
type: object
discriminator:
propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
cat: '#/components/schemas/Cat'
properties:
petType:
type: string
required:
- petType
Dog:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
properties:
breed:
type: string
Cat:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
properties:
indoor:
type: boolean
This enables better polymorphism support in code generators.
OpenAPI 3.2 (released 2024) adds features for modern API patterns.
3.1 documented webhooks using callbacks, which was awkward.
3.2 adds a top-level webhooks section:
webhooks:
petStatusChanged:
post:
summary: Pet status changed
description: Triggered when a pet's status changes
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
eventType:
type: string
enum: [STATUS_CHANGED]
petId:
type: string
format: uuid
oldStatus:
type: string
newStatus:
type: string
timestamp:
type: string
format: date-time
responses:
'200':
description: Webhook received
'400':
description: Invalid webhook payload
This is clearer and easier to document.
3.2 allows reusable path items:
components:
pathItems:
PetResource:
get:
summary: Get pet
parameters:
- $ref: '#/components/parameters/petId'
responses:
'200':
description: Pet found
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
put:
summary: Update pet
parameters:
- $ref: '#/components/parameters/petId'
requestBody:
$ref: '#/components/requestBodies/PetUpdate'
responses:
'200':
description: Pet updated
delete:
summary: Delete pet
parameters:
- $ref: '#/components/parameters/petId'
responses:
'204':
description: Pet deleted
paths:
/pets/{petId}:
$ref: '#/components/pathItems/PetResource'
/archived-pets/{petId}:
$ref: '#/components/pathItems/PetResource'
This reduces duplication when multiple paths share the same operations.
3.2 adds mutualTLS security scheme:
components:
securitySchemes:
mutualTLS:
type: mutualTLS
description: Client certificate authentication
This documents mTLS requirements.
3.2 improves link objects for HATEOAS:
components:
links:
AdoptPet:
operationId: createAdoption
parameters:
petId: '$response.body#/id'
description: Create an adoption application for this pet
Links can reference operations by ID, making HATEOAS documentation easier.
1. Update openapi version:
openapi: 3.1.0
2. Replace nullable with null type:
Before:
type: string
nullable: true
After:
type: [string, "null"]
3. Update JSON Schema references:
Before:
$ref: '#/definitions/Pet'
After:
$ref: '#/components/schemas/Pet'
4. Test with validators:
# Use Spectral or other OpenAPI 3.1 validators
npx @stoplight/spectral-cli lint openapi.yaml
1. Update openapi version:
openapi: 3.2.0
2. Move callbacks to webhooks:
Before (3.1):
paths:
/pets:
post:
callbacks:
statusChanged:
'{$request.body#/callbackUrl}':
post:
...
After (3.2):
webhooks:
statusChanged:
post:
...
3. Extract reusable path items:
Before:
paths:
/pets/{petId}:
get: {...}
put: {...}
delete: {...}
/archived-pets/{petId}:
get: {...}
put: {...}
delete: {...}
After:
components:
pathItems:
PetResource:
get: {...}
put: {...}
delete: {...}
paths:
/pets/{petId}:
$ref: '#/components/pathItems/PetResource'
/archived-pets/{petId}:
$ref: '#/components/pathItems/PetResource'
Check tool compatibility before upgrading:
OpenAPI 3.2 Support: - Swagger UI: 5.0+ (partial) - Redoc: 2.1+ (partial) - Stoplight: Full support - Postman: Partial support - Apidog: Full support
OpenAPI 3.1 Support: - Most tools now support 3.1 - Some older tools only support 3.0
Test your toolchain before upgrading production specs.
Upgrade to 3.1 if: - You need full JSON Schema support - You want better validation - Your tools support 3.1
Upgrade to 3.2 if: - You document webhooks - You have repetitive path definitions - You need mTLS documentation - Your tools support 3.2
Stay on 3.0 if: - Your tools don't support newer versions - You don't need new features - Migration cost outweighs benefits
Reuse schemas, parameters, and responses:
components:
schemas:
Pet: {...}
Error: {...}
parameters:
petId: {...}
responses:
NotFound: {...}
Include realistic examples:
components:
schemas:
Pet:
type: object
properties:
name:
type: string
examples:
- name: "Max"
species: "DOG"
breed: "Golden Retriever"
Use linters to catch errors:
npx @stoplight/spectral-cli lint openapi.yaml
Track changes in version control:
info:
version: 2.1.0
title: PetStore API
OpenAPI 3.2 is the most complete version yet. It adds webhooks, reusable path items, and better security documentation.
If your tools support it, upgrade. If not, 3.1 is still excellent.
The Modern PetStore API uses OpenAPI 3.2 to showcase all these features. Check it out to see real-world examples of advanced OpenAPI usage.
Ready to upgrade? Start with the migration guide above and test thoroughly before deploying.
Need help? Check the OpenAPI specification at spec.openapis.org for complete documentation.
