Quick answer: In a generated client, an explicit null and a missing field are not the same value at runtime. Nullable controls whether a field may hold null, and required controls whether the field has to appear, so the two are independent. On the wire, a missing key is simply absent while a nullable field is present with the value null, and a generated type only protects you if your code keeps those cases apart instead of collapsing them with loose equality.

Two independent axes in the spec

A property carries two separate facts. nullable: true says the value can be null, while membership in the required list says the key must be present. That gives four combinations: a required non-nullable field must appear with a value, a required nullable field must appear but can be null, an optional non-nullable field can be omitted but cannot be null if present, and an optional nullable field can be omitted or sent as null. Treating optional and nullable as synonyms is the root mistake behind most of these bugs.

They differ on the wire

The distinction survives serialization. A field that is undefined is omitted by the JSON serializer, so the key does not appear in the payload, while a null field is written as "field": null. On the way back, a missing key maps to the language's notion of absence, and an explicit null maps to null. Loose checks hide this: in JavaScript, x == null matches both null and undefined, so code written that way cannot tell an explicit empty value from a field the server never returned. Use strict checks and branch on each case when the meaning matters.

Languages do not map them the same way

The generator expresses the spec in each type system, but languages do not share one concept of "missing," so the mapping is not perfectly symmetric.

Language Nullable field Missing field
TypeScript T or null Optional T?
Python None Attribute absent or sentinel
Go *T set to nil Nil with omitempty
Java Null reference Absent, often Optional

Python and Go use a single nil-like value for more than one meaning, which is why telling null from absence there may require checking whether the key was present rather than only reading the value.

The difference matters in a partial update

The wire-level distinction has a concrete consequence in a PATCH or other partial update, where the two shapes often mean opposite actions. Sending an explicit null is how a client asks the server to clear a field, while omitting the field usually means leave it unchanged. Swapping them produces the wrong result: sending null where you meant to omit can wipe a value the user wanted to keep, and omitting the field where you meant to clear it lets the old value survive. That is why the serializer choice has to be deliberate rather than a side effect of how the object was built.

Verifying the behavior

The types deserve a check against real responses. Use a local mock that returns one payload with an explicit null field and another with that field omitted, then run an ordered scenario and assert the client model shows null in one case and absence in the other; Powerduck can drive that scenario and also confirm, on the recorded requests, that an undefined field is omitted while a null field is sent as null.

Honest limits

The generator reflects the spec, but it does not decide what null and absence mean in your business rules, and dynamic languages let loose equality bypass the generated types. OpenAPI 3.0 uses nullable while 3.1 expresses the same idea with a type array, and generator support across the two is uneven. When a target language has no separate absence value, some information from the spec is compressed and has to be recovered by inspecting the raw keys.

Frequently asked questions

Does optional mean nullable? No. Optional controls presence; nullable controls whether a present value can be null.

How do they differ in a request? Undefined omits the key; null sends it with a null value.

Why does == null cause problems? It matches both null and undefined, so the two cases can no longer be distinguished.

Does every language keep them separate? No. Python and Go use one nil-like value and may need a presence check.

The bottom line

Nullable and required are separate axes, and an explicit null stays different from a missing field through serialization and back, though some languages compress the two into one value. Verify both cases against a mock and use strict checks. For more on generated clients, see the OpenAPI codegen guide hub.