ネストされた複雑なリクエストボディをどうモデル化しますか？

Question

Accepted Answer

Pydanticモデルは**ネストされた**構造を持つことができます — モデルのフィールドは別のモデル、モデルのリスト、または複雑な型そのものになることができます — FastAPIが深くネストされたJSON（オブジェクト内のオブジェクト、オブジェクトの配列）を自動的に検証することを可能にします。

## ネストされたモデル

```python
from pydantic import BaseModel

class Address(BaseModel):
    street: str
    city: str
    zip: str

class User(BaseModel):
    name: str
    address: Address                    # a NESTED model
    tags: list[str] = []                # a list of strings
    addresses: list[Address] = []       # a list of NESTED models

@app.post("/users")
def create(user: User):                  # validates the WHOLE nested structure
    return user
```

```json
// FastAPI validates this entire structure, including the nested address:
{ "name": "Ann",
  "address": { "street": "1 Main", "city": "NY", "zip": "10001" },
  "tags": ["vip"] }
```

別のモデルとして型付けされたモデルフィールド（または `list[Model]`）は再帰的に検証されます — ネストされたオブジェクトと配列内のオブジェクトはすべてスキーマに対して自動的にチェックされます。

## 複雑で特殊な型

```python
from pydantic import BaseModel, HttpUrl, EmailStr
from datetime import datetime
from enum import Enum

class Status(str, Enum):                 # enums constrain to allowed values
    active = "active"
    inactive = "inactive"

class Item(BaseModel):
    url: HttpUrl                          # validates URL format
    email: EmailStr                       # validates email format
    created: datetime                     # parses ISO 8601 strings → datetime
    status: Status                        # must be one of the enum values
    metadata: dict[str, int]              # typed dict
    coordinates: tuple[float, float]      # typed tuple
```

Pydanticは豊富な型を処理します：enum（許可された値に制限）、`datetime`（ISO文字列を解析）、`HttpUrl`/`EmailStr`（形式検証）、およびtyped dict/タプル — すべてが自動的に検証されます。

## ジェネリック / 再利用可能なラッパー

```python
from typing import Generic, TypeVar
T = TypeVar("T")
class Paginated(BaseModel, Generic[T]):   # a reusable generic response wrapper
    items: list[T]
    total: int
# Paginated[User] → { items: [User...], total: N }
```

## なぜ重要なのか

現実のAPIはまずフラットなデータを扱わず — ネストされた複雑な構造を扱います（アドレスと注文リストを持つユーザー、ラインアイテムを持つ注文、設定オブジェクト）。Pydanticの**モデルをネストする**能力により、これらの深くネストされたリクエストボディの検証は容易になります。

モデルフィールドが別のモデル、モデルのリスト、または豊富な型になることができること — そしてFastAPIが**ネストされた構造全体を再帰的に**自動的に**検証する** — ことを理解することは、現実的で複雑な入力を安全に受け入れるAPIを構築するために重要です。

豊富な型のサポート（制約された値のためのenum、`datetime`解析、`HttpUrl`/`EmailStr`形式検証、型付きコレクション）はさらに、複雑なデータが手動チェックなしで正しいことを保証します。

ネストされた複雑なボディをモデル化する方法（およびページング処理などのために再利用可能なジェネリックラッパー）を知ることは、実際のアプリケーションが必要とする構造化データを処理するAPIを構築するための実践的な知識です。完全な検証は自動的に提供されます — これはFastAPIのPydanticベースの設計の主要な強みです。