JSON Flatten / Unflatten

Flatten nested JSON to dot-notation keys, or unflatten dot-notation back to nested objects.

Direction

JSON Input

Drop a .json file

Flattened JSON

{
  "user.name": "Alice",
  "user.address.city": "NYC",
  "user.address.zip": "10001",
  "tags": [
    "a",
    "b"
  ]
}

When is JSON flattening useful?

Flattened JSON is useful for storing nested data in flat-key stores like Redis, environment variables, or CSV files. Each nested key becomes a single dot-notation path — for example, user.address.city instead of a nested object. This makes it easy to compare configs, diff two JSON documents field by field, or feed structured data into tools that only accept flat key-value pairs. Arrays are preserved as-is in the flattened form since they cannot be expressed as dot-notation keys without ambiguity.

Built and maintained by Meet Shah · Last updated 19 July 2026

What this tool is used for

Turning a nested config into dot-notation keys for a flat key-value store.
Producing a flat structure so two documents can be diffed key by key.
Preparing nested data for a system that only accepts flat maps.
Unflattening a dot-notation config back into nested form for readability.
Finding which deep key holds a value by searching the flattened output.

Frequently Asked Questions

What does flattening a JSON object produce?: A single-level object whose keys are dotted paths — `{"user":{"name":"Alice"}}` becomes `{"user.name":"Alice"}`. Arrays get bracketed indices. It is the shape needed by anything that cannot represent nesting: a CSV column set, an environment file, a form encoding.
Is the operation reversible?: Usually, and the tool does both directions — but not always exactly. A key that already contains a dot becomes ambiguous, and an empty object or array flattens to nothing, so unflattening cannot know it was ever there. Round-tripping structured config is safe; round-tripping arbitrary JSON is not.
How are arrays represented?: By index in brackets: `tags[0]`, `tags[1]`. That preserves order, which dotted keys alone would not, and it lets the unflatten step tell an array from an object with numeric keys — a distinction that matters because JSON treats them as different types.
Why flatten JSON at all?: Because a lot of infrastructure is flat. Environment variables, most form encodings, spreadsheet columns, many analytics event schemas and several document databases' query languages all take a flat key-value map, so the nesting has to be encoded into the key.
What happens to a null or an empty object?: `null` survives as a value. An empty object or array vanishes, because flattening walks the leaves and an empty container has none. That is the main asymmetry to know about before relying on a round trip, and it is inherent to the representation rather than a bug.

Common errors and gotchas

Having a key that already contains a dot, which becomes an unintended level of nesting on unflatten.
Losing the distinction between an array index and an object key with a numeric name.
Producing keys that collide, where a value and a nested object share a path.
Assuming the round trip is lossless, which it is not once separators appear inside key names.
Flattening an empty object or array, which has no keys and simply disappears.