How to Format JSON: Methods, Tools & Best Practices

Warum die Formatierung von JSON wichtig ist

Unformatierter JSON ist technisch gültig, aber für Menschen unzugänglich. Ein einzeiliger Blob aus verschachtelten Objekten und Arrays ist während einer Debugging-Sitzung nahezu unmöglich zu scannen, und es verwandelt Code-Reviews in Ratespiele.

Richtig formatierter JSON bietet Ihnen drei unmittelbare Vorteile: Lesbarkeit — Sie können die Hierarchie von Schlüsseln und Werten visuell nachverfolgen; Debugging — Diff-Tools und Fehlermeldungen beziehen sich auf Zeilennummern, die tatsächlich etwas bedeuten; und Zusammenarbeit — Teamkollegen, die Ihre API-Antworten oder Konfigurationsdateien überprüfen, können diese auf einen Blick verstehen.

Die Formatierung verhindert auch subtile Fehler. Wenn JSON minimiert wird, ist es leicht, eine fehlplatzierte Klammer oder einen doppelten Schlüssel zu übersehen. Die Struktur zu erweitern, lässt diese Probleme ins Auge springen.

Die Regeln der JSON-Formatierung

Bevor Sie ein Tool zur Hand nehmen, ist es hilfreich zu verstehen, was "formatierter JSON" tatsächlich bedeutet. Die JSON-Spezifikation (RFC 8259) schreibt keine Whitespace-Regeln vor — die Formatierung ist rein eine Frage der Präsentation. Dennoch hat die Community klare Konventionen festgelegt:

• Jedes Schlüssel-Wert-Paar steht in einer eigenen Zeile.
• Verschachtelte Objekte und Arrays sind um eine Ebene tiefer eingerückt als ihr Elternteil.
• Ein Doppelpunkt folgt dem Schlüssel, getrennt durch ein einzelnes Leerzeichen: “key”: “value”.
• Kommas erscheinen am Ende jeder Zeile (nicht am Anfang).
• Öffnende geschweifte Klammern und eckige Klammern bleiben in derselben Zeile wie der Schlüssel; schließende Klammern richten sich nach dem Einrückungsniveau des Elternteils.

Hier ist ein minimales Beispiel. Dieser minimierte JSON:

{"name":"Alice","age":30,"roles":["admin","editor"],"address":{"city":"Portland","state":"OR"}}

Wird so formatiert mit einer Einrückung von 2 Leerzeichen:

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

Die 3 Möglichkeiten, JSON zu formatieren

Jeder Ansatz fällt in eine von drei Kategorien: Online-Tools, Befehlszeilen-Dienstprogramme oder programmatische Formatierung innerhalb Ihres Anwendungscodes. Die richtige Wahl hängt davon ab, wo Sie sich in Ihrem Arbeitsablauf befinden und wie oft Sie dies tun müssen.

1. Online-Tools

Browserbasierte Formatter sind der schnellste Weg, wenn Sie nur eine einmalige Nutzlast schön formatieren müssen — fügen Sie sie ein, klicken Sie auf einen Button, kopieren Sie das Ergebnis. Es gibt nichts zu installieren und keinen Kontextwechsel zu einem Terminal.

Online-Tools eignen sich gut für schnelles Debugging, das Teilen von formatierten Snippets mit nicht-technischen Stakeholdern oder wenn Sie auf einem Rechner sind, auf dem Sie keine Software installieren können. Der Nachteil ist, dass sie sich nicht in automatisierte Pipelines integrieren lassen.

Versuchen Sie es selbst: Fügen Sie beliebiges JSON in unseren JSON Formatter ein, um es sofort mit Ihrer Wahl der Einrückung zu verschönern.

2. Befehlszeilen-Tools

Wenn Sie im Terminal arbeiten, decken zwei Befehle fast jeden Formatierungsbedarf ab:

Pythons integriertes json.tool-Modul — auf jedem Rechner mit installiertem Python verfügbar, keine zusätzlichen Pakete erforderlich:

echo '{"name":"Alice","age":30}' | python -m json.tool

Dies gibt schön eingerückten JSON auf stdout aus. Sie können auch eine Datei ganz einfach durchleiten:

python -m json.tool data.json > data-formatted.json

jq — ein leichtgewichtiges, speziell entwickeltes JSON-Verarbeitungswerkzeug. Der einfachste Formatierungsbefehl ist einfach der Identitätsfilter:

cat data.json | jq '.'

jq fügt auch Syntaxhervorhebung in den meisten Terminals hinzu, und Sie können Filter verketten, um in einem Durchgang zu transformieren und zu formatieren. Es ist die bevorzugte Wahl für Shell-Skripte, die JSON verarbeiten.

Beide Befehle können in CI-Pipelines verkettet werden. Beispielsweise könnten Sie jq --sort-keys . in einem Pre-Commit-Hook ausführen, um sicherzustellen, dass alle JSON-Konfigurationsdateien in einem Repository konsistent formatiert sind.

3. Programmatische Formatierung

Wenn Sie Anwendungscode schreiben, ist die Formatierung von JSON in den meisten Sprachen ein Einzeiler.

JavaScript / TypeScript:

const formatted = JSON.stringify(data, null, 2);

Das dritte Argument von JSON.stringify steuert die Einrückung. Übergeben Sie 2 für 2 Leerzeichen, 4 für 4 Leerzeichen oder "\t" für Tabs.

Python:

import json

formatted = json.dumps(data, indent=2, ensure_ascii=False)

Go:

formatted, err := json.MarshalIndent(data, "", "  ")

Die programmatische Formatierung ist entscheidend, wenn Sie JSON als Teil Ihrer Anwendung generieren — beim Schreiben von Konfigurationsdateien, Erstellen von API-Antworten oder Generieren von Dokumentationen. Sie kontrollieren die Ausgabe vollständig.

Vergleich der Formatierungsansätze

Hier ist eine schnelle Referenz, um Ihnen zu helfen, die richtige Methode für die Situation auszuwählen:

Kriterien	Online-Tool	CLI (jq / json.tool)	Programmatisch
Benutzerfreundlichkeit	Einfügen und Klicken	Einzeilenbefehl	Erfordert Code-Kontext
Geschwindigkeit für einmalige Aufgaben	Schnell	Schnell	Langsam (benötigt ein Skript)
Automatisierung / CI	Nicht geeignet	Ausgezeichnet	Ausgezeichnet
Anpassung	Eingeschränkt	Mäßig (Flags)	Volle Kontrolle
Funktioniert offline	Nein	Ja	Ja
Handhabung großer Dateien	Browsergrenzen	Funktioniert gut	Hängt von der Implementierung ab

Die Einrückungsdebatte: 2 Leerzeichen vs 4 Leerzeichen vs Tabs

Dies ist eine der Debatten, die mehr Hitze als Licht erzeugt, aber es gibt praktische Gründe, jede Option zu bevorzugen.

2 Leerzeichen

Die häufigste Wahl in JSON. Es hält tief verschachtelte Strukturen kompakt und bietet dennoch eine klare visuelle Hierarchie. Die meisten Tools im JavaScript-Ökosystem (ESLint, Prettier, npm's package.json) verwenden standardmäßig 2 Leerzeichen. Wenn Sie mit Web-APIs oder Node.js-Projekten arbeiten, ist dies der sichere Standard.

4 Leerzeichen

Beliebt in Python-nahen Arbeitsabläufen und einigen Unternehmens-Java-Umgebungen. Die zusätzliche Breite macht die Verschachtelungsebenen offensichtlicher, was beim Lesen großer Konfigurationsdateien helfen kann. Der Nachteil ist, dass tief verschachtelter JSON schnell zum rechten Rand des Bildschirms drängt.

Tabs

Tabs ermöglichen es jedem Entwickler, seine eigene visuelle Breite in seinem Editor festzulegen. Das klingt theoretisch ideal, aber in der Praxis erwarten die meisten JSON-Tools und Linter Leerzeichen. Tabs werden auch inkonsistent in webbasierten Diff-Viewer und GitHub-PRs dargestellt.

Wann man was verwenden sollte:

• 2 Leerzeichen — Webprojekte, JavaScript/TypeScript-Codebasen, API-Nutzlasten. Der Standard der Community.
• 4 Leerzeichen — Python-lastige Teams, große Konfigurationsdateien, bei denen Klarheit über Kompaktheit siegt.
• Tabs — Monorepos mit gemischten Sprachpräferenzen und strengen Zugänglichkeitsanforderungen (Tabs ermöglichen benutzerdefinierte Breiten).

Das Wichtigste ist die Konsistenz innerhalb eines Projekts. Wählen Sie eine aus und setzen Sie sie durch.

Schlüssel sortieren

Die meisten Formatter bieten eine "Schlüssel sortieren"-Option, die die Objektschlüssel alphabetisch anordnet. Das ist nicht nur kosmetisch — es hat echte Vorteile für die Versionskontrolle.

Wenn die Schlüssel sortiert sind, werden Diffs bedeutungsvoll. Ohne Sortierung könnten zwei Entwickler die gleichen Schlüssel in unterschiedlicher Reihenfolge hinzufügen, was zu unübersichtlichen Diffs führt, die die tatsächliche Änderung verschleiern. Sortierte Schlüssel beseitigen dies vollständig.

Sortierte Schlüssel erleichtern auch das Scannen großer Konfigurationsdateien. Wenn Sie den Schlüssel kennen, nach dem Sie suchen, können Sie direkt zu seiner alphabetischen Position springen, ohne suchen zu müssen.

Die einzige Ausnahme: Einige JSON-Dateien haben eine absichtliche Schlüsselreihenfolge (wie eine package.json, in der name und version konventionell zuerst kommen). In diesen Fällen bewahren Sie die ursprüngliche Reihenfolge.

In jq sortieren Sie die Schlüssel mit:

jq --sort-keys '.' data.json

In JavaScript übergeben Sie eine Ersetzungsfunktion oder verwenden eine Bibliothek wie json-stable-stringify für eine deterministische Schlüsselreihenfolge.

Automatische Formatierung beim Speichern in VS Code

Die beste Formatierung ist die, über die Sie nie nachdenken müssen. VS Code kann JSON-Dateien automatisch jedes Mal formatieren, wenn Sie speichern. So richten Sie es ein:

Schritt 1: Öffnen Sie Ihre Einstellungen (Cmd+, auf macOS, Ctrl+, auf Windows/Linux) und fügen Sie diese Einträge hinzu:

{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  }
}

Schritt 2: Installieren Sie die Prettier - Code formatter-Erweiterung, falls Sie dies noch nicht getan haben. Sie kümmert sich um die JSON-Formatierung sowie um jede andere Sprache in Ihrem Projekt.

Schritt 3: Erstellen Sie eine .prettierrc im Stammverzeichnis Ihres Projekts, um die Einstellungen im gesamten Team zu standardisieren:

{
  "tabWidth": 2,
  "useTabs": false
}

Jetzt wird jede JSON-Datei im Projekt identisch formatiert, unabhängig davon, wer sie bearbeitet hat. Keine formatierungsbedingten Diffs mehr in Pull-Requests.

Umgang mit Randfällen

Die meisten Formatierungswerkzeuge kommen mit standardmäßigem JSON ohne Probleme zurecht, aber einige Situationen können Sie auf die Probe stellen:

• Große Zahlen — JSON unterscheidet nicht zwischen Ganzzahlen und Fließkommazahlen. Einige Formatter könnten 1.0 als 1 umformatieren oder die Genauigkeit bei sehr großen Ganzzahlen verlieren. Wenn Genauigkeit wichtig ist, überprüfen Sie die Ausgabe.
• Unicode-Escape-Sequenzen — Ein Formatter könnte \u00e9 in das Literalzeichen é oder umgekehrt umwandeln. Beides ist gültiges JSON, aber die Änderung kann unerwartete Diffs verursachen.
• Leere Objekte und Arrays — Einige Formatter erweitern {} auf mehrere Zeilen. Andere halten sie kompakt. Dies ist eine Stilpräferenz, aber seien Sie sich bewusst, dass dies zwischen den Tools variieren kann.
• Trailing Newline — Die POSIX-Konvention besagt, dass Textdateien mit einer neuen Zeile enden sollten. Die meisten Formatter fügen eine hinzu, aber nicht alle. Überprüfen Sie Ihre .editorconfig, wenn dies für Ihr CI wichtig ist.

Formatierung als Teil Ihres Arbeitsablaufs

Die effektivsten Teams behandeln die JSON-Formatierung genauso wie die Code-Formatierung — als automatisierten, nicht verhandelbaren Teil des Entwicklungsprozesses.

Pre-Commit-Hooks: Verwenden Sie ein Tool wie husky mit lint-staged, um Prettier oder jq vor jedem Commit auf JSON-Dateien auszuführen. Dies fängt Formatierungsprobleme ab, bevor sie in den Code gelangen.

CI-Überprüfungen: Fügen Sie Ihrer CI-Pipeline eine Formatierungsüberprüfung hinzu, die fehlschlägt, wenn irgendwelche JSON-Dateien nicht ordnungsgemäß formatiert sind. Prettier hat einen --check-Flag genau für diesen Zweck.

Editor-Integration: Formatieren beim Speichern beseitigt die manuelle Formatierung vollständig. In Kombination mit einer gemeinsamen Konfigurationsdatei stellt es sicher, dass jedes Teammitglied identische Ausgaben produziert.

Das Ziel ist es, die Formatierung unsichtbar zu machen — etwas, das automatisch geschieht, damit sich die Entwickler auf den tatsächlichen Inhalt ihrer JSON-Dateien konzentrieren können, anstatt darauf, wie sie aussehen.

Versuchen Sie es selbst: Fügen Sie unformatiertes JSON in unseren JSON Formatter ein, um es sofort zu verschönern. Sie können auch Ihr JSON validieren, um strukturelle Fehler vor der Formatierung zu erkennen.