JSON formatieren, validieren und mit Schema prüfen in der Praxis

Veröffentlicht am 2026-04-13 8 Min. Lesezeit

Zusammenfassung (TL;DR)

Ein Team, mit dem ich letzten Monat gearbeitet habe, hat eine einzeilige Änderung an feature_flags.json ausgeliefert. JSON.parse akzeptierte sie, die CI war grün, und sobald sie Staging erreichte, fiel jede Checkout-Variante auf den Legacy-Pfad zurück, weil flags.checkout_v2 der String "true" war statt des Booleans true. „JSON prüfen” war im Stillen zu drei verschiedenen Tätigkeiten geworden, und das Team hatte nur die ersten beiden erledigt. Pretty-Printing formt den Whitespace um, damit ein Mensch ein Blob lesen kann; es verifiziert nichts. Syntaxvalidierung bestätigt, dass ein String gemäß RFC 8259 parsebares JSON ist – passende Klammern, korrekte Anführungszeichen, gültige Zahlen-Literale – und genau das tut JSON.parse. Strukturelle Validierung ist ein eigener Schritt, der fragt, ob der geparste Wert die Form hat, die dein Programm erwartet: erforderliche Felder, korrekte Typen, erlaubte Enum-Werte, Stringlängen, Zahlenbereiche. Dieser letzte Schritt ist genau das, wofür JSON Schema gebaut wurde, und er ist derjenige, den die meisten Teams überspringen, bis ein Produktions-Bug wie der oben genannte sie zwingt, ihn einzubauen. Eine verlässliche Pipeline nutzt alle drei Layer an passender Stelle: formatieren, wenn du die Daten lesen willst, parsen, um fehlformatierte Eingaben abzufangen, und eine Ajv-artige Schemaprüfung an Vertrauensgrenzen laufen lassen – eingehende API-Anfragen, Konfigurationsdateien und Cross-Service-Nachrichten.

Hintergrund und Konzepte

JSON ist durch RFC 8259 (und das äquivalente ECMA-404) definiert. Die Grammatik ist absichtlich klein. Ein JSON-Dokument ist eines von: String, Zahl, true, false, null, Array oder Objekt. Strings sind in doppelte Anführungszeichen gesetzt und unterstützen eine kurze Liste von Escapes, darunter \n, \t, \", \\ und \uXXXX für Unicode-Code-Units. Zahlen folgen einer Dezimalgrammatik mit optionalem Vorzeichen, Bruchteil und Exponent, doch syntaktisch gibt es keinen Unterschied zwischen Ganzzahl und Gleitkomma. Objekte sind ungeordnete Sammlungen von stringbeschlüsselten Mitgliedern, Arrays sind geordnete Listen, und Whitespace außerhalb von Strings ist bedeutungslos.

Was JSON bewusst nicht enthält, ist fast ebenso wichtig. Es gibt keine Kommentare, keine abschließenden Kommata, keine einfachen Anführungszeichen und keine Hex- oder Binär-Literale. Unicode-Zeichen außerhalb des ASCII-Bereichs müssen entweder als rohe UTF-8-Bytes im kodierten Stream oder als \u-Escapes erscheinen. Erweiterungen wie JSON5 und HJSON lockern einige dieser Regeln, sind aber eigenständige Formate, und Parser, die striktes JSON akzeptieren, lehnen sie ab.

Ist ein Dokument einmal geparst, sagt seine syntaktische Gültigkeit nichts darüber aus, ob es die richtigen Daten sind. Eine Login-Payload wie {"user": "x", "pass": "y"} ist perfekt gültiges JSON, auch wenn dein Endpunkt {"username": "...", "password": "..."} erwartete. Um diese Klasse von Fehlern zu fangen, brauchst du ein Schema: eine maschinenlesbare Beschreibung dessen, was als akzeptables Dokument zählt. JSON Schema (die aktuell empfohlene Meta-Schema-Version ist Draft 2020-12) schließt diese Lücke. Es unterstützt erforderliche Felder, Typconstraints, enum und const, Stringmuster via Regex, Zahlenbereiche, Array-items und Eindeutigkeit, Objekt-properties und additionalProperties sowie Komposition via allOf, oneOf, anyOf und $ref. Ajv 8.12 kompiliert ein Schema einmal in eine JavaScript-Validator-Funktion, die schnell genug für Hot Paths ist – in einem Node-20.11-Service, den ich instrumentiert habe, lag ein kompilierter Ajv-Check gegen einen typischen Request-Body im zweistelligen Mikrosekundenbereich.

Pretty-Printing ist der alltäglichste der drei. Es fügt nur Whitespace ein – Einrückung und Zeilenumbrüche – ohne die Bedeutung zu ändern. Die meisten Editoren und Command-Line-Tools beherrschen es; Browser-DevTools tun es im Netzwerkpanel automatisch. Für Menschen nützlich, für Maschinen irrelevant.

Vergleich und Daten

AspektPretty-PrintingSyntaxvalidierungJSON-Schema-Validierung
ZweckDaten lesbar machenSicherstellen, dass der Text als JSON parstSicherstellen, dass geparste Daten einer erwarteten Form entsprechen
ErkenntNichts – nur WhitespaceNicht passende Klammern, falsche Anführungszeichen, ungültige Escapes, abschließende KommataFehlende Felder, falsche Typen, Werte außerhalb des Bereichs, unbekannte Schlüssel
Erkennt nichtStrukturelle Probleme, semantische ProblemeStrukturelle Probleme (erwartete Form), GeschäftsregelnSemantische Regeln jenseits des Schemas, feldübergreifende Invarianten ohne Custom Keywords
Typisches ToolingJSON.stringify(obj, null, 2), jq, IDE-FormatterJSON.parse, jq -e, beliebiger ParserAjv 8.x, python-jsonschema, OpenAPI-Validatoren
Wo anwendenEntwicklertools, LogsAn jeder Parse-Grenze (implizit)An API-Request/Response, Config-Load, Nachrichtengrenzen

Die drei Spalten sind keine Alternativen, sondern sequentielle Schichten. Eine 12 MB schwere einzeilige package-lock.json in einem rohen Editor zu öffnen, führt dazu, dass dein Diff-Tool den String nicht mehr vergleichen will, und das Prettyfizieren in eine eingerückte Form validiert nichts – es macht die Form nur lesbar. Diese Unterscheidung ist wichtig, weil die nächsten beiden Schichten, Syntax und Schema, oft mit „ich habe es pretty-printed und nichts ist explodiert” verwechselt werden. Formatiere, um zu lesen, parse, um Fehlformatierung zu fangen, und validiere mit einem Schema, um falsche Formen zu fangen. Nur die ersten beiden auszuliefern, ist eine häufige Lücke.

Praxisszenarien

Szenario 1 – Eine API-Antwort debuggen. Ein externes Zahlungsgateway liefert einen 600-zeiligen JSON-Body, und der Browser zeigt ihn in einer einzigen Zeile. Ihn hübsch zu formatieren – per Browser-DevTools, lokalem Formatter oder curl ... | jq . – macht ihn überflogenlesbar. Hier findet keine Validierung statt; das Ziel ist Lesbarkeit, während du nach dem Feld jagst, das falsch aussieht, und die wichtige Disziplin ist, diesen Schritt nicht „validiert” zu nennen.

Szenario 2 – Eine Konfigurationsdatei laden. Ein Service liest beim Start config.json. Ein strikter JSON-Parser fängt Syntaxfehler wie ein streunendes abschließendes Komma ab und weigert sich zu starten, was das richtige Verhalten ist. Doch wie der Eingangsvorfall zeigte, parst eine gültige Datei mit retries: "three" statt retries: 3 anstandslos und scheitert erst, wenn der Code einen String mit einer Zahl vergleicht. Das Muster, das für mich funktioniert hat, ist, Ajv.compile(schema)(config) in die allerersten Zeilen des Einstiegspunkts zu setzen und bei Fehlschlag process.exit(1) aufzurufen – eine fünfminütige Änderung, die sich bei den nächsten zwei Malen, wenn jemand die Datei von Hand bearbeitete, ausgezahlt hat.

Szenario 3 – Einen OpenAPI-Vertrag prüfen. Ein Team liefert ein OpenAPI-3.1-Dokument, das Endpunkte, Request-Bodys und Response-Formen unter components.schemas beschreibt. Vertragstests nehmen die Beispiel-Payloads aus der Spezifikation und validieren sie mit einem JSON-Schema-Validator gegen die Schemata. Wenn eine Server-Implementierung driftet – etwa eine Ganzzahl zurückgibt, wo die Spezifikation einen String versprach – meldet der Vertragstest den Unterschied, bevor ein Client in Produktion bricht. Dieselbe JSON-Schema-Engine, die du auch für eine einsame Config-Datei nutzen würdest; der Unterschied ist der Umfang der Abdeckung.

Häufige Missverständnisse

„JSON.parse reicht zur Validierung.” Es validiert Syntax, nicht Form. Ein Parser gibt fröhlich ein Objekt zurück, dem die Hälfte der Felder fehlt, die dein Code braucht. Behandle JSON.parse als Gate gegen fehlformatierten Text und lege an der Vertrauensgrenze eine Schemaprüfung darüber.

„JSON Schema ist nur serverseitig.” Im Browser zu validieren, bevor ein Request rausgeht, liefert Nutzer:innen sofortiges Feedback und reduziert Serverlast. Viele Formularbibliotheken und Ajv selbst laufen bequem im Browser. Serverseitige Validierung muss trotzdem laufen – traue dem Client nie – doch Client-seitige Checks verbessern UX, ohne das Sicherheitsmodell zu schwächen.

„JSON5 ist einfach JSON mit Kommentaren.” JSON5 ergänzt Kommentare, unquotierte Schlüssel, abschließende Kommata, Hex-Zahlen und mehr. Das macht es freundlicher als menschlich editiertes Config-Format – der bekannteste Konsument ist tsconfig.json, das eigentlich JSONC verwendet (ein anderer nicht-standardisierter Superset) – aber alles, was streng RFC 8259 folgt, akzeptiert es nicht. Nutze JSON5/JSONC, wo der Konsument Unterstützung dokumentiert; emittiere striktes JSON, wenn du ins Netzwerk schreibst oder an ein Tool, dessen Parser du nicht kontrollierst.

„YAML ist einfach JSON mit Einrückung.” Jedes gültige JSON-Dokument ist gültiges YAML, doch YAML fügt Features hinzu – Anchors und Aliases, getaggte Typen, mehrere Dokumente pro Datei, Block- und Folded-Skalare, einrückungssensitives Parsen – die Bugs einführen, die JSON nicht hat. Der Klassiker ist das sogenannte „Norway-Problem”: YAML 1.1 interpretiert NO als den Boolean false, sofern du es nicht quotest. Der Wechsel von JSON zu YAML, „um es lesbar zu machen”, tauscht eine Klasse von Problemen gegen eine andere ein.

Checkliste

  1. Willst du die Daten nur lesen? Pretty-print sie. Behaupte nicht, sie seien „validiert”.
  2. Überschreiten sie eine Vertrauensgrenze (HTTP-Request, Message Queue, Konfigurationsdatei)? Parse und führe dann eine JSON-Schema-Prüfung aus, nicht nur ein Parse.
  3. Kümmern dich unbekannte Felder? Setze additionalProperties: false im Schema und entscheide, ob du Extras ablehnst oder strippst.
  4. Sind die Fehler handlungsfähig? Konfiguriere den Validator (zum Beispiel Ajv mit allErrors: true), damit alle Verstöße zurückgegeben werden und Nutzer:innen sämtliche Probleme auf einmal sehen.
  5. Lebt das Schema neben dem Code, der die Daten nutzt? Drift zwischen Spezifikation und Implementierung ist leichter zu verhindern, wenn das Schema für beide die Quelle der Wahrheit ist.
  6. Ist das Format stabil genug für JSON? Wenn Menschen es bearbeiten müssen und du den Parser kontrollierst, sind JSON5/JSONC oder TOML nachgiebiger. Wenn Maschinen es austauschen, bleibe bei striktem JSON.

Verwandtes Tool

Der JSON-Formatter von Patrache Studio läuft im Browser, sodass die eingefügte Payload deine Maschine nie verlässt – nützlich, wenn du eine Produktionsantwort mit personenbezogenen Daten untersuchst. Payloads leben selten allein: Enthält das formatierte JSON ein eingebettetes Binary, erklären die Regeln in Base64 und URL-Kodierung: Zweck, Fallen, richtiger Einsatz, warum das Blob wächst und wann ein anderer Transport passender ist. Enthält die Payload IDs, behandelt UUID v1 vs. v4 vs. v7: Einen DB-Primärschlüssel wählen, warum die exakte Version, die du serverseitig erzeugst, Einfluss darauf hat, wie nachgelagerte Systeme das JSON indizieren, sortieren und cachen.

Quellen

Verwandtes Werkzeug

devtools.patrache.studio/json/formatter/