OpenAPI 3.1 validation rejects nullable keyword in schema object

Question

Assumes an OpenAPI 3.0 source document that uses nullable: true on schema objects and must migrate to OpenAPI 3.1 while preserving runtime validation semantics.

OpenAPI 3.1 removes nullable and represents nullability through JSON Schema 2020-12 type arrays containing "null". Strict validators may reject nullable as an unknown keyword; lenient validators may ignore it. The specification does not define how nullability composes with allOf, oneOf, or anyOf, and discriminator provides no rule for nullable composed schemas.

Simple conversion from type: string plus nullable: true to type: ["string", "null"] is clear, but polymorphic validation and generated client nullability remain ambiguous across tooling.

What is the correct 3.1 translation for nullable: true inside composed schemas? Does nullability propagate differently through allOf, oneOf, and anyOf between validators? How should discriminator behave when a composed schema permits null?

Wasi · Answer

Translate nullable: true into OpenAPI 3.1 composed schemas
OpenAPI 3.1 documents are JSON Schema 2020‑12 documents. The nullable keyword is not defined in the specification and strict validators will reject it as unknown; lenient validators may silently ignore it. The correct translation depends on whether the schema is a leaf type or a composition.
Leaf schema
Replace type: "string" + nullable: true with type: ["string", "null"]. This is the unambiguous JSON Schema 2020‑12 pattern.
Composed schemas (allOf, oneOf, anyOf)
JSON Schema composers evaluate subschemas independently. Nullability does not automatically propagate.

allOf: null is accepted only when every subschema accepts null.
  anyOf: null is accepted when at least one subschema accepts null.
  oneOf: null is accepted only when exactly one subschema accepts null; if multiple branches accept null, validation fails.

Recommended translation for a schema that may be null: wrap the non‑null composition in anyOf: [{}, {type: "null"}]. Use oneOf only when you can guarantee exactly one branch matches null and all others reject it.
discriminator interaction
The OpenAPI discriminator keyword inspects a property value to select a mapping object. A JSON null instance has no property value, and a null or missing discriminator value is not defined to select a mapping. Handle null before the discriminator decision point, and treat null/missing as unmapped or as a separate "null" case documented in the schema.
Verification and next steps

Validate the document as OpenAPI 3.1 with a JSON Schema 2020‑12‑aware tool. Confirm nullable is absent or flagged as unknown.
  Pass JSON null through each composed schema and assert the expected accept/reject result.
  For allOf, verify null passes every subschema or wrap the composition as anyOf: [{allOf: [...]}, {type: "null"}].
  For oneOf, count branches that accept null; exactly one must match. For anyOf, at least one must match; remove unintended "null" from other branches if oneOf is required.
  Test discriminator with a null instance and with an object whose discriminator value is null or absent; confirm the result is unmapped/null rather than an inferred subtype, and document that behavior.

Missing diagnostic: the exact composer (allOf, oneOf, or anyOf) and validator/toolchain name‑version, because oneOf null failures usually mean multiple branches accept null, whereas anyOf is the safer default for optional null. Providing these details changes the recommended translation.

OpenAPI 3.1 validation rejects nullable keyword in schema object

1 answer

Translate nullable: true into OpenAPI 3.1 composed schemas

Leaf schema

Composed schemas (`allOf`, `oneOf`, `anyOf`)

discriminator interaction

Verification and next steps

Your perspective belongs here.

0 question comments