Unawezaje kuunda miundo ya request body iliyofungamana (nested) na changamano?

Question

Accepted Answer

Miundo ya Pydantic inaweza **kufungamana (nest)** — field ya muundo inaweza yenyewe kuwa muundo mwingine, orodha ya miundo, au aina changamano — ikiruhusu FastAPI kuthibitisha JSON yenye muundo wa kina kiotomatiki (objects ndani ya objects, arrays za objects).

## Miundo iliyofungamana (nested)

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

Field ya muundo iliyowekwa aina kama muundo mwingine (au `list[Model]`) huthibitishwa kwa njia ya recursive — nested objects na arrays za objects vyote hukaguliwa dhidi ya schemas zao kiotomatiki.

## Aina changamano na maalum

```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 hushughulikia aina tajiri: enums (huzuia kwa thamani zinazoruhusiwa), `datetime` (huchanganua ISO strings), `HttpUrl`/`EmailStr` (uthibitishaji wa muundo), na typed dicts/tuples — vyote vikithibitishwa kiotomatiki.

## Vifuniko vya generic / vinavyoweza kutumika tena

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

## Kwa nini ni muhimu

API za ulimwengu halisi mara chache hushughulikia data tambarare — hushughulikia miundo changamano, iliyofungamana (mtumiaji mwenye anwani na orodha ya orders, order yenye line items, objects za usanidi), na uwezo wa Pydantic wa **kufungamanisha miundo** hufanya uthibitishaji wa request bodies hizi zenye muundo wa kina kuwa rahisi.

Kuelewa kwamba field ya muundo inaweza kuwa muundo mwingine, orodha ya miundo, au aina tajiri — na kwamba FastAPI **huthibitisha muundo mzima uliofungamana kwa njia ya recursive** na kiotomatiki — ni muhimu kwa kujenga API zinazokubali input halisi, changamano kwa usalama.

Usaidizi wa aina tajiri (enums kwa thamani zilizozuiwa, uchanganuzi wa `datetime`, uthibitishaji wa muundo wa `HttpUrl`/`EmailStr`, makusanyo yaliyowekwa aina) huhakikisha zaidi kwamba data changamano ni sahihi bila ukaguzi wa mkono.

Kujua jinsi ya kuunda miundo iliyofungamana na changamano (na vifuniko vya generic vinavyoweza kutumika tena kwa mambo kama pagination) ni maarifa ya vitendo kwa kujenga API zinazoshughulikia data yenye muundo ambayo programu halisi zinahitaji, kwa uthibitishaji kamili unaotolewa kiotomatiki — nguvu muhimu ya muundo wa FastAPI unaotegemea Pydantic.