Structured outputs nedir, JSON mode’dan farkı ne

Structured outputs nedir, JSON mode’dan farkı ne?

Bir modelin cevabını bir program okuyacaksa cevap her seferinde aynı biçimde gelmeli. Bir alan eksikse, bir sayı metin olarak geldiyse ya da JSON yarıda kaldıysa program durur. Kod inceleme prompt’u yazısında bulguyu birebir alıntıyla istemeyi, LLM-as-a-judge yazısında hakemin kararını kaydetmeyi anlattık; ikisinde de modelin cevabını kod okuyor. Bu yazı o cevabın biçimini anlatıyor: JSON almanın yolları, her birinin neyi garanti ettiği ve bu sonbaharda Claude’da neyin değiştiği.

JSON mode’da modelden JSON istersiniz ve API cevabın geçerli JSON olacağını söyler. Hangi alanların geleceğini söylemez. OpenAI’ın belgesi bunu açıkça yazıyor: JSON mode cevabın bir şemaya uyacağını değil, yalnızca hatasız ayrıştırılacağını garanti eder.

Tool calling’de (function calling da denir) modele bir araç tanıtırsınız. Model o aracı çağırmak istediğinde argümanlarını JSON olarak yazar. Araç strict değilse bu bir çabadır, garanti değil: Anthropic’in belgesine göre strict olmayan bir araçta model 2 yerine "2" yazabilir ya da zorunlu bir alanı atlayabilir. Strict bir araçta argümanlar şemaya uyar.

Structured outputs’ta şemayı cevabın kendisine verirsiniz. Model her token’ı seçerken yalnızca şemaya uyan token’lar arasından seçer; buna constrained decoding denir. Strict tool use aynı tekniği aracın argümanlarına uygular. Sonuç, geçerli ve şemadaki alanları taşıyan bir JSON’dur.

Peki hangisi ne için? Google’ın belgesi ayrımı kısaca koyuyor: structured outputs son cevabı biçimlendirmek için, function calling ise konuşmanın ortasında bir iş yaptırmak için. Cevabı bir veritabanına yazacaksanız structured outputs; model bir dosyayı okumak ya da bir komutu çalıştırmak istiyorsa tool calling.

Üç sağlayıcıda structured outputs nasıl açılır?

Üç sağlayıcı da aynı üç yolu sunuyor, ama adları, açılışları ve sınırları farklı. Tabloyu 20 Ekim 2026 günü her sağlayıcının kendi belgesinden okuduk:

Kaynak: OpenAI, Anthropic ve Google belgeleri, 20 Ekim 2026. “Belgede yazmıyor”: o gün okuduğumuz sayfalarda bunu anlatan bir cümle bulamadık. Google’da response_format Interactions API’nin, response_json_schema generateContent’in alanı. OpenAI’ın Responses API’si strict yazılmamış bir fonksiyonu mümkünse strict moda çeviriyor; Chat Completions’ta varsayılan strict değil.

OpenAI’da structured outputs’u Responses API’de text.format içinde type: "json_schema" ve strict: true ile açarsınız. Belge iki şart koyuyor: her alan required olmalı ve her nesnede additionalProperties: false yazmalı. İsteğe bağlı bir alan istiyorsanız tipine null eklersiniz. Şemanın sınırları da yazılı: en fazla 5.000 alan, 10 seviye iç içe nesne, 1.000 enum değeri ve bütün adlarla değerlerin toplamında 120.000 karakter. Desteklenmeyen bir anahtar kelime hata döndürür. Bir şemayla yapılan ilk istek, API şemayı işlediği için daha yavaştır; sonrakiler yavaşlamaz.

Tool calling’de strict: true argümanların şemaya uymasını sağlar ve OpenAI bunu her zaman açmanızı öneriyor. Modeli bir aracı çağırmaya zorlamak OpenAI’da hâlâ bir seçenek: tool_choice’a required yazarsanız model en az bir fonksiyon çağırır, bir fonksiyonun adını verirseniz tam olarak onu çağırır.

Anthropic’te structured outputs’un iki yarısı var: cevap için output_config.format (JSON outputs), araçlar için strict: true (strict tool use). İkisi aynı istekte birlikte kullanılabilir. Şema bir dilbilgisine (grammar) derlenir. Aynı şemanın ilk isteği bu yüzden gecikir; derlenen şema son kullanımından sonra 24 saat saklanır. Sınırlar istek başına: en fazla 20 strict araç, bütün şemalarda toplam 24 isteğe bağlı alan ve anyOf ya da birden çok tip kullanan 16 alan; derleme için de 180 saniyelik bir zaman aşımı var. minimum ya da maxLength gibi desteklenmeyen bir kural 400 döndürür. Alanlar şemadaki sırayla gelir, ama zorunlu alanlar isteğe bağlı olanlardan önce yazılır. Bir ayrıntı daha: output_config.format’u değiştirmek o konuşmanın prompt önbelleğini geçersiz kılar. Önbelleğin neden bozulduğunu prompt caching yazısında anlattık.

Bu sonbaharın asıl değişikliği de Anthropic’te. Claude’dan JSON almanın bilinen bir yolu, tek bir araç tanımlayıp tool_choice ile modeli o aracı çağırmaya zorlamaktı. Sürüm notlarına göre 22 Eylül’de çıkan Opus 5.5’te ve 28 Eylül’de çıkan Sonnet 5.5’te tool_choice’un any ve tool tipleri 400 hatası döndürüyor. Anthropic’in önerdiği yol, auto ile strict tool use; sabit bir JSON biçimi gerekiyorsa structured outputs. Araç belgesine göre Haiku 5.5 gibi düşünmesi varsayılan olarak açık modeller zorlamayı hâlâ kabul ediyor, ama zorlanan çağrıda model düşünmeden doğrudan aracı çağırıyor. 7 Ekim’de çıkan Haiku 5.5’te başka bir eski yöntem, asistan mesajının başını sizin yazmanız (prefill), 400 döndürebiliyor; structured outputs zaten prefill ile birlikte çalışmıyor.

Google’da güncel kılavuz Interactions API’yi anlatıyor: response_format’a mime_type: "application/json" ve schema verirsiniz. generateContent’te aynı iş response_json_schema ile yapılıyor. Belgeye göre model şemaya uyan, sözdizimi geçerli bir JSON yazıyor ve alanları şemadaki sırayla diziyor; çok büyük ya da çok iç içe şemaları API reddedebiliyor. Burada önemli bir fark var: OpenAI ve Anthropic desteklemedikleri bir şema kuralını hatayla geri çeviriyor, Gemini ise yok sayıyor. Şemanızda Gemini’nin desteklemediği bir kural varsa istek yine başarılı olur, ama o kural uygulanmaz. Function calling’de şemaya uyumu validated modu sağlıyor; any modu ise modeli her seferinde bir fonksiyon çağırmaya zorluyor.

Structured outputs neyi garanti etmez?

Şema cevabın biçimini garanti eder, içeriğini değil. Google bunu açıkça yazıyor: değerlerin anlamca doğru olduğu garanti edilmez. OpenAI da structured outputs’un yine hata içerebileceğini söylüyor ve bir uyarı ekliyor: girdi şemayla hiç ilgili değilse, model şemaya uymaya çalışırken uydurabilir. Anthropic ise şemanın hiç tutmayabileceği durumları sayıyor. Bakılması gerekenler:

En sık karşılaşılan ikisi ret ve kesilme. Anthropic’te güvenlik nedeniyle reddedilen bir istek hata olarak değil, stop_reason: "refusal" taşıyan normal bir cevap olarak gelir: HTTP 200 döner, üretilen token’lar ücretlenir ve cevap şemaya uymayabilir. OpenAI’da ret ayrı bir refusal alanında gelir. max_tokens’a takılan bir cevap iki sağlayıcıda da yarım kalır; Anthropic’in önerisi daha yüksek bir max_tokens ile yeniden denemek. Yani kodunuz önce cevabın neden bittiğine bakmalı, JSON’u ondan sonra ayrıştırmalı.

Claude’a özgü bir tuzak da şemadaki düşünce alanı. Şemaya bir reasoning alanı koyup modelin cevaptan önce orada düşünmesini istemek Claude’da reddedilmeye yol açabilir. Anthropic’in ret belgesi JSON çıktısında ya da bir aracın girdisinde reasoning, thinking ya da trace adlı bir alanı reasoning_extraction türündeki reddin sık nedenleri arasında sayıyor. Bunun yerine kısa bir açıklama, sonucun dayandığı kanıt ya da yapılanların bir özetini istemenizi öneriyor. 24 Eylül’den beri bu türden, daha hiç çıktı üretilmeden gelen bir ret de ücretleniyor. Kural sağlayıcıya özgü: OpenAI’ın kılavuzundaki örneklerden biri cevabı adım adım açıklamalarla veren bir şema. Claude’da modelin ne kadar düşüneceğini şema değil, effort ayarı belirler; effort yazısında anlattık.

Şemanın sağlayıcının elinde ne kadar sağlam olduğu da ayrı bir soru. Kendi kayıtlarımızda, bir yönlendirme servisinin kataloğunda response_format’u desteklediği yazan ama structured outputs’u desteklediği yazmayan bir uç noktaya katı bir JSON şeması gönderdik. Cevap bir hata değildi: HTTP 200 ve 1.639 karakterlik markdown. Üstelik içerik doğruydu: yoklamada kullandığımız diff’teki gerçek hatayı adıyla söylüyordu. Eksik olan yalnızca JSON’du. Bu tek bir yoklamanın kaydı, bir oran değil. Ama API’nin şema sözünün, cevabı okuyan kodun kontrolünün yerini tutmadığını gösteriyor. diffox’ta JSON olarak ayrıştırılamayan bir cevap başarılı sayılmıyor; çağrı hata veriyor ve incelemenin kaydına, hangi ajanın ya da adımın neden düştüğüyle birlikte geçiyor.

Kodlama ajanından komut satırında JSON nasıl alınır?

Aynı soru kodlama ajanlarında da var. Bir ajanı CI’da ya da bir betikte çalıştırıp sonucunu başka bir adıma verecekseniz, cevabın biçimine güvenebilmeniz gerekir. Beş aracın da komut satırından çalıştırılan bir yolu var, ama hepsi aynı şeyi vermiyor: kimi cevabı bir JSON zarfına koyuyor, kimi cevabın kendisini bir şemaya göre istiyor. Tabloyu 20 Ekim 2026 günü her aracın kendi belgesinden okuduk:

Kaynak: her aracın belgesi, 20 Ekim 2026. “Belgede yazmıyor”: o gün okuduğumuz sayfalarda bunu anlatan bir cümle bulamadık. Claude Code’un şemayı doğrulama ve yeniden isteme davranışı Agent SDK belgesinde yazıyor; claude -p o SDK’yı komut satırından çalıştırıyor. Cursor CLI’da çalışma başarısız olursa JSON yazılmıyor, süreç sıfırdan farklı bir kodla çıkıyor.

Tablodaki ayrım önemli. JSON zarfı, cevabın bir JSON nesnesinin içinde geldiği anlamına gelir; içindeki cevap yine serbest metindir. Bir sonraki adım cevaptaki alanları okuyacaksa ya şema seçeneği olan bir araç ya da cevabı kodda doğrulayan bir adım gerekir. Claude Code’un belgesi burada da açık: sonuç başarılı görünse bile structured_output alanı yoksa bunu da hata sayın. Claude Code bir ayrıntıyı daha yazıyor: şemadaki format anahtar kelimesini, örneğin "format": "email"’i, yalnızca bir not olarak görüyor ve uygulamıyor.

Gemini CLI’ı hâlâ kullanıyorsanız, gemini -p --output-format json cevabı response alanında metin olarak veriyor; şema seçeneği bu belgede yazmıyor. Google, ücretsiz katman ve Google One kullanıcıları için Gemini CLI’ı 18 Haziran 2026’da Antigravity CLI ile değiştirdi; ücretli API anahtarlarıyla Gemini CLI kullanılmaya devam ediyor.

Ajan döngüsünün sonunda JSON nasıl alınır?

Bir ajan döngüsünde model önce araçlarla okur, arar, dener; en sonda bir sonuç verir. O sonucun JSON olması için Claude’da son adımda modeli bir “submit” aracını çağırmaya zorlamak yeterliydi. Opus 5.5’te ve Sonnet 5.5’te bu yol 400 döndürdüğü için düzen artık şöyle:

1. tool_choice’u auto’da bırakın. Anthropic’e göre hangi aracın seçileceğini prompt yine etkiler ve zorlanmayan model aracı çağırmadan önce düşünebilir.
2. Modele strict: true bir son araç verin, örneğin submit, ve prompt’ta işi bitince onu tam bir kez, en son çağırmasını isteyin. Argümanlar şemaya uyacağı için sonucu ayrıca ayrıştırmanız gerekmez.
3. Döngüyü o araç gelince bitirin. Model aracı çağırmadan durursa, cevap max_tokens’ta kesilirse ya da bir ret gelirse bunu sonuç saymayın; açıkça hata verin.
4. Araç çağrılarına bir sınır koyun. Sınır dolunca aracı çalıştırmak yerine modele kararını şimdi vermesini söyleyin; turları da bir üst sınırla kesin.
5. Gerekçe istiyorsanız şemaya reasoning değil, kısa bir evidence alanı koyun.

Son cevap için bir araç yerine structured outputs da kullanılabilir: Anthropic’in belgesi strict araçlarla output_config.format’un aynı istekte birlikte çalıştığını yazıyor. Araç çağrıları şemaya uyar, son metin cevabı da şemaya bağlı gelir. Aşağıdaki örnek ilk yolu, Anthropic’in Python SDK’sıyla gösteriyor:

# Örnek: tool_choice auto’da kalır, döngü submit gelince biter.
import anthropic

client = anthropic.Anthropic()

SUBMIT = {
    "name": "submit",
    "description": "Give the final answer. Call exactly once, last.",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {
            "verdict": {"type": "string", "enum": ["HOLDS", "REFUTED", "UNSURE"]},
            "evidence": {"type": "string"},
        },
        "required": ["verdict", "evidence"],
        "additionalProperties": False,
    },
}


def run(model, messages, tools, run_tool, max_calls=8):
    calls = 0
    for _ in range(max_calls + 3):
        response = client.messages.create(
            model=model, max_tokens=8000, tools=tools + [SUBMIT], messages=messages)
        if response.stop_reason in ("max_tokens", "refusal"):
            raise RuntimeError("no answer: " + response.stop_reason)
        messages.append({"role": "assistant", "content": response.content})
        uses = [b for b in response.content if b.type == "tool_use"]
        for b in uses:
            if b.name == "submit":
                return b.input  # şemaya uyan sonuç
        if not uses:
            raise RuntimeError("the model stopped without calling submit")
        results = []
        for b in uses:
            calls += 1
            out = (run_tool(b.name, b.input) if calls <= max_calls
                   else "Tool budget spent: call submit now.")
            results.append({"type": "tool_result", "tool_use_id": b.id, "content": out})
        messages.append({"role": "user", "content": results})
    raise RuntimeError("turn limit reached without submit")

diffox’ta bir bulguyu pull request’e yazmadan önce deponun kendisine karşı kontrol eden adım bu düzende çalışıyor. Koddaki not açık: “A MANUAL LOOP, tool_choice left at auto”. Model salt okunur git araçlarıyla en fazla 8 çağrı yapabiliyor ve prompt ondan işi bitince submit_verdict aracını tam bir kez, en son çağırmasını istiyor. submit_verdict strict bir araç: kararı üç değerden biri (HOLDS, REFUTED, UNSURE), yanında da bir kanıt alanı var; şemada düşünce alanı yok. Sınır dolunca araç çalışmıyor, modele kararını vermesi söyleniyor; turlar da sınırın 3 fazlasında kesiliyor. Model kararını vermeden durursa kayda “karar yok” yazılıyor ve bulgu olduğu gibi kalıyor: hiçbir bulgu varsayılan olarak çürütülmüş sayılmıyor.

Hangi durumda hangisini kullanmalı?

Kural basit: JSON’u kim okuyacaksa onun ihtiyacına göre seçin ve gelen her cevabı yine kontrol edin. Sık karşılaşılan durumlar için özet:

Kartların ortak noktası şu: şema biçimi garanti ediyor, gerisi sizin kodunuzda. Bir metnin uzunluğu, bir sayının aralığı ya da bir alanın başka bir alanla tutarlılığı gibi şemanın anlatamadığı kurallar, cevap geldikten sonra kodda kontrol edilir. Kontrol tutmazsa bir kez yeniden isteyin; ikinci deneme de tutmazsa hatayı yutmayın, açıkça verin. Claude Agent SDK da böyle çalışıyor: uymayan çıktıyı yeniden istiyor, deneme sınırı dolunca hata döndürüyor. Modelin cevabından sonra çalışan bu tür kontrolleri harness engineering yazısında anlattık.