JSON Schema (JSON Şema)

#JSONSchema #VeriDoğrulama #OpenAPI #LLM

JSON verilerinin yapısını ve kısıtlamalarını tanımlayan standart spesifikasyon ve doğrulama dili.

JSON Schema, JSON verilerinin yapısını, türlerini ve kısıtlamalarını tanımlayan bir spesifikasyon standardıdır. Bir JSON belgesinin nasıl görüneceğini önceden tanımlamaya, veriyi doğrulamaya (validation) ve otomatik olarak belgelemeye olanak tanır. JSON Schema, JSON verisinin "blueprint"i (şablonu) olarak düşünülebilir. Bir JSON Schema belgesi, hangi alanların zorunlu olduğunu, her alanın türünü (string, number, boolean, array, object) ve geçerli değer aralığını tanımlar. Örneğin bir kullanıcı nesnesi için "name" alanı string ve zorunlu, "age" 0 ile 150 arasında integer, "email" regex ile doğrulanmış string olarak tanımlanabilir. Tip denetiminin yanı sıra minimum, maximum, minLength, maxLength, pattern ve enum anahtar kelimeleriyle çok katmanlı kısıtlamalar ifade edilebilir. JSON Schema, API dokümantasyonu ve doğrulamasında kritik bir rol oynamaktadır. OpenAPI Specification (Swagger), REST API'lerini tanımlarken JSON Schema'yı temel alır. Bu sayede API tanımlamasından otomatik olarak istemci SDK'ları, sunucu stub'ları ve dokümantasyon sayfaları üretilmesi mümkün olmaktadır. Kod üreteci araçlar ise OpenAPI tanımlamasından TypeScript tiplemeleri, Python Pydantic modelleri veya Java DTO sınıfları üretebilir; bu yaklaşım API'yi tek kaynak of truth olarak konumlandırır. Yapay zeka uygulamalarında JSON Schema, büyük dil modellerinin (LLM) yapılandırılmış çıktı üretmesi için zorunlu hale gelmiştir. OpenAI ve Anthropic'in function calling/tool use özelliklerinde her araç, parametrelerini JSON Schema ile tanımlar. Claude ve GPT-4'ün "structured outputs" modu da tamamen JSON Schema üzerine kuruludur; model yalnızca şemada tanımlanan alanlara sahip yanıtlar döndürür. Pydantic (Python) ve Zod (TypeScript) gibi kütüphaneler, JSON Schema doğrulamasını uygulama düzeyinde kolaylaştıran popüler araçlar arasındadır. TypeScript ekosisteminde Zod kütüphanesi, tip güvenli şema tanımını çalışma zamanı doğrulamasıyla birleştirir ve .toJSONSchema() yöntemiyle doğrudan JSON Schema çıktısı üretir. @sinclair/typebox ise TypeScript tiplerini JSON Schema olarak ifade ederek derleme ve çalışma zamanı arasındaki uyumu garantiler. Node.js tarafında AJV (Another JSON Schema Validator), JIT derleme kullanarak nanosaniye düzeyinde doğrulama performansı sunar. Sürüm tarihi açısından JSON Schema 2009'da taslak olarak başlamış; bugün Draft 2020-12 en kararlı sürüm konumundadır. Tekrar kullanılabilir alt şema tanımları ($defs), diğer şema referansları ($ref) ve şema birleşimi (allOf, anyOf, oneOf) bu standardın ileri özellikleri arasında yer alır.

JSON Schema Nasıl Çalışır?

Bir JSON Schema belgesi, geçerli JSON belgelerinin karşılaması gereken kısıtlamaları JSON formatıyla tanımlar. En üst düzey $schema, $id ve description alanları şemayı tanımlarken type, properties, required ve additionalProperties gerçek doğrulama kurallarını belirler. Bir doğrulayıcı (validator), gelen JSON belgesini bu şemayla karşılaştırır ve uyumsuzlukları bildirir. Örneğin additionalProperties: false ile şemada tanımlanmayan ekstra alanlar reddedilebilir; bu özellik API güvenliği açısından kritik öneme sahiptir.

Temel Tanımlamalar

string tipi için minLength, maxLength ve pattern (regex) kısıtlamaları kullanılır. number tipi için minimum, maximum ve multipleOf desteklenir. array tipleri için items (her elemanı) ve minItems/maxItems tanımlanabilir. required dizisi hangi alanların zorunlu olduğunu belirtir. enum belirli değerlere kısıtlamak için kullanılır. $ref başka bir şema parçasına referans verir; $defs ile yeniden kullanılabilir parçalar tanımlanır. allOf tüm şemaların sağlanmasını, anyOf herhangi birinin, oneOf ise yalnızca birinin sağlanmasını zorunlu kılar.

OpenAPI ve API Belgeleme

OpenAPI Specification, bir REST API'nin tüm endpoint'lerini, request/response gövdelerini ve parametrelerini JSON Schema ile tanımlar. swagger-ui gibi araçlar bu tanımı görsel bir dokümantasyon sayfasına dönüştürür. Kod üretici araçlar ise OpenAPI tanımlamasından otomatik olarak TypeScript tipleri, Python Pydantic modelleri veya Java DTO sınıfları üretebilir. Bu yaklaşımda API tanımı tek kaynak of truth olarak çalışır; şema değişince hem dokümantasyon hem de üretilen kod otomatik güncellenir.

LLM'lerde Yapılandırılmış Çıktı

Büyük dil modellerinin tahmin edilebilir yapılandırılmış çıktı üretmesi için JSON Schema kıyıca benimsenmiştir. OpenAI'de bir araç tanımlamasında parameters alanı JSON Schema'dır; Claude'da tool_schema aynı şekilde çalışır. Pydantic modeli JSON Schema'ya otomatik dönüştürülerek LLM'in belirli bir veri yapısını tutarlı olarak döndürmesi sağlanabilir. OpenAI Structured Outputs modu, grammer-constrained decoding ile modelin yalnızca geçerli JSON üretmesini güvence altına alır. Bu özellik ajan sistemlerinde güvenilir veri alışverişi için temel bir yapı taşıdır.

TypeScript, Zod ve Ekosistem

TypeScript ekosisteminde Zod, tip güvenli şema tanımını çalışma zamanı doğrulamasıyla birleştirir; Zod 4'te .toJSONSchema() yöntemiyle doğrudan standart çıktı üretilir. @sinclair/typebox ise TypeScript tiplerini JSON Schema olarak ifade ederek derleme ve çalışma zamanı uyumunu garantiler. Node.js tarafında AJV (Another JSON Schema Validator), JIT derleme kullanarak nanosaniye düzeyinde doğrulama performansı sunar. Python'da jsonschema paketi referans implementasyon olarak konumlanırken pydantic-core, Rust tabanlı hızlı doğrulama motoru olarak öne çıkar. Bu araçlar JSON Schema'yı yalnızca bir standart değil, tam teşekküllü bir geliştirici altyapısı hâline getirmiştir.

Sık Sorulan Sorular

JSON Schema ile JSON arasındaki fark nedir? JSON veri formatıdır; JSON Schema ise JSON verisinin yapısını tanımlayan bir meta-format. JSON Schema'nın kendisi de JSON formatındadır.

JSON Schema nerede kullanılır? API dokümantasyonu, form doğrulama, veritabanı şema doğrulama, LLM tool use ve veri boru hattı doğrulamasında yaygın olarak kullanılır.

Pydantic ve JSON Schema ilişkisi nedir? Pydantic modeli JSON Schema'ya .schema() veya .model_json_schema() metoduyla dönüştürülebilir; bu özellik LLM entegrasyonlarında ve FastAPI auto-docs üretiminde yoğun kullanılır.

$ref ile şema paylaşmak mümkün mü? Evet; $ref ve $defs kullanılarak tekrar eden şema parçaları bir kez tanımlanıp birden fazla yerde referans gösterilebilir; büyük şemalarda bakım kolaylığı açısından kritiktir.

allOf, anyOf, oneOf arasındaki fark nedir? allOf tüm şemaları karşılaması gerekir (kesişim), anyOf en az birini (birleşim), oneOf ise tam olarak birini karşılaması gerekir (özel birleşim — birden fazla eşleşirse hata verir).

JSON Schema doğrulaması performansı etkiler mi? AJV gibi optimize kütüphaneler JIT derleme kullanarak mikrosaniye düzeyinde doğrulama yapar; çoğu uygulamada ihmal edilebilir ek yük oluşturur.