In Pydantic 2, how do required, optional and defaulted fields differ on a BaseModel, and does `X | None` make a field optional?
answer
- type versus default
- None allowed is not omittable
- error type missing
- version 1 implicit None default
basics
~20 sIn Pydantic 2 a field is required unless it has a default. note: str | None is still required but accepts None; only note: str | None = None may be omitted. Version 1 gave Optional fields an implicit None default.
solid answer
~40 sIn Pydantic 2, **requiredness comes from the default, and nullability comes from the type**. `order_id: int` is required and rejects `None`; `currency: str = 'EUR'` may be omitted; `note: str | None` must still be present in the input, but `null` is an accepted value; `coupon: str | None = None` may be omitted and also accepts an explicit `null`. A missing required field produces a `ValidationError` entry with type `missing`. The trap is version 1, where an `Optional` or `Any` field without a default silently defaulted to `None`; version 2 dropped that so the rules more closely match dataclasses. `Field(...)` without a `default` or `default_factory` keeps a field required even though something is assigned.
code
python · 21 linesfrom pydantic import BaseModel, ValidationError
class Order(BaseModel):
order_id: int
note: str | None
coupon: str | None = None
currency: str = 'EUR'
try:
Order(order_id=1)
except ValidationError as exc:
print([(e['loc'], e['type']) for e in exc.errors()])
#> [(('note',), 'missing')]
order = Order(order_id=1, note=None)
print(order)
#> order_id=1 note=None coupon=None currency='EUR'
print(sorted(order.model_fields_set))
#> ['note', 'order_id']go deeper
Recall the rule: no default means required, and the type decides whether None is allowed. Be ready to name the error type missing.
Explain the required-but-nullable case, why Field() alone keeps a field required, and why defaults are not validated unless validate_default is set.
Show how the version 1 implicit None default breaks silently after an upgrade, and how model_fields_set separates an explicit null from an omitted key.
Argue when a contract should force clients to send an explicit null versus allowing omission, and how that choice is written into shared request models.
## Two separate questions: may it be omitted, may it be null? A Pydantic 2 model is a class that inherits from `BaseModel` and declares its **fields** as annotated class attributes. Every field answers two independent questions, and Pydantic takes each answer from a different place: - **Required or not** is decided by whether the field has a **default** (a plain assignment, `Field(default=...)` or `Field(default_factory=...)`). No default means the key must be present in the input. - **Nullable or not** is decided by the **type annotation**. `str | None` (or `Optional[str]`, which means the same thing) accepts `None` as a valid value; plain `str` rejects it with the error type `string_type`. Mixing the two up is the most common modelling mistake on this subject. `Optional` in the annotation reads like "optional to send", but in Pydantic 2 it only means "may be null". ## The cases side by side For an order received from a partner: | Declaration | May the key be omitted? | Is `null` accepted? | |---|---|---| | `order_id: int` | no | no | | `currency: str = 'EUR'` | yes, becomes `'EUR'` | no | | `note: str \| None` | **no** | yes | | `coupon: str \| None = None` | yes, becomes `None` | yes | | `gift_wrap: str \| None = 'plain'` | yes, becomes `'plain'` | yes | | `metadata: Any` | no | yes, anything is | The third row surprises people: a nullable field without a default is **required but nullable**. The client must send the key, even if the value is `null`. That is useful when "the partner explicitly had no note" and "the partner forgot the field" should not be confused. ## What a missing field looks like When a required field is absent, validation does not stop at the first problem: it carries on through the other fields, and the `ValidationError` it raises reports each failure found. Its `errors()` method returns a list of dictionaries. For a missing field the entry has: - `type`: `'missing'` - `loc`: a tuple naming the field, for example `('note',)` - `msg`: `'Field required'` Fields keep their declaration order, and so do the errors, which makes the list easy to read. ## `Field()` does not by itself create a default `Field()` attaches constraints and metadata to a field. Assigning it does **not** make the field optional: ```python from pydantic import BaseModel, Field class Customer(BaseModel): name: str = Field(max_length=40) # still required tier: str = Field(default='standard') # optional, defaults to 'standard' ``` You may see `Field(...)` with an ellipsis to stress "required"; the documentation discourages it because static type checkers handle it poorly. The **annotated pattern**, `name: Annotated[str, Field(max_length=40)]`, avoids the confusion entirely: there is no assignment, so nobody reads a default into it. Note one limit: type checkers only understand `default`, `default_factory` and `alias` in the assignment form, so put those there. Two more facts worth knowing: 1. Pydantic **does not validate defaults** unless you ask (`validate_default=True`), so `coupon: str = None` lets an omitted coupon become `None`, yet an explicit `null` from the client fails with `string_type`. Write `str | None = None` instead. 2. Unlike a standard dataclass, a Pydantic model may declare a required field after defaulted ones; field order matters for errors and dumps, not for legality. ## What changed from version 1 In Pydantic 1, a field annotated `Optional[X]` or `Any` received an **implicit default of `None`**, so it could be omitted. Version 2 removed that, and the migration guide calls it a breaking change. Code written for version 1 that relied on omitting an `Optional` field now raises a `missing` error, and the fix is to add `= None` explicitly where omission is really allowed. ## Rules of thumb - Decide omission and nullability separately for every field, then write the declaration that says both. - Use `X | None = None` for "may be left out, and null means nothing". - Use `X | None` with no default when the client must state the value, even as `null`. - After validation, `model_fields_set` tells you which fields were explicitly provided, which is how you separate "sent null" from "left out" once both have become `None`.
- In Pydantic 2, after validation both a sent `null` and an omitted `coupon` are `None`. How do you tell them apart?Read `model_fields_set` on the instance: it holds the names of fields that were explicitly provided, including ones provided as `None`. So `'coupon' in order.model_fields_set` is true for an explicit null and false for an omitted key. Dumping only the provided fields is a separate output option.
- Why might a team prefer `name: Annotated[str, Field(max_length=40)]` to `name: str = Field(max_length=40)` in Pydantic 2?The assignment form looks like a default even though the field stays required, which misleads readers. The annotated form has no assignment, can carry several metadata items, and can be reused as a named type. Keep `default`, `default_factory` and `alias` in the assignment form, because static type checkers only read them there.
- Annotating a field Optional means the client may leave it out.
- Assigning Field() to a field always gives it a default value.
- A str field defaulting to None rejects the model at class definition time.
- Required fields must be declared before defaulted ones, as in dataclasses.
- A missing required field raises only the first error and stops validating.
Assumes Pydantic 2; in version 1 an Optional or Any field without a default silently defaulted to None, and version 2 made such fields required.