# JSON-Explorer & Tabellen-Entfalter – Tief verschachtelte Strukturen durchsuchen, glätten und typisieren

> **Autor:** Lukas Kopischke (Lead Software-Engineer, Düsseldorf)
> **Kanonische URL:** https://lukiluki.me/garden/json-explorer
> **Markdown-Endpunkt:** https://lukiluki.me/garden/json-explorer.md
> **Kategorie:** Performance & Architektur | **Tags:** RFC 8259, RFC 9535 JSONPath, CSV-Parser, TypeScript-AST, Offline-PWA
> **Veröffentlicht:** 2026-10-27 | **Aktualisiert:** 2026-10-27
> **Zusammenfassung:** Tief verschachteltes JSON lokal im Browser erkunden: Pfade durchsuchen, Objekt-Arrays als Tabelle glätten, CSV reparieren und TypeScript-Typen ableiten.

---
Eine Webhook-Antwort, ein GraphQL-Dump oder ein Zustands-Export aus deinem Smart Home ist 900 Zeilen lang und sechs Ebenen tief verschachtelt. Du scrollst im Texteditor auf und ab, zählst geschweifte Klammern und weißt in Zeile 412 nicht mehr, ob das Feld `status` gerade zur Bestellung, zur Zahlung oder zum Versand-Paket gehört.

Ein strukturierter JSON-Explorer zerlegt den Text nach RFC 8259 (Offizieller Internet-Standard (IETF), der die strikte Grammatik für Objekte, Arrays, UTF-8-Zeichenketten, Zahlen und Literale im JSON-Datenformat festlegt.) in einen adressierbaren Objektbaum im Arbeitsspeicher, stellt jede Verschachtelungsebene als nebeneinanderliegende Spalte dar und faltet verschachtelte Objekt-Arrays über Punkt-Notation (`customer.address.city`) zu flachen Tabellen auseinander. Für Dateien bis etwa 20 MB gelingt das verzögerungsfrei im Browser; ab mehreren hundert Megabyte sind Streaming-Parser auf der Kommandozeile überlegen.

> **Merksatz:**
> Verschachteltes JSON wird erst dann mühelos lesbar, wenn Hierarchie-Ebenen nebeneinander statt untereinander stehen und wiederholte Objekt-Listen in flache Spalten aufgefaltet werden. Jeder Knoten besitzt dabei genau einen eindeutigen Zugriffspfad von der Wurzel bis zum Wert.

## Warum verlieren wir in tief verschachteltem JSON die Orientierung – und wie lösen Spalten-Navigation und Punkt-Glättung das?

In einer formatierten Textdatei wächst eine Baumstruktur gleichzeitig nach rechts (Einrückung) und nach unten (Zeilenanzahl). Sobald der Elternknoten `orders[0]` aus dem sichtbaren Bildschirmausschnitt verschwindet, muss dein Arbeitsgedächtnis den gesamten Pfad im Kopf behalten.

Zwei Darstellungsformen beheben dieses Strukturproblem ohne Datenverlust:

1. Miller-Columns (Spalten-Navigator) (Mehrspaltiges Navigationsmuster (bekannt aus dem NeXTSTEP- und macOS-Finder), bei dem jede ausgewählte Hierarchiestufe ihre Kind-Elemente in der direkt rechts angrenzenden Spalte öffnet.): Jede Ebene der JSON-Hierarchie erhält eine eigene schmale Spalte. Klickst du links auf `data`, daneben auf `store` und daneben auf `orders`, bleibt die gesamte Elternkette dauerhaft im Blickfeld, während ganz rechts der isolierte Teilbaum steht.
2. **Rekursive Punkt-Glättung (`Dot-Flattening`):** Enthält ein JSON-Dokument ein Array gleichartiger Objekte – etwa Bestellungen mit eingebettetem `customer`- und `payment`-Objekt –, projiziert ein rekursiver Durchlauf die geschachtelten Schlüssel auf zusammengesetzte Spaltennamen wie `customer.email` oder `payment.amountEur`. Aus einem verschachtelten Baum entsteht wieder eine zweidimensionale Tabelle, die sich sortieren, filtern und für Tabellenkalkulationen exportieren lässt.

### Sichere Pfad-Adressierung und Tabellen-Projektion im Code

Beim Kopieren eines Pfades in eigenen TypeScript- oder JavaScript-Code scheitert die einfache Punkt-Schreibweise (`a.b.c`), sobald Schlüssel Bindestriche oder Leerzeichen enthalten (wie `"content-type"`) oder optionale Zwischenobjekte zur Laufzeit `null` sein können. Eine saubere Hilfsfunktion prüft deshalb jeden Pfad-Abschnitt per regulärem Ausdruck und erzeugt auf Wunsch direkt sicheres Optional-Chaining (`?.`):

```typescript
const VALID_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;

export function buildSafeAccessPath(
  segments: Array<string | number>,
  useOptionalChaining = true
): string {
  let expr = "data";
  for (const seg of segments) {
    if (typeof seg === "number") {
      expr += useOptionalChaining ? `?.[${seg}]` : `[${seg}]`;
    } else if (VALID_IDENT.test(seg)) {
      expr += useOptionalChaining ? `?.${seg}` : `.${seg}`;
    } else {
      const escaped = seg.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
      expr += useOptionalChaining ? `?.["${escaped}"]` : `["${escaped}"]`;
    }
  }
  return expr;
}

export function flattenNestedRecord(
  record: Record<string, unknown>,
  prefix = "",
  maxDepth = 3
): Record<string, string | number | boolean | null> {
  const flat: Record<string, string | number | boolean | null> = {};

  for (const [key, value] of Object.entries(record)) {
    const column = prefix ? `${prefix}.${key}` : key;
    if (value === null || typeof value !== "object") {
      flat[column] = (value as string | number | boolean | null) ?? null;
    } else if (Array.isArray(value)) {
      flat[column] = value.every((v) => v === null || typeof v !== "object")
        ? value.join(", ")
        : `[${value.length} Einträge]`;
    } else if (maxDepth > 0) {
      Object.assign(
        flat,
        flattenNestedRecord(value as Record<string, unknown>, column, maxDepth - 1)
      );
    } else {
      flat[column] = JSON.stringify(value);
    }
  }
  return flat;
}
```

### Typableitung über heterogene Array-Elemente hinweg

Leitest du ein TypeScript-`interface` nur aus dem **ersten** Element `orders[0]` ab, übersiehst du schnell, dass `discountCode` in `orders[1]` den Wert `null` annimmt oder ein optionales Feld `windowOpen` erst im zweiten Sensor-Eintrag auftaucht. Ein verlässlicher Typ-Generator vereinigt deshalb alle Objekte eines Arrays: Taucht ein Schlüssel in weniger als 100 % der Elemente auf, erhält er das Optionalsymbol `?`; kommen unterschiedliche Laufzeittypen vor (`string` und `null`), entsteht automatisch der Union-Typ `string | null`.

Willst du zwei verschiedene Stände derselben JSON-Antwort nach einem Deployment gegenüberstellen, nutze anschließend den [Diff-Checker & Smart-Formatter](/garden/diff-checker), der Objektschlüssel vor dem Zeilenvergleich alphabetisch sortiert.

## Wann reicht ein Browser-Explorer – und wann brauchst du Streaming-Werkzeuge?

| Werkzeugklasse | Sinnvolle Dateigröße | Datenschutz & Betrieb | Stärken | Klare Grenze / Wann wechseln? |
| :--- | :--- | :--- | :--- | :--- |
| **Lokaler Browser-Explorer (`JSON.parse`)** | Bis ~20 MB | **100 % lokal im RAM** (kein Server-Upload) | Spalten-Navigation, sofortige Pfad-Kopie, CSV-Export und TypeScript-Ableitung per Klick | `JSON.parse` lädt den gesamten String am Stück in den Browser-Heap; ab ~50–100 MB drohen Tab-Ruckler |
| **`jq` (Kommandozeile)** | Megabyte bis mehrere Gigabyte | Lokal im Terminal | Skriptbare Filter-Pipelines in CI/CD-Jobs, Streaming-Modus (`--stream`) mit minimalem Speicherbedarf | Steile Lernkurve für komplexe Filter-Syntax; keine visuelle Spalten-Exploration |
| **DuckDB (`read_json_auto`)** | 50 MB bis dutzende Gigabyte | Lokal oder Embedded | Volle SQL-Aggregationen (`GROUP BY`, `JOIN`) direkt auf riesigen JSON- und `.jsonl`-Dateien | Für kurzes Inspizieren einzelner API-Antworten im Alltag überdimensioniert |

  #### Empfohlen (Do): Bewährte Praxis bei API- & CSV-Daten
* Beim Zugriff auf tief verschachtelte Fremd-APIs konsequent Optional-Chaining (`?.`) samt Fallback (`??`) verwenden
    * Beim CSV-Export für deutschsprachiges Excel ein UTF-8 Byte Order Mark (BOM) (Unsichtbare 3-Byte-Kennung (0xEF 0xBB 0xBF) am Dateianfang, an der Microsoft Excel unter Windows erkennt, dass Umlaute als UTF-8 statt Windows-1252 kodiert sind.) (`\uFEFF`) voranstellen und Semikolon (`;`) als Trennzeichen nutzen
    * TypeScript-Typen immer über **alle** Elemente eines Beispiel-Arrays statt nur über `items[0]` ableiten
  #### Vermeiden (Don't): Häufige Fallstricke
* Keine produktiven Kundendaten, Bearer-Tokens oder Webhook-Payloads in werbefinanzierte Online-JSON-Viewer mit Server-Backend einfügen
    * Keine unvalidierten JavaScript-Objektschnipsel per `eval()` parsen – immer striktes `JSON.parse()` nach gezielter Vorbereinigung nutzen
    * Keine 500-MB-Logdateien komplett in ein Browser-Textfeld kopieren, statt sie per `.jsonl`-Zeilenstream zu verarbeiten

> **Vorsicht bei großen 64-Bit-Ganzzahlen in JSON**
> Standard-`JSON.parse()` in JavaScript wandelt alle Zahlen in 64-Bit-Gleitkommazahlen (`IEEE 754 double`) um. Ganzzahlen oberhalb von `Number.MAX_SAFE_INTEGER` (`9.007.199.254.740.991`, etwa 64-Bit-Snowflake-IDs von Discord oder X/Twitter) verlieren dabei ihre letzten Ziffern! Solche IDs gehören in APIs zwingend als `"string"` übertragen.

## Prüfpunkte für saubere JSON- und CSV-Verarbeitung

- [ ] **Striktheit prüfen:** Stammt ein fehlerhafter Schnipsel aus einer Browser-Konsole oder Konfigurationsdatei, entferne nachgestellte Kommas und wandle einfache in doppelte Anführungszeichen um, bevor `JSON.parse()` läuft.
- [ ] **Null- und Optional-Fälle absichern:** Prüfe in der Auto-Tabelle, welche Spalten leere Zellen (`null`) aufweisen, und sichere genau diese Pfade im Anwendungscode ab.
- [ ] **64-Bit-IDs kontrollieren:** Enthält die Antwort numerische IDs mit mehr als 15 Dezimalstellen, stelle sicher, dass das Backend sie als Zeichenkette ausliefert.
- [ ] **Umlaute im CSV-Export gegenprüfen:** Öffne exportierte `.csv`-Dateien einmal real in der Ziel-Tabellenkalkulation, um Trennzeichen (`;` vs. `,`) und UTF-8-BOM zu bestätigen.

## Quellen und nächste Schritte

* **IETF RFC 8259** – *The JavaScript Object Notation (JSON) Data Interchange Format*: [datatracker.ietf.org/doc/html/rfc8259](https://datatracker.ietf.org/doc/html/rfc8259)
* **IETF RFC 9535** – *JSONPath: Query Expressions for JSON* (Standardisierte Pfad-Abfragesyntax, 2024): [datatracker.ietf.org/doc/html/rfc9535](https://datatracker.ietf.org/doc/html/rfc9535)
* **IETF RFC 4180** – *Common Format and MIME Type for Comma-Separated Values (CSV) Files*: [datatracker.ietf.org/doc/html/rfc4180](https://datatracker.ietf.org/doc/html/rfc4180)
* **Weiterführend im Digital Garden:** Nutze den [Diff-Checker & Smart-Formatter](/garden/diff-checker), um zwei umsortierte JSON-Antworten semantisch zu vergleichen, oder lies in [Home-Assistant MCP](/garden/home-assistant-mcp), wie KI-Agenten große verschachtelte Gerätestatus-Bäume gezielt filtern, bevor das Kontextfenster überläuft.

---
*Quelle: [Lukas Kopischke – Digital Garden](https://lukiluki.me/garden/json-explorer) | Vollständiger Index: [llms.txt](https://lukiluki.me/llms.txt)*