2026-09-30 · 6 min read · Rahul Chitturi
- openapi
- json-schema
- null
OpenAPI 3.0 adds a nullable flag beside a single type such as string. OpenAPI 3.1 follows JSON Schema and puts null inside the type array, as in ["string", "null"]. A document that mixes those spellings can pass one linter and fail the generator or the runtime validator.
The wire value null is also different from an omitted property. A required nullable field must be present and may be null. An optional field may be absent. Clients that collapse both cases into one language null hide which of those contracts failed.
Record the OpenAPI version and the null spelling
Save the openapi version, the schema fragment, and the payload that failed. Note whether null is expressed with nullable, a type array, a oneOf branch, or a $ref that adds a second definition. Then name the tool that rejected it: editor, generator, gateway, or application validator.
- Check that 3.0 schemas use a string type plus nullable.
- Check that 3.1 schemas include null in type.
- Treat a leftover nullable keyword in a 3.1 document as unenforced.
- Keep required and nullable as separate decisions.
Compare the generated model with the payload
Some generators emit an optional property for nullable and skip a JSON null. Others emit a union only when the type array contains null. A 3.0 file that already uses a type array can be ignored by a generator that still expects the nullable keyword.
Diff the schema you authored against the bundled schema the gateway loads. Inlining and allOf can drop nullable or widen a type union, so the file in Git is not always the contract that ran.
Reproduce null, omission, and a wrong type
Use Flashman's YAML/JSON converter for the schema, the JSON formatter for payloads, diff for the bundled document, and the case converter when property names differ between the spec and the client.
Test a present null, an omitted field, an explicit empty string, a 3.0 document read as 3.1, and a 3.1 type union read by a 3.0 generator. Accept the payload only in the cases the written contract allows.