How to Convert JSON to CSV: Flattening Arrays of Objects into Rows and Columns

Why the shape of your JSON matters

CSV is a flat, two-dimensional format: rows and columns, nothing more. JSON is a tree that can nest objects inside objects and arrays inside arrays. The clean case for conversion is a top-level array of objects, where each object becomes a row and each key becomes a column. Anything deeper has to be reshaped before it can fit into a grid.

Because different objects may carry different keys, the header row should be the union of every key seen, not just the keys of the first object. If you only read the first record, later columns silently vanish and the file becomes misaligned.

Flattening nested objects and arrays

The standard trick is dot notation. An object like {"address":{"city":"Lagos"}} becomes a column named address.city holding the value Lagos. Nesting can go as deep as you like: user.address.city is perfectly valid. Arrays are indexed by position, so tags containing ["api","web"] becomes two columns, tags.0 and tags.1.

Flattening works well when arrays are short and fixed in length. When an array can grow, indexed columns explode: a records with fifty tags produces fifty columns. In that case it is often cleaner to keep the array as a single joined string, such as "api;web;csv", or to split the data into a second related table.

Edge cases that break naive converters

The most common failure is quoting. If a value contains the delimiter (usually a comma), a double quote, or a line break, it must be wrapped in double quotes, and any double quote inside it must be doubled. So the value She said "hi" becomes "She said ""hi""". Skipping this corrupts every downstream row.

Other traps include null versus empty string (both usually render as an empty cell), booleans and numbers that a spreadsheet may reinterpret (a leading-zero code like 007 can lose its zeros), and encoding. Always write UTF-8, and consider a leading byte order mark if the file must open cleanly in older spreadsheet apps.

Frequently asked questions

What if my JSON is a single object, not an array?

Wrap it in an array so it becomes a one-row CSV. If you instead want each key on its own line, transpose it into a two-column key,value layout.

Which delimiter should I use, comma or semicolon?

The comma is the default in the CSV standard. Some regional spreadsheet setups expect a semicolon; if your values already contain commas, a semicolon or tab can reduce quoting.

How do I keep leading zeros from disappearing?

The zeros are in the CSV file; a spreadsheet drops them when it treats the column as a number. Import the column as text, or the spreadsheet will reformat it on open.

Can I round-trip the CSV back into JSON?

Partly. Flat columns convert back cleanly, but dot-notation keys need re-nesting and CSV loses type information, so numbers and booleans come back as strings unless you re-parse them.