JSON Schema Gerçekte Neyi Doğrular

İstek gövdesini "şu alanlara sahip bir JSON nesnesi" olarak belgeleyen bir API, gerçekten kontrol etmenin bir yolu olmadan bir şekli tanımlıyordur. JSON Schema, o tanımı kontrol edilebilir hale getirir: başka bir JSON belgesinin nasıl görünmesine izin verildiğini tanımlamak tek işi olan bir JSON belgesi, böylece "price alanı pozitif bir sayı olmalı" birinin sonunda okumayı bıraktığı bir yorum yerine kodun uygulayabileceği bir şey haline gelir.

Çoğu gerçek durumu kapsayan sözcük dağarcığı

Bir şema, birleşen küçük bir anahtar kelime setinden oluşur:

• type — "string", "number", "integer", "boolean", "object", "array", veya "null" (ya da bir alan birden fazla tip olabildiğinde birkaçının bir dizisi).
• properties + required — bir nesne için, hangi anahtarların var olduğu ve hangilerinin bulunması gerektiği. required'da listelenmeyen bir anahtar yasak değil, isteğe bağlıdır.
• enum — değer sabit bir listeden tam olarak biri olmalıdır ("status", "pending", "shipped", veya "delivered"'dır, başka bir şey değil).
• pattern, minLength/maxLength — bir string için bir düzenli ifade veya uzunluk sınırı.
• minimum/maximum — sayısal bir aralık.
• items — bir dizinin her elemanının sağlaması gereken şema.
• oneOf / anyOf / allOf — bir değer bir alt-şema listesinden tam olarak birine, en az birine, ya da hepsine uymalıdır — "bu alan ya bir string ya da bu başka şekildedir" mekanizması.

{ "name": "Ada", "age": 30 } için bir şema şöyle görünebilir:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name", "age"]
}

Ona karşı bir belgeyi doğrulamak, her iki ağacı birlikte gezmek ve her anahtar kelimeyi kontrol etmek demektir — { "name": "Ada", "age": -1 }, type/required kontrollerinden geçer ama minimum'da başarısız olur, ve hata tam olarak hangi alanın ve hangi kuralın olduğunu belirtir.

Aynı anda değil, iki farklı an için iki farklı araç

JSON Schema doğrulamasının gerçekte ne olmadığını belirtmekte fayda var: bu, belirli bir belgeye karşı, o belge var olduğu anda değerlendirilen bir çalışma zamanı kontrolüdür. JSON Schema Üretici ve Doğrulayıcı bunu iki yönde de yapar — bir örnek belgeden bir şema çıkarın, ya da elinizdeki bir şemaya karşı bir belgeyi doğrulayın — ama her iki durumda da size tek bir veri parçası hakkında bilgi verir.

JSON'dan TypeScript'e komşu ama farklı bir sorunu çözer: hiçbir veri var olmadan önce editörünüzün ve derleyicinizin anladığı bir type veya interface tanımı üretmek, bir uyumsuzluğu (user.name yerine user.naem okuyan kod) yalnızca tam olarak o kötü belge çalışma zamanında aktığında değil, derleme zamanında yakalamak. Gerçek bir sistem genellikle her ikisini de ister — bir servis sınırını geçen veriyi çalışma zamanında doğrulayan bir şema, ve onu ele alan kodu derleme zamanında dürüst tutan üretilmiş bir tip — ve bunları birinin diğerini ima ettiğini varsaymak yerine kasıtlı olarak senkronize tutmaya değer.

Bir doğrulayıcının gerçekte nasıl inşa edildiğine dair pratik bir not: bazı kütüphaneler hız için bir şemayı anlık olarak özel bir JavaScript fonksiyonuna derler, arka planda new Function(...) kullanarak — hızlıdır, ama doğrulayıcının çalışma zamanında kod derlemeye izin veren bir güvenlik politikasına (unsafe-eval) ihtiyaç duyduğu anlamına gelir, ki katı bir site bunu yalnızca bir form doğrulaması için vermek istemeyebilir. Yorumlanan bir doğrulayıcı — her kontrolde şema ağacını doğrudan gezen, yeni kod üretip derlemeyen biri — doğrulama başına daha yavaştır ama alternatif bir güvenlik politikasını tek bir özellik için gevşetmekse, sıradan JavaScript çalıştırmaktan başka hiçbir şeye ihtiyaç duymaz, ki bu daha muhafazakar varsayılandır.

Gerçek veriden ilk taslak bir şemaya geçmek için, önce dağınık bir örneği temizlemek üzere bunu JSON Biçimlendirici ile eşleştirmek, çıkarılan şemayı elle iyileştirmeden önce daha okunabilir hale getirir.