What is JSON Flattening?

Flattening converts a nested JSON structure into a single-level object where nested keys are joined with a delimiter. This is useful for data processing, database storage, and CSV export.

Example

Nested JSON:

{
  "user": {
    "name": "John",
    "address": {
      "city": "Boston"
    }
  }
}

Flattened (with dot delimiter):

{
  "user.name": "John",
  "user.address.city": "Boston"
}

Array Handling

Arrays are flattened with bracket notation:

// Input
{
  "tags": ["javascript", "typescript"],
  "users": [
    { "name": "Alice" },
    { "name": "Bob" }
  ]
}

// Output
{
  "tags[0]": "javascript",
  "tags[1]": "typescript",
  "users[0].name": "Alice",
  "users[1].name": "Bob"
}

Delimiter Options

Common Use Cases

• CSV export — Flatten before converting to CSV for spreadsheet-friendly data
• Search indexing — Elasticsearch and other search engines work better with flat documents
• Key-value stores — Redis, DynamoDB, and similar databases
• Environment variables — Config management systems
• Form data — HTML form serialization

Unflatten

The reverse operation reconstructs nested objects from flattened keys. Use this when you need to restore the original structure after processing.

Programmatic Flattening

JavaScript

function flatten(obj, prefix = '', delimiter = '.') {
  return Object.entries(obj).reduce((acc, [key, value]) => {
    const newKey = prefix ? `${prefix}${delimiter}${key}` : key;
    
    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
      Object.assign(acc, flatten(value, newKey, delimiter));
    } else {
      acc[newKey] = value;
    }
    
    return acc;
  }, {});
}

Python

def flatten(obj, prefix='', delimiter='.'):
    result = {}
    for key, value in obj.items():
        new_key = f"{prefix}{delimiter}{key}" if prefix else key
        if isinstance(value, dict):
            result.update(flatten(value, new_key, delimiter))
        else:
            result[new_key] = value
    return result

Command Line (with jq)

# Flatten with jq (recursive)
jq '[paths(scalars) as $p | {"key": $p | join("."), "value": getpath($p)}] | from_entries' data.json

Pro Tips

• 💡 Choose delimiter wisely — If your keys contain dots, use a different delimiter to avoid confusion
• 💡 Preserve array indices — The bracket notation preserves order when unflattening
• 💡 Use with CSV — Flatten first, then useJSON to CSV for spreadsheet export

Related Tools

• JSON to CSV — Export flattened data to CSV
• JSON Path — Query nested JSON data
• JSON Validator — Validate your JSON

Common Mistakes & Pro Tips

• Flattening builds path keys from nesting — A nested object like {"user":{"name":"Sam"}} becomes {"user.name":"Sam"}, where the new key is the dot-joined path to each leaf value. This is convenient for diffing, spreadsheets, and environment-variable style configs, but the result is no longer the original shape.
• Array indices use bracket or dotted-index notation — Arrays flatten with their numeric index, commonly as items[0].id or items.0.id depending on the convention chosen. To round-trip cleanly back to an array on unflatten, the tool must recognize purely numeric path segments and rebuild them as array positions rather than object keys.
• Keys containing dots collide with the path separator — If an original key literally contains a dot, such as {"a.b":1}, it becomes indistinguishable from a nested path a -> b after dot-flattening, so unflatten cannot tell them apart. Use bracket notation or a separator that does not appear in your keys to avoid silent data corruption.
• Empty objects and arrays have no leaf to flatten — Because flattening only emits keys for leaf values, an empty {} or [] disappears in a naive implementation, so unflatten cannot restore it. A correct round-tripper either preserves empties as explicit entries or you should be aware the empty containers may be lost.
• Unflatten reconstructs structure but can't recover lost order or types — Going from flat keys back to nested JSON rebuilds objects and arrays from the path segments, inferring an array when a segment is a non-negative integer. Sparse or non-sequential indices may produce arrays with gaps (null/undefined holes), so verify the rebuilt shape matches your intent.