How Do You Flatten a JSON Array into a CSV Spreadsheet?
To flatten a JSON array into CSV, you turn each array item into one row and each field into a column. Nested objects usually get mapped into dot-notated headers like user.name or address.city, which keeps the structure readable without hand-editing commas like it's a cursed relic from 1998. If you want to do it fast, try our free JSON to CSV tool.
What flattening actually means
CSV is blunt on purpose. It wants rows, columns, and not much else. JSON, on the other hand, is happy to nest objects inside objects, and that is exactly why conversion gets messy.
Flattening is the act of taking a tree and making it look like a table. The simplest rule is: one top-level object becomes one CSV row, and every property becomes a column. If a property is nested, the usual move is to build the column name from the path.
For example, this JSON:
[
{
"id": 1,
"name": "Ari",
"address": {
"city": "Berlin",
"zip": "10115"
}
}
]usually becomes this CSV:
id,name,address.city,address.zip
1,Ari,Berlin,10115That path notation is not a standard law of physics. It is just a practical convention. Some tools use dots, some use underscores, and some let you choose the separator.
Why JSON arrays are the part that matters
Arrays are what make JSON to CSV feel straightforward at first. If the JSON value is an array of objects, you already have a natural row structure. That is the good case.
The annoying cases show up when the array contains nested arrays, optional fields, or objects with inconsistent keys. A spreadsheet likes the same columns on every row. Real-world JSON often disagrees.
Take a dataset from an API. One record may include profile, another may not. One user may have two phone numbers, another may have none. The converter has to decide whether to leave blanks, merge values into one cell, or split the structure into multiple rows.
If you are not sure which shape you want, ask one question: what will the spreadsheet be used for? Reporting, filtering, and pivot tables usually want a wide table. Data import into another system may prefer a more normalized shape. The conversion strategy follows the downstream job, not aesthetic purity.
How nested objects and arrays are usually handled
Nested objects are the easy part. They get flattened into compound column names. The result is readable, predictable, and friendly to spreadsheet sorting and filtering.
Arrays inside objects are where most tools start making tradeoffs. A few common approaches are:
- Join values into one cell, like
tag1, tag2, tag3 - Pick one element, usually the first, when the array is known to be single-valued in practice
- Expand the array into separate rows, repeating the parent data for each item
Each option has a cost. Joining values is compact but harder to filter. Expanding rows is great for analysis but can duplicate parent fields and blow up the row count. Picking one element is only safe when the schema guarantees it.
If you want a more surgical way to inspect structure before converting, our guide on what JSONPath is and how to query JSON like a pro is useful for slicing out the exact branch you care about.
Choosing headers that won't become a maintenance problem
The header row in CSV is the contract. Once the file leaves your browser, those column names matter to imports, scripts, and anyone trying to debug the result. Good headers are consistent, unambiguous, and boring in the best way.
Keep an eye on duplicate property names from different branches. If both billing.city and shipping.city collapse to city, you just created a headache. Prefixing with the full path avoids collisions and makes the file easier to scan later.
You should also decide how to treat missing values. Most converters emit blanks, which is usually fine. If a field is present in some rows and absent in others, a blank cell is better than inventing a placeholder unless your import system needs one.
Another practical detail: quote handling. CSV requires quoting when a cell contains commas, quotes, or line breaks. A proper converter escapes those values for you so your file stays valid. If you ever see broken columns after export, malformed quoting is one of the first things to check.
What can go wrong with messy JSON
Not every JSON file is a neat array of objects. Sometimes the top-level value is a single object. Sometimes the data is wrapped inside another property like data.items. Sometimes half the records have extra fields because someone shipped a feature at 4:57 p.m.
Before converting, confirm that you are feeding the tool the right branch. If the useful records live under response.results, extracting that array first saves you from flattening a giant envelope object into nonsense columns. If your JSON is malformed, fix the syntax first or the conversion will fail before it starts.
A few common problems to watch for:
- Trailing commas in JSON arrays or objects
- Mixed data types in the same field
- Deeply nested arrays that need a decision, not a guess
- Property names that differ only by case
If the problem is not the conversion but the input itself, validate it before you export. The JSON validator can catch syntax mistakes without making you squint at brackets like an archaeologist.
When CSV is the right output, and when it isn't
CSV is great when the target is a spreadsheet, a simple import pipeline, or a data review workflow. It is lightweight, easy to open anywhere, and still the default lingua franca for boring, useful tabular data.
CSV is a poor fit when your JSON depends on hierarchy. If the structure itself matters — for example, parent-child relationships, repeated subrecords, or variable-depth trees — flattening can destroy meaning. In those cases, you may want multiple CSVs or a different format entirely.
As a rule of thumb, use JSON to CSV when:
- Each record can reasonably become one row
- You want spreadsheet sorting, filtering, or pivoting
- Nested data can be safely represented as extra columns or joined text
Keep JSON when:
- The nesting is the point
- You need exact structure for an API or app
- Arrays contain meaningful ordered sub-items
The conversion is not about flattening everything into oblivion. It is about making the data usable in the next step without lying about what it is.
A Worked Example
Here is a realistic example: a simple array of customers, each with a nested address and a list of tags. This is the kind of data that shows up in exports, webhook payloads, and admin dashboards.
[
{
"id": 101,
"name": "Mina",
"email": "mina@example.com",
"address": {
"city": "Lisbon",
"country": "PT"
},
"tags": ["paid", "beta"]
},
{
"id": 102,
"name": "Jon",
"email": "jon@example.com",
"address": {
"city": "Dublin",
"country": "IE"
},
"tags": []
}
]A practical flattening strategy would produce something like this:
id,name,email,address.city,address.country,tags
101,Mina,mina@example.com,Lisbon,PT,"paid, beta"
102,Jon,jon@example.com,Dublin,IE,""Here, the nested object becomes two extra columns, and the tags array is joined into one cell. That works well if the tags are informational and you mostly care about the customer row as a unit. If tags are the real subject, you might instead expand them into separate rows:
id,name,email,address.city,address.country,tag
101,Mina,mina@example.com,Lisbon,PT,paid
101,Mina,mina@example.com,Lisbon,PT,beta
102,Jon,jon@example.com,Dublin,IE,Same source data, different shape, different use case. That is the whole game.
Frequently Asked Questions
How do I convert a JSON array to CSV?
Make sure the JSON is an array of objects, then flatten each object into a row. Nested fields are usually turned into dot-notated column names, and arrays are either joined, expanded, or reduced depending on the structure. The easiest path is to paste the JSON into a converter and export the CSV directly.
What happens if my JSON has nested objects?
Nested objects are usually flattened into separate columns with path-style headers like user.name or address.city. That keeps the relationship visible without nesting cells inside cells, which CSV cannot really do. If two branches share the same field name, the full path avoids collisions.
Can arrays inside JSON be converted to CSV?
Yes, but you need to choose a rule. You can join array items into one cell, create one row per item, or ignore the array if it is not relevant to the export. The right choice depends on whether the array is descriptive or something you need to query later.
Why does my CSV have blank cells after conversion?
Blank cells usually mean a field was missing in some JSON objects. That is normal when the array contains records with different shapes. CSV wants a fixed set of columns, so missing data is represented as empty cells unless the tool is configured otherwise.
The Bottom Line
JSON to CSV is really about shape management. You take nested, flexible data and turn it into something rows-and-columns tools can handle without complaining. The hard part is not the mechanics; it is deciding how to represent nested objects, arrays, and missing fields in a way that still makes sense later.
If you are cleaning API output, preparing a spreadsheet import, or just trying to inspect a messy payload, start with the simplest possible flattening rule and adjust only when the data demands it. If you want to skip the manual wrangling, use our JSON to CSV tool and let the browser do the boring part.
After that, check the headers, confirm the array handling, and make sure the exported file still matches the shape your next step expects. That is usually enough to keep the spreadsheet from turning into a pile of silent bad assumptions.