JSON Flatten: Nested JSON to Dot Notation

Flatten nested JSON with the JSON flatten tool

JSON flatten converts a nested document into a single-level object. Every leaf value keeps its data type, and its key becomes the full path to that value, joined by a separator. {"user": {"address": {"city": "Paris"}}} becomes {"user.address.city": "Paris"}.

Flat keys are easier to diff, grep, sort, store in a key-value database or load into a spreadsheet column. They are also the format many translation files, feature-flag services and logging pipelines expect.

What does flattening JSON mean?

A JSON document is a tree. Flattening walks the tree and writes one entry for each leaf (a string, number, boolean or null), using the chain of object keys and array indexes as the new key. Nothing is lost: with the same separator, JSON unflatten rebuilds the original structure.

Example

Input:

{
  "user": {
    "id": 7,
    "address": { "city": "Paris" },
    "tags": ["admin", "beta"]
  },
  "meta": {}
}

Output with the default settings:

{
  "user.id": 7,
  "user.address.city": "Paris",
  "user.tags.0": "admin",
  "user.tags.1": "beta",
  "meta": {}
}

Notice that the empty object meta is kept as {} rather than silently dropped, so it survives a round trip.

Options explained

Key separator

The string placed between path segments. A dot matches lodash _.get, MongoDB and most i18n libraries. Use __ when the flat keys will become environment variables, or / to make them look like file paths.

Arrays

• Index as key (user.tags.0): arrays are treated like objects whose keys are numbers.
• Brackets (user.tags[0]): the index is written in square brackets, which reads like JavaScript and is what Spring and many form libraries use.
• Keep arrays as values: arrays are not expanded. With the _ separator, the example above gives "user_id": 7 and "user_tags": ["admin", "beta"]. Pick this when lists should stay lists, for example tag columns.

Indent

Formats the output with 2 spaces, 4 spaces or tabs.

Edge cases

• Keys that already contain the separator. A key like "v1.2" produces api.v1.2, which cannot be told apart from nested keys when you unflatten. Choose a separator that does not occur in your keys.
• Empty arrays and objects are written as [] and {} under their path instead of disappearing.
• A top-level array is allowed; its keys start with the index, such as 0.name or [0].name.
• A bare value such as 42 or "text" is rejected, because there is nothing to flatten.
• Large numbers pass through JavaScript's JSON parser, so integers above 2⁵³ lose precision just as they would in any browser app.

When to flatten JSON

• Comparing two configs line by line: flatten both, then diff them with JSON diff for a list of changed paths.
• Exporting nested API responses to CSV, where every column must be a single key.
• Building i18n catalogs where translators work with keys like checkout.button.pay.
• Writing search or analytics fields that do not support nesting.

If you only need to find the path of one value, the JSON path finder is quicker: click the value and copy its path.

Privacy

Flattening runs in your browser. Your JSON is not uploaded anywhere, so it is safe to paste production configs or API responses.

JSON flatten function in Python

A JSON flatten function in Python is a short recursive walk over the parsed data; the json module does the parsing and nothing else is needed. Dictionaries add their keys to the path and lists add their indexes. The detail most versions get wrong is empty containers: a loop over {} or [] adds nothing, so the key silently disappears. The and value checks below send empty containers to the leaf branch, which keeps them.

import json

def flatten(value, prefix="", sep="."):
    if isinstance(value, dict) and value:
        items = value.items()
    elif isinstance(value, list) and value:
        items = enumerate(value)
    else:
        return {prefix: value}
    flat = {}
    for key, child in items:
        path = f"{prefix}{sep}{key}" if prefix else str(key)
        flat.update(flatten(child, path, sep))
    return flat

text = '{"user": {"id": 7, "address": {"city": "Paris"}, "tags": ["admin", "beta"]}, "meta": {}}'
print(json.dumps(flatten(json.loads(text)), indent=2))

The output is identical to the default result of the tool above for the same document, and JSON unflatten turns it back into the nested form.