JSON-String maskieren / demaskieren

Was dieses Werkzeug tut

Ein JSON-String darf kein rohes doppeltes Anführungszeichen, keinen rohen Rückstrich und keinen wörtlichen Zeilenumbruch enthalten — das Format braucht diese Zeichen, um Anfang und Ende von Strings zu markieren. Deshalb werden sie als Escape-Sequenzen geschrieben, und dieses Werkzeug wandelt zwischen beiden Formen um. Fügen Sie gewöhnlichen Text ein und erhalten Sie die maskierte Fassung, bereit zum Einsetzen in JSON; wechseln Sie die Richtung, und maskierter Text wird wieder lesbar.

Die zweite Richtung ist die, wegen der die meisten hierherkommen: eine Logzeile, eine Fehlermeldung oder eine curl-Antwort, die als Wand aus Rückstrichen ankam. Alles läuft in Ihrem Browser — das zählt, wenn das, was Sie zu lesen versuchen, eine Produktionsantwort ist.

Die Escape-Sequenzen

JSON definiert eine kurze Liste von Escapes, und das Werkzeug verwendet genau diese Liste — nichts Exotischeres, denn alles andere ist kein gültiges JSON.

• \" — ein doppeltes Anführungszeichen, das sonst den String beenden würde.
• \\ — ein einzelner Rückstrich. Deshalb verdoppeln sich Windows-Pfade und Regex-Muster.
• \n und \r — Zeilenumbruch und Wagenrücklauf.
• \t — Tabulator. Es gibt auch \b und \f, für Rückschritt und Seitenvorschub.
• \/ — ein optionales Escape für den Schrägstrich. Gültig, nie erforderlich; dieses Werkzeug akzeptiert es und erzeugt es nie.
• \uXXXX — jedes Zeichen über seinen hexadezimalen Code; so lassen sich Steuerzeichen und alles außerhalb von ASCII schreiben.

Steuerzeichen — alles unterhalb von Code 32 — haben in einem JSON-String überhaupt keine wörtliche Form und kommen deshalb immer als \uXXXX-Escapes heraus, auch wenn Sie keine ASCII-Ausgabe verlangt haben.

Warum sich Rückstriche vermehren

Der häufigste Grund, zu so einem Werkzeug zu greifen, ist Text, der mehr als einmal maskiert wurde. Jeder Kodierdurchgang maskiert die Rückstriche, die der vorherige eingefügt hat, sodass ein einzelnes Anführungszeichen einen immer längeren Schweif bekommt:

original    He said "hi"
escaped     He said \"hi\"
escaped x2  He said \\\"hi\\\"

Das passiert, wenn ein Wert nach JSON serialisiert wird, dieses JSON als String in einem weiteren JSON-Dokument abgelegt und das Ergebnis geloggt wird. Einmal dekodieren entfernt eine Schicht; führen Sie es erneut auf dem Ergebnis aus, bis der Text sich normal liest. Wenn nach dem Dekodieren noch Rückstriche übrig sind, ist das eine echte weitere Schicht und kein Fehler der Umwandlung.

Anführungszeichen: Wert oder Fragment

Ein vollständiger JSON-String-Wert schließt die umgebenden doppelten Anführungszeichen ein. Meistens fügen Sie aber in einen String ein, der in Ihrem Code oder Ihrer Konfiguration bereits existiert — dort wären diese Anführungszeichen falsch. Deshalb erzeugt das Maskieren standardmäßig nur den maskierten Inhalt, und die Option „umschließende Anführungszeichen einschließen" ergänzt sie, wenn Sie einen Wert wollen, den Sie als Ganzes einfügen können.

Beim Dekodieren ist diese Wahl unnötig — es nimmt beide Formen an. Fügen Sie ein Fragment ein oder einen kompletten, in Anführungszeichen stehenden Wert direkt aus einem JSON-Dokument: die umschließenden Anführungszeichen werden erkannt und entfernt.

Unicode — und wann man es doch maskiert

JSON ist ein Unicode-Format. „שלום" und „😀" sind genau so, wie sie geschrieben sind, vollkommen gültige JSON-Strings, und sie lesbar zu lassen ist hier die Voreinstellung. Die \uXXXX-Option gibt es für die Systeme, die nicht mitgezogen sind: alte Log-Pipelines, Terminals und Parser, die ASCII voraussetzen und alles andere verstümmeln.

Ein Detail zählt, wenn diese Option an ist. Zeichen außerhalb des Grundbereichs — die meisten Emoji — werden intern als zwei Einheiten gespeichert, ein sogenanntes Ersatzzeichenpaar, und das Format verlangt, dass beide Hälften als getrennte Escapes geschrieben werden. Ein Emoji wird daher zu zwei \u-Escapes und nicht zu einem längeren. Werkzeuge, die das falsch machen, erzeugen Escapes, die kein Parser akzeptiert — die übliche Erklärung für Emoji, die ein System überstehen und im nächsten zerbrechen.

Wenn das Dekodieren scheitert

Nicht jede Rückstrich-Sequenz ist ein gültiges Escape. \q bedeutet in JSON nichts, und \u12 ist ein \u-Escape, dem die Hälfte seiner Ziffern fehlt. Statt sie unverändert durchzureichen und eine Ausgabe zurückzugeben, die richtig aussieht, aber nicht dem entspricht, was Ihre Daten sagten, hält das Werkzeug an und meldet Zeile und Spalte genau dort, wo die fehlerhafte Sequenz beginnt.

In der Praxis ist dieser Fehler aufschlussreich: Ein vereinzeltes \q bedeutet meist, dass der Text nie für JSON maskiert war, und ein abgeschnittenes \u meist, dass die Eingabe gekappt wurde — eine an einer Längenbegrenzung beschnittene Logzeile oder eine Kopie, die mitten in der Sequenz endete.