Hur modellerar du kapslade och komplexa request bodies?

Question

Accepted Answer

Pydantic-modeller kan **kapslas** — ett modellsfält kan i sig vara en annan modell, en lista med modeller, eller komplexa typer — vilket låter FastAPI validera djupt strukturerad JSON (objekt inom objekt, arrayer av objekt) automatiskt.

## Kapslade modeller

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

Ett modellsfält som är typad som en annan modell (eller `list[Model]`) valideras rekursivt — kapslade objekt och arrayer av objekt kontrolleras alla mot sina scheman automatiskt.

## Komplexa och speciella typer

```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 hanterar rika typer: enums (begränsa till tillåtna värden), `datetime` (tolkar ISO-strängar), `HttpUrl`/`EmailStr` (formatvalidering), och typade dicts/tuples — allt valideras automatiskt.

## Generisk / återanvändbar omslag

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

## Varför det är viktigt

API:er i verkligheten hanterar sällan platt data — de hanterar komplexa, kapslade strukturer (en användare med en adress och en lista med beställningar, en beställning med radartiklar, konfigurationsobjekt), och Pydantic:s förmåga att **kapsla modeller** gör validering av dessa djupt strukturerade request bodies enkelt.

Att förstå att ett modellsfält kan vara en annan modell, en lista med modeller, eller en rik typ — och att FastAPI **validerar hela den kapslade strukturen rekursivt** och automatiskt — är viktigt för att bygga API:er som accepterar realistisk, komplex input på ett säkert sätt.

Det rika typstödet (enums för begränsade värden, `datetime`-tolkning, `HttpUrl`/`EmailStr`-formatvalidering, typade samlingar) säkerställer vidare att komplexa data är korrekta utan manuella kontroller.

Att veta hur man modellerar kapslade och komplexa bodies (och återanvändbara generiska omslag för saker som sidnumrering) är praktisk kunskap för att bygga API:er som hanterar den strukturerade data som verkliga applikationer kräver, med full validering tillhandahållen automatiskt — en nyckelfördel med FastAPI:s Pydantic-baserade design.