Pydantic: Required vs. Optional Fields

Why it exists

To provide a clear, type-safe way to distinguish between data that a client must provide versus data that is optional or has a sensible fallback. This prevents runtime errors from missing keys and simplifies API contracts by making intent explicit.

The mental model

Think of a Pydantic model as a contract. By default, every field you declare is a mandatory clause. To make a clause optional, you must explicitly state what happens if it's not provided by giving it a default value. If a field has a default, Pydantic won't raise an error if it's missing from the input data.

How it works

Pydantic inspects the type annotations and assignments in your model definition. A field without a default value (e.g., username: str) is required. A field with a direct default value (e.g., items_in_cart: int = 0) is optional and will use 0 if not provided. A field typed with a union including None and given a default of None (e.g., middle_name: str | None = None) is also optional. To set a default while adding other metadata, use the Field() function's default argument: score: int = Field(default=0).

When to use it

Use default values for fields that have a logical fallback, like a status flag (is_enabled: bool = True). Use Optional[T] = None (or T | None = None) for fields that are genuinely optional and have no other sensible default, like a user's bio. This is fundamental to building almost any Pydantic model for an API.

When not to use it

Avoid setting defaults for fields that are essential for the object's identity or core function, such as a user's email or a product's id. Forcing the client to provide this data makes the API contract more robust and explicit. The footgun is assuming my_field: str = Field(...) sets a default; it does not, it only attaches metadata to a required field.

One canonical example

In a UserProfile model, username: str is required and will raise an error if missing. is_premium_member: bool = False is optional and defaults to False if not provided. bio: str | None = None is also optional, defaulting to None. Finally, follower_count: int = Field(default=0) shows how to set a default while also providing other configurations via Field().