JSON-Formatierung Best Practices — Einrückbarkeit, Lesbarkeit und die Debatten, die nicht sterben

JSONs Grammatik ist minimal. Sechs Werttypen, keine Kommentare, keine nachgestellten Kommas, keine Flexibilität bei der Art, wie Strings angeführt werden. Diese Strenge ist seine Stärke für Maschinen und seine Schwäche für Menschen. Wenn ein Mensch JSON lesen oder schreiben muss — in einer Konfigurationsdatei, einer API-Antwort, einem Diff — dann zählt die Formatierung.

Dieser Beitrag behandelt jede Formatierungsentscheidung, der Sie begegnen werden, was das Ökosystem entschieden hat und wo die Debatten noch immer toben.

Einrückung: 2 Leerzeichen gewinnt

Der Tabulatoren-vs-Leerzeichen-Krieg hat in der JSON-Welt einen Gewinner: 2 Leerzeichen. Fast jeder bedeutende Styleguide, Linter und Formatter verwendet standardmäßig 2-Leerzeichen-Einrückung:

• Google JSON Style Guide — 2 Leerzeichen
• Prettier — 2 Leerzeichen (Standard)
• ESLint — 2 Leerzeichen (die meisten Konfigurationen)
• AWS CloudFormation — 2 Leerzeichen
• Kubernetes-Manifeste — 2 Leerzeichen

Der Grund ist pragmatisch: JSON ist bereits mit seinen Anführungszeichen und geschweiften Klammern wortreich. 4-Leerzeichen-Einrückung schiebt verschachtelte Objekte über den rechten Rand der meisten Editoren hinaus. 2 Leerzeichen halten die Dinge lesbar, ohne horizontalen Platz zu verschwenden.

Verwenden Sie 4 Leerzeichen, wenn Ihr Team es bevorzugt und Sie konsequent sind. Verwenden Sie Tabulatoren, wenn Sie müssen, aber seien Sie sich bewusst, dass die meisten JSON-Tools Leerzeichen annehmen und gemischte Einrückung in einer JSON-Datei ein auf(parser)fehler wartend auftritt.

Nachgestellte Kommas: immer noch nein

JSON erlaubt keine nachgestellten Kommas. Dies ist der häufigste Syntaxfehler in händisch bearbeiteten JSON-Dateien. Sie schreiben:

{
  "name": "Alice",
  "items": ["a", "b",],
}

Und ein strenger Parser lehnt es ab. Das nachgestellte Komma nach "b" und das nachgestellte Komma nach der schließenden geschweiften Klammer } sind beide illegal.

YAML erlaubt nachgestellte Kommas (und die meisten Sprachen tun das). JSON nicht. Wenn Ihre Tools JSONC (JSON mit Kommentaren, verwendet in VS Codes tsconfig.json und settings.json) unterstützen, sind nachgestellte Kommas erlaubt. Aber reines JSON — das Typ, das über APIs reist — toleriert sie nicht.

Die beste Verteidigung: Verwenden Sie einen Formatter, der dies automatisch erkennt. Fügen Sie Ihr JSON vor dem Committen in einen Validator ein.

Schön vs. kompakt

Schön formatiertes JSON hat Zeilenumbrüche und Einrückungen. Es ist lesbar, diffbar und debugbar:

{
  "status": "ok",
  "count": 42
}

Kompaktes JSON hat keinen Leerraum zwischen Tokens. Es ist kleiner im Draht:

{"status":"ok","count":42}

Die Faustregel:

• Menschen面向 (Konfigurationsdateien, Logs, API-Antworten beim Debuggen) → schön formatieren.
• Maschinen面向 (Produktions-API-Nutzlasten, Nachrichtenwarteschlangen, Ereignisströme) → kompakt.
• Speicher (Datenbanken, Caches) → kompakt, es sei denn, Sie müssen es manuell während des Debuggens lesen.

Kompaktes JSON spart etwa 20-30% der Größe im Vergleich zu 2-Leerzeichen-schön-formatiertem JSON. Für eine 10KB-Nutzlast sind das 2-3KB. Über Millionen von Anfragen summiert sich das. Für eine Konfigurationsdatei, die Sie manuell bearbeiten, ist die Lesbarkeit von schön formatiertem JSON die extra Bytes wert.

Sortierte Schlüssel

Sollten Objektschlüssel alphabetisch sortiert werden?

Dafür: Diffs sind deterministisch. Wenn Sie einen Schlüssel hinzufügen, erscheint nur diese Zeile in einem git-Diff. Ohne sortierte Schlüssel kann das Einfügen eines Schlüssels in der Mitte jeden folgenden Schlüssel verschieben, was einen lautstarren Diff erzeugt.

Dagegen: Logische Gruppierung ist lesbarer. "name" zuerst und "id" zweite ist intuitiv. Alphabetische Sortierung setzt "address" ohne semantischen Grund vor "name".

Die pragmatische Antwort: Sortieren Sie Schlüssel in maschinell generiertem JSON (APIs, Konfigurationen, Diffs). Behalten Sie die logische Reihenfolge in händisch geschriebenem JSON bei. Die meisten Formatter (Prettier, jq, python -m json.tool) haben ein --sort-keys-Flag, das Sie im CI aktivieren können.

Schlüsselnamenkonventionen

JSON-Schlüssel sind Strings, und das Ökosystem hat sich auf zwei Konventionen geeinigt:

• camelCase — der JavaScript/Node.js-Standard. firstName, lastName, createdAt.
• snake_case — der Python/Ruby/Rust-Standard. first_name, last_name, created_at.
• kebab-case — selten in JSON, häufiger in URLs und CSS. Für API-Schlüssel vermeiden.

Wählen Sie eine und halten Sie sich daran. Die meisten APIs verwenden camelCase. Wenn Sie eine REST-API für JavaScript-Konsumenten bauen, ist camelCase der Weg des geringsten Widerstands. Wenn Sie mit Python-Diensten interagieren, reduziert snake_case Reibung.

Das Schlimmste, was Sie tun können, ist zu mischen: firstName in einem Endpunkt, last_name in einem anderen. Wählen Sie eine Konvention, setzen Sie sie mit einem Linter durch und gehen Sie weiter.

Zahlenformatierung

JSON unterscheidet nicht zwischen Ganzzahlen und Gleitkommazahlen. 42 und 42.0 sind beide gültig, und die meisten Parser behandeln sie identisch. Aber die Formatierung zählt für die Lesbarkeit:

• Ganzzahlen: kein Dezimalpunkt. 42, nicht 42.0.
• Gleitkommazahlen: Verwenden Sie so viele Ziffern wie nötig. 3.14159, nicht 3.14159000000000.
• Große Zahlen: Verwenden Sie wissenschaftliche Schreibweise, wenn die Zahl riesig ist. 1e10 ist klarer als 10000000000.

JSON unterstützt nicht Infinity, -Infinity oder NaN. Wenn Ihre Sprache diese serialisiert, ist die Ausgabe kein gültiges JSON und Parser werden es ablehnen.

Strings: einfache vs. doppelte Anführungszeichen

JSON erfordert doppelte Anführungszeichen für Strings. Das ist nicht verhandelbar. 'hello' ist kein gültiges JSON. "hello" ist es.

Wenn Ihr Linter oder Editor einfache Anführungszeichen in JSON-Dateien erlaubt, analysiert er JSONC oder eine Supermenge, nicht Standard-JSON. APIs und Parser, die striktes JSON erwarten, werden einfach angeführte Strings ablehnen.

Kommentare: immer noch nicht erlaubt

JSON hat keine Kommentarsyntax. Dies ist by Design (die Spezifikation sagt, JSON ist “ein Datenaustauschformat”, keine Konfigurationssprache), aber es ist die häufigste Beschwerde von Entwicklern, die YAML verwenden.

Workarounds:

• Verwenden Sie einen "comment" oder "_comment"-Schlüssel. Es ist hässlich, aber gültig.
• Verwenden Sie JSONC (VS Codes Format), wenn Ihre Tools es unterstützen.
• Wechseln Sie zu YAML oder TOML für Konfigurationsdateien, bei denen Kommentare wichtig sind.

Der Formatter-Workflow

Der beste Workflow für JSON-Formatierung:

1. Schreiben Sie JSON, wie Sie wollen. Verschwenden Sie keine Zeit mit manuellem Einrücken.
2. Führen Sie beim Speichern einen Formatter aus. Prettier, jq oder den eingebauten Formatter Ihres Editors.
3. Committen Sie die formatierte Ausgabe. Konsistente Diffs, keine Stildebatten.
4. Validieren Sie im CI. Ein JSON-Lint-Schritt erkennt nachgestellte Kommas und Syntaxfehler, bevor sie in die Produktion gelangen.

Dies eliminiert jedes Formatierungsdebate. Der Formatter entscheidet, alle anderen schreiben Code.

Häufige Fehler

• Nachgestellte Kommas — der häufigste Analysefehler in händisch bearbeitetem JSON.
• Einfache Anführungszeichen — gültig in JavaScript-Objektliteralen, ungültig in JSON.
• Unangeführte Schlüssel — { name: "Alice" } ist JavaScript, nicht JSON.
• Kommentare — // das ist kein JSON oder /* auch das nicht */.
• Gemischte Einrückung — Mischen von Tabulatoren und Leerzeichen in derselben Datei.

Fügen Sie Ihr JSON vor dem Deployment in einen Validator ein. Es dauert eine Sekunde und erspart Ihnen dreißig Minuten Debugging eines mysteriösen 400-Fehlers.