In Pydantic 2, how do exclude_unset, exclude_none and exclude_defaults differ, and which one lets a PATCH handler tell absent fields from explicit nulls?
answer
- how the field got its value
- set by the caller versus defaulted
- model_fields_set
- null sent on purpose must survive
basics
~20 sexclude_unset drops fields the caller never supplied, tracked in model_fields_set; exclude_none drops every None, including an explicit null; exclude_defaults drops values equal to the default. A PATCH handler needs exclude_unset, so a sent null still clears the field.
solid answer
~40 sThe three flags on `model_dump()` and `model_dump_json()` filter on different things. `exclude_unset=True` uses `model_fields_set`, the set of fields explicitly provided at construction or assigned later, so anything filled from a default disappears. `exclude_none=True` looks only at the value and drops every `None`, whether the caller sent `null` or it came from the default. `exclude_defaults=True` drops any value that compares equal to the field's default, even one the caller sent on purpose. For a PATCH I validate the body into a model whose fields all have defaults, then take `patch.model_dump(exclude_unset=True)`: an absent field is missing from the result, while an explicit `null` arrives as `None` and clears the stored value. I then merge that dict into the stored data and re-validate the full model, because `model_copy(update=...)` does not validate.
code
python · 19 linesfrom pydantic import BaseModel
class ProfilePatch(BaseModel):
display_name: str | None = None
bio: str | None = None
newsletter: bool = False
patch = ProfilePatch.model_validate_json('{"bio": null}')
print(patch.model_fields_set)
#> {'bio'}
print(patch.model_dump(exclude_unset=True))
#> {'bio': None}
print(patch.model_dump(exclude_none=True))
#> {'newsletter': False}
print(patch.model_dump(exclude_defaults=True))
#> {}go deeper
Recall that exclude_unset drops fields the caller did not send, exclude_none drops None values, and exclude_defaults drops values equal to the default.
Explain model_fields_set and walk through the PATCH flow: a patch model with defaults, exclude_unset to get the changes, and why an explicit null must survive to clear a field.
Show the production traps: model_copy skipping validation, nested updates replacing whole objects, assignments in validators marking fields as set, and combined flags dropping nulls.
Set a team convention for partial updates, one patch model per resource and a single merge-and-revalidate helper, so absent-versus-null handling is not reinvented per endpoint.
## What Pydantic remembers about each field Every Pydantic 2 model instance keeps a set called **`model_fields_set`**: the names of the fields that were **explicitly provided** when the instance was created, whether by keyword, by `model_validate()` or by `model_validate_json()`. A field filled from its `default` or `default_factory` is not in it. Assigning to a field after construction adds that field to the set, and so does `model_copy(update=...)` for the keys it updates. The three exclusion flags of `model_dump()` and `model_dump_json()` each filter on a different property: | Flag | Drops a field when | Explicit `null` from the caller | Value the caller sent that equals the default | |---|---|---|---| | `exclude_unset=True` | it is not in `model_fields_set` | kept, as `None` | kept | | `exclude_none=True` | its value is `None` | dropped | kept, unless it is `None` | | `exclude_defaults=True` | its value `==` the field's default | dropped when the default is `None` | dropped | Only `exclude_unset` asks *how the value got there*. The other two look at the value alone, so they cannot tell "the client said nothing" from "the client said null". ## The PATCH pattern A partial update needs three outcomes per field: leave it alone (absent), clear it (explicit `null`), or set it (a value). With Pydantic: 1. Declare a **patch model** whose every field has a default, usually `None`, so an absent field validates. 2. Validate the request body into it with `model_validate_json()`. 3. Take `changes = patch.model_dump(exclude_unset=True)`. Absent fields are not in `changes`; a field sent as `null` is present with value `None`. 4. Merge `changes` over the stored record and **re-validate the full model**, for example `Profile.model_validate(stored.model_dump() | changes)`. Step 4 matters. `model_copy(update=changes)` is tempting, but its docstring is explicit: updates are **not validated** and **not applied recursively**. A `null` sent for a field the full model requires would be stored silently, and an update to one key of a nested model would replace the whole nested object. Re-validating the merged dict catches the first. The shallow `|` merge above still replaces a nested object wholesale, so a deep partial update of nested data needs a recursive merge before validation. ## Traps that break the pattern - **Combining flags.** `exclude_unset=True, exclude_none=True` together drop the explicit `null` again, so the client can never clear a field. - **Assigning in code.** Setting `patch.bio = ...` after construction, including inside an after-mode model validator, marks the field as set, so it reappears in the `exclude_unset` dump. - **Defaults are not "set".** A field filled by `default_factory` is unset too, so it vanishes from the patch, which is what you want. - **Round trips set everything.** If you dump a model in full and validate the result again, every field is now in `model_fields_set`, and a later `exclude_unset` dump includes values that were originally defaults. - **Nested models.** Each nested model instance keeps its own `model_fields_set`, so `exclude_unset` also filters inside nested objects that the caller did send. ## When the other two flags are right - `exclude_none` suits outbound payloads where `null` and absent mean the same to the consumer and you want a smaller body. - `exclude_defaults` suits a compact export where any value equal to the default can be reconstructed by the reader. It is wrong for PATCH, because a client that deliberately sets a field back to its default value is ignored. ## Pinning the behaviour with tests The pattern is easy to break in a refactor, so cover the four outcomes per resource: - a body that omits a field leaves the stored value unchanged; - a body with an explicit `null` clears an optional field; - a body with a value replaces the stored value; - a body with `null` for a field the full model requires is rejected by the re-validation step, not stored. A fifth test is worth adding when validators assign values: send a body that omits the normalised field and assert that the dump from `exclude_unset=True` still omits it. ## An alternative since 2.14 Pydantic also offers a **`MISSING` sentinel**, stable since 2.14 and imported with `from pydantic import MISSING`: a field whose value is `MISSING` is left out of every dump automatically, which models "absent" in the value itself instead of in `model_fields_set`. The documentation offers it as an alternative to `exclude_unset`, and `exclude_unset` remains the common pattern.
- Why not apply the patch with stored.model_copy(update=changes)?`model_copy(update=...)` writes the values straight into the copy without validating them and without merging nested models, so a `null` for a required field or a wrongly typed value is stored silently, and a partial nested update replaces the whole nested object. Merging into a dict and calling `model_validate()` on the full model runs every type check and validator again.
- A model validator assigns a normalised value to a field the client did not send; what happens to the PATCH dump?Assignment after construction adds the field to `model_fields_set`, so `model_dump(exclude_unset=True)` now includes it and the handler overwrites a value the client never touched. Normalise only fields already in `model_fields_set`, or do the normalisation on the full model after the merge.
- How do you see which fields a request actually supplied, without dumping?Read `patch.model_fields_set`, a set of field names. It is the same information `exclude_unset` uses, so you can branch on it directly, for example to require at least one field in a PATCH body, or to audit which attributes a client changed.
A change-of-address form with one box per line: a box left untouched means keep what you have, while a box with 'remove' written in it means clear it. exclude_unset reads which boxes were touched; exclude_none only sees that both look empty.
- exclude_none is enough for PATCH because absent fields are None anyway
- exclude_defaults keeps explicit values the client sent, even if they equal the default
- model_fields_set is fixed at construction and never changes afterwards
- model_copy(update=...) validates the updated values like the constructor does
- Adding exclude_none to exclude_unset is harmless extra cleanup