# OpenAPI 3.0 Versus 3.1 — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/s-versions

> Recognise the differences between 3.0 and 3.1 and migrate safely.

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

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

**Quiz:** How is a nullable string expressed in OpenAPI 3.1?

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

*Answer:* type: [string, 'null']. 3.1 follows JSON Schema, which expresses null as a type in a type array.