Wie lässt sich die JSON-Schema-Modellkompatibilität 2026 abnehmen: Verwenden drei Modelle dieselbe Definition?

Die Antworten sehen formal korrekt aus, scheitern aber beim Anbieterwechsel an fehlenden Feldern, verworfenen Einschränkungen oder falschen Geschäftsbeziehungen.

Schnellste Lösung: Teilen Sie nur ein geprüftes Geschäfts-Kernschema, übersetzen Sie es je Anbieter über einen nachvollziehbaren Adapter und nehmen Sie Syntax sowie Geschäftssemantik mit derselben Testsuite getrennt ab.

Für wen diese Abnahme gedacht ist

Plattformingenieure brauchen eine klare Grenze zwischen dem gemeinsamen Schema und anbieterspezifischen API-Parametern. Testteams benötigen identische Eingaben, damit Ergebnisse nicht nur optisch, sondern reproduzierbar vergleichbar sind. Schemaautoren sollten unnötig tiefe Verschachtelungen und Erweiterungen vermeiden, die später stillschweigend entfallen könnten.

Warum ein gemeinsames JSON Schema nicht automatisch drei Schnittstellen abdeckt

JSON Schema ist zunächst eine standardisierte Sprache zur Beschreibung und Validierung von Daten. Die offizielle Übersicht führt mehrere Entwürfe und Vokabulare; daraus folgt nicht, dass jede Modell-API den vollständigen Standard akzeptiert. Besonders wichtig ist der Unterschied zwischen einem gültigen Schema nach der Norm und einem Schema, das ein konkreter Anbieter in einem bestimmten Ausgabemodus verarbeitet. Die offizielle JSON-Schema-Spezifikation ist deshalb der normative Ausgangspunkt, nicht die Zusage einer einzelnen Modellplattform.

Für die JSON-Schema-Modellkompatibilität entstehen in der Praxis mindestens fünf Begrenzungen:

Unterstützte Schlüsselwörter: Ein Anbieter kann nur einen Teil der Validierungslogik akzeptieren. Ein Schema mit Bedingungen, Referenzen oder komplexen Abhängigkeiten kann normgerecht sein und trotzdem bei einer API-Anfrage abgewiesen oder vereinfacht werden.
Strenge und Verpackung: Manche Schnittstellen erwarten das Schema in einem bestimmten Parameterobjekt, zusammen mit einem Namen oder einem Aktivierungsschalter für den strikten Modus. Diese Verpackung gehört nicht zur fachlichen Definition, ist aber für die Anfrage erforderlich.
Stille Bedeutungsverluste: Wird ein nicht unterstütztes Schlüsselwort automatisch entfernt, kann die Antwort zwar parsebar bleiben, aber eine vorherige Pflichtbedingung nicht mehr erfüllen. Das ist kein harmloses Kompatibilitätsdetail.
Unterschied zwischen Form und Inhalt: type, required und enum prüfen die Struktur. Sie beweisen nicht, dass eine Kundennummer existiert, eine Berechtigung vorliegt oder zwei Felder logisch zusammenpassen.
Operatives Risiko: Ein strukturell gültiges Werkzeugargument kann dennoch auf die falsche Ressource zeigen, außerhalb des erlaubten Mandanten liegen oder einen nicht idempotenten Vorgang auslösen.

Der Draft 2020-12 ist eine konkrete Spezifikationsfassung und sollte im Repository ausdrücklich festgehalten werden; die Dokumentation zu Draft 2020-12 beschreibt die dazugehörige Struktur. Für die Abnahme genügt es daher nicht, „JSON Schema“ als Versionsangabe zu verwenden. Jede Testakte braucht mindestens den verwendeten Entwurf, die Anbieter-API und die Modell- oder Endpunktversion.

Kann dieselbe Schema-Datei unverändert für alle drei Modelle verwendet werden?
Nur dann, wenn alle drei dokumentierten Schnittstellen genau die verwendeten Schlüsselwörter, Datentypen, Referenzen, Striktheitsregeln und Verpackungsanforderungen akzeptieren. Diese Annahme darf nicht aus ähnlichen Beispielen abgeleitet werden. Für ein Plattformteam ist ein gemeinsames fachliches Kernschema realistisch; eine unveränderte Rohdatei als universelle API-Datei ist dagegen keine belastbare Freigabestrategie.

Erster Schritt: Den fachlichen Kern auf ein überprüfbares Subset begrenzen

Die Schemaautoren sollten zuerst entscheiden, welche Einschränkungen wirklich Geschäftsrisiken verhindern. Ein kleines, bewusstes Kernschema ist nicht dasselbe wie ein schwaches Schema. Es ist eine portable Definition, deren Regeln später nicht unbemerkt verschwinden.

Die folgende Checkliste gehört in den Pull Request des Schemas:

[ ] Spezifikationsentwurf und $schema-Kennzeichnung sind festgelegt.
[ ] Für jedes Objekt ist dokumentiert, ob unbekannte Eigenschaften erlaubt oder verboten sind.
[ ] Alle für die Weiterverarbeitung notwendigen Felder stehen in required.
[ ] Jeder Datentyp ist fachlich begründet und nicht nur aus einem Beispiel übernommen.
[ ] enum wird nur für tatsächlich geschlossene Wertebereiche eingesetzt.
[ ] Array-Elemente besitzen eine eindeutige Struktur und eine definierte Reihenfolge, sofern diese relevant ist.
[ ] $ref-Verweise sind auflösbar, versioniert und für den jeweiligen Anbieteradapter abbildbar.
[ ] additionalProperties wird bewusst verwendet und nicht automatisch überall verboten.
[ ] Beziehungen zwischen Feldern, etwa „Enddatum darf nicht vor Startdatum liegen“, sind zusätzlich als Geschäftsregel dokumentiert.
[ ] Ein Beispiel mit gültigem und ein Beispiel mit absichtlich ungültigem Inhalt liegt vor.

Die Erklärung zum Validierungsablauf eines JSON-Schema-Validators hilft bei der Trennung von Schemafehlern und Datenfehlern. Für die Modellabnahme ist außerdem festzuhalten, ob ein Fehler vor der Modellgenerierung, in der generierten Antwort oder erst im nachgelagerten Validator entsteht.

Unterstützen die drei großen Modell-APIs das vollständige JSON Schema 2020-12?
Eine allgemeine Zusage sollte nicht in den Testplan aufgenommen werden. Die jeweilige Plattformdokumentation beschreibt ihren unterstützten Ausschnitt und ihre Einschränkungen. Das OpenAI Structured Outputs-Handbuch ist deshalb getrennt von der JSON-Schema-Norm zu lesen. Gleiches gilt für die Gemini-Dokumentation zu strukturierten Ausgaben. Für Claude muss das Team die dokumentierte Werkzeug- und Eingabeverarbeitung prüfen; die offizielle Übersicht zur Tool-Nutzung ist dafür die maßgebliche Referenz.

Zweiter Schritt: Für jede API einen sichtbaren Adapter bauen

Ein Adapter darf nicht einfach „kompatibel machen“, indem er unbekannte Schlüssel löscht. Er muss aus dem Kernschema eine Anbieterdefinition erzeugen und dabei jeden Eingriff protokollieren.

Eine belastbare Adapterpipeline besteht aus fünf Operationen:

Kernschema laden: Der Adapter liest eine festgelegte Schema-Version aus dem Repository, nicht eine dynamische Datei aus einem Arbeitsverzeichnis.
Unterstützung prüfen: Jedes verwendete Schlüsselwort wird gegen eine versionierte Support-Matrix geprüft. „Nicht dokumentiert“ wird als ungeklärt behandelt, nicht als unterstützt.
API-Verpackung erzeugen: Name, Parameterpfad, strikter Modus und sonstige Anfrageoptionen werden in der jeweiligen Form ergänzt. Das fachliche Schema bleibt davon getrennt.
Transformation diffen: Entfernte, umbenannte oder vereinfachte Regeln erscheinen in einer maschinenlesbaren Änderungsdatei. Ein semantisch wichtiger Verlust blockiert den Build.
Ausgabe zurückvalidieren: Die tatsächliche Modellantwort wird gegen das Anbieter- beziehungsweise Kernschema geprüft. Ein HTTP-Erfolg gilt nicht als fachlicher Erfolg.

Die OpenAI-API-Referenz beschreibt die konkreten Anfrage- und Antwortfelder der Schnittstelle und sollte mit der Structured-Outputs-Anleitung gemeinsam versioniert werden: OpenAI API Reference. Die Gemini-API-Referenz ist entsprechend für die Erzeugung von Inhalten und die tatsächliche Parameterstruktur heranzuziehen: Gemini Generate-Content-Referenz.

Welche Schema-Schreibweisen werden von Structured Outputs typischerweise zum Problem?
Das lässt sich nur je Anbieter und Schnittstellenmodus entscheiden. Besonders kritisch sind nicht dokumentierte Schlüsselwörter, komplexe Verzweigungen, unaufgelöste $ref-Ketten, rekursive Strukturen und Regeln, die zwar im Standard existieren, aber nicht im jeweiligen Ausgabemodus akzeptiert werden. Der Adapter muss solche Fälle entweder fachlich gleichwertig umformen oder ablehnen. Ein automatisches Weglassen ohne Warnung ist eine Sperrbedingung.

Ein gutes Transformationsergebnis enthält daher nicht nur die erzeugte Anbieterdatei, sondern auch:

die Quellversion des Kernschemas,
die Ziel-API und den Zielmodus,
die Liste unterstützter und nicht unterstützter Schlüsselwörter,
jede entfernte oder veränderte Einschränkung,
die Begründung für eine zulässige Vereinfachung,
einen Verweis auf die Tests, die danach erfolgreich waren.

Dritter Schritt: Eine gemeinsame Testmatrix für alle Modelle ausführen

Die Testteams sollten nicht drei voneinander abweichende Beispieldateien pflegen. Ein kanonischer Eingabesatz wird unverändert an jeden Adapter und jede API gegeben. Unterschiede in der Modellantwort werden danach klassifiziert.

Mindestens diese Testklassen gehören in die Matrix:

Normalfall: Alle Pflichtfelder sind vorhanden und fachlich plausibel.
Fehlendes Pflichtfeld: Ein notwendiges Feld wird entfernt. Der Test prüft, ob die Antwort abgelehnt, repariert oder fälschlich akzeptiert wird.
Falscher Datentyp: Eine Zahl wird als Text, ein Objekt als Liste oder ein geschlossener Wert außerhalb des enum übergeben.
Unbekannte Eigenschaft: Ein zusätzliches Feld wird eingefügt. Das Team dokumentiert, ob es abgewiesen, ignoriert oder ausgegeben wird.
Tiefe Verschachtelung: Ein realistisch verschachteltes Objekt prüft, ob Referenzen und Unterobjekte vollständig erhalten bleiben.
Große Eingabe: Ein langer, aber fachlich zulässiger Inhalt prüft Abschneiden, unvollständige JSON-Ausgabe und Grenzfälle der Verarbeitung.
Mehrdeutige Anweisung: Der Inhalt versucht, das Ausgabeformat zu verändern oder Pflichtfelder zu umgehen.
Wiederholung: Derselbe Test wird mit identischer Anfrage wiederholt, um sporadische Parser- und Toolfehler sichtbar zu machen.

Für jeden Lauf werden Request-Kennung, API-Version, Modellbezeichnung, Schema-Version, Adapterversion, HTTP-Status, Rohantwort, Parse-Ergebnis und Validierungsfehler gespeichert. Ohne diese Metadaten kann ein späterer grüner Lauf nicht beweisen, dass dieselbe technische Konfiguration getestet wurde.

Die Testauswertung sollte drei Ebenen getrennt ausweisen:

Transport: Wurde die Anfrage vom Dienst angenommen?
Syntax: Ist die Antwort gültiges JSON und entspricht sie dem vereinbarten Schema?
Semantik: Sind Werte, Beziehungen und Berechtigungen fachlich korrekt?

Wie lässt sich die Prüfung über mehrere Modelle automatisieren?
Ein zentraler Test-Runner ruft pro Fall einen Anbieteradapter auf, normalisiert nur technische Hüllen und übergibt danach dieselbe Antwortprüfung. Er darf nicht Unterschiede in Feldern oder Fehlern „weg-normalisieren“. Ein fehlendes Feld bleibt ein fehlendes Feld. Der Bericht markiert zusätzlich, ob der Fehler im Adapter, beim Dienst, im Parser oder in der Geschäftsvalidierung entstand.

Für OpenAI Structured Outputs, Gemini Structured Output und Claude Structured Outputs sollten deshalb getrennte Ergebnisfelder geführt werden, auch wenn die Geschäftserwartung identisch ist. So bleibt sichtbar, ob ein Anbieter die Anfrage ablehnt, ein Modell eine andere Form produziert oder der nachgelagerte Validator eine fachliche Unstimmigkeit findet.

Vierter Schritt: Agenten und Werkzeuge unabhängig vom Schema absichern

Ein Modell darf niemals allein deshalb eine Aktion auslösen, weil seine Argumente formal zum Schema passen. Bei Tool Calling beschreibt das Schema die Form der Parameter; die Autorisierung muss außerhalb der Modellantwort durchgesetzt werden.

Die Agentenverantwortlichen prüfen vor einer Ausführung:

[ ] Die Identität des aufrufenden Dienstes ist serverseitig bekannt.
[ ] Der Ressourcenbezeichner wird gegen den richtigen Mandanten und die erlaubte Umgebung geprüft.
[ ] Schreib-, Lösch- und Geldbewegungsaktionen benötigen eine eigene Berechtigung.
[ ] Ein Idempotenzschlüssel verhindert ungewollte Wiederholungen.
[ ] Zeit-, Mengen- und Kostenlimits werden unabhängig vom Modellwert kontrolliert.
[ ] Sensible Daten werden vor Protokollierung und Weitergabe minimiert.
[ ] Eine riskante Aktion kann in einen Prüf- oder Freigabeschritt umgeleitet werden.
[ ] Fehler und Rückgaben des Tools werden nicht ungeprüft als Tatsachen in den nächsten Modellschritt übernommen.

Diese Grenze ist besonders relevant, wenn das Schema Felder wie user_id, account_id, path, amount oder operation enthält. Ein korrektes Format verhindert weder eine fremde Kontonummer noch einen gültigen, aber unzulässigen Dateipfad. Der Ausführer muss solche Werte aus einer vertrauenswürdigen Sitzung ableiten oder gegen eine serverseitige Policy prüfen.

Fünfter Schritt: Die fachliche Bedeutung hinter der Form abnehmen

Die Verbraucher der Ausgabe, etwa Datenbanken, Abrechnungssysteme oder Benutzeroberflächen, übernehmen die letzte Verantwortung. Ein Schema kann eine Zeichenkette verlangen, aber nicht feststellen, ob diese Zeichenkette eine reale Bestellung beschreibt. Es kann ein Datum erzwingen, aber nicht automatisch die zeitliche Beziehung zweier Daten bewerten.

Dafür braucht die Pipeline zusätzliche Regeln:

Datenbank-Constraints prüfen Eindeutigkeit, Fremdschlüssel und zulässige Zustände.
Fachliche Validatoren prüfen Beziehungen zwischen Feldern.
Faktenprüfungen gleichen externe oder interne Quellen ab.
Unsichere Modellantworten werden als Prüfstatus gespeichert, nicht als bestätigte Tatsachen.
Ein erfolgreiches Parsing wird nicht mit einer erfolgreichen Geschäftsaktion gleichgesetzt.

Warum entstehen trotz Schema-konformer Antworten falsche Daten?
Weil Strukturvalidierung und Wahrheitsprüfung unterschiedliche Aufgaben haben. Eine Antwort kann alle Pflichtfelder, Datentypen und Enumerationswerte erfüllen und trotzdem einen falschen Kunden, eine erfundene Begründung oder eine unpassende Zuordnung enthalten. Die Abnahme muss deshalb mindestens einen fachlichen Erwartungswert oder eine prüfbare Referenz für kritische Felder enthalten.

So fällt die Freigabeentscheidung

Die Entscheidung sollte nicht aus einem Gesamtscore bestehen, der einen kritischen Fehler durch viele harmlose Erfolge verdeckt. Für jedes Schema werden harte Sperrbedingungen und nachrangige Qualitätsmängel getrennt dokumentiert.

Wenn alle folgenden Bedingungen erfüllt sind, wird das gemeinsame Kernschema freigegeben:

Die normative Version ist festgelegt.
Jeder Anbieteradapter erzeugt eine nachvollziehbare Zieldefinition.
Keine geschäftskritische Einschränkung wird still entfernt.
Alle Pflicht-, Typ-, Enumerations- und Referenztests laufen erfolgreich.
Tool- und Berechtigungsprüfungen liegen außerhalb des Modells.
Die semantischen Verbraucherprüfungen sind erfolgreich.
Schema-Version, API-Version, Adapterversion und Samplesatz sind im Bericht eingefroren.

Wenn nur die Syntax zwischen den Anbietern stabil ist, aber einzelne Schlüsselwörter fehlen, wird ein anbieterspezifisches Schema verwendet. Das gemeinsame Kernschema bleibt die fachliche Quelle, während die Zieldefinition dokumentiert abweicht. Der Bericht muss die Abweichung und ihre Auswirkung auf die Geschäftslogik enthalten.

Wenn die Anbieter unterschiedliche Geschäftssemantik erzeugen, wird der Workflow aufgeteilt. Das ist etwa erforderlich, wenn ein Modell die gewünschte Beziehung nicht zuverlässig abbildet, ein Tool-Aufruf nicht sicher begrenzbar ist oder eine Vereinfachung die Datenbankregeln verletzt. Ein geteilter Workflow ist besser als eine scheinbar einheitliche Schnittstelle mit unbemerkten Fehlentscheidungen.

Die Abnahmeakte vor dem Go-live

Eine feste Akte macht spätere Regressionen überprüfbar. Sie sollte nicht nur den zuletzt erfolgreichen Lauf enthalten, sondern die technische Ausgangslage dauerhaft beschreiben.

Prüfbestandteil	Muss im Bericht stehen	Blockiert die Freigabe bei
Schemaquelle	Version, Entwurf, Hash und aufgelöste Referenzen	unklarer oder wechselnder Quelle
Anbieteradapter	Ziel-API, Modell, Verpackung und Transformations-Diff	still gelöschten Geschäftsregeln
Samplesatz	normale, fehlerhafte und sicherheitsrelevante Fälle	fehlenden Negativtests
Laufdaten	Anfrageversion, Status, Rohantwort und Parsergebnis	nicht reproduzierbaren Ergebnissen
Geschäftsprüfung	Feldbeziehungen, Fakten- und Datenbankregeln	rein struktureller Prüfung
Agentensicherheit	Berechtigung, Ressource, Idempotenz und Limits	direkter Ausführung nur nach Modelloutput
Entscheidung	gemeinsam, anbieterspezifisch oder geteilter Workflow	fehlender Begründung

Für Teams, die diese Läufe parallel auf mehreren Entwicklungsumgebungen ausführen, ist die Umgebung selbst ein Teil der Testakte. Betriebssystem, Laufzeit, Parserbibliothek und Zugangskonfiguration müssen reproduzierbar sein; besonders bei CI/CD-Tests mit Remote-Zugriff sollten Sitzungsdaten und Zugangsdaten getrennt von den Testartefakten verwaltet werden. Hinweise zu Erreichbarkeit und Support lassen sich im Vuncloud Hilfe-Center nachlesen.

Aktuelle Schnittstelle oder gemietete Mac-Testumgebung?

Eine rein lokale Testumgebung bleibt für langfristige, konstante Lasten und den Zugriff auf physische Schnittstellen sinnvoll. Ein wechselnder Pool eigener Geräte verursacht jedoch Wartung, Betriebssystemwechsel, belegte Arbeitsplätze und schwer vergleichbare Ausgangszustände. Eine gewöhnliche Cloud-VM bildet zudem nicht jede Mac-spezifische Laufzeit oder Integrationsprüfung ab. Für Teams, die nur für Abnahmeläufe, parallele CI/CD-Jobs oder zeitlich begrenzte Cross-Model-Tests eine reproduzierbare Umgebung benötigen, kann das Mieten eines Mac mini bei Vuncloud die planbarere Option sein: Die Testfälle bleiben getrennt vom Arbeitsplatz, mehrere Mitarbeitende können dieselbe Umgebung nutzen, und der Aufwand für Anschaffung und Gerätewechsel sinkt. Vor einer Entscheidung sollten Datenschutz, Zugriffsmodell, Sitzungsdauer und Anforderungen an physische Anschlüsse geprüft werden; für dauerhafte Hochlast ist der eigene Mac weiterhin die ehrlichere Wahl.