Python【What Is Pydantic?】The Data Validation Engine Behind FastAPI

What Is Pydantic (and Why It Matters)

Pydantic is the data validation engine behind FastAPI — a Python library that guarantees your API’s data remains accurate, type-safe, and consistent.

So how does Pydantic guard your data?

By defining a schema.

Defining a Schema with Pydantic

Why You Need a Schema

When building APIs with FastAPI, you must define the structure of the data your API will receive and return.

How to Write a Schema

This is the Schema.

from pydantic import BaseModel

class SearchRequest(BaseModel):
    query: str
    topk: int

If a user sends this JSON:

{"query": "moon phases", "topk": "five"}

FastAPI will automatically return an error:
topk must be an integer, not a string.
That’s Pydantic at work — validating your data before it ever reaches your logic.

How JSON Validation Works

FastAPI communicates with clients using JSON.
But the data you receive isn’t always correct.

Examples:

• "topk": "3" → value is a string, not an integer.
• Missing "query" field → incomplete data.

Summary: The Structural Logic

Sample Directory Structure

project_name/api/
├─ main.py        … FastAPIアプリ本体・共通初期化・Router登録・/dashboard
├─ models.py          … Pydanticの入出力スキーマ（全エンドポイント共通）
└─ routers/
   ├─ chat.py         … /search /ask /generate（チャット系API）
   ├─ stats.py        … /stats/*（ヘルス・計測・可観測性）
   ├─ admin_canary.py … /admin/canary/*（カナリア配信の切替・比率）
   ├─ admin_incidents.py … /admin/incidents/*（インシデント運用）
   ├─ admin_backup.py … /admin/backup/*（バックアップ運用）
   └─ admin_cache.py  … /admin/cache/*（キャッシュ運用）

Core Structure of FastAPI｜Definition → Action → Execution

FastAPI Application
├── models/   ← Pydantic layer
│      Defines data structures (schemas)
│      Example: SearchRequest, GenerateResponse
│
├── routers/  ← FastAPI layer
│      Defines API routes and logic
│      Example: /search, /generate
│
└── main.py   ← Application layer
       Assembles and initializes the entire app

• models＝ what data looks like（定義）
• routers＝ what app does（動作）
• main/app＝ how everything runs（起動）

Difference Between models.py and routers

In FastAPI, Pydantic is used inside models.py to define the structure of your data.
The routers/ directory, on the other hand, uses those models to create actual API endpoints.
Together, they form the foundation of your app’s structure — definition and action.

Summary

In short:

models.py → Definition
routers/ → Action

So:
models.py protects the structure.
routers operate based on that structure.

Core Pydantic Classes

Canary deployment schemas ?

a canary in a coal mine 🐤

Note｜Canary Deployment Schemas

In large-scale systems, not every update is released to everyone at once.
Instead, new versions are gradually rolled out to a small group of users first — this is called canary deployment.

🐤 The name comes from the canaries once used in coal mines.

In the past, these birds were the first to sense danger when the air turned toxic.
Similarly, in software development, a canary deployment means releasing new code to a small group of users first — to detect problems before they spread.

Vocabulary

• entry layer | エントリ層
• router | ルーター
• middleware | ミドルウェア
• exception handler | 例外ハンドラ
• request/response schema | リクエスト/レスポンスのスキーマ
• canary rollout | カナリア配信
• observability | 可観測性
• lifespan | ライフスパン（起動/終了フック）
• application state | アプリケーション状態
• dependency injection | 依存性注入

Closing Thought

FastAPI is fast — but what makes it trustworthy is Pydantic.
It’s the quiet engine that turns code into structure and structure into reliability.
Pydantic transforms speed into stability, and simplicity into safety.

Pydantic entrusts correctness to structure, not to human attention.
It prevents errors before they appear, building reliability through design.

なぜスキーマが必要か

FastAPIでAPIを作るとき、どんなデータを受け取り、どんなデータを返すかを定義しなければならない。
そのデータの「形」を決める設計図をスキーマという。

Pydantic：データ完全性の番人

Pydanticは、APIで扱うデータが正しい形式かどうかをチェックするPythonライブラリ。
受け取ったJSONが想定した型と一致しているかを検証し、正しいデータだけを通す。
いわば「正しい形のデータしか通さない門番」のような存在。

JSONの中身をどう検証しているか

FastAPIの通信は基本的にJSON形式だが、送られてくるデータがいつも正しいとは限らない。

例：

• "topk": "3" → 文字列として送られている
• "query" が欠けている

こうした不整合をPydanticが検出し、FastAPIが自動でエラーレスポンスを返す。
これにより、バグやセキュリティ事故を未然に防ぐことができる。

補足｜カナリアデプロイ用スキーマ

大規模なシステムでは、すべてのユーザーに一度に新バージョンを配信するわけではない。
まず一部のユーザーだけに段階的に展開する ―― これが カナリアデプロイ（Canary Deployment） 。

名前の由来は炭鉱の「カナリア」。 昔、空気が悪くなると最初に気づく存在がカナリアだった。 同じように、新しいコードをまず一部のユーザーに試してもらって、問題がないか確認する手法。

おわりに

FastAPIは速さで注目されるが、その信頼性を支えているのはPydantic。
コードを構造に変え、構造を信頼に変える静かなエンジン。
スピードを安定に、シンプルさを安全に変える──それがPydanticの真価。

Pydanticは「正しさ」を人間の注意ではなく、構造に委ねる設計思想。
エラーを起こす前に防ぎ、信頼を構造的に築く。