JSON Schema Doğrulama: JSON Verisini Tanımlama ve Doğrulama Rehberi

JSON Schema Nedir?

JSON Schema, bir JSON belgesinin yapısını, içeriğini ve kısıtlamalarını tanımlamanıza olanak sağlayan bildirimsel bir dildir. Bunu veri üreticisi ile tüketicisi arasındaki bir sözleşme olarak düşünün. Üretici "Her zaman bir name dizesi ve bir age tamsayısı içeren bir nesne göndereceğim" der ve tüketici, gelen her verinin işlemeden önce bu vaade gerçekten uyduğunu doğrulayabilir.

Bu önemlidir çünkü JSON'un kendisi şemasızdır. Herhangi bir geçerli JSON değeri -- bir dize, bir sayı, rastgele anahtarlarla derin iç içe geçmiş bir nesne -- tamamen yasaldır. Bu özgürlük hızlı prototipleme için harikadır, ancak iki sistemin verinin nasıl görünmesi gerektiği konusunda anlaşması gereken anda bir yükümlülüğe dönüşür. Bir şema olmadan, her doğrulama kuralı uygulama kodunda yaşar, işleyiciler arasında dağılmış, sıklıkla tekrarlanmış ve kaçınılmaz olarak tutarsızdır.

JSON Schema Neden API'ler için Önemli?

REST API'leri JSON verileri üzerinden iletişim kurar ve her uç noktanın örtük bir şekli vardır: zorunlu alanlar, beklenen türler, değer kısıtlamaları. JSON Schema bu şekli açık ve makine tarafından okunabilir hale getirir. Bir şemanız olduğunda şunları yapabilirsiniz:

• İstekleri doğrulayın -- iş mantığınıza ulaşmadan önce sunucuda, anlaşılmaz 500 hataları yerine net 400 hataları döndürerek.
• Yanıtları doğrulayın -- üretime ulaşmadan önce kırılma değişikliklerini yakalamak için entegrasyon testlerinde.
• Otomatik dokümantasyon oluşturun -- Swagger/OpenAPI gibi araçlar tür tanımlarının omurgası olarak JSON Schema kullanır.
• Kod oluşturun -- şemadan TypeScript'e, şemadan Go struct'a, şemadan Python dataclass'a araçlar manuel tür tanımlarını ortadan kaldırır.

JSON Schema Temelleri

Her JSON Schema'nın kendisi bir JSON nesnesidir. Mümkün olan en basit şema, herhangi bir geçerli JSON'u kabul eden boş bir nesne {} şeklindedir. Buradan, neye izin verildiğini daraltmak için anahtar sözcükler eklersiniz.

İlkel Türler

type anahtar sözcüğü temeldir. JSON Schema altı ilkel tür ve bir yapısal değiştirici tanır:

Özellikler ve Zorunlu Alanlar

Nesneler için properties anahtar sözcüğü hangi anahtarların beklendiğini ve her birinin nasıl görünmesi gerektiğini tanımlar. required anahtar sözcüğü bu anahtarlardan hangilerinin mevcut olması gerektiğini listeler. İşte pratik bir örnek:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name", "email"]
}

Bu şema şunu söyler: veri bir nesne olmalıdır; boş olmayan bir name dizesi ve geçerli bir email dizesi içermelidir; age isteğe bağlıdır ancak varsa negatif olmayan bir tamsayı olmalıdır.

Ek Özellikleri Kontrol Etme

Varsayılan olarak nesneler, properties ile tanımlananların ötesinde herhangi bir ek anahtarı kabul eder. "additionalProperties": false ayarlamak şemayı katı yapar -- yalnızca listelenen anahtarlara izin verilir. Bu, beklenmeyen alanların bir istemci hatası veya sürüm uyuşmazlığı anlamına gelebileceği API'ler için değerlidir.

Format Doğrulama

format anahtar sözcüğü, temel türlerin ötesinde anlamsal doğrulama sağlar. Bir alan dize olabilir, ancak herhangi bir dize değil -- bir e-posta adresi, bir tarih, bir URI veya bir IP adresi olmalıdır. Formatlar size bu ek anlam katmanını verir.

Yerleşik Formatlar

JSON Schema, doğrulayıcıların destekleyebileceği bir dizi standart format tanımlar. En yaygın kullanılanlar şunlardır:

Açıklama mı Doğrulama mı?

Önemli bir nüans: varsayılan olarak format anahtar sözcüğü bir açıklama (annotation) niteliğindedir, bir doğrulama (assertion) değil. Bu, uyumlu bir doğrulayıcının değeri formata karşı gerçekten kontrol edip etmeyebileceği anlamına gelir. Draft 2020-12'de, geçersiz formatlarda doğrulamanın başarısız olmasını istiyorsanız format doğrulamasını açıkça etkinleştirmeniz gerekir. Birçok popüler kütüphane (JavaScript için Ajv gibi) formatı varsayılan olarak veya bir eklenti aracılığıyla doğrulama olarak ele alır, ancak şartname düzeyindeki davranışı bilmek önemlidir.

Taslak Sürümleri: Draft-07 ve 2020-12

JSON Schema birçok taslak sürümden geçerek evrilmiştir. Pratikte en sık karşılaşacağınız ikisi Draft-07 (2018'de yayımlandı) ve Draft 2020-12 (mevcut kararlı sürüm) olacaktır. Farklılıkları anlamak projeniz için doğru sürümü seçmenize yardımcı olur.

Temel Farklılıklar

Hangi Sürümü Seçmelisiniz?

Draft-07'yi seçin eğer ekosisteminiz zaten kullanıyorsa (birçok OpenAPI 3.0 aracı Draft-07 üzerine inşa edilmiştir), doğrulama kütüphaneniz henüz 2020-12'yi tam olarak desteklemiyorsa veya mevcut araçlarla maksimum uyumluluk istiyorsanız.

Draft 2020-12'yi seçin eğer eski kısıtlaması olmayan yeni bir proje başlatıyorsanız, temiz şema birleştirme için unevaluatedProperties'e ihtiyacınız varsa veya en son kararlı standartta kalmak istiyorsanız.

JSON Şema Oluşturucumuzu Nasıl Kullanılır?

Ücretsiz JSON Şema Oluşturucu aracımız herhangi bir JSON verisini alır ve otomatik olarak geçerli bir şema üretir. Tamamen tarayıcınızda çalışır, bu yüzden verileriniz cihazınızdan asla ayrılmaz.

Adım Adım Rehber

1. JSON Şema Oluşturucu aracını açın.
2. JSON verinizi yapıştırın -- bu bir örnek API yanıtı, bir yapılandırma nesnesi veya doğrulamak istediğiniz herhangi bir JSON yapısı olabilir.
3. Oluştur'a tıklayın ve araç her alanı analiz edecek, türleri çıkaracak, formatları (email, date-time, URI, UUID) algılayacak ve zorunlu özellikleri belirleyecektir.
4. Çıktıyı inceleyin -- oluşturulan şema, düzgün girintileme ve tüm anahtar sözcüklerle birlikte çıktı panelinde görünür.
5. Doğrula sekmesine geçin ve şemanızı yeni JSON verileriyle test edin. Farklı bir veri yapıştırın ve doğrulamayı geçip geçmediğini, her ihlal için net hata mesajlarıyla görün.
6. Şemayı tek tıklamayla kopyalayın ve projenize entegre edin -- ister bir API ara katmanı, ister bir CI test paketi, ister bir yapılandırma doğrulayıcısı olsun.

Oluşturucunun Otomatik Algıladıkları

• Türler -- string, number, integer, boolean, object, array, null
• Formatlar -- e-posta adresleri, tarih-saat damgaları, URI'ler, UUID'ler, IPv4 adresleri
• Zorunlu alanlar -- örnekte mevcut olan tüm anahtarlar varsayılan olarak zorunlu işaretlenir
• İç içe yapılar -- nesneler içindeki nesneler, nesne dizileri ve karışık diziler özyinelemeli olarak işlenir

Gerçek Dünya Kullanım Senaryoları

JSON Schema akademik bir alıştırma değildir. Yazılım geliştirme yaşam döngüsünün tamamında gerçek sorunları çözer. İşte en etkili kullanım senaryoları.

API İstek ve Yanıt Doğrulama

En yaygın kullanım senaryosu. Her uç noktanın istek gövdesi ve yanıt gövdesi için bir şema tanımlayın. Bozuk verileri erken reddetmek için ara katmanda (Express, FastAPI, Spring) gelen istekleri doğrulayın. Gerilemeleri yakalamak için entegrasyon testlerinde yanıtları doğrulayın. Bu tek uygulama, bütün bir hata sınıfını ortadan kaldırır.

Form Doğrulama

react-jsonschema-form ve Ajv gibi kütüphaneler, JSON Schema'dan ön yüz form doğrulaması yapmanıza olanak tanır. Şemayı bir kez tanımlayın ve hem sunucu hem de istemci aynı kuralları uygulasın. Artık "ön yüzde çalışıyor ama arka uçta başarısız oluyor" hataları yok.

Yapılandırma Dosyaları

JSON veya YAML yapılandırma dosyalarını okuyan uygulamalar, şema doğrulamasından büyük ölçüde faydalanır. VS Code gibi araçlar, yapılandırma dosyaları (package.json, tsconfig.json, .eslintrc) için otomatik tamamlama ve satır içi hata vurgulama sağlamak üzere JSON Schema kullanır. Kendi yapılandırma dosyalarınız için de aynısını yapabilirsiniz.

Veri Göçü ve ETL

Sistemler arası veri göçünde şemalar bir kontrol noktası görevi görür. Dönüşümden önce kaynak veriyi beklenen şemaya karşı doğrulayın ve dönüşümden sonra çıktıyı hedef şemaya karşı doğrulayın. Bu, format uyuşmazlıklarını, eksik alanları ve tür hatalarını üretim veritabanını bozmadan önce yakalar.

Sözleşme Testi

Mikro hizmet mimarilerinde ekipler JSON Schema'ları sözleşme olarak yayımlayabilir. A Servisi "Bu şekli üretiyorum" der, B Servisi "Bu şekli bekliyorum" der ve bir CI hattı her iki tarafın uyumlu kaldığını doğrular. Bu, tam kapsamlı sözleşme test çerçevelerinden daha hafiftir ancak en yaygın kırılmayı kapsar: yapısal değişiklikler.