About this tool
Flattening turns nested JSON into a single level of keys, where each key is the path to a value. {"customer": {"address": {"city": "London"}}} becomes {"customer.address.city": "London"}. Flat JSON is what spreadsheets, CSV exports, database columns, search indexes, environment variables and many logging and analytics tools expect.
Options
- Separator:
.is the most common;_or__suit column names and environment variables (ASP.NET Core readsLogging__LogLevel__Default, for example);/mirrors JSON Pointer. - Arrays: write positions as path segments (
items.0.sku), in brackets (items[0].sku, as lodash and JavaScript use), or keep arrays whole as values. - Max depth: stop flattening after a number of levels and keep deeper values as nested JSON.
- Top-level array: for an array of records, flatten each record separately, which gives you rows ready for a table. Off, the array index becomes part of every key.
- Empty objects and arrays are kept as
{}and[]by default, so JSON unflatten can restore the exact original.
Example
{ "id": 7, "user": { "name": "Ada", "tags": ["admin", "beta"] } }
→ { "id": 7, "user.name": "Ada", "user.tags.0": "admin", "user.tags.1": "beta" }
Watch out for separators inside keys
If a key already contains the separator (for example "version.major"), the flat key is ambiguous and unflattening it later produces an extra level. Pick a separator that doesn’t appear in your keys, such as __.
Flatten JSON in code
function flatten(value, prefix = '', out = {}) {
if (value === null || typeof value !== 'object') {
out[prefix] = value;
return out;
}
for (const [k, v] of Object.entries(value)) {
flatten(v, prefix ? `${prefix}.${k}` : k, out);
}
return out;
}import pandas as pd
# Nested objects become "customer.address.city" columns
df = pd.json_normalize(records, sep=".")Going to a spreadsheet? JSON to CSV flattens and converts in one step.
FAQ
What does it mean to flatten JSON?
Flattening converts nested objects and arrays into a single-level object whose keys are paths, such as "user.address.city". Values stay the same.
How are arrays flattened?
By default each array position becomes part of the path: tags.0, tags.1. You can switch to bracket style (tags[0]) or keep arrays as whole values.
How do I flatten an array of JSON objects?
Paste the array with “Top-level array: flatten each item” on. Each object is flattened separately, so you get one flat record per item, ready for CSV or a database.
Can I unflatten the result again?
Yes. Use JSON Unflatten with the same separator and you get the original structure back, including empty objects and arrays.
Which separator should I use?
A dot is the most common. Use __ for environment variables or when your keys already contain dots.