JSON-Fehler Schritt für Schritt diagnostizieren

JSON wirkt einfach, weil es wenige Datentypen und vertraute Satzzeichen besitzt. Gerade deshalb erreicht ein kleiner Fehler ein Werkzeug oft als wenig hilfreiche Meldung: ein unerwartetes Komma, eine Position oder ein „ungültiges Token“. Das Ziel ist nicht, Änderungen zu raten, bis das Dokument nicht mehr fehlschlägt. Reduziere den Fall, finde die gemeldete Position, korrigiere grammatikgerecht und prüfe, ob die Daten weiterhin dasselbe bedeuten.

RFC 8259 beschreibt JSON als Datenaustauschformat mit Objekten, Arrays, Zahlen, Zeichenketten, Wahrheitswerten und null. Namen in einem Objekt sind Zeichenketten in doppelten Anführungszeichen. Eine Zeichenkette darf keinen echten Zeilenumbruch enthalten. Kommata trennen Werte; sie schließen keine Liste mit einem zusätzlichen Trennzeichen. Diese strengen Regeln sorgen dafür, dass verschiedene Programme ein Dokument gleich auslegen.

Ein Parser prüft Syntax, nicht Absicht. Er kann zeigen, wo er den Text nicht mehr versteht, aber nicht, ob zwei unterschiedlich benannte Felder denselben Preis meinen, ob eine Kennung führende Nullen verloren hat oder ob ein Datum die richtige Zeitzone trägt. Trenne den Fehler, der JSON unlesbar macht, von einem semantischen Problem, das nach dem Formatieren bleibt.

Ein vollständiges reproduzierbares Beispiel

Beginne mit einer kleinen Kopie ohne echte Geheimnisse. Diese Nutzlast enthält vier häufige Probleme. Die Reihenfolge ist wichtig: Ein Parser meldet normalerweise das erste Hindernis und versteckt weitere, bis dieses behoben ist.

{
  "customer": "Ada",
  "items": ["notebook", "pen",],
  "note": "Deliver before
Friday",
  'orderId': "007",
  "total": 24.90,
  "amount": 24.90
}

Das Komma nach "pen" steht am Ende. Der Umbruch zwischen before und Friday liegt unmaskiert in einer Zeichenkette. orderId verwendet einfache Anführungszeichen; das ist in manchen JavaScript-Kontexten erlaubt, aber nicht in JSON. total und amount sind dagegen syntaktisch gültig, obwohl sie möglicherweise denselben Betrag beschreiben. Diese letzte Frage verlangt Kenntnis des API-Vertrags.

Eine Parserposition lesen

Fehler von JSON.parse() nennen je nach Engine und Browser Position, Zeile oder Spalte. Zähle ab dem Beginn der exakt übergebenen Eingabe, einschließlich Leerzeichen und Umbrüchen. Die Position ist nicht zwingend die Ursache. Sie bezeichnet oft das Zeichen, an dem die Grammatik nicht weitergehen kann. Ein Endkomma kann bei ] auffallen; eine unmaskierte Zeichenkette beim Zeilenumbruch.

Verwende einen Editor mit Zeilen- und Spaltenanzeige. Kopiere Text ohne Anführungszeichen umzuwandeln und vermeide Anwendungen, die Leerzeichen ergänzen. Bei einer absoluten Position betrachte etwa zwanzig Zeichen davor und danach. Bei einer Zeilennummer prüfe auch die vorherige Zeile: Ein Begrenzer wird häufig geöffnet, bevor das Symptom sichtbar wird.

Die praktische Aufgabe besteht darin, eine unlesbare Nutzlast von einer gültigen, aber fachlich falschen zu unterscheiden. Ein Formatter funktioniert erst bei korrekter Grammatik. Stammt das Dokument aus Log, Umgebungsvariable oder HTTP-Antwort, bewahre zunächst das Original und die Quelle auf. Ersetze Werte nicht blind: Eine Fehlerbehebung kann Signatur, Prüfsumme oder Kennung verändern. Reduziere die Probe auf den reproduzierenden Block und entferne personenbezogene Daten vor dem Teilen.

Untersuche das Beispiel in vier Durchgängen. Erstens: Bei items trennt das Komma unmittelbar vor ] keinen weiteren Wert und muss weg. Zweitens: In note wird der Umbruch als Backslash und n geschrieben, nicht als physischer Umbruch. Drittens: Ersetze die einfachen Anführungszeichen des Schlüssels durch doppelte. Viertens: Frage den Produzenten, ob total und amount unterschiedliche Konzepte sind. Sind sie derselbe Betrag, behalte den festgelegten Namen und dokumentiere die Migration.

{
  "customer": "Ada",
  "items": ["notebook", "pen"],
  "note": "Deliver before\nFriday",
  "orderId": "007",
  "total": 24.90
}

Das korrigierte JSON lässt sich parsen, erhält orderId als Zeichenkette und kodiert den Umbruch portabel. Wandle "007" nicht nur wegen seines Aussehens in eine Zahl um: Codes und Referenzen sind keine Mengen.

Führe den Parser zuerst in der Umgebung aus, die fehlgeschlagen ist. Notiere Meldung und Position, bevor du Text umschreibst. Prüfe eine Kopie mit einem Formatter; ändert sich die Meldung, wurde die Eingabe vielleicht normalisiert. Korrigiere genau einen Syntaxfehler, parse erneut und wiederhole. Vergleiche bei gültigem Ergebnis Schlüssel, Typen, Längen und wichtige Werte mit einer bekannten Probe. Für eine API vergleiche zusätzlich Schema oder Vertrag. Ein Schema kann Felder verlangen, entscheidet aber nicht selbst, welcher Betrag richtig ist.

In Automatisierungen erfasse Fehlermeldung und nahen Kontext, nicht die ganze sensible Nutzlast. Umschließe JSON.parse() in JavaScript mit Ausnahmebehandlung und liefere eine Diagnose ohne Tokens. Bewahre in einer Integration Anfragekennung, Vertragsversion und anonymisierte Probe. So bleibt das Problem reproduzierbar, ohne Debug-Logs zur weiteren Offenlegung zu machen.

Doppelte Anführungszeichen, Backslashes und Kommata sind Syntax, kein optionaler Stil. In einer Zeichenkette bedeutet \n einen Umbruch, \" ein Anführungszeichen und \\ einen Backslash. Eine offene Zeichenkette kann dazu führen, dass der Parser ein späteres Zeichen beschuldigt. Ebenso kann eine fehlende Klammer erst am Dokumentende gemeldet werden, wenn das erwartete Schließen sicher ausgeblieben ist.

Exakt doppelte Namen sind besonders riskant: Viele Parser behalten den letzten, während RFC 8259 vor unvorhersehbarem Verhalten bei nicht eindeutigen Namen zwischen Implementierungen warnt. Semantische Duplikate wie total und amount sind schwieriger: Beide können überleben und zwei Interpretationen erzeugen. Definiere einen kanonischen Namen, lehne die mehrdeutige Kombination beim Produzenten ab und ergänze einen Migrationstest.

Vermeide „Reparatur“-Werkzeuge, die JavaScript-ähnlichen Text ohne Bericht über Änderungen in JSON verwandeln. Anführungszeichen hinzuzufügen, Kommata zu löschen oder Werte umzuwandeln kann eine Inkompatibilität des Produzenten verbergen. Verwende auch keine regulären Ausdrücke zur vollständigen JSON-Validierung: maskierte Zeichenketten und Verschachtelung machen das Verfahren brüchig. Der Parser ist für Syntax zuständig; Vertragstests und Schemavalidierung decken Anforderungen danach ab.

Ein weiterer Fehler ist, gültiges JSON mit einer korrekten Antwort zu verwechseln. {"enabled":"false"} ist gültig, aber der Typ sollte vielleicht boolean sein. 9007199254740993 kann beim JavaScript-Zahlentyp Präzision verlieren. 03/04/2026 erklärt seine Reihenfolge nicht. Prüfe Typ, Einheit, Zeitzone, Bereich und Fachregeln, bevor ein Wert an eine andere Schicht geht.

Nutze synthetische Daten zum Lernen des Ablaufs und prüfe, wo ein Werkzeug Inhalt verarbeitet, bevor interne Informationen eingefügt werden. Teile eine große Nutzlast auf: prüfe Kopf, ein Array-Element und die Abschlussstruktur. Schneide nicht mitten in Zeichenkette oder UTF-8-Sequenz. Bewahre UTF-8 und vermeide Textprogramme, die gerade in typografische Anführungszeichen verwandeln.

Meldungen unterscheiden sich zwischen Browsern und Versionen. Eine Position ist nur mit exakt derselben Eingabe reproduzierbar. Nenne in einem Bericht Clientversion, wörtliche Meldung, bereinigtes Fragment und Reproduktionsschritte. Veröffentliche keine vollständige Nutzlast als Beispiel, wenn sie E-Mail-Adressen, interne Pfade, Sitzungen oder Kontonummern enthält.

Dieser Leitfaden zertifiziert nicht, dass eine Nutzlast sicher, autorisiert oder für eine professionelle Entscheidung geeignet ist. JSON verschlüsselt, signiert und prüft keine Berechtigungen. Ein wohlgeformtes Dokument kann eine bösartige Anweisung, veraltete Daten oder manipulierte Zahlen enthalten. Syntaxvalidierung ersetzt weder Authentifizierung, Autorisierung, Größenlimits, sichere Protokolle noch menschliche Prüfung, wenn der Kontext sie verlangt.

Browserwerkzeuge helfen beim Prüfen von Text, sollten aber nicht die einzige Kontrolle einer kritischen Integration sein. Befolge bei Zahlungen, Gesundheit, Sicherheit, rechtlichen Pflichten oder regulierten Daten Vertrag, Verfahren und zugelassene Umgebungen der verantwortlichen Organisation. Wenn unklar ist, was ein doppeltes Feld bedeutet, stoppe den Import und frage den Datenverantwortlichen.

Bevor du einen JSON-Fehler als gelöst ansiehst, bewahre eine geschützte Kopie und erstelle ein minimales Beispiel ohne Geheimnisse. Lies die erste Parsermeldung und finde ihre Position in der exakten Eingabe. Repariere jeweils nur eine Regel: Kommata, Anführungszeichen, Escapes und Abschlüsse. Parse nach jeder Änderung erneut. Vergleiche danach Schlüssel, Typen, Kennungen, Zahlen, Daten und gleichwertige Felder mit dem Vertrag. Bestätige, dass keine doppelten Namen oder überlappenden Bedeutungen bleiben. Teste schließlich den echten Verbraucher mit kontrollierten Daten, dokumentiere die Ursache und korrigiere den Produzenten, damit er dasselbe Dokument nicht erneut ausgibt.

Plane außerdem einen kleinen Regressionstest für jede Ursache. Ein Test mit Endkomma soll abgelehnt werden, eine Zeichenkette mit \n dagegen akzeptiert werden. Prüfe, dass Kennungen wie "007" Zeichenketten bleiben, und dass der Produzent nicht zugleich total und amount für denselben Betrag sendet. Dadurch bleibt die Korrektur nicht nur eine einmalige manuelle Bereinigung. Bei Änderungen am Vertrag erhöhe dessen Version, kommuniziere das Ende alter Felder und beobachte kontrolliert, ob noch alte Clients Dokumente liefern. Eine eindeutige Fehlermeldung am Produzenten ist für Nutzer besser als eine stille, verlustbehaftete Umwandlung beim Empfänger.