JSON prüfen

Dass JSON ungültig ist, sagt einem alles Mögliche — die Konsole eines Browsers erledigt das in einer Zeile. Wertvoll ist das Wo, und darin ist jeder Parser schlecht, jedenfalls auf eine Art, mit der man arbeiten könnte. „Unerwartetes Token }“ in einer vierhundert Zeilen langen Datei ist eine Feststellung des Offensichtlichen ohne Adresse.

Diese Seite nennt deshalb Zeile und Spalte, druckt diese Zeile ab und setzt einen Zeiger unter das Zeichen. In der Praxis reicht das fast immer, um das Problem zu sehen, ohne die Datei zu öffnen: Ein fehlendes Komma erkennt man, sobald man die Zeile darüber sieht, und der Zeiger steht fast immer auf dem Token, das nach dem Vergessenen kam.

Das ist das Nützlichste, was man über JSON-Fehlermeldungen wissen kann. Ein Parser ist zufrieden, bis etwas auf das Vorangegangene nicht mehr folgen kann — ein fehlendes Komma am Ende von Zeile 12 wird also am Anfang von Zeile 13 gemeldet, wo der nächste Schlüssel auftaucht und dort nicht stehen darf.

Also nach oben schauen. Der Zeiger markiert das erste Zeichen, das nicht mehr angenommen werden konnte; falsch ist meist das Ende der vorherigen Zeile oder der vorherige Wert. Der Extremfall ist eine fehlende schließende Klammer: Die wird am Dateiende gemeldet, wie weit weg das auch sein mag.

Für JSON-Parse-Fehler gibt es keinen Standard. Chrome und Node sagen „at position 42“ und hängen in neueren Versionen Zeile und Spalte an. Firefox nennt Zeile und Spalte und keine Position. Safari nennt bei manchen Fehlern beides nicht.

Diese Seite nimmt den Zeichen-Offset, wo es einen gibt, und rechnet Zeile und Spalte selbst aus — die Antwort ist damit in jedem Browser dieselbe statt der jeweiligen lokalen Formulierung. Wo eine Meldung weder das eine noch das andere trägt, sagt sie das, statt zu raten: Eine falsche Zeilennummer in einer langen Datei kostet mehr Zeit als gar keine.

Es heißt, dass das Dokument syntaktisch JSON ist: Die Klammern gehen auf und zu, die Zeichenketten sind korrekt in Anführungszeichen und maskiert, die Zahlen sind Zahlen. Das prüft ein Parser, und das ist es, was scheitert, wenn irgendetwas deine Datei mit einer nichtssagenden Meldung ablehnt.

Es heißt nicht, dass das Dokument die richtige Form hat. Ob es die Felder enthält, die eine API erwartet, ob ein Wert im zulässigen Bereich liegt, ob ein Datum ein Datum ist — das ist Schema-Validierung und braucht ein Schema. Wenn dein JSON hier durchgeht und trotzdem abgelehnt wird, ist das Problem von der Syntax zur Bedeutung gewandert und der Fehler, den du suchst, ein anderer.

Ein Komma vor einer schließenden Klammer — in JavaScript erlaubt, in JSON5 erlaubt, in JSON nicht, und der Grund, aus dem die meisten hier landen. Ein einfaches Anführungszeichen, wo JSON ein doppeltes verlangt. Ein nicht maskiertes Anführungszeichen oder ein Backslash innerhalb einer Zeichenkette, was meist von einem eingefügten Windows-Pfad kommt. Und ein Kommentar, den es in JSON gar nicht gibt.

Der fünfte ist seltener und schwerer zu sehen: ein nicht maskiertes Steuerzeichen in einer Zeichenkette, also ein echter Zeilenumbruch oder Tabulator, der hineinkopiert statt als Maskierung geschrieben wurde. In den meisten Editoren ist er unsichtbar, und man sollte ihn vermuten, wenn der Zeiger auf etwas zeigt, das völlig in Ordnung aussieht.

Der Typ der obersten Ebene, die Anzahl der Schlüssel über das ganze Dokument, die Verschachtelungstiefe und die Größe in Bytes. Sie stehen dort, weil „gültig“ allein ein Ja ohne Inhalt ist — und weil jede der vier Zahlen eine Frage beantwortet, die tatsächlich jemand hat.

Auf die Verschachtelungstiefe lohnt sich der Blick am meisten. Alles jenseits von etwa sechs Ebenen ist meist ein Datenmodell, das gewachsen statt entworfen ist, und ein verlässlicher Hinweis darauf, dass der Code, der das Dokument verarbeitet, unangenehm werden wird. Schlüssel werden nach Vorkommen und nicht nach verschiedenen Namen gezählt: Die Frage lautet, wie viel drinsteckt, nicht wie viele Feldnamen es gibt.

Ein Tabulator ist für die Spaltenzählung ein Zeichen und für das Auge acht Spalten. Ein in Zeichen gezählter Zeiger landet in einer mit Tabulatoren eingerückten Datei also nirgendwo in der Nähe des Problems — und mit Tabulatoren eingerückt sind sehr viele JSON-Dateien.

Deshalb werden Tabulatoren in der abgedruckten Zeile durch je ein Leerzeichen ersetzt, bevor der Zeiger gesetzt wird. Die Zeile sieht dadurch schmaler aus als in deinem Editor; der Zeiger steht dafür unter dem richtigen Zeichen, und das ist die nützlichere von beiden Eigenschaften.

Ein Dokument, das geprüft wird, ist fast immer eines, das gerade irgendwo in der Produktion scheitert — und genau das sind die Dokumente, die man keinem Fremden geben sollte. Es ist dieselbe Kategorie wie die Tokens auf der Base64-Seite und verdient dieselbe Behandlung.

Das Parsen erledigt der eingebaute Parser deines Browsers in dieser Seite. Es wird nichts gesendet, und das Netzwerk-Panel ist die Art, das zu prüfen, statt einem Satz auf einer Marketingseite zu glauben.

Ein UTF-8-Byte-Order-Mark am Dateianfang ist unsichtbar und für einen strengen JSON-Parser ein Fehler an Position null. Wer eine Datei aus einem Windows-Editor exportiert oder aus einer Tabellenkalkulation gespeichert hat, hat gute Chancen auf eines — und die Meldung „unerwartetes Zeichen“ ganz am Anfang eines Dokuments, das offensichtlich mit einer Klammer beginnt, ist fast immer genau das.

Verwandt und ebenso unsichtbar: ein geschütztes Leerzeichen aus einer Textverarbeitung, ein Zero-Width-Space aus einer Webseite, ein Zeilenumbruch mitten in einer Zeichenkette. Alle drei sehen im Editor aus wie nichts und sind für den Parser etwas. Wenn der Zeiger auf eine völlig unauffällige Stelle zeigt, ist das die Spur, der man folgen sollte.

Die Formatierseite lehnt ungültiges JSON ebenfalls ab, sagt aber nur, dass es ungültig ist — und das ist Absicht: Wer formatieren wollte, will sein Dokument zurück und keine Diagnose. Ein Zeiger mitten in einer Ausgabe, die eigentlich das eingerückte Dokument sein sollte, wäre eine Antwort auf eine nicht gestellte Frage.

Diese Seite ist die andere Hälfte davon. Sie gibt kein formatiertes Dokument zurück, weil das hier niemand sucht — sie beantwortet ausschließlich das Warum. Zwei Seiten für zwei Fragen, statt einer, die beides halb macht.