What Does Flattening a JSON Mean? The Term Explained (2026 Guide)

The word itself: what "flat" means in data

Forget JSON for a moment and picture the word. A flat surface has no bumps, no layers, no hidden depth: everything sits at the same level, visible at once. Data people borrowed that image. Flat data is data with no nesting: every value sits at the top level, one value per slot, nothing tucked inside anything else.

A spreadsheet row is the purest example of flat data. One row, one set of columns, one value per cell. The value in cell C4 does not contain another spreadsheet. It contains text, or a number, or nothing. That is flat.

JSON, by contrast, is almost never flat. It nests: objects hold objects, arrays hold objects, objects hold arrays. A customer record can carry an address object, which carries coordinates, which carry a pair of numbers. That nesting is JSON's whole point, and it is also the reason the word "flattening" exists at all. You cannot pour a tree into a table without doing something to the branches. Flattening is the name for that something.

So when someone says "flatten the JSON", they mean: rewrite this nested structure so that every value lives at the top level, with names that record where it came from. The value itself does not change. Its address changes, from a path through nested objects to a single flat name.

Why the word exists: JSON nests, CSV does not

Here is the tension in one picture. JSON is a tree: branches, sub-branches, leaves. CSV is a table: rows and columns, and nothing deeper. A CSV cell cannot hold an object. It can only hold text. So any conversion from JSON to CSV must answer the same question: what do we do with the nesting?

There are only a few possible answers, and "flattening" is the most common one. Take this real record, the kind an API might return:

Nested: the address object lives inside the customer record

{
  "id": "A-101",
  "customer": { "name": "Amelia", "city": "Austin" },
  "tags": ["new", "vip"]
}

The customer object is one level down. The tags list is one level down. A CSV has no "one level down", so the flattened version pulls everything up to the surface. Verified output from the converter on this page:

What flattening actually does, step by step

Flattening is not one trick, it is four small rules applied everywhere. Run the record above through the converter on this page with flattening on, and here is exactly what comes out, verified on the build machine:

Flattened: depth 1, one value per slot (verified converter output)

{
  "id": "A-101",
  "customer.name": "Amelia",
  "customer.city": "Austin",
  "tags": "new; vip"
}

Rule one: nested objects become dot-notation columns. The path to the value becomes the name: customer.name, customer.city. The dots are just breadcrumb trails. Nothing about Amelia's name changed, only its address label did.

Rule two: short lists of plain values get joined into one cell. "new" and "vip" became the single text "new; vip". The two values are still there, but they are now one string with a separator, and the fact that there were two of them is no longer machine-readable.

Rule three: lists of objects cannot be joined sensibly, so they collapse into JSON text inside a single cell. An items list like [{"sku":"B1","qty":2}] becomes one long quoted cell. The data survives, but as text you would have to parse again, not as structure.

Rule four: null and empty values become empty cells. There is no way to write "explicitly nothing" in a flat table, so null simply vanishes into a blank. Keep this one in mind: after flattening, you cannot tell "was null" apart from "was an empty list" or "was missing entirely".

Compare that with flattening switched off on the same data, and the difference is the whole meaning of the word. With the toggle off, the customer object stays as one cell of JSON text: {"name":"Amelia","city":"Austin"}. The data is not lost, but it is not flat either: there is still nesting inside the cell, and a spreadsheet will show you an unreadable blob. Flat means flat all the way down, one value per cell, no exceptions.

The confusion to clear up: flattening is not minifying

Ask five beginners what "flatten a JSON" means and one of them will do this: delete all the newlines and spaces, producing one giant single line. That is minifying, not flattening, and the distinction matters because the words sound related but describe completely different things.

Minifying changes whitespace. Flattening changes structure. A minified JSON file is still nested, it is just nested on one line. Verified on the build machine: parsing the minified and pretty-printed versions of the same record produces byte-identical structures, and the customer object is still an object either way. The tree did not move. Only the paint changed.

Minified is still nested (depth 2); flattened is depth 1

# minified: no whitespace, STILL nested -> customer is an object
{"id":"A-101","customer":{"name":"Amelia","city":"Austin"},"tags":["new","vip"]}

# flattened: depth 1, nothing nested at any width
{"id":"A-101","customer.name":"Amelia","customer.city":"Austin","tags":"new; vip"}

Why does the confusion happen? Because in casual speech, "flat" sometimes means "one line", as in "flatten this into one line". In data work, "flat" means "no nesting". If a tutorial tells you to flatten JSON before importing it into a spreadsheet, it means the structural kind: dot-notation columns, joined lists, one value per cell. Deleting whitespace will not help your import one bit.

The same idea wears different names

Once you know what flattening means, you start seeing it everywhere, wearing different clothes. In Python's pandas library, the function is called json_normalize, and "normalize" is doing exactly the flattening job: nested objects become dot-notation columns. Verified in our earlier testing: it flattens customer.address into customer.city the same way the converter on this page does.

In Excel's Power Query, the button says "Expand": you click the little double-arrow on a column of nested records and it expands them into new columns. Same idea, friendlier verb. In SQL, UNNEST turns a nested array into rows. Same family.

One honest warning: in jq, the command-line JSON tool, "flatten" means something narrower. jq's flatten collapses nested arrays into one array, it does not turn objects into dot-notation paths. If a jq tutorial says "flatten", check which meaning it means before assuming. The data world reuses its words loosely, and this is the one place the term genuinely splits.

Flattening also has two close cousins worth naming, because people mix up all three. Flattening keeps one row per record and widens the columns. Exploding keeps the columns and multiplies the rows: one row per list item. Joining folds a list into a single cell, which is what rule two above does to short lists. Our guide to flattening the JSON data walks through the explode-or-join decision with real examples, and our toggle deep-dive shows what the converter's own flatten switch does cell by cell.

What flattening costs you

Flattening is honest work, but it is lossy work, and the losses are worth naming before you click anything. First, the shape is gone for good. After flattening, nothing records that city and state were siblings inside one address object. They are just two columns that happen to share a prefix.

Second, dot-notation has an ambiguity nobody warns you about. If your JSON literally contains a key called "a.b" at the top level AND a nested object a with key b, both flatten to the same column name, and one value silently overwrites the other. Rare in practice, brutal when it hits.

Third, joined lists lose their count as data. "new; vip" looks like one string. A program reading the CSV cannot know it was two tags without splitting on the separator, and if a tag itself ever contains a semicolon, even that breaks.

Fourth, types collapse. 101 becomes the characters "101". true becomes the characters "true". Whatever opens the CSV decides what they mean, and Excel in particular loves to reinterpret your data: leading zeros vanish, long IDs become scientific notation. The values survived flattening; they may not survive the spreadsheet.

None of this means flattening is wrong. It means flattening is a one-way trip, and you should keep the original JSON as your source of truth. Flatten a copy, work on the copy, and never throw away the tree you flattened it from.

Should you flatten? A 60-second decision

Your destination decides, not your data. If the destination is a spreadsheet, a CSV import, or a human scanning rows, flatten: that is what those tools are built to consume, and a flattened file opens cleanly everywhere.

If the destination is another program, an API, or a round trip back to JSON later, do not flatten. Keep the nesting, because every flattening loss listed above becomes a bug you have to unpick on the way back.

If you are unsure, flatten a copy and eyeball it. Open the CSV, check that the dot-notation columns make sense, that the joined lists look right, that nothing important became an unreadable blob. Sixty seconds of looking beats an hour of debugging a bad import.

Spreadsheet, CSV import, human review: flatten, it is what those tools expect.
API, database, round-trip back to JSON: keep the nesting, flattening losses become bugs.
Unsure: flatten a copy, open it, and check the columns before committing.

Try it on this page

The converter at the top of this page flattens by default. Paste any nested JSON into it and watch the preview: nested objects become dot-notation columns, lists join with "; ", and every cell holds exactly one value. Toggle flattening off and paste the same JSON to see the difference the word makes: nested blobs in cells versus a clean flat table. That side-by-side, on your own data, is the fastest way to make the term stick.

If your JSON has lists of objects you actually want as rows, flattening alone will not do it: that is exploding, a different operation, and our data-prep guide covers exactly when to explode instead.

Related guides

Frequently asked questions

What does flattening a JSON mean in simple terms?

It means rewriting nested JSON so nothing is nested anymore. Objects inside objects become dot-notation names like customer.city, short lists become one joined cell, and every value sits at the top level, one per cell. The result is a flat table, which is what CSV files and spreadsheets need.

Is flattening JSON the same as minifying it?

No, and this is the most common confusion. Minifying removes whitespace, producing one long line that is still fully nested. Flattening changes the structure itself, pulling nested values up to the top level. A minified file parses to the exact same tree; a flattened file is a different, shallower shape.

Does flattening a JSON file change my data?

It changes the shape, not the values. Every leaf value survives, but nesting becomes dot-notation columns, lists become joined text, types collapse to text, and null becomes an empty cell. Keep the original JSON as your source of truth and treat the flattened file as a working copy.

What is the difference between flattening and exploding JSON?

Flattening keeps one row per record and widens the columns: nested paths become new columns. Exploding keeps the columns and multiplies the rows: each item in a list gets its own row, with the rest of the record repeated. Flatten a customer with three tags and you get one row with a "tag1; tag2; tag3" cell; explode it and you get three rows. Our data-prep guide covers when to choose which.

Why do CSV files need flat data?

Because a CSV has only rows, columns, and text. There is nowhere to put nesting: a cell cannot contain an object, only characters. So nested structures must be flattened (or packed as JSON text in a cell) before they can live in a CSV at all.

Can I unflatten a CSV back to nested JSON?

Only approximately. Dot-notation columns like customer.city can be regrouped into nested objects by a script, and some tools do this, but the information flattening destroyed is gone: joined lists cannot reliably split back into arrays, types are guesswork, and null versus missing is unknowable. If you need the nesting back, keep the original JSON.

Does the JSON to CSV converter on this page flatten automatically?

Yes, flattening is on by default: paste nested JSON and the preview shows dot-notation columns immediately. You can switch it off, in which case nested objects and arrays stay as JSON text inside single cells. For spreadsheet work, leave it on.

Watch flattening happen live

Paste nested JSON into the converter and see flattening turn it into dot-notation columns. Free, no sign-up, runs entirely in your browser.

Open the JSON to CSV converter

All guides