Pydantic exclude_none: teaching the difference between required keys and nullable values
Required describes key presence; nullable describes permitted values. The team's acceptance checklist must separate them.
Pydantic exclude_none: teaching the difference between required keys and nullable values
A nullable field can permit an empty value without permitting omission of the key itself. Applying an option that removes None values everywhere can discard keys a consumer requires. Treat key presence and value missingness as separate states to describe the round-trip contract accurately. [1, 2, 3]
What the primary source establishes
A feature request explains that exclude_none removes fields valued None regardless of whether they have defaults, making a required nullable field's serialized output fail validation when read back. The description of current behavior is distinct from the proposed policy change. [1]
The handover decision
Producer and consumer should write separate examples for an omitted key, an explicit null, and a real value. Agree on serialization options that remove required keys before changing them. Retain field_name, required, key_present, and value_is_null rather than treating these as a single completeness flag. [1, 3]
A reference defined before the output
In the illustrative contract, x is required but permits null. An object containing x:null is normal and records the key as present. An object without x records it as absent and fails. Filling null with a made-up value would answer a different question and would not teach the presence requirement. [1, 3]
The scoped Truthound check
Truthound Core 3.3.2 offers ColumnExistsValidator for required keys represented as actual table columns. To detect key omission in individual raw objects, extract key_present before combining them into a table. A column's existence does not prove that every source object originally contained that key. [1, 2, 3]
Limits and alternative choices
A NotNull rule that rejects every null is not an alternative implementation of this contract. Keep required nullable fields during serialization and validate the response schema again. If x is optional in the consumer contract, omitting it may be normal. [1, 3]
Application conditions
Extract raw-object key presence separately and preserve required keys as actual columns, distinguishing null values from absent columns.
Alternatives
Keep required nullable fields during serialization and validate the response schema again.
Limitations
A NotNull rule that rejects every null is not an alternative implementation of this contract.
Evidence
- Event checked
- Subject checked
- Modified
