Flatten Nested JSON: Dot-Notation Keys

Nested JSON is great for transport and bad for ingestion. Spreadsheets want one row of headers; SQL columns want flat field names; analytics events want predictable property keys. Flattening — collapsing every nested path into a single dot-notation key — is the standard fix. This guide shows the conversion, the edge cases, and when not to flatten.

Drop your data into the JSON flatten tool for an instant result, or read on for how it works.

TL;DR

Flattening rewrites a nested JSON value as a flat object whose keys are dotted paths to each leaf. { "user": { "name": "Otter" } } becomes { "user.name": "Otter" }. Arrays become numeric segments: items.0.sku. The shape is fully reversible as long as no source key contains a dot or a digit-only string.

Step 1 — Flatten a nested object

The simplest case: nested objects become dotted keys.

Input

{
  "id": "u_001",
  "user": {
    "name": "Otter",
    "email": "otter@example.com"
  }
}

Output

{
  "id": "u_001",
  "user.name": "Otter",
  "user.email": "otter@example.com"
}

Every leaf is now a top-level field. Importing this into a CSV is a one-step operation: the keys become the column headers, the values become the cells.

Step 2 — Flatten arrays

Arrays get their indexes added as numeric path segments.

Input

{
  "id": "ord_A100",
  "items": [
    { "sku": "widget", "qty": 2 },
    { "sku": "gadget", "qty": 5 }
  ]
}

Output

{
  "id": "ord_A100",
  "items.0.sku": "widget",
  "items.0.qty": 2,
  "items.1.sku": "gadget",
  "items.1.qty": 5
}

This is faithful but rarely what you want for analytics — the schema changes with the array length. For tabular output where each array element is a row, see the explode strategy in the JSON to CSV guide.

Step 3 — Decide your separator

The dot is conventional but not universal. Three common choices:

Separator	Example	When to use
.	user.email	Default. Works everywhere except when keys contain dots.
/	user/email	JSON Pointer style (RFC 6901). Use when keys might contain dots.
[] notation	user[0].email	Familiar from JS. Disambiguates indexes from string keys.

Pick one per project. Mixing separators in the same dataset is the fastest path to a parser that "kinda works".

Step 4 — Handle edge cases

Empty objects and arrays

{ "a": {}, "b": [] }

Most tools omit these entirely from the flat output — there are no leaves to address. That's the right default; if you need to preserve them, switch to the JSON Pointer form which can encode empty containers as terminal paths.

Null values

{ "x": { "y": null } }

Becomes { "x.y": null }. The null is preserved as a value. Don't confuse it with "field missing" downstream.

Keys with dots in them

{ "user.name": "Otter" }

If the input keys already contain dots, the flat output is ambiguous: you can't tell whether a.b.c came from { a: { b: { c } } }, { "a.b": { c } }, or { "a.b.c": ... }. Switch to a separator that doesn't appear in your keys.

Deeply nested structures

{ "a": { "b": { "c": { "d": { "e": 1 } } } } }

Flattens to { "a.b.c.d.e": 1 }. Functionally fine, but key length grows linearly with depth — at six or seven levels, the column headers become unreadable. Consider whether the source needs to be that deep before flattening.

When to flatten and when not to

Flatten when

• You're exporting to a tabular format (CSV, spreadsheet, SQL columns).
• You're sending data to an analytics tool that wants flat event properties (Amplitude, Mixpanel, Segment).
• You're indexing values in a search engine that needs flat field names.
• You need to diff structurally different payloads — flat keys make additions and removals obvious.

Don't flatten when

• The consumer can handle nested objects (most modern APIs).
• Arrays vary in length — flattened keys become row-specific schemas that no consumer can handle.
• The nesting carries meaning (a tree, a graph) that flat keys would erase.

Use it before JSON-to-CSV

Flattening is a useful pre-step for the JSON to CSV converter: once everything is a leaf, the CSV step is just "map each key to a column". For inspecting the structure first, the interactive JSON tree viewer makes it obvious where the leaves live.

If you only want some keys flattened — for example, a user object flattened but the rest left intact — the JSON query tool can extract the subtree first and the flattener handles the rest.

Flatten in the browser, no upload

The free JSON flatten tool on JSONZen runs entirely client-side. It supports dot, slash, and bracket-notation output, handles arrays correctly, and never sends your data to a server. Useful for any payload containing internal identifiers, customer data, or anything that shouldn't leave your machine.

Closing recommendation

Flatten right before the boundary where flatness is required — CSV export, analytics ingest, search index. Don't flatten in the middle of your application and pass the flat shape around: the nested form is easier to read, easier to type, and easier to evolve.