Nested JSON - flatten - CSV
Flatten nested JSON to CSV
Updated: May 2026
APIs often return nested objects: customer.address.city, order.total.amount, product.category.name. To analyze this data in a spreadsheet, flatten the structure into CSV columns without losing the relationship between fields.
Free - No upload - Browser-based conversion
Common nested JSON structures
Most REST APIs return objects with sub-objects for logical grouping: user profile with an address block, order with a shipping and billing address, product with a category object and a pricing block. Here is a realistic example from a user API:
[{
"id": 1,
"user": {
"name": "Alice",
"address": { "city": "London", "country": "GB" }
},
"order": { "total": 49.9, "currency": "GBP" }
}]Without flattening, this cannot be represented in a flat CSV. With flattening enabled, each nested property becomes a column using dot notation.
What flattening produces
The nested structure above produces the following CSV:
id,user.name,user.address.city,user.address.country,order.total,order.currency
1,Alice,London,GB,49.9,GBPDot notation keeps column names readable and unambiguous — user.address.city is clearly different from order.address.city, which matters when both exist in the same dataset.
Nested arrays: the hard case
A JSON object may contain an array of sub-objects, such as an order with multiple line items. This is the hardest case to flatten, because a flat CSV has one row per record and arrays imply multiple rows per parent record.
The available strategies are:
- Raw — the entire array is JSON-stringified into a single cell. Keeps the row structure simple but makes the cell hard to read in Excel.
- Joined — scalar values in the array are joined with a comma into one cell (useful for simple tag arrays).
- Expanded — one CSV row per array element, repeating the parent fields. Produces more rows but is easier to filter and pivot.
Limits to anticipate
- Excessive depth — JSON nested 3 or more levels deep produces very long column names (a.b.c.d.e) that are hard to work with in Excel.
- Heterogeneous arrays — arrays containing objects of different shapes produce sparse columns with many empty cells.
- Key collisions — if two different paths flatten to the same column name, one value overwrites the other.
How to do it with Flowfiles
- Open the converter.
- Paste the nested JSON.
- Keep JSON to CSV mode selected.
- Enable object flattening.
- Choose how arrays are handled (raw, joined or expanded).
- Convert and review the generated columns.
Frequently asked questions
How deep does flattening go?
The tool flattens all levels recursively. A path like a.b.c.d becomes a single column name. There is no hard depth limit, but deeply nested structures produce long column names that may be truncated in some spreadsheet applications.
What happens to arrays of nested objects?
Arrays of objects cannot be flattened into a single row without a strategy choice. The tool offers raw (JSON text in a cell), joined (comma-separated scalars) or expanded (one row per element). Choose expanded when you need to filter or pivot by array items.
Do dot-notation columns import correctly in Excel?
Excel treats the dot as a regular character in a column name — it does not interpret it as a hierarchical separator. Columns named user.name and order.name will appear as-is in the header row. Some database import tools (like MongoDB) do interpret dot notation during import.
Can I disable flattening?
Yes. When flattening is disabled, nested objects are serialized as JSON strings inside their CSV cell. This preserves the data but makes the cell content difficult to use directly in a spreadsheet.
How do I handle JSON keys that already contain a dot?
A key like "file.name" at the top level would be indistinguishable from a flattened path file -> name. This is a known ambiguity in dot-notation flattening. If your JSON uses dots in key names, consider preprocessing the JSON to rename those keys before flattening.
Is the output always valid CSV?
Yes. The flattener produces well-formed CSV — values containing commas or quotes are properly quoted and escaped. The output can be loaded into any CSV-aware tool.
Can I reconstruct the JSON from the flattened CSV?
Partially. Flat scalar paths (user.name, order.total) can be reconstructed into nested objects using the dot notation. Arrays that were stored as raw JSON in a cell can also be parsed back. Expanded arrays (one row per element) are harder to reconstruct without knowing the original array key.