Skip to content
ToolPlankDEV
JSON Tools
100% In-Browser Execution

Updated:

JSON Flatten and Unflatten

Paste nested JSON for a json flatten into single-level path keys such as user.address.city, or paste flat keys to rebuild the nested JSON. Pick the delimiter and array style, and a round trip check confirms nothing was lost. Nothing is uploaded.

Options:

JSON

Input
0 chars · 0 lines

Result

Ready
Processing in browser...
0 chars · 0 linesUpdates as you type

Summary

Path counts, depth, collisions, the round trip check and notes about empty values appear here.

Processed on your device. Your text is not sent to our servers.

More free tools you may need next.

Quick Guide

How to use JSON Flatten and Unflatten

Simple step-by-step instructions to get the exact output you need.

  1. 01

    Paste or open your JSON

    Paste nested JSON into the left box, press Paste, or open a .json file. Example loads a user record. Flat keys, i18n file, path = value list and Tricky keys load other cases.

  2. 02

    Check the direction

    Auto-detect flattens nested JSON and unflattens a JSON object whose keys are already paths, or a list of path = value lines. Set Direction to Flatten or Unflatten when you want to choose yourself.

  3. 03

    Pick the delimiter, array style and output

    Choose a dot, underscore, double underscore, slash, colon or your own delimiter, brackets or delimiter indexes for arrays, and flat JSON, a path = value list or CSV as the output. Max depth, prefix, key case and sort keys are in the same options bar.

  4. 04

    Read the summary, then copy or download

    The summary shows the number of paths, the deepest level, collisions and the result of the lossless check. Press Copy, or Download to save flattened.json, flattened.txt, flattened.csv or unflattened.json.

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:

JSON
{"user":{"name":"Ada","address":{"city":"London"},"tags":["admin","beta"]}}

becomes this flat JSON with the default settings:

JSON
{
  "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:

JSON
{"user.name":"Ada","user.roles[0]":"admin","user.roles[1]":"editor"}

comes back as:

JSON
{
  "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:

JSON
{
  "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:

Text
APP__DB__HOST = "localhost"
APP__DB__PORT = 5432

Keys 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"] and price.usd stay 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.lat and array positions such as tags.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:

JSON
{
  "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:

JavaScript
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:

Text
{ '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.

  • 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.

Frequently Asked Questions

Technical Q&A for JSON Flatten and Unflatten

Common questions about edge cases, character encoding, and privacy guarantees.

Paste the JSON and the flat result appears on the right. Every value gets one key with its full path, such as user.address.city, and the summary confirms that unflattening gives back the same JSON.

Paste a JSON object whose keys are paths, such as {"user.name": "Ada"}, and Auto-detect rebuilds the nested objects and arrays. You can also paste path = value lines, or set Direction to Unflatten yourself.

Keep the delimiter on Dot. Set Arrays to Same as delimiter if you also want array positions written as tags.0 instead of tags[0].

By default it is quoted as ["price.usd"], so it cannot be mixed up with a nested price object. You can escape it as price\.usd instead, or leave it as is and accept that two keys may collide.

Yes. They are written as {} and [] values so unflattening restores them. Turn off Keep empty {} and [] to leave them out.

No. Numbers are copied exactly as written, so 12345678901234567890 and 19.90 come out unchanged in both directions.

That is a conflict, because a cannot be a number and an object at once. By default you get an error naming both keys. Set Conflicts to Last wins or First wins to keep one of them.

Missing items are filled with null by default, so [0] and [3] give an array of four items. You can choose an error instead, or close the gaps so the items are renumbered.

Yes. Set Delimiter to Double underscore and Key case to UPPER, and choose the path = value list output to get lines such as APP__DB__HOST = "localhost".

No. Flattening and unflattening run in your browser and the text is not sent anywhere.