How to Use Optional Fields in Pydantic Models with FastAPI

In FastAPI, you make a field optional in a Pydantic model by using Optional from the typing module and setting a default value like None. This tells FastAPI that the field can be missing in the request without causing validation errors.

Syntax

To declare an optional field in a Pydantic model for FastAPI, you use Optional[Type] from Python's typing module and assign a default value, usually None. This means the field can be left out when sending data.

• Optional[Type]: Marks the field as optional of the given type.
• default value: Usually None, it sets the default if the field is missing.

python

from typing import Optional
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: Optional[str] = None  # Optional field with default None
    price: float
    tax: Optional[float] = None  # Another optional field

Example

This example shows a FastAPI app with a Pydantic model where some fields are optional. When you send a POST request without the optional fields, FastAPI accepts it without errors and uses None for missing optional fields.

python

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

@app.post("/items/")
async def create_item(item: Item):
    return {
        "name": item.name,
        "description": item.description,
        "price": item.price,
        "tax": item.tax
    }

Output

POST /items/ with JSON {"name": "Book", "price": 12.5}
Response: {"name": "Book", "description": null, "price": 12.5, "tax": null}

Common Pitfalls

Common mistakes when using optional fields include:

• Not importing Optional from typing.
• Forgetting to assign a default value like = None, which makes the field required.
• Using Optional without a default value still requires the field in input.

Always combine Optional[Type] with a default value to make a field truly optional.

python

from typing import Optional
from pydantic import BaseModel

# Wrong: Optional but no default, field is required
class WrongItem(BaseModel):
    name: str
    description: Optional[str]  # This is still required

# Right: Optional with default None
class RightItem(BaseModel):
    name: str
    description: Optional[str] = None  # Truly optional

Quick Reference

Concept	Usage	Effect
Optional field	field: Optional[Type] = None	Field can be missing or null in input
Required field	field: Type	Field must be present in input
Optional without default	field: Optional[Type]	Field is still required (common mistake)
Default value	field: Type = default_value	Field is optional with default
Use in FastAPI	Use Pydantic model with Optional fields	Allows flexible request bodies

Key Takeaways

Use Optional[Type] with a default value like None to make fields optional in Pydantic models.

Without a default value, Optional fields are still required in input.

FastAPI uses Pydantic models to validate requests and respects optional fields properly.

Always import Optional from typing to avoid errors.

Optional fields help create flexible APIs that accept partial data.