OpenAPI 3.0 Versus 3.1

What changed in 3.1

OpenAPI 3.1 brought schemas into full alignment with JSON Schema 2020-12, which changed several details. Nullability: 3.0 used nullable: true; 3.1 removes it and uses type arrays such as type: [string, 'null'] (or oneOf with type: 'null'). Examples: schema example (singular) is deprecated in favour of JSON Schema's examples array. exclusiveMinimum and exclusiveMaximum are numbers in 3.1, not booleans. $ref siblings: in 3.0, keywords next to a $ref were ignored; in 3.1, schema $ref behaves like any other keyword, and reference objects may override summary and description. New features: top-level webhooks, pathItems in components, the mutualTLS security scheme, license.identifier for SPDX licence IDs, and paths becoming optional. Tooling support for 3.1 has matured in major tools (Swagger UI, Redoc, Redocly, Spectral, openapi-generator, springdoc-openapi 2.x, FastAPI), but check each tool in your pipeline before migrating. Swagger 2.0 documents can be converted to 3.x with converters, followed by manual review.

The same field in 3.0 and 3.1

Nullability, examples and exclusive bounds change syntax.

# OpenAPI 3.0
discountPercent:
  type: number
  nullable: true
  minimum: 0
  maximum: 100
  exclusiveMaximum: true      # boolean in 3.0
  example: 12.5

# OpenAPI 3.1 (JSON Schema 2020-12)
discountPercent:
  type: [number, 'null']
  minimum: 0
  exclusiveMaximum: 100       # number in 3.1
  examples: [12.5]

Upgrade the toolchain, then the document

A 3.1 document fed to a generator or validator that only understands 3.0 may silently ignore type arrays or fail entirely. Confirm every tool in the pipeline supports 3.1 before changing the version field.

Quick check: How is a nullable string expressed in OpenAPI 3.1?

• nullable: true
• x-nullable: true
• type: [string, 'null']
• required: false