JSON Flatten / Unflatten

About the JSON Flattener

The JSON Flattener converts nested JSON objects into a flat, single-level key-value structure using dot notation. Deeply nested JSON from API responses, configuration files, and event payloads becomes a flat map where each key is the full path to its value — making it easy to index into databases, map to CSV columns, use in analytics pipelines, or work with systems that do not support nested structures.

How to Use

• Paste your nested JSON into the input field.
• Choose the separator character for the flattened key path: . (dot, default), _ (underscore), or / (slash).
• Click Flatten. The output is a single-level JSON object where each key is the full dot-separated path to the original value.
• Use the Unflatten option to reverse the process — converting a flat dot-notation map back to a nested JSON object.

How JSON Flattening Works

Flattening recursively traverses every nested object and array, concatenating the path segments into a single key:

• A nested object {"user": {"name": "Alice", "age": 30}} becomes {"user.name": "Alice", "user.age": 30}.
• Arrays are indexed: {"tags": ["api", "json"]} becomes {"tags.0": "api", "tags.1": "json"}.
• Mixed nesting: {"order": {"items": [{"sku": "A1"}]}} becomes {"order.items.0.sku": "A1"}.
• Null values and empty strings are preserved as flat key-value pairs.
• Already-flat values (strings, numbers, booleans, nulls) are kept as-is.

Common Use Cases

• Database ingestion — Relational databases and columnar stores (BigQuery, Redshift, Snowflake) cannot store nested objects natively. Flatten the JSON first, then map each flat key to a column.
• CSV / spreadsheet export — Flat key-value pairs map directly to spreadsheet columns. Nested JSON cannot be represented in a flat CSV without prior flattening.
• Log processing and analytics — Elasticsearch, Splunk, and similar tools perform better with flat field names. Pre-flattening JSON events can simplify query syntax and aggregation.
• Configuration management — Flattened config keys like database.host and database.port are easy to override via environment variables in 12-factor applications.
• API response normalisation — Deeply nested API responses from REST or GraphQL services are easier to work with in data pipelines when flattened to a predictable single-level structure.

Common JSON Flattening Issues

• Key collisions — If a JSON object has a key a.b and also a nested key {"a": {"b": 1}}, both flatten to the same key. Avoid dots in key names when using dot notation, or choose a separator that does not appear in your keys.
• Large arrays — Arrays with thousands of elements produce thousands of flat keys, creating very wide output that may exceed column limits in spreadsheet tools or query plan complexity in databases.
• Type loss on unflatten — Unflattening relies on key name conventions to reconstruct nesting. Keys with numeric segments (items.0) are reconstructed as arrays; others as objects. If the original structure had numeric string keys intended as object keys (not array indices), reconstruction may produce unexpected output.
• Deep nesting depth — Extremely deep structures (20+ levels) can produce very long key paths that exceed field name limits in some databases or message brokers.

Frequently Asked Questions

What is the difference between flattening and serialising JSON?

Flattening produces a flat JSON object — a JavaScript object with no nested sub-objects, only primitive values. Serialising converts the entire JSON structure to a string. They serve different purposes: flattening is for structured data transformation; serialisation is for transport and storage of the raw JSON text.

How do I flatten JSON in code?

Python: the flatten_json package (pip install flatten-json) provides flatten(nested_dict). JavaScript: the flat npm package (npm install flat) provides flatten(obj) and unflatten(obj). In Pandas: pd.json_normalize(data) flattens nested JSON into a DataFrame with dot-notation column names. In PHP: a recursive function iterating keys and building path strings covers most cases.

Can I flatten arrays without indexing them?

Standard flattening always indexes array elements (items.0, items.1). If you want to merge array values into a single field (e.g., joining tags as a comma-separated string), that is an array collapse, not standard flattening — a separate transformation step is needed after flattening.

Is there a standard format for flattened JSON keys?

No universal standard exists. Dot notation (user.address.city) is the most common convention, used by Elasticsearch, Logstash, and most flattening libraries. Underscore (user_address_city) is common in analytics contexts. Choose consistently within a pipeline and document the separator to avoid ambiguity when unflattening.