Bagaimana anda memodelkan badan permintaan yang bersarang dan kompleks?

Question

Accepted Answer

Model Pydantic dapat **bersarang** — medan model dapat menjadi model lain, daftar model, atau tipe kompleks — memungkinkan FastAPI memvalidasi JSON yang terstruktur dalam (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"] }
```

Medan model yang diketik sebagai model lain (atau `list[Model]`) divalidasi secara rekursif — objek bersarang dan array objek semua 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: enum (batasi ke nilai yang diizinkan), `datetime` (mengurai string ISO), `HttpUrl`/`EmailStr` (validasi format), dan dict/tuple yang diketik — semuanya divalidasi secara otomatis.

## Pembungkus 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 menangani data datar — mereka menangani struktur kompleks dan bersarang (pengguna dengan alamat dan daftar pesanan, pesanan dengan item baris, objek konfigurasi), dan kemampuan Pydantic untuk **menyarangkan model** membuat memvalidasi badan permintaan yang terstruktur dalam menjadi mudah.

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

Dukungan tipe kaya (enum 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 pembungkus generik yang dapat digunakan kembali untuk hal seperti paginasi) adalah pengetahuan praktis untuk membangun API yang menangani data terstruktur yang diperlukan aplikasi nyata, dengan validasi lengkap yang disediakan secara otomatis — kekuatan utama desain berbasis Pydantic FastAPI.