Structured Outputs und JSON Mode im Vergleich

Was sind Structured Outputs und was unterscheidet sie vom JSON Mode?

Wenn ein Programm die Antwort eines Modells liest, muss die Antwort jedes Mal in derselben Form kommen. Fehlt ein Feld, kommt eine Zahl als Text oder bricht das JSON mittendrin ab, bleibt das Programm stehen. Im Beitrag über den Code-Review-Prompt ging es darum, eine Feststellung mit wörtlichem Zitat anzufordern, im Beitrag über LLM-as-a-Judge darum, das Urteil des Richters festzuhalten; in beiden liest Code die Antwort des Modells. Dieser Beitrag behandelt die Form dieser Antwort: die Wege zu JSON, was jeder davon garantiert und was sich in diesem Herbst bei Claude geändert hat.

Im JSON Mode bitten Sie das Modell um JSON, und die API sagt zu, dass die Antwort gültiges JSON ist. Welche Felder darin stehen, sagt sie nicht zu. Die Dokumentation von OpenAI schreibt das ausdrücklich: JSON Mode garantiert nicht, dass die Antwort einem Schema entspricht, sondern nur, dass sie sich fehlerfrei parsen lässt.

Beim Tool Calling (auch Function Calling genannt) beschreiben Sie dem Modell ein Tool. Will das Modell dieses Tool aufrufen, schreibt es die Argumente als JSON. Ist das Tool nicht strikt, ist das nur Best Effort, keine Garantie: Laut der Dokumentation von Anthropic kann das Modell bei einem nicht strikten Tool "2" statt 2 schreiben oder ein Pflichtfeld auslassen. Bei einem strikten Tool passen die Argumente zum Schema.

Bei Structured Outputs geben Sie das Schema der Antwort selbst mit. Bei jedem Token wählt das Modell nur unter den Tokens, die zum Schema passen; das nennt man Constrained Decoding. Strict Tool Use wendet dieselbe Technik auf die Argumente eines Tools an. Das Ergebnis ist JSON, das gültig ist und die Felder des Schemas enthält.

Und wofür nimmt man was? Die Dokumentation von Google bringt den Unterschied kurz auf den Punkt: Structured Outputs sind dafür da, die endgültige Antwort zu formatieren, Function Calling dafür, mitten im Gespräch etwas erledigen zu lassen. Soll die Antwort in eine Datenbank, nehmen Sie Structured Outputs; will das Modell eine Datei lesen oder einen Befehl ausführen, Tool Calling.

Wie schaltet man Structured Outputs bei den drei Anbietern ein?

Alle drei Anbieter bieten dieselben drei Wege, aber Namen, Einschalten und Grenzen unterscheiden sich. Die Angaben in der Tabelle stammen aus der Dokumentation des jeweiligen Anbieters, gelesen am 20. Oktober 2026:

Quelle: Dokumentation von OpenAI, Anthropic und Google, 20. Oktober 2026. „Steht nicht in der Dokumentation“ heißt: Auf den Seiten, die wir an diesem Tag gelesen haben, fanden wir keinen Satz dazu. Bei Google ist response_format ein Feld der Interactions API, response_json_schema eines von generateContent. Die Responses API von OpenAI stellt eine Funktion, die nicht als strict markiert ist, nach Möglichkeit auf den strikten Modus um; in Chat Completions ist strict nicht der Standard.

Bei OpenAI schalten Sie Structured Outputs in der Responses API in text.format ein, mit type: "json_schema" und strict: true. Die Dokumentation stellt zwei Bedingungen: Jedes Feld muss required sein, und in jedem Objekt muss additionalProperties: false stehen. Wollen Sie ein optionales Feld, ergänzen Sie seinen Typ um null. Auch die Grenzen des Schemas sind festgelegt: höchstens 5.000 Felder, 10 Ebenen verschachtelter Objekte, 1.000 Enum-Werte und 120.000 Zeichen für alle Namen und Werte zusammen. Ein nicht unterstütztes Schlüsselwort führt zu einem Fehler. Die erste Anfrage mit einem Schema ist langsamer, weil die API das Schema verarbeitet; die folgenden werden nicht langsamer.

Beim Tool Calling sorgt strict: true dafür, dass die Argumente zum Schema passen, und OpenAI empfiehlt, es immer einzuschalten. Das Modell zum Aufruf eines Tools zu zwingen, ist bei OpenAI weiterhin möglich: Setzen Sie tool_choice auf required, ruft das Modell mindestens eine Funktion auf; geben Sie den Namen einer Funktion an, ruft es genau diese auf.

Bei Anthropic haben Structured Outputs zwei Hälften: output_config.format für die Antwort (JSON Outputs) und strict: true für Tools (Strict Tool Use). Beide lassen sich in derselben Anfrage zusammen nutzen. Das Schema wird zu einer Grammatik kompiliert. Deshalb dauert die erste Anfrage mit einem bestimmten Schema länger; das kompilierte Schema bleibt nach der letzten Nutzung 24 Stunden gespeichert. Die Grenzen gelten pro Anfrage: höchstens 20 strikte Tools, insgesamt 24 optionale Felder über alle Schemas und 16 Felder, die anyOf oder mehrere Typen nutzen; für das Kompilieren gibt es außerdem ein Timeout von 180 Sekunden. Eine nicht unterstützte Regel wie minimum oder maxLength führt zu einem 400-Fehler. Die Felder kommen in der Reihenfolge des Schemas, Pflichtfelder aber vor den optionalen. Noch ein Detail: Wer output_config.format ändert, macht den Prompt-Cache dieses Gesprächs ungültig. Warum der Cache bricht, haben wir im Beitrag über Prompt Caching erklärt.

Die wichtigste Änderung dieses Herbstes betrifft ebenfalls Anthropic. Ein bekannter Weg, JSON von Claude zu bekommen, war, ein einziges Tool zu definieren und das Modell mit tool_choice zu zwingen, es aufzurufen. Laut den Release Notes geben bei Opus 5.5, erschienen am 22. September, und bei Sonnet 5.5, erschienen am 28. September, die tool_choice-Typen any und tool einen 400-Fehler zurück. Anthropic empfiehlt Strict Tool Use mit auto und, wenn Sie eine feste JSON-Form brauchen, Structured Outputs. Laut der Tool-Dokumentation akzeptieren Modelle, bei denen das Nachdenken standardmäßig eingeschaltet ist, etwa Haiku 5.5, das Erzwingen weiterhin; bei einem erzwungenen Aufruf ruft das Modell das Tool aber direkt auf, ohne nachzudenken. Bei Haiku 5.5, erschienen am 7. Oktober, kann ein anderer alter Weg einen 400-Fehler liefern: den Anfang der Assistant-Nachricht selbst zu schreiben (Prefill). Structured Outputs funktionieren ohnehin nicht zusammen mit Prefill.

Bei Google beschreibt die aktuelle Anleitung die Interactions API: Sie geben response_format ein mime_type: "application/json" und ein schema mit. In generateContent geht dasselbe mit response_json_schema. Laut der Dokumentation schreibt das Modell syntaktisch gültiges JSON, das zum Schema passt, und ordnet die Felder in der Reihenfolge des Schemas; sehr große oder tief verschachtelte Schemas kann die API ablehnen. Hier gibt es einen wichtigen Unterschied: OpenAI und Anthropic weisen eine nicht unterstützte Schema-Regel mit einem Fehler zurück, Gemini ignoriert sie. Enthält Ihr Schema eine Regel, die Gemini nicht unterstützt, ist die Anfrage trotzdem erfolgreich, die Regel wird aber nicht angewendet. Beim Function Calling sorgt der Modus validated dafür, dass die Argumente zum Schema passen; der Modus any zwingt das Modell dagegen, jedes Mal eine Funktion aufzurufen.

Was garantieren Structured Outputs nicht?

Ein Schema garantiert die Form der Antwort, nicht ihren Inhalt. Google schreibt das ausdrücklich: Dass die Werte inhaltlich richtig sind, ist nicht garantiert. OpenAI sagt ebenfalls, dass Structured Outputs Fehler enthalten können, und fügt eine Warnung hinzu: Hat die Eingabe mit dem Schema gar nichts zu tun, kann das Modell beim Versuch, das Schema zu erfüllen, Dinge erfinden. Anthropic wiederum zählt die Fälle auf, in denen das Schema womöglich gar nicht greift. Darauf sollten Sie achten:

Am häufigsten begegnen einem Ablehnungen und abgeschnittene Antworten. Bei Anthropic kommt eine aus Sicherheitsgründen abgelehnte Anfrage nicht als Fehler, sondern als normale Antwort mit stop_reason: "refusal": Sie liefert HTTP 200, die erzeugten Tokens werden berechnet, und die Antwort passt womöglich nicht zum Schema. Bei OpenAI kommt die Ablehnung in einem eigenen Feld refusal. Eine Antwort, die an max_tokens stößt, bleibt bei beiden Anbietern unvollständig; Anthropic empfiehlt, es mit einem höheren max_tokens erneut zu versuchen. Ihr Code sollte also zuerst prüfen, warum die Antwort endete, und erst danach das JSON parsen.

Eine Falle speziell bei Claude ist ein Denkfeld im Schema. Wer ein Feld reasoning ins Schema setzt und das Modell bittet, dort vor der Antwort nachzudenken, kann bei Claude eine Ablehnung auslösen. Die Dokumentation von Anthropic zu Ablehnungen zählt ein Feld namens reasoning, thinking oder trace in der JSON-Ausgabe oder in der Eingabe eines Tools zu den häufigen Ursachen einer Ablehnung vom Typ reasoning_extraction. Stattdessen empfiehlt sie, um eine kurze Erklärung zu bitten, um die Belege für das Ergebnis oder um eine Zusammenfassung des Erledigten. Seit dem 24. September wird auch eine solche Ablehnung berechnet, die kommt, bevor überhaupt eine Ausgabe entstanden ist. Die Regel gilt nur für diesen Anbieter: Eines der Beispiele in der Anleitung von OpenAI ist ein Schema, das die Antwort mit Schritt-für-Schritt-Erklärungen liefert. Wie viel das Modell bei Claude nachdenkt, bestimmt nicht das Schema, sondern die Effort-Einstellung; mehr dazu im Beitrag über Effort.

Wie verlässlich ein Schema in der Hand des Anbieters ist, ist eine eigene Frage. In unseren eigenen Aufzeichnungen haben wir ein striktes JSON-Schema an einen Endpunkt geschickt, den der Katalog eines Routing-Dienstes als kompatibel mit response_format führte, nicht aber mit Structured Outputs. Die Antwort war kein Fehler: HTTP 200 und 1.639 Zeichen Markdown. Dabei stimmte der Inhalt sogar: Er nannte den echten Fehler in dem Diff, den wir für die Testanfrage verwendet hatten, beim Namen. Es fehlte nur das JSON. Das ist die Aufzeichnung einer einzigen Testanfrage, keine Quote. Aber sie zeigt, dass das Schema-Versprechen einer API die Prüfung im Code, der die Antwort liest, nicht ersetzt. In diffox gilt eine Antwort, die sich nicht als JSON parsen lässt, nicht als Erfolg; der Aufruf schlägt fehl und landet im Protokoll des Reviews, zusammen mit der Angabe, welcher Agent oder welcher Schritt warum ausgefallen ist.

Wie bekommt man JSON von einem Coding-Agenten auf der Kommandozeile?

Dieselbe Frage stellt sich bei Coding-Agenten. Wenn Sie einen Agenten in der CI oder in einem Skript ausführen und sein Ergebnis an einen weiteren Schritt weitergeben, müssen Sie sich auf die Form der Antwort verlassen können. Alle fünf Tools lassen sich von der Kommandozeile aus starten, aber nicht alle liefern dasselbe: Manche packen die Antwort in einen JSON-Umschlag, andere verlangen die Antwort selbst nach einem Schema. Die Angaben in der Tabelle stammen aus der Dokumentation des jeweiligen Tools, gelesen am 20. Oktober 2026:

Quelle: Dokumentation des jeweiligen Tools, 20. Oktober 2026. „Steht nicht in der Dokumentation“ heißt: Auf den Seiten, die wir an diesem Tag gelesen haben, fanden wir keinen Satz dazu. Dass Claude Code die Ausgabe gegen das Schema prüft und erneut anfragt, steht in der Dokumentation des Agent SDK; claude -p führt dieses SDK auf der Kommandozeile aus. Schlägt in Cursor CLI ein Lauf fehl, wird kein JSON geschrieben, und der Prozess endet mit einem Exit-Code ungleich null.

Der Unterschied in der Tabelle ist wichtig. Ein JSON-Umschlag heißt, dass die Antwort in einem JSON-Objekt steckt; die Antwort darin bleibt freier Text. Soll der nächste Schritt Felder aus der Antwort lesen, brauchen Sie entweder ein Tool mit Schema-Option oder einen Schritt, der die Antwort im Code prüft. Die Dokumentation von Claude Code ist auch hier deutlich: Selbst wenn das Ergebnis erfolgreich aussieht, werten Sie es als Fehler, wenn das Feld structured_output fehlt. Claude Code nennt noch ein Detail: Das Schlüsselwort format im Schema, etwa "format": "email", betrachtet es nur als Anmerkung und setzt es nicht durch.

Falls Sie noch Gemini CLI nutzen: gemini -p --output-format json liefert die Antwort als Text im Feld response; eine Schema-Option nennt diese Dokumentation nicht. Für Nutzer der kostenlosen Stufe und von Google One hat Google Gemini CLI am 18. Juni 2026 durch Antigravity CLI ersetzt; mit kostenpflichtigen API-Schlüsseln lässt sich Gemini CLI weiter nutzen.

Wie bekommt man am Ende einer Agentenschleife JSON?

In einer Agentenschleife liest, sucht und probiert das Modell erst mit Tools; ganz am Ende liefert es ein Ergebnis. Damit dieses Ergebnis bei Claude JSON war, reichte es bisher, das Modell im letzten Schritt zu zwingen, ein „submit“-Tool aufzurufen. Weil dieser Weg bei Opus 5.5 und Sonnet 5.5 einen 400-Fehler liefert, sieht das Muster jetzt so aus:

1. Lassen Sie tool_choice auf auto. Laut Anthropic beeinflusst der Prompt weiterhin, welches Tool gewählt wird, und ein Modell, das nicht gezwungen wird, kann nachdenken, bevor es das Tool aufruft.
2. Geben Sie dem Modell ein letztes Tool mit strict: true, etwa submit, und bitten Sie es im Prompt, dieses Tool genau einmal und als Letztes aufzurufen, wenn die Arbeit fertig ist. Da die Argumente zum Schema passen, müssen Sie das Ergebnis nicht eigens parsen.
3. Beenden Sie die Schleife, sobald dieser Aufruf kommt. Hört das Modell auf, ohne das Tool aufzurufen, wird die Antwort bei max_tokens abgeschnitten oder kommt eine Ablehnung, zählen Sie das nicht als Ergebnis, sondern melden einen klaren Fehler.
4. Begrenzen Sie die Tool-Aufrufe. Ist die Grenze erreicht, führen Sie das Tool nicht mehr aus, sondern sagen dem Modell, es solle jetzt entscheiden. Begrenzen Sie auch die Zahl der Runden.
5. Wenn Sie eine Begründung wollen, setzen Sie ein kurzes Feld evidence ins Schema, nicht reasoning.

Für die letzte Antwort lassen sich statt eines Tools auch Structured Outputs nutzen: Die Dokumentation von Anthropic schreibt, dass strikte Tools und output_config.format in derselben Anfrage zusammen funktionieren. Die Tool-Aufrufe passen zum Schema, und auch die letzte Textantwort ist an das Schema gebunden. Das Beispiel unten zeigt den ersten Weg mit dem Python-SDK von Anthropic:

# Beispiel: tool_choice bleibt auf auto, die Schleife endet mit submit.
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  # das Ergebnis, passend zum Schema
        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")

Nach diesem Muster arbeitet in diffox der Schritt, der eine Feststellung gegen das Repository selbst prüft, bevor sie in den Pull Request geschrieben wird. Die Notiz im Code sagt es deutlich: “A MANUAL LOOP, tool_choice left at auto”. Das Modell kann mit schreibgeschützten Git-Tools höchstens 8 Aufrufe machen, und der Prompt bittet es, das Tool submit_verdict genau einmal und als Letztes aufzurufen, wenn es fertig ist. submit_verdict ist ein striktes Tool: Das Urteil ist einer von drei Werten (HOLDS, REFUTED, UNSURE), daneben gibt es ein Feld für Belege; ein Denkfeld hat das Schema nicht. Ist die Grenze erreicht, läuft das Tool nicht mehr, und das Modell wird aufgefordert, sein Urteil abzugeben; die Runden enden 3 über der Grenze. Hört das Modell auf, ohne ein Urteil abzugeben, wird „kein Urteil“ protokolliert, und die Feststellung bleibt, wie sie ist: Keine Feststellung gilt standardmäßig als widerlegt.

Welcher Weg passt zu welchem Fall?

Die Regel ist einfach: Richten Sie die Wahl danach, wer das JSON liest und was er braucht, und prüfen Sie trotzdem jede Antwort, die ankommt. Eine Übersicht für häufige Fälle:

Allen Karten gemeinsam ist: Das Schema garantiert die Form, um den Rest kümmert sich Ihr Code. Regeln, die ein Schema nicht ausdrücken kann, etwa die Länge eines Textes, der Bereich einer Zahl oder ob ein Feld zu einem anderen passt, prüft der Code, nachdem die Antwort da ist. Schlägt die Prüfung fehl, fragen Sie einmal erneut an; schlägt auch der zweite Versuch fehl, schlucken Sie den Fehler nicht, sondern melden ihn klar. Das Claude Agent SDK arbeitet genauso: Es fordert eine unpassende Ausgabe neu an und gibt einen Fehler zurück, wenn das Limit der Versuche erreicht ist. Solche Prüfungen, die nach der Antwort des Modells laufen, haben wir im Beitrag über Harness Engineering beschrieben.