JSON Schema → Pydantic

Untuk apa ini?

JSON Schema dan Pydantic adalah dua cara utama mendeskripsikan objek terstruktur — JSON Schema adalah lingua franca untuk OpenAPI spec, LLM function-calling, dan structured outputs; Pydantic adalah library validasi data de-facto-nya Python. Sering kali kamu punya yang satu dan butuh yang lain. Tool ini melakukan konversi satu arah: tempel JSON Schema, dapatkan class Pydantic yang bisa langsung kamu drop ke file Python.

Kapan digunakan

• Structured output LLM. response_format dari OpenAI dan tool-use Anthropic keduanya menerima JSON Schema. Setelah kamu mendesain dan menguji schema, biasanya kamu ingin model Pydantic untuk memvalidasi dan mengakses field di Python.
• Generasi klien OpenAPI. Spec OpenAPI memberi JSON Schema untuk tiap request/response body; ini cara cepat mendapatkan model Pydantic yang cocok tanpa menarik generator kode penuh.
• Migrasi Schema → Python. Kamu mewarisi sistem yang pakai JSON Schema untuk validasi dan ingin memindahnya ke Pydantic. Tempel tiap schema, dapatkan class awal, refinasi.
• Scaffolding cepat. Kamu sketsa bentuk di JSON di notebook; ubah menjadi model nyata dengan satu paste.

Apa yang tool ini tangani

• type: object dengan properties + required — menghasilkan class BaseModel bersarang.
• type: array dengan items — menghasilkan List[X].
• Primitif: string → str, integer → int, number → float, boolean → bool, null → None.
• format pada string: date-time → datetime, email → EmailStr, uri/url → HttpUrl, uuid → UUID.
• enum → Literal[...]; const → Literal[X].
• oneOf/anyOf → Union[...]; varian null dilipat ke Optional[...].
• Array type: ["string", "null"] → Optional[str].
• description → Field(..., description=...).
• default → default field.
• minimum/maximum/minLength/maxLength → Field(ge=..., le=..., min_length=..., max_length=...).
• Nama field yang bukan identifier Python valid disanitasi, dan alias= ditambahkan untuk mempertahankan nama wire asli. Model dikonfigurasi dengan populate_by_name=True.
• Objek bersarang menjadi class bersarang, dinamai berdasarkan field jika tidak ada title.
• $defs / definitions dipancarkan sebagai class terpisah.

Yang belum ditangani

• $ref eksternal (URL ref). Ref lokal ke $defs berfungsi.
• patternProperties. Memancarkan komentar TODO.
• additionalProperties dengan schema. Memancarkan komentar TODO.
• Komposisi allOf multi-base. allOf single-element diunwrap.
• Validator kustom berdasarkan pattern — pancarkan field tapi lewati regex. Tambahkan Pydantic @field_validator setelah tempel jika kamu butuh.

Kesalahan umum

• Pydantic v2 vs v1. Output default v2 (saat ini). Ganti via dropdown kalau kamu di codebase v1.
• Output adalah titik awal, bukan kata akhir. Review. Terutama untuk union kompleks, tipe rekursif, dan apa pun dengan aturan validasi kustom.
• Nama penting. Field "Root class name" mengontrol nama class top-level. Sub-class dinamai dari property title jika ada, kalau tidak dari field yang berisi mereka.
• Required vs Optional di v2. Field required tanpa default pakai .... Field optional default ke None dan dibungkus dalam Optional[T].