Kako modelirate ugniježđena i složena tijela zahtjeva?

Question

Accepted Answer

Pydantic modeli mogu biti **ugniježđeni** — polje modela može biti drugi model, lista modela ili složeni tipovi — što dozvoljava FastAPI-ju da automatski validira duboko strukturirane JSON (objekte unutar objekata, nizove objekata).

## Ugniježđeni modeli

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

Polje modela koje je napisano kao drugi model (ili `list[Model]`) validira se rekurzivno — ugniježđeni objekti i nizovi objekata svi se provjeravaju prema njihovim shemama automatski.

## Složeni i specijalni tipovi

```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 rukuje bogatim tipovima: enums (ograničava na dozvoljene vrijednosti), `datetime` (parsira ISO stringove), `HttpUrl`/`EmailStr` (validacija formata) i typed dicts/tuples — sve validira automatski.

## Generički / ponovno iskoristivi wrapperi

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

## Zašto je to važno

API-ji iz stvarnog svijeta rijetko se bave ravnim podacima — oni rukuju složenim, ugniježđenim strukturama (korisnik s adresom i listom narudžbi, narudžba s stavkama, objekti konfiguracije), a Pydantic-ova sposobnost **ugniježđivanja modela** čini validaciju tih duboko strukturiranih tijela zahtjeva beznaponom.

Razumijevanje da polje modela može biti drugi model, lista modela ili bogat tip — i da FastAPI **validira cijelu ugniježđenu strukturu rekurzivno** i automatski — važno je za izgradnju API-ja koji primaju realistične, složene unose na siguran način.

Podrška bogatih tipova (enums za ograničene vrijednosti, `datetime` parsiranje, `HttpUrl`/`EmailStr` validacija formata, tipizirane kolekcije) dalje osigurava da su složeni podaci ispravni bez ručnih provjera.

Znanje kako modelirati ugniježđena i složena tijela (i ponovno iskoristive generičke wrappere za stvari kao što su straničenja) praktično je znanje za izgradnju API-ja koji rukuju strukturiranim podacima koje zahtijevaju prave aplikacije, s potpunom validacijom pruženijom automatski — ključna snaga FastAPI-jevog Pydantic-temeljnog dizajna.