Nested objects and arrays are great for modeling structure, but awkward wherever you need a flat list of key-value pairs — spreadsheets, log lines, or a diff you can actually scan. Flattening solves exactly that mismatch.
How it works
Every nested field becomes one row, where the key is the full path to the value (written with dots or bracketed indexes) and the value is the value itself. {"user": {"address": {"city": "Austin"}}} becomes the pair user.address.city → "Austin". Array elements get an index in the path, like items[0].name.
Where this shows up: i18n key files
Flat dot-notation keys are the standard shape for translation files in libraries like i18next and react-intl — settings.profile.title rather than a nested JSON tree. Translation platforms and spreadsheet-based workflows for localization teams almost always expect that flat form, so flattening a nested locale file is often the first step before handing it to a translator.
Why this is useful
- Importing nested API data into a spreadsheet or a flat database table.
- Making a line-by-line diff between two complex objects actually readable.
- Finding one value fast in a deeply nested JSON document by seeing its full path at a glance.
The reverse operation: unflatten
Rebuilding the nested structure from a flat list means parsing each key back into path segments (splitting on dots and bracketed indexes) and building up nested objects and arrays as you go. It gets ambiguous when a path could mean two things — if the data has both a literal key "a.b" and a nested path a.b, unflatten can't tell which was intended and will flag it as a conflict instead of guessing.