JSON flach machen

Flach machen verwandelt ein verschachteltes Dokument in eine einzige Ebene aus Punktpfaden: Aus {"a":{"b":1}} wird {"a.b":1}. Der umgekehrte Weg stellt es wieder her.

Das tut man, bevor man JSON in irgendetwas Rechteckiges lädt: eine Tabellenkalkulation, einen Data Frame, einen Feature-Flag-Speicher, eine Environment-Datei, ein Formular.

Der Hin- und Rückweg, und der eine Fall, der ihn bricht

Flach machen und wieder aufbauen liefert das ursprüngliche Dokument zurück, samt leerer Objekte und leerer Arrays, die etliche Implementierungen klammheimlich verschlucken.

Es gibt genau einen Fall, in dem das nicht geht: ein Schlüssel, der selbst das Trennzeichen enthält. Bei {"a.b": 1} ist der flache Pfad "a.b" nicht von einem verschachtelten {"a":{"b":1}} zu unterscheiden. Dieses Werkzeug erkennt das und warnt Sie, statt etwas zu erzeugen, das nicht zurückkommt. Wählen Sie dann ein anderes Trennzeichen.

Arrays: Indexschreibweise oder Klammerschreibweise

Die Punktschreibweise ergibt tags.0 und tags.1. Die Klammerschreibweise ergibt tags[0] und tags[1]. Beide überstehen hier den Hin- und Rückweg, und der Eingabeparser akzeptiert beide.

Die Punktschreibweise ist das, was json_normalize aus pandas erzeugt und was die meisten CSV-Pipelines erwarten. Die Klammerschreibweise liest sich besser, wenn ein Schlüssel plausibel numerisch sein könnte, denn tags[0] und tags.0 sind auf eine Weise mehrdeutig, wie tags["0"] es nicht ist.

Wo dabei Information verloren geht

Ein numerischer Objektschlüssel ist nach dem Flachmachen nicht mehr von einem Array-Index zu unterscheiden. {"2024": {"total": 1}} wird zu "2024.total", und der Rückweg mit eingeschalteter Array-Erkennung erzeugt ein Array mit 2024 leeren Plätzen.

Schalten Sie „numerische Schlüssel als Arrays“ aus, wenn Ihre Schlüssel tatsächlich numerische Zeichenketten sind - üblich bei allem, was nach Jahr, HTTP-Statuscode oder ID abgelegt ist.

How to do this in code

Flach machen im Code.

import pandas as pd

# The workhorse. sep defaults to '.'
df = pd.json_normalize(records)

# Explode a nested array into one row per element
df = pd.json_normalize(
    records,
    record_path='items',
    meta=['id', 'created_at'],
)

# Every leaf as a dotted path
jq -r 'paths(scalars) as $p | "\($p | join(".")) = \(getpath($p))"' in.json

# A flat object rather than lines
jq '[leaf_paths as $p | {(($p | map(tostring) | join("."))): getpath($p)}] | add' in.json

function flatten(value, prefix = '', out = {}) {
  if (value && typeof value === 'object') {
    const entries = Array.isArray(value)
      ? value.map((v, i) => [i, v])
      : Object.entries(value);
    if (entries.length === 0) {
      out[prefix] = value;      // preserve {} and []
      return out;
    }
    for (const [k, v] of entries) {
      flatten(v, prefix ? `${prefix}.${k}` : String(k), out);
    }
    return out;
  }
  out[prefix] = value;
  return out;
}

Häufige Fragen

Welches Trennzeichen soll ich nehmen?

Einen Punkt, sofern Ihre Schlüssel keine Punkte enthalten. Der Unterstrich ist die übliche zweite Wahl, und ein Schrägstrich ist nützlich, wenn das Ergebnis irgendwohin geht, wo ohnehin in Pfaden gedacht wird.

Kann ich nur einen Teil des Dokuments flach machen?

Setzen Sie eine Tiefenbegrenzung. Alles darunter bleibt ein verschachtelter Wert - genau das, was Sie wollen, wenn der tiefe Teil ein undurchsichtiger Block ist, den Sie speichern statt abzufragen.

Was passiert mit null?

Es bleibt standardmäßig erhalten, als flacher Schlüssel mit dem Wert null. Es gibt eine Option, nulls wegzulassen: nützlich für einen Diff und gefährlich für den Rückweg.