JSON Schema → Pydantic

Do czego to służy?

JSON Schema i Pydantic to dwa główne sposoby opisywania ustrukturyzowanego obiektu — JSON Schema to lingua franca dla OpenAPI, function calling LLM-ów i structured output; Pydantic to faktyczny standard walidacji w Pythonie. Często masz jedno, a potrzebujesz drugiego. To narzędzie robi konwersję w jedną stronę: wklej JSON Schema, dostań klasę Pydantic gotową do wklejenia do pliku .py.

Kiedy tego użyć

• Structured output LLM-a. response_format z OpenAI i tool-use z Anthropica oba biorą JSON Schema. Po zaprojektowaniu zwykle chcesz model Pydantic do walidacji i dostępu do pól w Pythonie.
• Generowanie klienta OpenAPI. Spec OpenAPI daje JSON Schema na request/response body; szybki sposób na modele Pydantic bez pełnego generatora.
• Migracja Schema → Python. Odziedziczyłeś system z walidacją JSON Schema, chcesz przejść na Pydantic. Wklej każdy schema, dostań klasę startową, dopracuj.
• Szybki scaffolding. Naszkicowałeś kształt w JSON-ie w notebooku; zamień to w prawdziwy model jednym wklejeniem.

Co narzędzie obsługuje

• type: object z properties + required — zagnieżdżona klasa BaseModel.
• type: array z items — List[X].
• Prymitywy: string → str, integer → int, number → float, boolean → bool, null → None.
• format na stringu: date-time → datetime, email → EmailStr, uri/url → HttpUrl, uuid → UUID.
• enum → Literal[...]; const → Literal[X].
• oneOf/anyOf → Union[...]; wariant null składa się do Optional[...].
• type: ["string", "null"] → Optional[str].
• description → Field(..., description=...).
• default → default pola.
• minimum/maximum/minLength/maxLength → Field(ge=..., le=..., min_length=..., max_length=...).
• Nazwy nie-pythonowe są oczyszczane, dodawany alias=; model konfigurowany z populate_by_name=True.
• Obiekty zagnieżdżone → klasy zagnieżdżone, nazwane wg title jeśli jest, inaczej wg pola.
• $defs/definitions → osobne klasy.

Czego (jeszcze) nie obsługuje

• Zewnętrzne $ref (URLe). Lokalne do $defs działają.
• patternProperties — komentarz TODO.
• additionalProperties z schemą — komentarz TODO.
• Wielobazowa kompozycja allOf. Jednoelementowe allOf jest rozpakowywane.
• Custom walidatory na pattern — pole jest, regex pomijany. Dodaj @field_validator po wklejeniu, jeśli potrzeba.

Częste pułapki

• Pydantic v2 vs v1. Default v2. Przełącz w dropdownie, jeśli codebase to v1.
• Wyjście to punkt startowy. Zrób review, zwłaszcza dla złożonych unii i typów rekurencyjnych.
• Nazwy się liczą. Pole "Root class name" kontroluje nazwę top-levelowej klasy. Podklasy: title lub nazwa pola.
• Required vs Optional w v2. Required bez defaultu używa .... Optional spada do None w Optional[T].