Resource Schemas for CRUD Operations

1. The Problem with a "One-Size-Fits-All" Schema

In a typical CRUD (Create, Read, Update, Delete) workflow, the data you expect as input is often different from the data you send back as output.

Consider a User resource:

• Creating a user (input): The client sends a username, email, and password. They should not be able to specify a user id, as this is generated by the database.
• Reading a user (output): The API returns the user's id, username, and email. It must never send the password back to the client.
• Updating a user (input): The client might want to update just the email. They shouldn't be forced to provide all other fields. This means the fields in an update schema are often optional.

Using a single Pydantic model for all these cases leads to awkward compromises, like making fields optional when they should be required in certain contexts. Let's watch a short video that frames this problem clearly.

This tension between what the client provides and what the database stores is precisely why we need separate schemas.

2. The Solution: Schemas for Different Contexts

The solution is to define distinct Pydantic models for each context: creation, response, and updates. This allows you to enforce strict, context-specific rules for your data.

A great way to understand this is by reading the SQLModel documentation written by FastAPI's creator, Sebastián Ramírez (Tiangolo). Although it uses SQLModel, the concepts for defining separate Pydantic BaseModel schemas are identical.

As the documentation shows, FastAPI uses these distinct models to automatically:

• Validate incoming data: The HeroCreate type hint ensures clients can only send name, secret_name, and age.
• Filter and serialize outgoing data: The response_model=HeroPublic parameter ensures the response includes the id and matches the response schema. This is a powerful security feature that prevents accidentally leaking sensitive data, like passwords or internal fields.

The result is a clear and self-documenting API. The generated OpenAPI documentation (Swagger UI) will show different schemas for input and output, making the API contract unambiguous for frontend developers.

3. Schemas for Updates: PUT vs. PATCH

The pattern of separate schemas becomes even more crucial when handling updates. HTTP has two primary methods for updates: PUT and PATCH.

• PUT: Requires the client to send the entire resource representation. If a field is omitted, it should be set to its default value (e.g., null). This implies a schema where all fields are required, much like a Create schema.
• PATCH: Allows the client to send a partial representation, including only the fields they want to change. This requires a schema where all fields are optional.

Your experience with DRF serializers maps here: you might use the same serializer for create and PUT, but a PATCH operation often requires partial=True. In Pydantic, we achieve this by defining an Update schema.

Let's watch how to implement this in practice.

The model_dump(exclude_unset=True) method is the idiomatic way to handle partial updates in FastAPI and is a vital technique to add to your toolkit.

4. Avoiding Duplication with Inheritance

You've probably noticed that our Create, Update, and Response schemas share many of the same fields. Manually keeping them in sync is tedious and error-prone. This is where a key Object-Oriented principle—inheritance—comes to the rescue, a practice you're interested in for building modern applications.

We can define a Base schema with all the common fields and then have our specific schemas inherit from it.

Let's return to the SQLModel documentation to see this elegant solution.

So, a common structure for a resource might look like this:

from pydantic import BaseModel
from typing import Optional




# 1. Base model with shared fields
class ItemBase(BaseModel):
    name: str
    description: Optional[str] = None
    price: float




# 2. Create model inherits from Base
class ItemCreate(ItemBase):



    # No extra fields needed for creation
    pass




# 3. Update model with all fields optional
class ItemUpdate(BaseModel):
    name: Optional[str] = None
    description: Optional[str] = None
    price: Optional[float] = None



    # Note: It's often simpler to define the Update model separately
    # rather than inheriting, because all fields change their type to Optional.




# 4. Response model inherits from Base and adds fields from the DB
class ItemResponse(ItemBase):
    id: int
    owner_id: int

    class Config:
        orm_mode = True # Now called `from_attributes` in Pydantic v2

This structure is scalable, maintainable, and clearly communicates the intent of your API.

Conclusion

Today you've learned a crucial pattern for professional API development with FastAPI. By using separate Pydantic schemas, you create a more secure, robust, and well-documented API.

Key Takeaways:

• A single data model rarely fits all CRUD operations.
• Create Schema: Defines the data a client sends to create a resource. It should exclude server-generated fields like id.
• Response Schema: Defines the data the server sends back. It should include server-generated fields and exclude sensitive data like passwords. Use it with the response_model parameter.
• Update Schema: Defines the data for PATCH requests. It typically has all fields marked as optional.
• Use model.model_dump(exclude_unset=True) to get a dictionary of only the fields provided by the client in a partial update.
• Use inheritance from a Base model to keep your schemas DRY (Don't Repeat Yourself) and easy to maintain.

In our next lesson, we will dive deeper into configuring these models. You will learn how to configure Pydantic model behavior, such as ORM integration, using model_config. This will bridge the gap between our Pydantic data schemas and our database models, a crucial step toward building a complete application.