AI araç şemasını genişlettiniz; yeni alan neden hâlâ reddediliyor?

Yeni alanı eklediniz, eski kapanış yerinde kaldı

AI aracının şemasında yalnız id alanı vardı. Yeni sürümde qty alanını ayrı bir bölümle eklediniz. İki bölümü allOf altında birleştirince id ve qty içeren örnek nesne hâlâ reddediliyor. İlk tepki doğrulayıcıyı gevşetmek olabilir. Önce eski şemanın fazla alan yasağının hangi kapsamı gördüğünü inceleyin. Şemaları birleştirmek, kapalı bir alt şemanın izin verdiği alanları otomatik olarak genişletmez.

Burada beş sentetik JSON nesnesi üzerinden yalnız şema bileşimini sınayacağız. id metin, qty en az bir olan tam sayı olsun; ikisi de zorunlu. Başka alan kabul edilmesin. Stok, kullanıcı yetkisi veya gerçek araç işlemi hakkında karar vermiyoruz. Şemayı geçen nesne yalnız bu yapısal koşulları sağlar. Kurumun işlem kuralları daha sonra ve kendi güncel verisiyle kontrol edilir.

Kapalı temel şemanın kapsamını görün

JSON Schema açıklamasında additionalProperties, aynı alt şemada tanımlanan alanları görür. allOf kullanmak bu alan listesini miras alma gibi genişletmez. Böylece id tanımlayan ve additionalProperties:false diyen temel bölüm qty alanını fazladan sayar. Dış bölüm qty’yi tanıyor olsa da nesne her iki koşulu birlikte sağlamalıdır. Bir bölümün kabulü diğer bölümün reddini ortadan kaldırmaz.Kaynak: JSON Schema — Objects and Unevaluated Properties

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "additionalProperties": false
    }
  ],
  "properties": {
    "qty": {
      "type": "integer",
      "minimum": 1
    }
  },
  "required": [
    "qty"
  ]
}

Bu şemada dış required qty ister. İç kapalı bölüm ise id dışındaki her alanı reddeder. Sonuçta normal bir id/qty nesnesi iç bölümden geçmez. qty alanını kaldırmak da dış zorunluluğu bozacağı için çözüm değildir. İstenen veri sözleşmesini koruyarak kapanışın hangi düzeyde yapılacağını değiştirmek gerekir. Buradaki hata nesnenin içindeki değerde değil, şema parçalarının birlikte kurduğu koşuldadır.

Kapanışı birleşimin dışına taşıyın

unevaluatedProperties, başarılı değerlendirmelerde tanınan alt şema alanlarını da hesaba katabilir. Bu özellik draft 2019-09 ile eklenmiştir; örneğimiz draft 2020-12 kullanır. Temel bölümün kendi additionalProperties:false kapanışını kaldırıp birleşimin dışında unevaluatedProperties:false kullanıyoruz. Böylece id ve qty farklı bölümlerde tanımlansa da birlikte kabul edilir; tanınmayan debug alanı dışarıda kalır. Doğrulayıcının bu taslağı desteklediğini ayrıca doğrulayın.Kaynak: JSON Schema — Objects and Unevaluated Properties

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        }
      },
      "required": [
        "id"
      ]
    }
  ],
  "properties": {
    "qty": {
      "type": "integer",
      "minimum": 1
    }
  },
  "required": [
    "qty"
  ],
  "unevaluatedProperties": false
}

Yalnız dışarıya yeni anahtarı ekleyip iç additionalProperties:false satırını yerinde bırakmak yeterli değildir. İç bölüm yine qty’yi reddeder. Bu nedenle değişikliği iki adım olarak okuyun: eski kapanışı kaldır, yeni kapanışı bütün bileşimin değerlendirmesinden sonra uygula. İncelemede bu iki hareketin de yapıldığını doğrulayın. Yoksa doğru anahtar adı görüldüğü için hâlâ çelişkili olan bir şema onaylanabilir.

Geçen ve kalması gereken kayıtları birlikte deneyin

Düzeltilmiş şemanın J1’i geçirmesi tek başına yeterli değildir; J2’nin hâlâ reddedilmesi kapanışın korunduğunu gösterir. J3 ve J5 de alan adı tanınıyor diye değer koşullarının kaybolmadığını sınar. J4, zorunluluğun sürdüğünü gösterir. Bu küçük tablo aynı anda kabul edilmesi gereken bir örnekle reddedilmesi gereken dört farklı nedeni ayırır; bütün retleri tek “hata” sayısına indirmez.

Nesnede fazladan alanı sessizce silen bir dönüştürücü varsa doğrulama öncesindeki girdiyle sonraki nesne farklı olabilir. Bu alıştırmada böyle bir düzeltme yapılmaz. Ham nesneler aynen korunur ve geçer/ret kararı verilir. Şemanın yapısını incelerken araç kitaplığının otomatik tür çevirme veya fazla alan temizleme seçeneklerini de kaydedin; aksi halde şemadan gelen karar ile ön işlemden gelen değişiklik karışır.

Şema sürümünü ve birleşim sınırını belirtin

Draft 2020-12. Temel şema id metin ve zorunlu; ilk sürümde additionalProperties:false. Dış bölüm allOf ile temeli kullanıp qty tam sayı minimum1 ve zorunlu alanını ekliyor. J1…J5 nesnelerini değiştirmeden değerlendir. Ardından temel kapanışı kaldırıp dış unevaluatedProperties:false ile istenen iki alanlı sözleşmeyi kur. Eski kapanışı yerinde bırakma. Beş kararın nedenini ayrı yaz; stok, yetki veya gerçek araç başarısı iddia etme.

Doğrulayıcıyı seçerken yalnız JSON’un ayrıştırılmasını test etmek yeterli değildir. Kullanılan taslak ve anahtarların gerçekten uygulanması gerekir. Eski bir doğrulayıcı bilinmeyen unevaluatedProperties anahtarını yok sayarsa J2 yanlışlıkla geçebilir. Bu yüzden fazladan alan karşı örneği aynı zamanda çalışma ortamının önemli bir uyumluluk kontrolüdür. Test raporuna kitaplık sürümü ve etkin taslak bilgisini yazın; yalnız şema dosyasındaki $schema metnini çalışma kanıtı saymayın.

• Temel bölümde eski kapanış kaldırıldı mı?
• Dış kapanış bütün tanınmış alanları kapsıyor mu?
• Zorunlu alanlar ve değer sınırları korunuyor mu?
• Doğrulayıcı taslağı gerçekten destekliyor mu?

Üçüncü alanı açık bir kararla ekleyin

Yeni gereksinim not adlı isteğe bağlı bir metin alanı olsun. Bunu düzeltilmiş şemanın dış properties bölümüne ekleyin. id=K1, qty=2, not="deneme" nesnesi ile aynı nesneye debug=true eklenmiş hali için karar verin. not=3 geldiğinde ne olacağını da yazın. İsteğe bağlı alan demek alan verilirse her türün kabul edilmesi demek değildir.

properties.not={"type":"string"} eklenir; required listesine eklenmez. Metin not geçer. debug hâlâ tanınmadığı için ret. not=3 tür koşulunu sağlamaz ve reddedilir. not hiç verilmezse diğer koşullar sağlandığında nesne geçer.

Şema değişikliği tesliminde yalnız yeni alanı gösteren örneği saklamayın. Eski kapanışın nereden kaldırıldığı, yeni kapanışın kapsamı ve ret örnekleri de kayıtta bulunsun. AI aracının sözleşmesini genişletirken hem yeni ihtiyacı kabul ettiğinizi hem tanımsız alanları açık kapıdan içeri almadığınızı bu şekilde somut olarak gösterebilirsiniz.