JSON to CSV

JSON is built to represent arbitrarily nested, tree-shaped data — objects inside objects, arrays inside objects, values of genuinely different types sitting side by side — while CSV can only represent one flat, uniform table: rows and columns, every row with the same set of columns, every cell a single plain value. Converting from the first shape to the second necessarily means making decisions about how to flatten something that does not naturally fit into rows and columns, which is where most of the actual complexity in this kind of conversion lives — not in reading the JSON syntax itself, which is straightforward, but in deciding what a spreadsheet row should even mean for data that was never tabular to begin with.

A nested object like `{"user": {"name": "Ada", "id": 42}}` has no single obvious column to become in a flat table, so it flattens into two separate columns — `user.name` and `user.id` — with the dot notation preserving exactly where each value came from in the original structure. This is a widely recognised convention specifically because it is reversible: a column named `user.name` unambiguously describes a path back into a nested structure, which matters if the CSV ever needs to be converted back to JSON or imported into a system that understands dotted paths as nested fields.

Nested arrays are handled differently, and deliberately so: rather than exploding an array into additional rows — which would change how many rows the table has depending on how many nested items happen to be inside one record, a genuinely surprising and often unwanted side effect — an array value is serialised as JSON text inside a single cell. The row count stays predictable and matches the input record count exactly, which is almost always what someone converting to a spreadsheet actually wants, at the cost of that one cell needing further parsing if its contents are needed individually.

Real API responses and hand-assembled JSON frequently contain records where not every object has identical keys — an optional field present on some records and absent on others, or a schema that evolved over time so older and newer records differ slightly. CSV cannot represent that variation directly, since every row needs to align to the same fixed set of columns; a program reading a CSV file has no way to know a row is "missing" a column unless every row explicitly has a cell for it. The resolution is computing the union of every key seen across every record, in the order each key was first encountered, and filling an empty cell for any record that is missing a given field — so the shape stays consistent across the file without silently dropping any record's columns or misaligning values into the wrong column.