Flattening is lossy, and that is fine
JSON is a tree; CSV is a rectangle. Every conversion has to decide what to do with the parts that do not fit, and pretending otherwise produces surprises:
- Nested object → dotted columns,
address.city - Array → JSON text in the cell
- null → empty cell
- Missing key → empty cell, column still present
If you need the tree back afterwards, keep the JSON. CSV is an export format here, not a storage format.
The union header
Real data is ragged: some records have a note, some do not. Taking the first
record's keys as the header would drop every column that only appears later.
This uses the union of all keys, in the order they were first seen, so nothing
is quietly lost.
Quoting you can rely on
A value gets quotes when it contains the delimiter, a quote, a newline, or leading and trailing whitespace. Internal quotes are doubled. That is the RFC 4180 rule, and it is what makes a file with an address column open correctly rather than shifting every subsequent field one to the right.
Questions
What happens to nested objects?+
They become dotted column names, so an address object with a city inside produces a column named address.city. Nesting has no representation in a flat table, and dotted paths are the convention every spreadsheet user already recognises.
What happens to arrays inside a record?+
They are written as JSON text in the cell. There is no correct flat representation of a list in a single cell, and inventing one — semicolon-joining, say — silently corrupts any value that contains a semicolon.
My records have different keys. Does that work?+
Yes. The header is the union of every key seen, in first-seen order, and a record missing a key gets an empty cell. Using only the first record's keys, which many converters do, would silently drop columns.
Will it open correctly in Excel?+
The quoting is correct per RFC 4180, so values containing commas, quotes and newlines survive. If your locale uses the comma as a decimal separator, pick the semicolon delimiter — otherwise Excel will split numbers across columns.