How-to guide

How to Flatten Nested JSON

Flattening rewrites a nested document as one level of keys, joining the path with dots so that user.address.city becomes a single key. It is how JSON is loaded into a spreadsheet, a column store or an environment-variable set. It reverses cleanly unless keys already contain dots, or arrays are indexed into the key names.

JSON Flatten

Turn nested JSON into a flat map of dot-separated paths.

Open the tool

Nested JSON is natural to produce and awkward to consume. Anything expecting rows and columns — a CSV export, a database table, a analytics warehouse — needs one level, and flattening is the standard way to get there.

The operation is usually reversible, which is what makes it safe. The two exceptions are worth knowing before you flatten something you intend to reconstruct later.

Step by step

Choose the path separator
A dot is conventional and reads well. Choose something else if your keys already contain dots, because the separator has to be a character that never appears in a key name or the path becomes ambiguous.
Decide how arrays are handled
Arrays are usually flattened by index, so tags becomes tags.0 and tags.1. That is reversible but produces a different key set for every record, which matters if you are building spreadsheet columns from the keys.
Flatten and check the deepest path
Look at the longest key in the output. It shows the true depth of the document and often reveals nesting nobody knew was there — a wrapper object around the payload, for example.
Watch for key collisions
If a document contains both a key literally named a.b and a nested a containing b, both flatten to the same key and one silently wins. This is rare but silent, which is what makes it dangerous.
Unflatten to restore the structure
The reverse operation rebuilds the nesting from the paths. Round-trip a sample before relying on it: flatten, unflatten, and compare against the original to confirm nothing was lost.

Example

A two-level document and its flattened form. Note how the array becomes indexed keys.

Nested

{
  "user": { "name": "Ada", "address": { "city": "London" } },
  "tags": ["admin", "dev"]
}

Flattened

{
  "user.name": "Ada",
  "user.address.city": "London",
  "tags.0": "admin",
  "tags.1": "dev"
}

Frequently asked questions

What does flattening JSON mean?

Rewriting a nested document so every value sits at the top level, with the path to it joined into the key. user.address.city replaces three levels of nesting with one key, which is what tabular formats and column stores require.

Can flattening be reversed?

Usually yes — unflattening splits each key on the separator and rebuilds the structure. It fails only when a key already contained the separator, or when a collision meant two different values mapped to the same flattened key.

How are arrays flattened?

By index, so tags becomes tags.0, tags.1 and so on. This preserves order and reverses correctly, but it means records with different array lengths produce different key sets — awkward when the keys are becoming spreadsheet columns.

Why would I flatten JSON at all?

To load it somewhere that expects one level: a CSV export, a relational table, an analytics warehouse, or a set of environment variables. It is also a quick way to see the true depth and shape of an unfamiliar document.

What happens to empty objects and arrays?

They have no leaf values, so they usually vanish from the flattened output entirely. That makes the round trip lossy for documents where an empty array is meaningfully different from an absent key.

Tools used in this guide

All tools →

All guides →

Last reviewed 28 August 2026.