Kompatibilität vom Verbraucher her definieren
Ob eine Änderung bricht, hängt davon ab, was bestehende Clients senden und lesen, nicht nur von der Schema-Gültigkeit. Unterstützte Clients, historische Datensätze und Rückrollfenster werden zuerst dokumentiert.
Neue Pflichtfelder, engere Typen oder entfernte Enum-Werte gefährden alte Produzenten. Auch optionale Felder können Clients mit strengem additionalProperties-Verhalten brechen.
- Produzenten und Verbraucher erfassen.
- Kompatibilitätsfenster datieren.
- Nicht allein auf Versionsnummern vertrauen.
Dokumente mit gleichem Umfang vergleichen
Altes und neues JSON Schema müssen dasselbe Wurzelobjekt beschreiben. OpenAPI-Dokumente stammen aus vergleichbaren Umgebungen; sonst entstehen Fehlalarme.
ByteQuant prüft direkte Felder, Pflichtstatus, Typen, Enums, Pfade, Methoden, Parameter und entfernte Antworten. Externe $ref und Bedingungen brauchen eine vollständige Auflösung.
Befunde mit anonymisierten Fixtures reproduzieren
Für jeden Befund werden kleinste nicht personenbezogene alte und neue Requests sowie Responses gespeichert. Fehlende Felder, unbekannte Enums, leere Arrays und große Payloads gehören neben den Normalfall.
Ein Struktur-Diff beweist kein Verhalten. Defaults, Fehlercodes, Sortierung, Pagination und Autorisierung werden in Vertragstests beobachtet.
Brüche in Migrationen übersetzen
Erforderliche Brüche beginnen mit einer Übergangsphase: neues Feld optional akzeptieren, Produzenten migrieren, Nutzung messen und erst danach erzwingen. Entfernte Pfade benötigen Überschneidung, Frist und Warnung.
Release Notes nennen Operation, altes und neues Verhalten, Migrationsbeispiel, Termin und Rückrollweg.
Release-Gate mit Nachweisen schließen
Lokale Vorprüfung, Fixtures, Verbrauchertests und Staging-Beobachtung werden in einem Datensatz verbunden. Freigabe und akzeptierte Risiken bleiben menschlich.
Nach dem Release werden Fehlerraten und Alt-Clients beobachtet. Sensible Payloads und Zugangsdaten gehören nicht in Berichte oder CI-Logs.
- Vorher/Nachher-Metriken verbinden.
- Rückrollkriterien vorab definieren.
- Synthetische Daten verwenden.
Werkzeuge für diesen Ablauf
Diese Werkzeuge liefern unterschiedliche Nachweise für dieselbe Entscheidung. Prüfen Sie jedes Ergebnis zusätzlich in der realen Umgebung, im Vertrag oder anhand einer maßgeblichen Quelle.
- JSON-Schema-Kompatibilitätsprüfung
- OpenAPI-Breaking-Change-Prüfung
- Struktureller JSON-Vergleich
- OpenAPI-Endpunktinventar
Den Ratgeber sicher ausprobieren
Testen Sie die Schritte aus „JSON-Schema- und OpenAPI-Verträge ohne Client-Brüche weiterentwickeln“ zuerst mit synthetischen Daten in JSON-Schema-Kompatibilitätsprüfung. Häkchen bleiben nur in diesem Tab.
Den Ratgeber in eine wiederholbare Prüfung überführen
Nutzen Sie diesen Prüfplan mit 4 Werkzeugen für „JSON-Schema- und OpenAPI-Verträge ohne Client-Brüche weiterentwickeln“. Ziel: Praxisleitfaden zur Prüfung von Pflichtfeldern, Typen, Enums, API-Pfaden, Parametern und Antworten in einem sicheren Release-Ablauf. Beginnen Sie mit einem sicheren Beispiel statt Echtdaten und dokumentieren Sie Sollergebnis und Abnahmeentscheidung jedes Schritts.
JSON-Schema-Kompatibilitätsprüfung
- Vorbereitung
- Altes Schema zuerst, neues Schema danach einfügen.
- Durchführung
- Strukturvergleich ausführen.
- Abnahmekontrolle
- Jeden Befund mit Fixtures und Verbrauchertests prüfen.
- Erwartete Ausgabe
- eine geparste Struktur, Feldkennzahlen und klare Syntaxbefunde. Findet strukturelle Änderungen zwischen zwei JSON-Schema-Versionen, die Verbraucher brechen können.
OpenAPI-Breaking-Change-Prüfung
- Vorbereitung
- Altes und neues OpenAPI-JSON einfügen.
- Durchführung
- Bruchkandidaten erzeugen.
- Abnahmekontrolle
- Mit Serververhalten, Requests und SDK-Tests bestätigen.
- Erwartete Ausgabe
- normalisierte Webkonfiguration, Komponentenübersicht und konkrete Prüfhilfen. Meldet entfernte Pfade, Methoden, Parameter und Antworten in zwei OpenAPI-JSON-Dokumenten.
Struktureller JSON-Vergleich
- Vorbereitung
- Syntaktisch gültiges JSON mit den vom Werkzeug genannten Objekten, Arrays oder Feldern Prüfen Sie das Format zuerst mit einem synthetischen Beispiel statt mit sensiblen Echtdaten.
- Durchführung
- Lokale Verarbeitung starten. Die Verarbeitung nutzt deterministische Regeln und erhält Feld- und Typgrenzen.
- Abnahmekontrolle
- Abnahmekriterium: Feldnamen, Werttypen, Escaping sowie Leer- und Nullwerte im Vergleich zur Quelle Prüfen Sie Schema, Kodierung und mögliche Datenverluste im Zielsystem.
- Erwartete Ausgabe
- eine geparste Struktur, Feldkennzahlen und klare Syntaxbefunde. Erkennen Sie hinzugefügte, entfernte und geänderte JSON-Pfade.
OpenAPI-Endpunktinventar
- Vorbereitung
- die vom Werkzeug verlangte URL, HTTP-Header, cURL-Anweisung, API-Definition oder Webkonfiguration Prüfen Sie das Format zuerst mit einem synthetischen Beispiel statt mit sensiblen Echtdaten.
- Durchführung
- Lokale Verarbeitung starten. Die Eingabe wird ohne Netzwerkanfrage geparst; Bestandteile und riskante Annahmen werden getrennt dargestellt.
- Abnahmekontrolle
- Abnahmekriterium: Vergleich mit aktuellem Standard und realem Serververhalten in einer autorisierten Testumgebung Prüfen Sie Schema, Kodierung und mögliche Datenverluste im Zielsystem.
- Erwartete Ausgabe
- normalisierte Webkonfiguration, Komponentenübersicht und konkrete Prüfhilfen. Methoden, Pfade, Tags und Sicherheit aus OpenAPI-JSON extrahieren.
Für JSON-Schema-Kompatibilitätsprüfung gilt folgende Grenze: Prüfen Sie Schema, Kodierung und mögliche Datenverluste im Zielsystem. Ist diese Bedingung nicht erfüllt, darf die Ausgabe nicht an den nächsten Arbeitsschritt übergeben werden.
Dokumentieren Sie für „JSON-Schema- und OpenAPI-Verträge ohne Client-Brüche weiterentwickeln“ Werkzeug, Einstellung, Browserversion und den Abnahme- oder Ablehnungsgrund für „API-Versionsprüfung — Findet strukturelle Änderungen zwischen zwei JSON-Schema-Versionen, die Verbraucher brechen können.“ – nicht den sensiblen Inhalt. So bleibt die Prüfung ohne Echtdaten wiederholbar.