Bagaimana Anda memodelkan badan permintaan yang bersarang dan kompleks?

Question

Accepted Answer

Model Pydantic dapat **bersarang** — bidang model dapat berupa model lain, daftar model, atau tipe kompleks — memungkinkan FastAPI memvalidasi JSON yang sangat terstruktur (objek dalam objek, array objek) secara otomatis.

## Model bersarang

```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"] }
```

Bidang model yang diketik sebagai model lain (atau `list[Model]`) divalidasi secara rekursif — objek bersarang dan array objek semuanya diperiksa terhadap skema mereka secara otomatis.

## Tipe kompleks dan khusus

```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 menangani tipe kaya: enums (membatasi pada nilai yang diizinkan), `datetime` (mengurai string ISO), `HttpUrl`/`EmailStr` (validasi format), dan typed dicts/tuples — semuanya divalidasi secara otomatis.

## Wrapper generik / dapat digunakan kembali

```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 }
```

## Mengapa ini penting

API dunia nyata jarang berurusan dengan data rata — mereka menangani struktur kompleks dan bersarang (pengguna dengan alamat dan daftar pesanan, pesanan dengan item baris, objek konfigurasi), dan kemampuan Pydantic untuk **bersarang model** membuat validasi badan permintaan yang sangat terstruktur menjadi tanpa kesulitan.

Memahami bahwa bidang model dapat berupa model lain, daftar model, atau tipe kaya — dan bahwa FastAPI **memvalidasi seluruh struktur bersarang secara rekursif** dan otomatis — penting untuk membangun API yang menerima input realistis dan kompleks dengan aman.

Dukungan tipe kaya (enums untuk nilai terbatas, penguraian `datetime`, validasi format `HttpUrl`/`EmailStr`, koleksi yang diketik) selanjutnya memastikan data kompleks benar tanpa pemeriksaan manual.

Mengetahui cara memodelkan badan bersarang dan kompleks (dan wrapper generik yang dapat digunakan kembali untuk hal-hal seperti paginasi) adalah pengetahuan praktis untuk membangun API yang menangani data terstruktur yang diperlukan aplikasi nyata, dengan validasi lengkap disediakan secara otomatis — kekuatan utama desain berbasis Pydantic FastAPI.