How do you declare a nullable field in OpenAPI 3.0 versus OpenAPI 3.1?

## Why the two versions differ at all OpenAPI 3.0's Schema Object was a modified subset of an old JSON Schema draft in which `type` held exactly one value. There was no way to say "a string or null". OpenAPI therefore added its own keyword, `nullable`, as an extension to the subset. OpenAPI 3.1 realigned the Schema Object with JSON Schema 2020-12, which supports `type` as an array of type names including `"null"`. With native support available, the bespoke keyword was removed. ## The 3.0 form ``` closedAt: type: string format: date-time nullable: true ``` `nullable: true` widens the declared type to also permit the JSON literal `null`. It defaults to `false`, so an ordinary `type: string` rejects null. ## The 3.1 form ``` closedAt: type: [string, "null"] format: date-time ``` Quote `"null"` in YAML — unquoted `null` parses as the YAML null value rather than the string `"null"`, and the schema then makes no sense. An equivalent but more verbose spelling is `oneOf: [{type: string}, {type: "null"}]`, which is sometimes needed when the null branch must sit next to other composition. ## The migration trap When you bump `openapi` from `3.0.3` to `3.1.0`, every `nullable: true` in the document becomes a no-op. `nullable` is not part of the 3.1 vocabulary; JSON Schema 2020-12 ignores keywords it does not know, so validation quietly narrows — a field that used to accept null now rejects it, and the failure appears at runtime in whichever consumer sends null first. Linters such as Spectral ship rules that flag `nullable` in a 3.1 document, and turning that rule on before the bump is the cheapest safeguard. ## nullable next to $ref This is the second-most-asked follow-up. In OpenAPI 3.0, a Reference Object's siblings are ignored: writing ``` address: $ref: '#/components/schemas/Address' nullable: true ``` does not make the referenced schema nullable — the `$ref` wins and the sibling is dropped. The 3.0 workaround is to wrap it: ``` address: allOf: - $ref: '#/components/schemas/Address' nullable: true ``` The single-element `allOf` exists purely to give `nullable` a place to live. This is why 3.0 documents are littered with one-branch `allOf` wrappers that also carry `description` or `example`. In OpenAPI 3.1, Schema Objects follow JSON Schema 2020-12, where `$ref` may coexist with sibling keywords, so the wrapper is unnecessary for schema-level annotations. ## nullable is not optional Nullability and requiredness are separate axes. `required: [closedAt]` with a nullable schema means "the key must be present, and null is a legitimate value". Dropping the field from `required` means "the key may be absent". Modelling both — optional *and* nullable — leaves consumers unable to distinguish absent from null unless their client library exposes a tri-state, which most do not. Decide which of the two states you actually need. ## What generators do Generators map nullability to the target language's null handling: a nullable field becomes a nullable type, an `Optional`, or a type union. Where it bites is round-tripping — a generated client that deserializes null into a language null and then re-serializes may emit the field as absent rather than null, silently converting "clear this value" into "leave it unchanged" on a PATCH. If null carries meaning in your API, test the round trip through the generated client rather than trusting the schema alone. ## Neighbouring 3.1 changes worth knowing The `nullable` removal is one item in a family of JSON Schema realignments: `exclusiveMinimum` and `exclusiveMaximum` become numbers in 3.1 rather than booleans modifying `minimum`/`maximum`, and the Schema Object's singular `example` is deprecated in favour of the JSON Schema `examples` array. If you are auditing a document for a 3.1 move, sweep for all of these together — they are the changes a mechanical converter is most likely to leave behind.