JSON Şeması nedir?
Bu standart, bir JSON belgesinin hangi anahtarları taşıyabileceğini, her anahtarın hangi değer türünü alabileceğini ve hangi alanların eksiksiz gelmesi gerektiğini yazılı biçimde tanımlar. Tanım da JSON ile yazıldığı için makineler tarafından okunabilir. Denetimde gelen kaydın tanıma uyup uymadığına bakılır. Ancak kaydın gerçek dünyada doğru olduğunu, bir kontenjanın boş olduğunu ya da bir ödemenin tamamlandığını bu standart söylemez.
Alan türü ve zorunluluk seçimi
Şema yazarken önce hangi alanların kayıt için vazgeçilmez olduğuna karar verin. Telefon, kurs kodu ve kayıt tarihi çoğu akışta gerekir; not alanları ise genellikle isteğe bağlıdır. Zorunlu alan sayısı arttıkça form uzar ve kullanıcının yarıda bırakma olasılığı yükselir. Bu yüzden zorunluluk kararını yalnızca veri tutarlılığı açısından değil, kullanıcının bilgiyi sağlayıp sağlayamayacağı açısından da değerlendirin.
Tür seçimi de önemlidir. Telefon numarasını sayı olarak tanımlamak baştaki sıfırı kaybettirebilir; metin olarak tanımlamak ise ayrıca biçim kuralı gerektirir. Tarihlerde de dize türü ile biçim kuralını birlikte düşünün. Şema hangi seçimin doğru olduğunu bilmez; yalnızca sizin seçtiğiniz kuralı uygular.
Ek alanlar ve sürüm yönetimi
additionalProperties değerini kapalı tutmak yazım hatalarını erken yakalar; kurs_kodu yerine kurskodu gönderilen alan reddedilir. Ancak form sürümleri sık değişiyorsa yeni bir alan eski istemcilerde sorun çıkarabilir. Bu durumda hangi sürümde hangi alanların kabul edildiğini sürüm notunda tutun ve reddedilen istekleri ayrıca izleyin.
allOf ile parçalara ayrılmış şemalarda alan görünürlüğü beklediğinizden farklı olabilir. Böyle yapıları üretime almadan önce birkaç geçerli ve hatalı örnek kayıtla deneyin. Biçim denetiminin yalnızca yapıyı kapsadığını akılda tutmak, iş kurallarının ayrıca kontrol edilmesi gerektiğini de görünür kılar.
Temsili işletme örneği
Temsili bir kurs kayıt formu ad, telefon, kurs kodu ve kayıt tercihi alanlarını içeren bir JSON gönderir. Şemada ad ve kurs kodu zorunlu, kurs kodu tanımlı değerlerden biri ve ek alanlar kapalı olsun. Yazım hatalı bir alan adı reddedilir. Ancak şemadan geçen bir kayıtta kurs kodu yanlış dönem için girilmiş olabilir ya da kontenjan dolmuş olabilir. Bu kontroller ayrı bir adımda yapılır ve kayıt sisteminin yanıtı da ayrıca doğrulanır.
Biçim denetimi, şema ve iş kuralı ayrımı
| Kontrol katmanı | Ne sorar | Örnek başarısızlık |
|---|---|---|
| Sözdizimi | JSON yazımının geçerli olup olmadığı | Eksik virgül nedeniyle kayıt hiç okunamaz |
| Şema | Alan adı, tür, zorunluluk ve ek alan kuralı | Biçimi doğru ama dönem kodu hatalı bir kurs kodu |
| İş kuralı | Kontenjan, yetki ve kaydın anlamı | Biçimce doğru bir kayıt için kontenjan dolu |
Sık karıştırılan nokta
Yanlış düşünce: Şemadan geçen kayıt işlenmiş ve geçerlidir. Düzeltme: Şema yalnızca yapıyı denetler. Kontenjan, ödeme, kimlik ve yetki kontrolleri ayrı sistemlerde yapılmalı ve sonucu kullanıcıya bildirmeden önce doğrulanmalıdır.
Uygulamada dikkat edilecekler
- Her şema için zorunlu alanları ve gerekçelerini ekip belgesinde tek bir tabloda listeleyin.
- additionalProperties değerini belirlerken hangi sürümlerin ek alan göndereceğini sürüm notuna yazın.
- allOf veya benzeri birleşik yapı kullanan şemaları en az bir geçerli ve bir hatalı örnek kayıtla test edin.
- Biçim denetiminden sonra iş kuralı kontrollerini ayrı bir adım olarak tanımlayın ve her adımın hata mesajını farklı yazın.
Sık sorulan sorular
Şema geçtiyse alanlar veritabanına doğrudan yazılabilir mi?
Yazılabilir, ama bu yeterli değildir. Şema yalnızca alanların biçimine bakar. Yazmadan önce tekilleştirme, iş kuralları ve yetki kontrollerinin de tamamlanması gerekir.
additionalProperties kapalı olunca eski istemciler ne olur?
additionalProperties false ise şemada tanımlanmayan bir alanı gönderen istemcinin verisi doğrulamadan geçmeyebilir. Örneğin önceki sürümde kabul edilen bir alan yeni şemada artık tanımlı değilse, o alanı göndermeye devam eden istemciler etkilenir. Alan ekleme veya kaldırma kararını gerçek istek örnekleriyle ve sürüm uyumluluğuyla birlikte değerlendirin.
Teknik kaynak
Teknik tanım için birincil kaynağa başvurulmuştur. İşletme senaryosu açıklama amacıyla hazırlanmış temsili bir örnektir.
İlgili kavramlar
Kavramdan uygulamaya
İşletmenize uyarlamak için ilgili rehberleri inceleyin.
Hata Bildiriminde Hangi Bilgi Yeterli? Kapsam Ve Alternatif KarşılaştırmasıChatbot Kapsamı: Okuma, Yazma Ve Devir KararıTüm blog rehberleri