Turning Nested YAML Into Flat CSV Columns
Why CSV needs flat rows, how nested YAML becomes JSON in a cell, how the header union handles uneven records, and how to prepare data.
Why CSV wants a flat grid
A CSV is a plain grid of rows and columns where every cell holds a single value. YAML, by contrast, can nest mappings inside mappings and lists inside lists to any depth. To bridge the two, the converter treats each top-level record as one row and each key as one column. That works cleanly when your data is a list of shallow records, which is exactly the shape a spreadsheet expects.
How nested values are handled
When a value is itself an object or an array, it cannot fit a flat cell as-is, so it is serialised to compact JSON. An address mapping becomes text like {"city":"Portland"}, and a tags list becomes ["lead","eng"]. The JSON stays intact and readable, and because it may contain commas or quotes, the CSV writer wraps the cell in quotes so the structure is preserved. This keeps the export lossless even though the layout is flattened.
The header is a union of keys
Records in real YAML are not always uniform, so the header row is built from the union of keys found across all records rather than just the first one. If one person has an age and another has a city, both age and city become columns and each row fills only the fields it has. Missing fields are left blank, which means uneven records still produce a tidy, aligned table instead of a ragged one.
Preparing YAML for a clean export
For the neatest CSV, shape your YAML as a list of records that share the same keys and keep values shallow. If a field is naturally nested, decide whether you want it flattened into JSON text or split into separate top-level keys before converting. Choosing a delimiter that does not clash with your data, such as a pipe when values contain commas, can also make the file easier to open. A little tidying up front usually beats reformatting the CSV afterwards.