Was ist JSON Schema? Warum setzen OpenAI, Gemini, Claude und MCP zunehmend auf JSON Schema?

JSON Schema ist der maschinenlesbare Vertrag zwischen AI Agent, Modell, Tool und API. Dieser Beitrag zeigt anhand von Ausgabeformaten, Function Calling, MCP und Multi-Modell-Adaptern, wie Entwickler stabile Datenflüsse aufbauen und geschäftliche Prüfungen von reiner Schema-Validierung trennen.

Die veröffentlichte JSON-Schema-Version 2020-12 ist laut offizieller Spezifikation weiterhin die aktuelle Fassung (JSON Schema Specification). Für AI Agent-Anwendungen folgt daraus eine klare Entscheidung: Verwenden Sie JSON Schema als maschinenlesbaren Vertrag für Felder, Typen und zulässige Werte, aber pflegen Sie für OpenAI, Gemini, Claude und MCP jeweils geprüfte Adapter. Eine einzige Definition lässt sich nicht automatisch unverändert überall einsetzen.

Geeignet für: AI-Anwendungsentwickler, die stabile Ausgaben oder Tool-Parameter benötigen. Plattformingenieure, die Datenverträge über mehrere Modelle hinweg wiederverwenden. Testingenieure, die Schema- und Kompatibilitätsprüfungen automatisieren.

Nicht ausreichend für: Systeme, die nach einer erfolgreichen Schema-Prüfung automatisch von korrekten Berechtigungen, realen Ressourcen oder fachlich richtigen Geschäftsdaten ausgehen.

Warum JSON Schema für einen AI Agent mehr als gültiges JSON liefert

JSON ist zunächst nur ein Datenformat. Ein Ergebnis wie { "status": "ok" } kann syntaktisch korrekt sein. Es sagt aber nicht, ob status vorhanden sein muss, ob nur ok, failed oder pending erlaubt sind oder ob zusätzlich eine numerische Auftragsnummer erforderlich ist.

JSON Schema beschreibt genau diese Struktur. Typische Bestandteile sind:

• type für Objekt, Array, Zeichenkette, Zahl oder Boolean,
• properties für die erlaubten Felder,
• required für Pflichtfelder,
• enum für begrenzte Werte,
• items für die Struktur von Array-Elementen,
• $ref und $defs für wiederverwendbare Teilschemas,
• additionalProperties oder verwandte Schlüsselwörter zur Begrenzung unbekannter Felder.

Die offizielle Spezifikation trennt dabei unter anderem Kernmechanismen und Validierungswortschatz. JSON Schema kann deshalb nicht nur validieren, sondern auch Datenstrukturen dokumentieren und wiederverwendbare Definitionen organisieren.

Der Unterschied zwischen Daten und Datenvertrag

Ein Schema darf nicht mit einer vollständigen fachlichen Prüfung verwechselt werden. format: "date" kann eine Datumsdarstellung beschreiben. Es beweist nicht, dass der Termin im Kalender existiert. Ein Feld order_id mit dem Typ string beweist nicht, dass die Bestellung tatsächlich vorhanden ist oder dem angemeldeten Kunden gehört.

Wir trennen in Produktionssystemen deshalb mindestens zwei Ebenen:

1. Strukturelle Validierung: Sind Felder vorhanden und typgerecht?
2. Geschäftliche Validierung: Ist das Datum zulässig, gehört die Bestellung zum Benutzer, liegt der Betrag im erlaubten Bereich und ist der Statuswechsel erlaubt?

Diese Trennung reduziert ein typisches Fehlerszenario: Ein Modell liefert formal korrekte Daten, der Ausführer behandelt sie jedoch als vertrauenswürdige Realität.

Wie begrenzt JSON Schema strukturierte Antworten?

Bei einer strukturierten Antwort erhält das Modell ein gewünschtes Ergebnisformat. Ein AI Agent kann dadurch beispielsweise eine Klassifikation, eine Liste von Aktionen oder eine normalisierte Datensammlung erzeugen.

Ein minimales internes Schema könnte so aussehen:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.invalid/schemas/action-result.json",
  "type": "object",
  "properties": {
    "decision": {
      "type": "string",
      "enum": ["approve", "review", "reject"]
    },
    "reasons": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["decision", "reasons"],
  "additionalProperties": false
}

Damit ist festgelegt, dass decision nur einen der drei Werte annehmen darf und reasons eine Liste von Zeichenketten sein muss. Das verhindert nicht jede inhaltliche Fehlentscheidung. Es verhindert aber, dass nachgelagerter Code mit wechselnden Feldnamen wie result, recommendation oder final_status umgehen muss.

OpenAI Structured Outputs

OpenAI unterscheidet zwischen älterem JSON-Modus und Structured Outputs. Der JSON-Modus soll gültiges JSON erzeugen. Structured Outputs verwendet dagegen ein angegebenes JSON Schema. Bei strict: true wird eine exakte Schema-Befolgung angestrebt, wobei die offizielle Dokumentation ausdrücklich nur ein unterstütztes JSON-Schema-Teilset nennt (OpenAI API-Referenz zu Structured Outputs).

Für die Architektur bedeutet das:

• Das interne Schema darf umfangreicher sein als das Schema der API-Anfrage.
• Nicht unterstützte oder unnötig komplexe Schlüsselwörter müssen vor dem Senden entfernt oder umgebaut werden.
• Die Antwort wird zusätzlich in der eigenen Anwendung validiert.
• Eine Modellantwort darf niemals ohne Authentifizierungs- und Geschäftsprüfung eine irreversible Aktion auslösen.

Gemini Structured Output

Gemini Structured Output verwendet ebenfalls eine JSON-Schema-Definition, unterstützt laut offizieller Google-Dokumentation aber nur ein Teilset. Genannt werden unter anderem string, number, integer, boolean, object, array und null; zusätzlich werden beschreibende Eigenschaften wie title und description unterstützt (Google-Dokumentation zu strukturierten Ausgaben).

Die praktische Folge ist nicht, Gemini zu vermeiden. Die Folge ist, das Schema vorab auf die tatsächlich akzeptierte Form zu reduzieren. Ein verschachteltes Modell mit vielen Referenzen, Bedingungen oder fortgeschrittenen Kompositionsschlüsseln sollte nicht ungeprüft als Anfrageformat verwendet werden.

Claude und Tool-Parameter

Anthropic beschreibt Tool-Definitionen über input_schema. Dieses Schema definiert, welche Parameter Claude für ein Tool liefern soll. Die offizielle Anleitung weist zusätzlich darauf hin, dass ausführliche Tool-Beschreibungen für die Auswahl und Nutzung wichtig sind (Anthropic-Anleitung zur Tool-Nutzung).

Das ist ein anderer Einsatzpunkt als eine reine strukturierte Textantwort:

• Das Modell entscheidet, ob ein Tool verwendet werden soll.
• Das Schema beschreibt die erwarteten Argumente.
• Ihre Anwendung validiert die Argumente.
• Erst danach wird die konkrete Funktion ausgeführt.

Claude erhält dadurch keinen direkten Zugriff auf eine Datenbank oder ein Dateisystem. Das Schema beschreibt nur die Form des Vorschlags.

Unterstützen die drei Modelle vollständiges JSON Schema?

Nein, diese Aussage wäre zu weitgehend. Die offiziellen Dokumentationen beschreiben unterschiedliche Schnittstellen und Teilmengen. „Unterstützt JSON Schema“ bedeutet deshalb nicht automatisch Unterstützung für alle Drafts, alle Validierungswortschlüssel oder alle Referenzmechanismen. Für eine belastbare Aussage benötigen Sie ein konkretes Schema, ein konkretes Modell, eine konkrete API-Version und einen dokumentierten Testzeitpunkt.

Welche Rolle spielen inputSchema und outputSchema im Model Context Protocol?

Das Model Context Protocol verbindet nicht einfach ein Modell mit beliebigem Code. Es definiert, wie Server Werkzeuge anbieten und wie Clients diese Werkzeuge aufrufen. In der Tools-Spezifikation enthält eine Tool-Definition unter anderem name, description, inputSchema und optional outputSchema (MCP Tools Specification).

inputSchema: Was darf das Tool annehmen?

inputSchema beschreibt die erwarteten Parameter. Bei einem Tool create_ticket könnten beispielsweise title, priority und project_id Pflichtfelder sein. Der MCP-Client kann diese Beschreibung an ein Modell weiterreichen. Der Server muss die Eingabe trotzdem selbst prüfen.

Wichtig ist die Sicherheitsgrenze: inputSchema verleiht keine Berechtigung. Ein Feld project_id mit dem Typ string autorisiert weder den Zugriff auf jedes Projekt noch beweist es, dass das Projekt existiert. Die Berechtigungsprüfung gehört in den Tool-Server.

outputSchema: Was darf das Tool zurückgeben?

outputSchema beschreibt die erwartete Struktur eines strukturierten Ergebnisses. Die Spezifikation nennt dafür structuredContent. Wenn ein Output-Schema vorhanden ist, müssen Server strukturierte Ergebnisse liefern, die diesem Schema entsprechen; Clients sollten diese Ergebnisse validieren. Für ältere Clients empfiehlt die Spezifikation zusätzlich eine serialisierte Darstellung in einem Textblock.

Was ist im MCP-Datenfluss besonders wichtig?

Ein typischer Ablauf sieht so aus:

1. Der MCP-Server veröffentlicht Name, Beschreibung und inputSchema.
2. Der Client stellt diese Tool-Information dem AI Agent bereit.
3. Das Modell erzeugt einen Tool-Aufruf mit Argumenten.
4. Der Client validiert die Argumente.
5. Der Server prüft zusätzlich Identität, Berechtigungen und Geschäftsregeln.
6. Das Tool führt die Aktion aus.
7. Das Ergebnis wird als Text, strukturiertes Ergebnis oder beides zurückgegeben.
8. Der Client validiert structuredContent gegen outputSchema.

MCP ersetzt dabei nicht die modellseitige Auswahlentscheidung. Das Protokoll standardisiert die Exponierung und den Aufruf von Tools. Ob ein Modell ein Tool auswählt, hängt weiterhin von Modell, Beschreibung, Kontext und Adapter ab.

Erfahrung aus der Plattformarbeit: Ein gut definiertes Schema verhindert viele Parsing-Fehler. Es verhindert aber keinen Missbrauch eines korrekt geformten Aufrufs. Authentifizierung, Autorisierung, Rate Limits und Protokollierung müssen außerhalb des Schemas bleiben.

Die Wiederverwendung einer Schema-Datei über mehrere Plattformen

Ja, eine gemeinsame Definition ist möglich, aber nicht als blind kopierte Datei. Wir empfehlen einen dreistufigen Aufbau:

Die Hauptdefinition sollte eine eindeutige Kennung und eine Versionsnummer besitzen. Adapter dürfen keine neue Fachlogik erfinden. Jede Umwandlung muss nachvollziehbar bleiben:

action-result@2.1.0
  ├── openai-strict@2.1.0
  ├── gemini-structured@2.1.0
  ├── claude-tool-input@2.1.0
  └── mcp-tool@2.1.0

Ein Adapter kann beispielsweise $ref auflösen, description kürzen, optionale Felder in eine kompatible Form bringen oder nicht unterstützte Kompositionsregeln in eine Anwendungskontrolle verschieben. Er darf jedoch nicht stillschweigend amount von einer Zahl in eine Zeichenkette umwandeln, ohne diese Änderung zu protokollieren.

Dritte Entscheidung: Wann ist Rückwärtskompatibilität gebrochen?

Eine Änderung ist kritisch, wenn ein bisher gültiger Produzent sie nicht mehr erzeugen kann oder ein bisher gültiger Konsument sie nicht mehr akzeptiert. In der Praxis unterscheiden wir:

• Additiv: Ein neues optionales Feld wird ergänzt.
• Einschränkend: Ein bisher erlaubter Wert wird aus einer enum entfernt.
• Strukturell: Ein Objekt wird durch ein Array ersetzt.
• Semantisch: Ein Feld bleibt technisch gleich, bedeutet aber etwas anderes.
• Anbieterbezogen: Ein Schlüsselwort funktioniert im internen Schema, nicht aber in einem bestimmten API-Teilset.

Für jeden Adapter speichern wir daher:

• Schema-Draft oder Dialekt,
• Modellname und API-Version,
• Umwandlungsregeln,
• Testfälle mit gültigen und ungültigen Beispielen,
• erwartete Fehlermeldungen,
• Rückfallversion.

Schema-Governance in einer Produktionsumgebung

Die folgende Vorgehensweise ist für ein Multi-Modell-Projekt belastbarer als manuelle Anpassungen in einzelnen Prompts.

Schritt 1: Fachobjekt statt Anbieterfunktion definieren

Beginnen Sie mit dem Geschäftsobjekt. Ein ActionRequest sollte nicht deshalb anders heißen, weil eine Plattform function und eine andere tool verwendet. Anbieterbegriffe gehören in den Adapter.

Schritt 2: Pflichtfelder und Zustände festlegen

Definieren Sie Pflichtfelder, Typen und erlaubte Zustände. Schreiben Sie zusätzlich in die Beschreibung, wann ein Tool nicht verwendet werden darf. Das verbessert die Auswahlentscheidung des Modells, ersetzt aber nicht die technische Prüfung.

Schritt 3: Hauptschema validieren

Prüfen Sie das Hauptschema gegen den vorgesehenen JSON-Schema-Dialekt. Validieren Sie anschließend echte Beispieldaten. Ein Schema, das sich selbst validieren lässt, ist nicht automatisch fachlich sinnvoll.

Schritt 4: Anbieteradapter erzeugen

Erzeugen Sie für OpenAI, Gemini, Claude und MCP jeweils eine dokumentierte Variante. Entfernen Sie nur Regeln, die das Zielsystem nicht verarbeiten kann. Jede Entfernung muss in einer Konvertierungsdatei begründet werden.

Schritt 5: Positiv- und Negativfälle testen

Testen Sie mindestens:

• fehlendes Pflichtfeld,
• falscher Datentyp,
• ungültiger Enum-Wert,
• unbekanntes zusätzliches Feld,
• leeres Array,
• verschachtelte Referenz,
• gültige Struktur mit nicht existierender Ressource.

Der letzte Fall ist besonders wichtig. Er muss die Schema-Prüfung bestehen, aber später an der Geschäftsvalidierung scheitern.

Schritt 6: Modellantwort und Toolaufruf getrennt prüfen

Bei strukturierten Antworten prüfen Sie die Modellantwort. Bei Function Calling prüfen Sie die vom Modell erzeugten Argumente. Bei MCP prüfen Sie sowohl Eingabe als auch strukturiertes Ergebnis. Vermischen Sie diese drei Prüfstellen nicht in einem einzigen Parser.

Schritt 7: Regression in CI/CD ausführen

Lassen Sie bei jeder Schemaänderung alle Adapter und Beispieldaten prüfen. Dokumentieren Sie Modell- und API-Versionen mit dem Testlauf. Wenn ein Anbieter sein Teilset verändert, muss der Lauf fehlschlagen, bevor eine neue Version produktiv geht.

Welche Schema-Tests sollten Sie am 18.08.2026 mindestens wiederholen?

Für eine plattformübergreifende Prüfung sollten Sie ein Beispiel mit Objekt, Array, Enumeration, Referenz und zusätzlichen Eigenschaften verwenden. Notieren Sie den verwendeten Draft, das Modell, den API-Endpunkt und das Prüfdatum. Danach testen Sie die vier Zielpfade separat: strukturierte Ausgabe, Tool-Parameter, Claude-input_schema und MCP-inputSchema beziehungsweise outputSchema.

Die MCP-Dokumentation enthält außerdem einen Vorschlag zur stärkeren Ausrichtung auf JSON Schema 2020-12. Dieser Vorschlag ist nicht automatisch mit einer abgeschlossenen Spezifikationsänderung gleichzusetzen. Deshalb sollten Implementierungen stets zwischen aktuell verbindlicher Spezifikation und Entwurf unterscheiden (MCP SEP-2106).

Grenzen von JSON Schema

JSON Schema ist nicht der richtige Ort für jedes Problem. Folgende Regeln gehören meist in Anwendungscode oder eine Policy-Schicht:

• Ist der Benutzer berechtigt, das Tool aufzurufen?
• Existiert die angegebene Ressource wirklich?
• Gehört die Ressource zum Mandanten?
• Darf ein Status von approved zu cancelled wechseln?
• Ist der Betrag innerhalb des individuellen Kreditlimits?
• Ist die angeforderte Aktion idempotent?
• Muss vor der Ausführung eine menschliche Freigabe erfolgen?

Ein Schema kann einen Betrag als Zahl mit Mindest- und Höchstwert beschreiben. Es kennt aber ohne zusätzlichen Datenbankzugriff nicht das aktuelle Kreditlimit. Ein Schema kann eine E-Mail-Adresse formal beschreiben. Es beweist nicht, dass das Postfach existiert.

Für DSGVO-relevante Agenten sollten Sie außerdem Datenminimierung, Aufbewahrungsfristen und Zugriffskontrollen getrennt dokumentieren. Die Datenschutzinformationen von ZekVPS sind dafür ein sinnvoller Bezugspunkt, wenn Schema-Tests oder CI/CD-Läufe personenbezogene Testdaten verarbeiten.

Die passende Architekturentscheidung für Ihr Projekt

Verwenden Sie eine gemeinsame Hauptdefinition, wenn mehrere Modelle dasselbe Geschäftsobjekt verarbeiten. Verwenden Sie Anbieteradapter, wenn die Schnittstellen unterschiedliche Teilmengen oder Feldnamen verlangen. Validieren Sie immer an der Systemgrenze und führen Sie danach die fachliche Prüfung aus.

Für kleine Prototypen reicht ein einfaches Objekt mit type, properties und required. Für einen Produktions-Agenten benötigen Sie zusätzlich Versionsverwaltung, Negativtests, Berechtigungsprüfungen und eine Rückfallstrategie. Der entscheidende Qualitätsmaßstab ist nicht, ob ein Modell einmal korrektes JSON erzeugt. Entscheidend ist, ob eine Änderung an Modell, API oder MCP-Client frühzeitig einen reproduzierbaren Testfehler auslöst.

Wenn Ihre aktuelle Umgebung für solche Regressionen auf einem einzelnen lokalen Mac läuft, entstehen oft drei konkrete Nachteile: Der Rechner ist bei Wartung oder Abwesenheit nicht verfügbar, mehrere Entwickler teilen sich denselben Testknoten, und reproduzierbare macOS-spezifische CI/CD-Läufe benötigen zusätzlich Pflege für Updates, Zugänge und lokale Abhängigkeiten. Für kurzfristige Cross-Platform-Tests kann ein gemieteter Remote-Mac deshalb sinnvoller sein als der Kauf zusätzlicher Hardware. ZekVPS passt eher zu temporären Testfenstern und automatisierten Prüfungen; für dauerhaft hohe Last oder benötigte physische Schnittstellen bleibt eigene Hardware die bessere Wahl. Einen möglichen Einstieg bildet Mac mini in den USA Ost mieten.

Beginnen Sie mit dem Hauptschema, erzeugen Sie daraus geprüfte Anbieterprofile und speichern Sie jede Konvertierungsregel zusammen mit Modell, API-Version und Testdatum. Erst wenn diese Regressionen zuverlässig laufen, sollte ein Remote-Mac als zusätzlicher CI/CD-Ausführungsknoten bewertet werden.