JSON to CSV Converter

JSON is hierarchical and CSV is flat, so this conversion is a genuine change of shape rather than a change of syntax. The mechanism is flattening: nested paths become column headers, so `{"user":{"city":"Oslo"}}` produces a column called `user.city`. Every leaf value in the document needs its own column.

That works cleanly when the JSON is an array of uniform, shallow objects, which is the case CSV was designed for - one object per row, one field per column. It works less well the further you get from that shape, and understanding why saves a lot of frustration.

The awkward case is nested arrays. A user with three phone numbers has to become either three columns (`phones[0]`, `phones[1]`, `phones[2]`) or three rows, and neither is obviously right. Columns break as soon as someone has four numbers. Rows duplicate every other field. There is no third option, because the mismatch is structural.

The header row has to be fixed before any data is written, which means every possible column must be known up front. If the objects in your array have different keys - a common situation with optional fields - the converter has to scan them all to build the union of keys, and every row then carries empty cells for the fields it lacks.

That is why a heterogeneous array can produce a very wide, very sparse spreadsheet. Fifty objects that each use ten of a hundred possible fields yields a hundred columns that are ninety percent empty. The data is complete; the presentation is poor. When that happens, the better move is usually to split the array by record type and convert each group separately.

Column order follows first appearance, so the keys of the first object come first. If a stable, predictable column order matters - because a downstream import depends on it - sort the keys before converting.

CSV is barely standardised. RFC 4180 exists but predates most implementations and is widely ignored, so the details vary: comma or semicolon as the delimiter, CRLF or LF as the line ending, whether quotes are doubled or backslash-escaped, and whether a byte order mark is expected.

Excel is the main reason these choices matter. On systems where the list separator is a semicolon - much of continental Europe - Excel will not split comma-delimited files into columns at all. It also needs a UTF-8 byte order mark to display non-ASCII characters correctly, and without one it will render accented and CJK text as mojibake.

Excel also transforms values on import in ways that lose data. Long numeric strings become scientific notation, so an ID like `1234567890123456` displays as `1.23457E+15`. Leading zeros are stripped, breaking postcodes and account numbers. Anything resembling a date is converted to one, which is how the gene name `SEPT2` became a date and prompted the genetics community to rename several genes. None of this is caused by the conversion, but all of it will be blamed on it.