JSON Schema, başka bir JSON belgesi kullanarak bir JSON belgesinin yapısının nasıl olması gerektiğini tanımlamanın bir yoludur. Verileri kodda koşullarla elle doğrulamak yerine, beklenen türleri, zorunlu alanları ve değer kısıtlamalarını bildirimsel olarak tanımlayabilir ve ardından verileri otomatik olarak kontrol edebilirsiniz.
Temel draft-07 anahtar kelimeleri
type— beklenen değer türü (object, string, number, array vb.).required— mutlaka bulunması gereken nesne alanlarının listesi.properties— nesnenin her bir alanı için ayrı ayrı şema tanımı.enum— bir değeri belirli bir seçenek kümesiyle sınırlar.pattern— bir dizeyi düzenli ifadeyle doğrular, örneğin TC Kimlik No formatı için.
Örnek: Türkiye Cumhuriyeti Kimlik Numarası için pattern
TC Kimlik Numarası her zaman 11 haneden oluşur ve ilk hane hiçbir zaman 0 olamaz. Bir kayıt formu API'sinin şeması bu alanı şöyle tanımlayabilir: "tcKimlikNo": {"type": "string", "pattern": "^[1-9]\\d{10}$"}. Bu, numaranın gerçek algoritmik sağlama (checksum) kuralını doğrulamaz — bunun için ayrı bir hesaplama gerekir — ama 10 veya 12 haneli bir değeri, boşluk içeren bir girdiyi veya baştaki sıfırı hemen yakalar; bunlar bir form alanından kopyalanırken en sık yapılan hatalardır.
Bu, sözdizimi doğrulamasından nasıl farklı
Sıradan JSON doğrulaması yalnızca metnin sözdizimsel olarak doğru olduğunu kontrol eder — doğru parantezler, tırnaklar, virgüller. JSON Schema çok daha fazlasını kontrol eder: bir nesnede zorunlu bir email alanı var mı, age değeri bir dize değil de bir sayı mı, status izin verilen değerler listesinde mi.
Buna neden ihtiyaç duyulur
- Üçüncü taraf bir API'nin yanıtının belgelenmiş sözleşmeye uyduğunu doğrulamak.
- Bir hatayı erkenden yakalamak için dağıtımdan önce yapılandırma dosyalarını doğrulamak.
- Beklenen veri yapısını hemen otomatik olarak kontrol edilebilecek bir formatta belgelemek.
additionalProperties: fazladan alan eklenebilir mi
Varsayılan olarak JSON Schema, bir nesnede properties içinde tanımlananların ötesinde herhangi bir alana izin verir — required ve properties yalnızca bir minimumu belirler, tüketici bir listeyi değil. Bilinmeyen alanları yasaklamak gerekiyorsa, açıkça "additionalProperties": false eklemek gerekir — bu bayrak olmadan şema "açık" kalır.