How to flatten JSON into paths and values, and back again

Flattening turns a nested JSON document into a single-level list of paths and values, such as "user.name": "Ana". It is what a nested document needs before it can meet something that has no concept of nesting: an environment file, a spreadsheet column, a translation catalogue, anything built from key and value pairs with no structure of its own.

Why flatten a document at all

A few concrete cases come up often enough to name directly.

Spreadsheets and CSV exports have columns, not nested objects, so a report built from JSON data usually needs one column per path before it can be opened in a spreadsheet at all. Environment files (.env, Java properties, some CI variable lists) are flat key and value pairs by format, so a config object has to be flattened before it can populate one. Translation catalogues are commonly a flat map from a dotted key like nav.home to a string, which is itself a flattened view of a nested {"nav": {"home": "..."}} source. And a diff tool that only understands flat key and value pairs can compare two flattened documents line by line, which is easier to read than a nested diff for a document that is mostly leaves.

Using the JSON flattener

Choose a direction and a path style, since there is no single standard for how a flattened path should be written. Three spellings are offered, and the tool states which one is in force rather than picking one silently.

Flattening

{"user":{"name":"Ana","tags":["a","b"]},"empty":{}}

with the dotted style returns:

{
  "user.name": "Ana",
  "user.tags.0": "a",
  "user.tags.1": "b",
  "empty": {}
}

Nested keys become dotted paths, array elements get their index appended, and the empty object is kept as a value in its own right rather than vanishing, since without it there would be nothing to give a path to and the document would not survive the round trip back.

Two genuinely ambiguous cases, handled in the open

A key that already contains the separator character would produce a path nobody could read back correctly, so the tool refuses it by name: a key like "a.b" under the dotted style is rejected with a message naming the key and suggesting a different path style, rather than silently producing a broken path.

Going the other way, unflattening, a path segment made only of digits could mean either an array index or an object key that happens to be numeric, and nothing about a flattened document says which. “Digits are array indexes” is a toggle for exactly this reason: guessing wrong turns an object keyed by year into an array with thousands of empty slots.

Round tripping

Unflattening the example above, with the same path style, returns the exact original document: the nested object, the two element array in its original order, and the empty object preserved rather than dropped. That round trip is the real proof that a path style’s dots and indexes were read back correctly, since a wrong assumption about array indexing usually only shows up once you convert back and compare against the original.

Keep empty containers

Turning this off drops empty objects and arrays entirely rather than keeping them as flat entries, which is useful when the flat form is headed somewhere that cannot hold an empty value at all, such as certain environment file formats.

Flatten arrays too

By default, arrays are flattened element by element, so "tags": ["a", "b"] becomes two separate rows, tags.0 and tags.1. Turning off “Flatten arrays too” keeps an array as a single value instead: tags stays one row holding the whole array literal. This matters when the destination genuinely wants an array back, such as a CSV column that should hold a comma-separated list rather than two indexed columns. Unflattening respects the same choice: with the toggle off, a row whose value is an array literal is read back as one array rather than rejected as an unexpected nested structure.

Frequently asked questions

What is flattening for? It turns a nested document into a flat list of paths and values so it can populate something with no concept of nesting, such as a spreadsheet column, an environment file, or a translation catalogue.

Why does unflattening ask about digits? A path segment made only of digits could be an array index or a numeric object key, and a flattened document does not record which. The toggle removes the guess.

Will I get my document back exactly? Yes, provided the same path style and toggles are used on the way back. The tool’s own round-trip tests cover nested objects, arrays kept whole or split, empty containers, null, and empty strings.