JSON to CSV Deep Flattener
A flat JSON-array-of-objects converts to CSV trivially — one row per object, one column per key. Real JSON is rarely flat: API responses, webhook payloads, log entries, and config files are routinely three or four levels deep with arrays mixed in. Most JSON-to-CSV converters stop at the first level and stringify the nested objects, which is the wrong answer almost every time. This tool walks the full tree, flattens object paths into dot-notation column headers, and handles arrays with a configurable strategy.
How Deep Flattening Works
The tool walks every object in the input array and collects every leaf path it encounters. A leaf path is the chain of keys leading to a primitive value: user.address.city, order.total, metadata.tags. Each unique leaf path becomes a CSV column. For a given row, if the path exists with a value, that value goes in the cell; if it does not exist (because that record happened not to have an address, say), the cell is empty. The column ordering is stable: top-level keys first in their original order, then nested keys grouped under their parent. The result is the natural flat representation a spreadsheet user expects.
Array Handling Strategies
Arrays are the hard case. The tool supports three strategies: join, explode, and index. Join concatenates array elements with a delimiter (comma by default) into a single cell — best for tag lists where order does not matter much. Explode duplicates the row once per array element, so a record with three tags becomes three rows, each carrying one tag plus identical values for every other column — best when you want to filter or pivot by the array element later. Index expands the array into separate columns (tags.0, tags.1, tags.2) — best when array position is meaningful and the array length is consistent.
Use Cases and Source Shapes
API responses where each record has nested address, billing, or metadata objects flatten cleanly with the join or index strategy. Webhook payloads where each event carries an array of items (line items, attendees, attachments) are best handled with explode — you get one row per item in the array, with the parent event repeated, which is the natural shape for analytics tools. Survey export JSON where every question is a key under a responses object becomes a wide CSV with one column per question. Log entries with nested context objects (request, user, environment) flatten to a CSV that opens cleanly in any spreadsheet for filter-and-sort work.
Edge Cases and How They Are Handled
Mixed types in the same array (sometimes string, sometimes object) cause the path-collection pass to record both shapes; the resulting CSV has all union columns and cells where a given record had the wrong shape are left empty. Null values are preserved as empty cells rather than the literal string null. Keys containing dots in their actual name (rare but legal in JSON) are bracketed in the path: data["my.key"].value. Very deep nesting (10+ levels) is handled correctly but produces wide CSVs that may be unwieldy in spreadsheet tools; consider whether deep flattening is actually what you want or whether a hierarchical view would be more useful.
Pair this with related tools: JSON ↔ CSV Converter for the flat case in either direction, JSON Formatter to inspect the source structure first, CSV Cleaner for post-conversion cleanup, and CSV Row Filter to slice the result. The deep flattener is most useful as the first step in a pipeline that ends in a spreadsheet or a SQL table.
Frequently Asked Questions
Built by Derek Giordano · Part of Ultimate Design Tools