Yapay zekâ geçerli JSON verdi diye cevap doğru mu?
JSON olarak okunabilen yanıt, doğru bilgi demek değil. Şema uyumu, eksik alanlar, belgeyle eşleştirme ve insan onayını resmî belgelerle birbirinden ayırıyorum.
Kaynaklar ve araçlar
- OpenAI Structured Outputs resmî belgeleri
- JSON Schema: nesne, null, metin ve format kuralları
- Kaynak kontrol tarihi: 11 Kasım 2026
Yöntem ve sınır
- Kaynaklı rehber; model veya GPU ölçümü değil
- Örnek veri temsili; gerçek model çıktısı değil
- Kontrol ve onay akışı öneridir; etkinliği ölçülmedi
Bir yapay zekâ yanıtının yazılıma sorunsuz aktarılması ile içindeki bilginin doğru olması farklı şeylerdir. Yanıtın geçerli JSON olması, yazılımın onu okuyabilmesi için bir adımdır; içindeki bilginin doğru olduğunu göstermez. OpenAI’nin Structured Outputs belgesi de sınırı açıkça koyuyor: Yapılandırılmış çıktılar hâlâ hata içerebilir.[1]

Bu ayrım, bir belgeden ödeme bilgisi çıkarırken önem kazanır. Yazılımın beklediği alanlar eksiksiz gelebilir; ancak tutar yanlış satırdan, tarih başka belgeden alınmış olabilir. Burada ihtiyacımız olan, yalnızca düzgün bir veri kabı değil, o verinin hangi kontrollerden geçerek işleme dönüşeceğidir.
Üç ayrı soru: okunuyor mu, uyuyor mu, doğru mu?
İlk soru, metnin JSON olarak ayrıştırılabilmesidir. İkinci soru, belirlediğiniz şemaya uyup uymamasıdır. OpenAI belgesindeki ayrımla JSON modu, belirli bir şemaya uyumu garanti etmez; Structured Outputs ise sağladığınız şemaya uygun üretim içindir.[1]
Bir şema, tutar alanının sayı olmasını ve durum alanının izin verilen seçeneklerden birini taşımasını isteyebilir. JSON Schema’da required, bulunması gereken alanları belirtir; additionalProperties: false ise tanımlanmamış ek alanları engelleyebilir.[2] Bunlar değerlidir: Yanlış alan adı veya beklenmedik veri türü yüzünden bozulan entegrasyonların önüne biçim düzeyinde bir sözleşme koyarsınız.
Üçüncü soru farklıdır: Bu tutar gerçekten ilgili belgede mi yazıyor? İzin verilen seçeneklerden biri seçildi diye doğru seçenek seçilmiş olmaz. OpenAI’nin hata uyarısını uygulamaya çevirirsek, şemaya uygunluğu bilgi doğruluğunun yerine koymamak gerekir.[1] Şema kontrolünü geçen kayıt, henüz doğruluğu kabul edilmiş kayıt değildir.
Bu yüzden arayüzde tek bir yeşil “başarılı” işareti yerine, farklı sonuçları ayırmayı öneriyorum: “yanıt tamamlandı”, “şemaya uydu”, “belgeyle karşılaştırıldı”, “iş kurallarını geçti”, “onaylandı”. Böylece bir teknik başarı, sessizce işlem iznine dönüşmez.
Boş alan bırakmak başarısızlık değildir
Bütün alanları doldurmak ilk bakışta iyi bir hedef gibi görünebilir. Oysa OpenAI, girdi şemayla tamamen ilgisiz olduğunda modelin şemaya uyma çabasının uydurulmuş bilgiye yol açabileceğini açıkça belirtiyor.[1] Dolayısıyla şemayı tasarlarken “bilgi yoksa ne olacak?” sorusunu da cevaplamak gerekir.
Burada iki kuralı karıştırmayalım. Genel JSON Schema’da properties içinde tanımlanan her alan kendiliğinden zorunlu değildir.[2] OpenAI Structured Outputs kullanımında ise bütün alanların required olarak belirtilmesi istenir; belge, isteğe bağlı değeri temsil etmek için türün null ile birleştirilmesini anlatır.[1] Alanın bulunması zorunlu olabilir, fakat dolu bir değer taşıması zorunlu olmayabilir.
Temsili veri, model çıktısı değil:
{
"belge_no": "ORNEK-001",
"vade_tarihi": null,
"eksiklik_nedeni": "Belgede vade tarihi bulunamadı"
}
Bu örnekte önerilen sözleşme şudur: Tarih belgede bulunamıyorsa tahmin edilmesin; null dönülsün ve eksiklik açıklansın. İlgili alan için tür tanımı "type": ["string", "null"] olabilir. Bu, sağlayıcıya gönderilecek tam istek değil, şema tasarımını anlatan bir parçadır.[1]
JSON’da null, alanın hiç bulunmamasıyla aynı değildir.[3] Ayrıca null tek başına “bulunamadı”, “okunamadı” veya “uygulanamaz” demek değildir; bu anlamı uygulama sözleşmeniz belirlemeli. Birden fazla neden önemliyse ayrı bir durum alanı kullanın. Boş metni de otomatik olarak eksiklik işareti saymayın: Yalnızca string türüyle tanımlanmış bir alan boş metni kabul edebilir; uzunluk kısıtı ayrıca tanımlanır.[4]
Bu tasarımın amacı eksikleri saklamak değil, görünür kılmaktır. null kabul etmek doğruluk garantisi sağlamaz; yalnızca sistemin bilmediği yerde değer üretmesini zorunlu tutmayan bir yol açar.
Doğrulama tek bir kontrolden oluşmasın
Aşağıdaki akış bir ürün garantisi değil, belge uyarılarından hareketle önerdiğim uygulama tasarımıdır.
Önce yanıtın durumunu kontrol edin.** OpenAI, güvenlik nedeniyle reddedilen yanıtın verdiğiniz şemaya uymayabileceğini ve reddin ayrıca ele alınması gerektiğini açıklıyor. Belgede çıktı sınırı nedeniyle tamamlanmamış yanıtın kontrolü de gösteriliyor.[1] Reddedilmiş veya yarıda kalmış yanıtı “alanlar eksik geldi” diyerek sıradan bir kayıt gibi işlemeyin.
Sonra veri sözleşmesini uygulayın.** Alanlar, türler ve izin verilen değerler beklediğiniz yapıya uymalı. Burada genel JSON Schema özellikleriyle sağlayıcının desteklediği özellikleri eşitlemeyin: OpenAI Structured Outputs, JSON Schema dilinin bir alt kümesini destekliyor.[1] Uygulamanın kabul edeceği sözleşme ile API’ye gönderdiğiniz şemanın uyumunu ayrıca gözetin. Örneğin OpenAI Structured Outputs, nesne şemalarında additionalProperties: false ayarını zorunlu tutar.[1]
Ardından belgeyle eşleşmeyi denetleyin.** Çıkarılan değerin ilgili belge ve ilgili alanla ilişkisini gösterin. Bir tarihin biçim olarak geçerli olması, belgedeki vade tarihi olması demek değildir. İnceleme ekranında değerin yanında bulunduğu bölüm veya kısa alıntı gösterilmesini öneriyorum. Bu eşleştirme de denetlenmelidir; modelin yazdığı açıklama kendiliğinden kanıt sayılmamalı.
Son olarak iş kurallarını çalıştırın.** Ödeme tutarı, hesap bilgisi ve para birimi gibi alanları mevcut yetkili kayıtlarla karşılaştırın. Gerekli hesapları uygulama kodunda yeniden yapın. Belgeden doğru çıkarılmış bir bilginin bile o işlem için kullanılıp kullanılamayacağı ayrı bir karardır. Örneğin eski bir belgedeki hesap numarası, yeni ödeme için kendiliğinden yetkili hesap kabul edilmemeli.
Bir ayrıntı özellikle yanıltıcı olabilir: Genel JSON Schema belgelerinde format varsayılan olarak açıklama niteliğindedir; doğrulama etkisi doğrulayıcının ayarına bağlı olabilir. Uygulamalar formatları kısmen de denetleyebilir.[5] Bu nedenle format: "date" yazıldığını görmekle yetinmeyin; kullandığınız doğrulayıcının gerçekten neyi reddettiğini kontrol edin. Biçim denetimi çalışsa bile tarihin doğru belgeden alındığını ayrıca değerlendirin.
İnsan onayı, sonradan eklenmiş bir düğme olmasın
Önerim, insan onayını “her şeye bir kez bak” görevine çevirmek yerine, işlem riskine göre tasarlamak. Geri alınabilir bir taslakla para transferine temel olacak kayıt aynı kabul yolundan geçmek zorunda değil. Eksik bilgi, belgeler arasında çelişki veya sonuçları ağır bir işlem varsa otomatik ilerlemeyi durdurun.
Onaylayacak kişiye yalnızca temiz JSON göstermeyin. Önerilen değeri, ilgili belge bölümünü, başarısız kontrolleri ve eksiklikleri birlikte sunun. Onay, düzeltme ve ret seçeneklerini açıkça ayırın. “İnsan gördü” ile “insan bu işlemi onayladı” aynı kayıt olmasın.
Özellikle modelin ürettiği bir onaylandi alanını gerçek insan onayı yerine kullanmayın. Onay durumunu uygulama belirlesin; kim tarafından ve ne zaman verildiğini kendi kayıtlarından tutsun. Benzer biçimde modelin “kontrol edildi” demesi, bağımsız kontrolün çalıştığı anlamına gelmesin. Bu ayrım, öneri üretme yetkisi ile işlem yapma yetkisini birbirinden ayırır.
Okurun elinde kalması gereken karar
Structured Outputs’tan vazgeçmek gerekmiyor. Biçim sözleşmesini kullanmak, doğruluk sorusunu unutmamak gerekiyor. Kabul akışını şu sırayla düşünün: **Tamamlanmış yanıt → şema uyumu → belgeyle eşleşme → iş kuralı kontrolü → gereken yerde insan onayı.
Her aşamanın başarısız olduğunda ne yapacağı önceden belli olsun: yeniden deneme, eksik bilgi isteme, incelemeye gönderme veya işlemi durdurma. Geçerli JSON, bu yolun başlangıcındaki teknik başarıdır; sonundaki onay kararı değildir.
Yöntem notu: Bu yazı resmî belgelerden hazırlanmış bir rehberdir. Benchmark veya model deneyi yapılmadı. Örnek veri temsilidir; gerçek model çıktısı değildir. Kontrol ve onay akışı önerilerinin etkinliği bu çalışma kapsamında ölçülmedi.
Kaynaklar
[1] https://developers.openai.com/api/docs/guides/structured-outputs
[2] https://json-schema.org/understanding-json-schema/reference/object
[3] https://json-schema.org/understanding-json-schema/reference/null
[4] https://json-schema.org/understanding-json-schema/reference/string
[5] https://json-schema.org/understanding-json-schema/reference/type