JSON Schema → Pydantic

Bu ne işe yarar?

JSON Schema ve Pydantic, yapılandırılmış bir nesneyi tanımlamanın iki ana yoludur — JSON Schema OpenAPI spec'leri, LLM function-calling ve yapılandırılmış çıktılar için ortak dildir; Pydantic ise Python'un fiili veri doğrulama kütüphanesidir. Sık sık birine sahip oluyorsun ve diğerine ihtiyacın oluyor. Bu araç dönüşümü tek yönde yapar: bir JSON Schema yapıştır, bir Python dosyasına bırakabileceğin bir Pydantic sınıfı al.

Ne zaman kullanılır

• LLM yapılandırılmış çıktılar. OpenAI'nin response_format'u ve Anthropic'in tool-use'u her ikisi de JSON Schema alır. Şemayı tasarlayıp test ettikten sonra genellikle Python'da alanları doğrulamak ve erişmek için bir Pydantic modeli istersin.
• OpenAPI istemci üretimi. Bir OpenAPI spec her request/response body için JSON Schema verir; bu, tam bir kod üreteci çekmeden eşleşen Pydantic modelleri elde etmenin hızlı yoludur.
• Şema → Python geçişleri. JSON Schema doğrulamasını kullanan bir sistemi miras aldın ve Pydantic'e taşımak istiyorsun. Her şemayı yapıştır, başlangıç sınıfı al, ince ayar yap.
• Hızlı iskelet. Şekli bir notebook'ta JSON'da kabaca çizdin; tek yapıştırmayla onu gerçek bir modele dönüştür.

Bu aracın işlediği

• type: object ile properties + required — iç içe BaseModel sınıfı üretir.
• type: array ile items — List[X] üretir.
• İlkel tipler: string → str, integer → int, number → float, boolean → bool, null → None.
• String üzerinde format: date-time → datetime, email → EmailStr, uri/url → HttpUrl, uuid → UUID.
• enum → Literal[...]; const → Literal[X].
• oneOf/anyOf → Union[...]; null varyant Optional[...]'a katlanır.
• type: ["string", "null"] dizileri → Optional[str].
• description → Field(..., description=...).
• default → alan varsayılanı.
• minimum/maximum/minLength/maxLength → Field(ge=..., le=..., min_length=..., max_length=...).
• Geçerli Python tanımlayıcısı olmayan alan adları temizlenir ve orijinal kablo adını korumak için bir alias= eklenir. Model populate_by_name=True ile yapılandırılır.
• İç içe nesneler iç içe sınıflar olur; title sağlanmadıysa alan adına göre adlandırılır.
• $defs / definitions ayrı sınıflar olarak çıkarılır.

Bu aracın işlemediği (henüz)

• Harici $ref (URL ref'leri). $defs'e yerel ref'ler çalışır.
• patternProperties. TODO yorumu çıkarır.
• Şema ile additionalProperties. TODO yorumu çıkarır.
• Çoklu tabanlı allOf kompozisyonu. Tek öğeli allOf açılır.
• pattern tabanlı özel doğrulayıcılar — alanı yayınlar ama regex'i atlar. İhtiyacın olursa yapıştırdıktan sonra Pydantic @field_validator ekle.

Yaygın tuzaklar

• Pydantic v2 vs v1. Varsayılan çıktı v2 (güncel). v1 kod tabanındaysan dropdown ile değiştir. Büyük farklar: required için Field(...), class Config: yerine model_config, kullanımdan kaldırılmış doğrulayıcı dekoratörleri.
• Çıktı bir başlangıç noktasıdır, son söz değil. İncele. Özellikle karmaşık birleşimler, özyinelemeli tipler ve özel doğrulama kuralları olan her şey için.
• İsimler önemlidir. "Root class name" alanı üst seviye sınıf adını kontrol eder. Alt sınıflar mevcut olduğunda title özelliklerine göre, yoksa onları içeren alana göre adlandırılır.
• v2'de Required vs Optional. Varsayılansız bir required alan ... kullanır. Optional alanlar None'a varsayılan olur ve Optional[T] içinde sarılır.