Request Body with Pydantic Models

Defining Your First Pydantic Model

Pydantic models serve as the foundational building blocks for data validation in FastAPI. When you define a class that inherits from Pydantic's BaseModel, you are essentially establishing a contract for the data structure that your application expects to receive. Inside this model, you declare fields with specific type annotations. When a request arrives, FastAPI inspects the incoming JSON payload and attempts to coerce it into the types you defined. If the client sends data that cannot be converted—such as a string where an integer is expected—FastAPI automatically intercepts the error and returns a 422 Unprocessable Entity response, complete with a detailed explanation of what went wrong. This declarative approach eliminates the need for manual data parsing and redundant type checking, ensuring that by the time your code reaches your business logic, the data is already cleaned, typed, and validated. This architectural choice pushes data integrity concerns to the boundary of your application, keeping your core business logic clean and predictable.

from pydantic import BaseModel

# Define the structure of the data expected from the client
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False  # Default value for optional fields

Integrating Models into Path Operations

Once you have defined your Pydantic model, integrating it into a path operation function is straightforward. You simply declare the model as a parameter in your function signature. FastAPI detects that this parameter is a Pydantic model and automatically looks for it in the request body. Because the framework uses Python type hints for reflection, it understands that the JSON body must correspond to the structure defined in your class. When the request is received, the framework parses the JSON, validates it against the schema, and initializes an instance of your model class. This means you do not have to manually parse dictionary keys or handle missing values manually. Your function receives a fully instantiated Python object, allowing you to access fields using dot notation rather than string keys. This provides a robust development experience, as it allows your IDE to provide accurate autocompletion and type checking, drastically reducing the surface area for common runtime errors related to missing or malformed data.

from fastapi import FastAPI

app = FastAPI()

@app.post("/items/")
def create_item(item: Item):
    # FastAPI validates the body against the Item model automatically
    return {"received": item.name, "total_price": item.price}

Handling Nested Data Structures

Real-world APIs often require hierarchical data, where one object contains others. Pydantic makes this simple by allowing you to use other Pydantic models as field types within your main schema. This approach allows you to model complex JSON objects with deep nesting without writing custom validation code for each level of the tree. When a client sends a complex JSON payload, FastAPI recursively validates each nested object against its respective model. If any deep part of the JSON is invalid, the framework aggregates all validation errors and reports them in a structured format back to the client. This recursive validation logic is critical for maintaining consistency in large payloads where manual validation would quickly become unmanageable and error-prone. By nesting models, you gain the ability to enforce strict data constraints at every level, ensuring that internal objects adhere to the same quality standards as top-level request parameters, ultimately leading to a more resilient system architecture.

class User(BaseModel):
    username: str

class Post(BaseModel):
    title: str
    author: User  # A nested Pydantic model structure

@app.post("/posts/")
def create_post(post: Post):
    return {"post_title": post.title, "author": post.author.username}

Utilizing Advanced Field Constraints

While basic type annotations provide essential validation, Pydantic offers the Field class to add additional constraints to your data fields. These constraints can include numeric ranges, string length limits, regex patterns, or specific validation logic. By applying these constraints, you can ensure that the data strictly conforms to your application's domain logic before it is ever processed. For instance, if you require that a price must always be positive or a username must match a specific format, Field allows you to express these requirements directly within the model definition. This metadata is not only used for runtime validation but is also automatically exposed in the OpenAPI documentation generated by FastAPI. Consequently, developers interacting with your API can immediately understand the limitations and requirements of each field without having to inspect the source code or guess the constraints. This tight integration between validation and documentation promotes a consistent and professional API design that is self-documenting and easy for both front-end and back-end teams to understand.

from pydantic import Field

class ValidatedItem(BaseModel):
    name: str = Field(..., min_length=3)
    price: float = Field(..., gt=0)  # Must be greater than zero

@app.post("/safe-items/")
def save_item(item: ValidatedItem):
    return item

Handling Multiple Models and Body Parameters

Sometimes your API endpoint needs to accept both a Pydantic model for the main data and additional query parameters or single path variables simultaneously. FastAPI manages this intelligently by distinguishing between different types of parameters. Any parameter defined in the function signature that is not part of the path (path parameter) and is a Pydantic model will be interpreted as a request body. You can even combine multiple Pydantic models in a single endpoint if the request body is expected to be a JSON object containing different components. If you need to map a JSON body to a specific field name using Body(), you can define it as such. This granular control allows you to design flexible endpoints that handle diverse input sources while still benefiting from automatic validation and documentation. By understanding how FastAPI resolves parameter sources, you can build sophisticated endpoints that maintain high performance and readability while strictly enforcing data schemas, making the API easier to maintain and scale over time as your product evolves.

from fastapi import Body

@app.post("/complex-request/")
def complex_endpoint(item: Item, user: User = Body(...)):
    # Multiple models can be parsed from the same JSON payload
    return {"item": item.name, "user": user.username}

Interview questions

All FastAPI interview questions →

Check yourself

Take the full FastAPI quiz →