What JSON flattening means
A json flatten turns a nested document into one level of keys. Each key is the full path to a value, with the names joined by a delimiter. The value at user, then address, then city gets the key user.address.city. Unflattening does the opposite and rebuilds the nesting from those paths.
This nested JSON:
{"user":{"name":"Ada","address":{"city":"London"},"tags":["admin","beta"]}}becomes this flat JSON with the default settings:
{
"user.name": "Ada",
"user.address.city": "London",
"user.tags[0]": "admin",
"user.tags[1]": "beta"
}Strings, numbers, true, false and null stay as they are. Numbers are copied character for character, so 19.90 stays 19.90 and a 20-digit ID is not rounded. The work happens in your browser and the JSON is not uploaded. See the Privacy Policy.
How to unflatten JSON back to nested objects
Paste a flat object and the tool reads each key as a path. Parts in brackets such as [0] become array positions, and the other parts become object keys. This input:
{"user.name":"Ada","user.roles[0]":"admin","user.roles[1]":"editor"}comes back as:
{
"user": {
"name": "Ada",
"roles": [
"admin",
"editor"
]
}
}You can also paste lines such as app.db.port = 5432 or app.db.port=5432. Spaces around the equals sign are ignored, and blank lines and lines that start with # are skipped. The value after the equals sign is read as JSON, so 5432 stays a number and "5432" stays text. A value that is not valid JSON is kept as plain text and the summary counts it. When the tool writes a list, a key that really starts or ends with a space, starts with #, or contains = is put in brackets or escaped, so it still reads back the same.
Auto-detect picks a direction with a simple rule. A path = value list is unflattened. A JSON object is unflattened when none of its values is a nested object or array, and at least one key contains the delimiter, a bracket path such as [0] or a backslash. With Arrays set to Same as delimiter, an object whose number keys start at 0, such as {"0": true}, also counts. Everything else is flattened. An object that is already flat and has none of these keys comes out unchanged, and the notes say so. Set Direction yourself when the rule guesses wrong.
Two kinds of trouble get a clear message. A conflict is a path that holds a value and also has keys under it, such as a = 1 next to a.b = 2. A gap is an array with a missing index, such as items[0] and items[3]. Conflicts can raise an error, or keep the last or the first value. Gaps can be filled with null, raise an error, or be closed so the items are renumbered. Filling stops at index 99,999 so a typo cannot create a huge array.
Delimiters and array styles
The delimiter is the text between path parts. A dot is the common choice for config files and JSON to dot notation. Underscore and double underscore suit environment variables, slash looks like a URL or JSON Pointer path, and colon matches some cache and config systems. A custom delimiter can be any short text without digits, brackets, backslashes, equals signs or double quotes.
Arrays can be written two ways. Brackets give user.tags[0]. Same as delimiter gives user.tags.0, or user/tags/0 with a slash:
{
"user.name": "Ada",
"user.address.city": "London",
"user.tags.0": "admin",
"user.tags.1": "beta"
}The same setting controls unflattening. With brackets, a plain number such as .0 is an object key named 0. With Same as delimiter, it becomes an array index, unless you turn on Numbers as object keys.
Upper case keys with a double underscore give names such as APP__DB__HOST, the form ASP.NET Core reads for nested settings from environment variables:
APP__DB__HOST = "localhost"
APP__DB__PORT = 5432Keys that contain the delimiter, and a lossless round trip
A key can already contain a dot. If you flatten {"price.usd": 12.5, "price": {"usd": 10}} the plain way, both values want the key price.usd and one is lost. The Special keys option decides what happens:
- Quote in brackets writes the key as a JSON string in brackets:
["price.usd"] andprice.usdstay apart. - Escape with a backslash writes
price\.usd, which is shorter and still safe to read back. - Leave as is writes the key unchanged. The summary then reports the collision and keeps the later value.
The same rules cover empty keys, keys with a backslash or bracket, and number-like keys when arrays use the delimiter. Empty objects and arrays are written as {} and [] values by default, so unflattening restores them instead of dropping them.
The lossless check runs the result back through unflatten and compares it with your input. When it passes, the summary says so. When it fails, it names the first place that differs, for example a key that went missing because of a collision or a changed key case.
Where flat JSON is useful
- Spreadsheets and CSV. Flat paths fit in a column. The CSV output gives two columns, path and value. For one row per record with a column per field, use JSON to Excel.
- Environment variables and config. Paths with a double underscore map nested settings to variable names. For Java and Spring, JSON to Properties writes a .properties file directly.
- Translation files. Many i18n tools store messages under keys like
auth.login.title. Flattening shows every message on its own line, which makes missing or extra keys easy to spot. - Search indexes. Elasticsearch stores fields of nested objects under dotted names such as
user.name, so a flat view matches the field names you query. - MongoDB updates and queries. MongoDB addresses nested fields with dot notation such as
address.geo.latand array positions such astags.0. Set Arrays to Same as delimiter to get that form. - Comparing documents. Two flat files can be sorted and compared line by line. Turn on Sort keys, or use Sort JSON Keys on the nested file first.
Max depth, prefix and other options
Max depth stops after a number of levels and keeps the rest as nested JSON. With a depth of 2, {"a":{"b":{"c":{"d":1}}}} becomes:
{
"a.b": {
"c": {
"d": 1
}
}
}Prefix adds a fixed start to every key, such as app, and removes it again when you unflatten. Key case can turn keys to upper or lower case, which cannot be undone, so the lossless check reports it. Sort keys orders object keys A to Z at every level and leaves array items where they are. Allow comments and trailing commas reads JSON with // and /* */ comments.
Flatten JSON in JavaScript
For simple data, a short recursive function does the job:
function flatten(value, prefix = "", out = {}) {
if (value !== null && typeof value === "object" && Object.keys(value).length > 0) {
for (const [key, child] of Object.entries(value)) {
const path = Array.isArray(value) ? `${prefix}[${key}]` : prefix ? `${prefix}.${key}` : key;
flatten(child, path, out);
}
} else {
out[prefix] = value;
}
return out;
}
console.log(flatten({ user: { name: "Ada", tags: ["admin", "beta"] } }));It prints:
{ 'user.name': 'Ada', 'user.tags[0]': 'admin', 'user.tags[1]': 'beta' }This version does not quote keys that contain dots, writes into a plain object, so a key named __proto__ is not stored as a normal key, works on data from JSON.parse, which already rounded numbers longer than about 15 digits, and can run out of stack on very deep input. The tool on this page handles those cases, keeps keys in a Map while rebuilding, and limits nesting to 1,000 levels.
Limits and related tools
- Input up to 2,000,000 characters and up to 500,000 paths in one run, in either direction. A file with more paths gets an error instead of a partial result. Files near those limits can take a second or more.
- Flat output is longer than the input, because every key repeats its full path. When the result passes 2,000,000 characters, the status and the notes say it is too long to paste back. Download it instead, or split the JSON first.
- Nesting up to 1,000 levels. Deeper input gets a clear error instead of freezing the page.
- An empty object or array has no paths. Flattening returns {} or [] unchanged, and unflattening {} or [] gives the same value back. A single value such as 42 is also returned as it is.
- CSV cells that start with =, +, -, @, a tab or a carriage return get a ' in front so spreadsheet apps do not run them as formulas. Plain numbers such as -5 are left alone, and cells with commas, quotes, line breaks or spaces at either end are quoted.
- Duplicate keys in one object keep the last value, as JSON parsers do, and the summary lists them.
- CSV output keeps values as text, so it cannot be unflattened. Use the path = value list when you need to come back.
- Keys named __proto__, constructor or prototype are kept as ordinary keys and flagged in the notes.
To describe the structure of the nested JSON, try the JSON Schema Generator. To turn it into YAML, use JSON to YAML. To go from a .properties file back to JSON, use Properties to JSON.