Request-body schemas
Define JSON payloads for POST, PUT, PATCH, or similar operations.
FastAPI · Class
BaseModel
BaseModel is the Pydantic superclass for defining typed data models in FastAPI. Subclass it to describe request bodies with standard Python annotations, enabling structured input handling and automatic API schema generation.
How it works
BaseModel is a Pydantic base class used to define typed data models. In FastAPI, a path-operation parameter annotated with such a model is interpreted as a request body, while the model's fields provide validation and schema information.
Syntax
class ModelName(BaseModel):
field_name: field_typeKey points
- Create a data model by subclassing BaseModel.
- Declare model fields with ordinary Python type annotations.
- Use a BaseModel-derived Pydantic model to describe request-body data.
- FastAPI distinguishes path inputs by matching parameter names with placeholders in the route.
- A model-typed endpoint parameter is read as structured request-body input.
- One operation can combine model-based body data with path and query parameters.
Common mistakes
- A model parameter is not treated as a path parameter; path parameters are selected by matching their names to the route.
- Declaring a model parameter makes FastAPI read it from the request body, so clients must send the matching structured payload.
Example: BaseModel request body
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
@app.post("/items/")
async def create_item(item: Item) -> Item:
return item
The model declares the request fields and their Python types; FastAPI uses the model parameter as the request body and returns the validated model.
When to use it
Reusable data models
Share one typed structure across multiple endpoint declarations.
Structured and nested data
Expose nested objects with explicit field types.
Interview questions
QWhat does BaseModel provide in a FastAPI endpoint?
A class inheriting from Pydantic's BaseModel defines the fields of a data model using standard Python types. FastAPI uses that model to interpret a path-operation parameter as request-body data and to generate its schema.
Follow-up: How can the same model participate in response handling? Annotate the return type or use response_model; FastAPI can then validate, document, serialize, and filter the returned data.
QHow are fields declared and typed?
Each model attribute is declared with a Python type, such as str or float, and optional fields can have a default of None. FastAPI uses those declarations for request-body structure and automatic documentation.
Follow-up: How would you represent nested JSON? Define a field whose type is another Pydantic model; FastAPI supports arbitrarily deeply nested models.
QHow does FastAPI decide where endpoint input comes from?
A parameter annotated with a Pydantic model is taken from the request body, while a parameter whose name matches a path placeholder is taken from the path. Body, path, and query parameters can be declared together.
Follow-up: Can model fields come from forms instead? Yes: declare the model with Form and FastAPI extracts each field from submitted form data.
Related
Pydantic modelsRequest BodyResponse Model - Return TypeNested ModelsForm Models