JSON Flattening Notation Reference
Flattening turns a nested JSON value into flat columns so it fits a CSV file or a spreadsheet. Each leaf value gets a header that records its path: dots for object keys, [n] for array indices. These are the exact rules the JSON ↔ CSV converter applies in both directions, so a flattened file can be rebuilt into nested JSON.
Notation
| JSON value | Flattened header | Cell value |
|---|---|---|
| {"address":{"city":"Tokyo"}} | address.city | Tokyo |
| {"items":[{"sku":"A-1"}]} | items[0].sku | A-1 |
| {"tags":["red","blue"]} | tags[0] and tags[1] | red and blue |
| {"orders":[{"lines":[{"qty":1}]},{"lines":[{"qty":2}]}]} | orders[1].lines[0].qty | 2 |
| {"a.b":1} (key contains a dot) | ["a.b"] | 1 |
| {"x":null} | x | null (the literal word) |
| A key one record has and another lacks | the shared header | empty in the row that lacks it |
Array strategies
| Mode | Input | Resulting columns and cells |
|---|---|---|
| Index columns | {"tags":["red","blue"]} | tags[0] = red, tags[1] = blue |
| Join | {"tags":["red","blue"]} | one column tags = red|blue |
| JSON string | {"tags":["red","blue"]} | one column tags = ["red","blue"] as text |
| Expand to rows | {"tags":["red","blue"]} | two rows: tags = red, then tags = blue, other fields repeated |
Each strategy shown on the same input, {"tags":["red","blue"]}.
CSV quoting (RFC 4180)
| Cell contains | Emitted as |
|---|---|
| The delimiter (e.g. a comma) | Wrapped in double quotes: "a,b" |
| A double quote | Quoted, with the quote doubled: "say ""hi""" |
| A line break | Quoted; the line break stays inside the quotes |
| Plain text | Emitted as-is, no quotes |
Frequently asked questions
What is JSON flattening and why does CSV need it?
CSV is a flat grid: rows and columns, nothing nested. JSON allows objects inside objects and arrays inside arrays. Flattening encodes each leaf's position into its column header (address.city, items[0].sku) so the nesting survives as plain text that a spreadsheet can show and sort.
How do I get nested JSON back from a flattened CSV?
Parse the headers with the same notation: split on dots for object keys and read [n] as array indices. The JSON ↔ CSV converter does this with its Rebuild nested keys option, so a file flattened by these rules converts back to the original structure.
Why do different tools produce different headers for the same JSON?
There is no standard for flattened headers. Some tools join keys with dots, some with underscores or slashes, some index arrays and some stringify them, and most do not document the choice, which makes their output hard to reverse. This page documents one explicit convention end to end.