Example data in schema in FastAPI - Deep Dive

Overview - Example data in schema

What is it?

Example data in schema means providing sample values inside data models to show what kind of data is expected. In FastAPI, schemas are defined using Pydantic models, and example data helps users and developers understand the shape and content of requests and responses. This example data appears in the automatic API documentation, making it easier to test and learn the API.

Why it matters

Without example data, API users might guess what data to send or receive, leading to confusion and errors. Example data acts like a clear signpost, showing exactly how data should look. This improves communication between developers and users, speeds up development, and reduces bugs caused by misunderstandings.

Where it fits

Before learning example data, you should understand how to define schemas with Pydantic models in FastAPI. After mastering example data, you can explore advanced API documentation customization and validation techniques to make your APIs even clearer and more robust.

Mental Model

Core Idea

Example data in schema is like a filled-out form that shows exactly what kind of information is expected in each field.

Think of it like...

Imagine you get a blank job application form. Without any hints, you might not know what to write. But if the form has sample answers filled in, you instantly understand what each question wants.

Schema Model
┌───────────────┐
│  Field Name   │  Example Value
├───────────────┤
│  username     │  "alice123"
│  age          │  30
│  email        │  "[e-mail]"
└───────────────┘

This table shows fields with example data to guide users.

Build-Up - 7 Steps

1

Foundation

Understanding Pydantic Schemas

Concept: Learn what Pydantic schemas are and how they define data shapes in FastAPI.

In FastAPI, you create data models using Pydantic. These models describe what data your API expects or returns. For example, a User model might have fields like name, age, and email, each with a type like string or integer.

Result

You can define clear data structures that FastAPI uses to validate and document your API.

Understanding schemas is the base for adding example data because examples live inside these models.

2

Foundation

What Is Example Data in Schemas

Concept: Example data shows sample values inside schema fields to illustrate expected input or output.

Example data is like a sample filled form inside your schema. It doesn't affect how your API works but helps users see what kind of data to send or expect. FastAPI uses this data to generate interactive docs.

Result

Your API documentation will show sample data, making it easier to understand and test.

Knowing example data is just for documentation helps avoid confusion about its role.

3

Intermediate

Adding Example Data Using Field Arguments

🤔Before reading on: Do you think example data is added by creating a separate example object or by adding parameters inside the schema fields? Commit to your answer.

Concept: You can add example data directly inside schema fields using Pydantic's Field function.

Use Pydantic's Field with the 'example' parameter to add sample values. For instance: from pydantic import BaseModel, Field class User(BaseModel): username: str = Field(..., example="alice123") age: int = Field(..., example=30) This shows example data for each field.

Result

API docs display these example values next to each field.

Understanding that example data lives inside field definitions helps you keep schemas clean and self-explanatory.

4

Intermediate

Using Config Class for Schema Examples

🤔Before reading on: Can you guess if example data can be set for the whole schema at once, or only per field? Commit to your answer.

Concept: You can define example data for the entire schema using the Config class inside the Pydantic model.

Inside your schema, add a Config class with 'schema_extra' dictionary containing an 'example' key: class User(BaseModel): username: str age: int class Config: schema_extra = { "example": { "username": "alice123", "age": 30 } } This sets a full example object for the schema.

Result

The API docs show a complete example object for the schema, not just per field.

Knowing you can provide a full example helps when you want to show realistic data combinations.

5

Intermediate

Example Data in Nested Schemas

Concept: Example data can be nested inside schemas that contain other schemas, showing complex data structures.

If your schema has fields that are other schemas, you can add example data at each level. For example: class Address(BaseModel): city: str = Field(..., example="New York") zip_code: str = Field(..., example="10001") class User(BaseModel): name: str = Field(..., example="Alice") address: Address This shows examples inside nested objects.

Result

API docs display nested example data clearly, helping users understand complex inputs.

Recognizing nested examples lets you document real-world data shapes accurately.

6

Advanced

Customizing OpenAPI Examples in FastAPI

🤔Before reading on: Do you think FastAPI allows multiple examples per schema or only one? Commit to your answer.

Concept: FastAPI supports multiple named examples for a schema using OpenAPI extensions, allowing richer documentation.

You can add multiple examples by using the 'examples' parameter in Field or by customizing the OpenAPI schema directly. For example: class User(BaseModel): username: str = Field(..., examples={ "normal": {"summary": "A normal user", "value": "alice123"}, "admin": {"summary": "An admin user", "value": "admin007"} }) This shows different example scenarios in docs.

Result

API docs let users pick from multiple example inputs, improving clarity and testing.

Knowing how to provide multiple examples helps create professional, user-friendly APIs.

7

Expert

How Example Data Affects API Clients and Testing

🤔Before reading on: Does example data influence API validation or runtime behavior? Commit to your answer.

Concept: Example data is purely for documentation and does not affect validation or runtime, but it can be used by tools to generate test cases or client code.

Example data is ignored by FastAPI when processing requests. However, tools like Swagger UI use it to pre-fill forms, and code generators can use it to create sample clients. Misusing example data as defaults can cause confusion. Understanding this separation helps avoid bugs and improves API usability.

Result

You get clear docs and better testing without risking runtime errors from example data.

Understanding the separation between example data and actual validation prevents common mistakes in API design.

Under the Hood

FastAPI uses Pydantic models to define schemas. When you add example data via Field or Config, FastAPI includes this information in the OpenAPI schema it generates. This schema is a JSON document describing your API's inputs and outputs. The OpenAPI schema is then used by tools like Swagger UI to render interactive documentation with example values shown. At runtime, example data is ignored for validation and processing.

Why designed this way?

Separating example data from validation keeps the API logic clean and focused on correctness. Including examples in the OpenAPI schema leverages existing standards for API documentation, making FastAPI compatible with many tools. This design balances clarity for users with strict data handling for the server.

┌───────────────┐      ┌───────────────┐      ┌───────────────┐
│ Pydantic     │      │ FastAPI       │      │ OpenAPI       │
│ Schema       │─────▶│ Generates     │─────▶│ Schema JSON   │
│ with Example │      │ OpenAPI Spec  │      │ with Examples │
└───────────────┘      └───────────────┘      └───────────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ Swagger UI Docs  │
                          │ Shows Example    │
                          └─────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does example data affect how FastAPI validates incoming requests? Commit to yes or no.

Common Belief: Example data is used by FastAPI to validate and fill missing fields in requests.

Reality: Example data is only for documentation and does not affect validation or default values.

Why it matters: Confusing example data with defaults can cause developers to expect automatic filling of missing data, leading to runtime errors.

Quick: Can you add multiple named examples to a single schema field in FastAPI? Commit to yes or no.

Common Belief: You can only add one example per field in FastAPI schemas.

Reality: FastAPI supports multiple named examples using the 'examples' parameter, allowing richer documentation.

Why it matters: Knowing this enables better API documentation that covers different use cases, improving user understanding.

Quick: Does example data appear in the actual JSON response sent by FastAPI? Commit to yes or no.

Common Belief: Example data is included in the API responses sent to clients.

Reality: Example data is not sent in responses; it only appears in the API documentation.

Why it matters: Misunderstanding this can lead to confusion about what data clients actually receive.

Quick: Is it a good practice to use example data as default values in schemas? Commit to yes or no.

Common Belief: Using example data as default values is recommended to simplify client requests.

Reality: Example data should not be used as defaults because it can cause unexpected behavior and hides required fields.

Why it matters: Mixing examples with defaults can cause bugs and unclear API contracts.

Expert Zone

1

Example data can be overridden or extended in subclasses of schemas, allowing flexible documentation for inherited models.

2

When using complex nested schemas, example data must be carefully coordinated to avoid inconsistent or incomplete examples in docs.

3

FastAPI's automatic docs cache example data, so changes may require server restart to reflect in UI.

When NOT to use

Avoid relying on example data for input validation or defaulting values; use Pydantic's default and validator features instead. For APIs that require dynamic example generation, consider custom OpenAPI schema generation or external documentation tools.

Production Patterns

In production, example data is used to create clear, interactive API docs that help frontend teams and third-party developers test endpoints quickly. Multiple named examples demonstrate different scenarios, and nested examples clarify complex data. Teams often automate example updates alongside schema changes to keep docs accurate.

Connections

API Documentation

Example data is a key part of API documentation generation.

Understanding example data helps you create clearer, more useful API docs that improve developer experience.

Data Validation

Example data complements but does not replace data validation.

Knowing the difference prevents mixing documentation with runtime logic, leading to more robust APIs.

User Interface Design

Example data in APIs is like placeholder text in UI forms.

Recognizing this connection helps design APIs that are intuitive and easy to use, just like good UI.

Common Pitfalls

#1 Using example data as default values causing unexpected behavior.

Wrong approach:

class User(BaseModel):
username: str = Field("alice123", example="alice123")
age: int = Field(30, example=30)

Correct approach:

class User(BaseModel):
username: str = Field(..., example="alice123")
age: int = Field(..., example=30)

Root cause:

Confusing example data with default values leads to fields being optional unintentionally.

#2 Not providing example data, making API docs unclear.

Wrong approach:

class User(BaseModel):
username: str
age: int

Correct approach:

class User(BaseModel):
username: str = Field(..., example="alice123")
age: int = Field(..., example=30)

Root cause:

Omitting examples leaves users guessing expected data formats.

#3 Adding example data only at the top-level schema, ignoring nested fields.

Wrong approach:

class Address(BaseModel):
city: str

class User(BaseModel):
name: str = Field(..., example="Alice")
address: Address

class Config:
schema_extra = {"example": {"name": "Alice", "address": {}}}

Correct approach:

class Address(BaseModel):
city: str = Field(..., example="New York")

class User(BaseModel):
name: str = Field(..., example="Alice")
address: Address

class Config:
schema_extra = {"example": {"name": "Alice", "address": {"city": "New York"}}}

Root cause:

Ignoring nested examples causes incomplete or confusing documentation.

Key Takeaways

Example data in FastAPI schemas helps users understand what data to send or expect by showing sample values.

Example data is only for documentation and does not affect validation or runtime behavior.

You can add example data per field using Field or for the whole schema using the Config class.

Multiple named examples and nested examples improve clarity for complex APIs.

Avoid mixing example data with default values to prevent bugs and confusion.