JSON Flatten & Unflatten Tool

How to Use the JSON Flatten & Unflatten Tool

1. Paste your nested JSON object into the input panel on the left.
2. Select Flatten to convert nested structures to flat dot-notation keys, or Unflatten to rebuild nested JSON from flat keys.
3. Choose your preferred separator — dot (.) for standard notation or slash (/) for JSON Pointer-style paths.
4. Toggle Bracket arrays to switch between items.0.name and items[0].name notation.
5. Click Copy to copy the result to your clipboard.

Features

• Bidirectional conversion — flatten nested JSON to flat keys, or unflatten flat keys back to nested structures.
• Configurable separator — use dot notation (a.b.c) or slash notation (a/b/c) for JSON Pointer compatibility.
• Array notation options — choose between dot-indexed (items.0) or bracket-indexed (items[0]) array keys.
• Auto-processing — output updates as you type with a debounced 120ms delay.
• One-click copy — copy the flattened or unflattened result instantly.
• Privacy-first — all processing happens in your browser. No data is transmitted to any server.

What Is JSON Flattening?

JSON flattening is the process of converting a deeply nested JSON object into a single-level (flat) object where each key represents the full path to the original value. For example, the nested object {"user": {"address": {"city": "London"}}} becomes {"user.address.city": "London"}. The reverse operation — unflattening — takes these dot-separated keys and reconstructs the original nested hierarchy.

Flattening is a lossless transformation: the flat representation contains exactly the same data as the nested original, just in a different shape. This makes it invaluable for interoperability between systems that expect different data structures.

Common Use Cases for JSON Flattening

Environment Variables from Nested Configs

Many applications use nested JSON or YAML for configuration, but deployment environments (Docker, Kubernetes, CI/CD pipelines) require flat environment variables. Flattening a config file like {"database": {"host": "localhost", "port": 5432}} produces keys like database.host and database.port that map directly to environment variable names like DATABASE_HOST and DATABASE_PORT after a simple case transformation.

Flat Key-Value Stores

Databases like Redis, DynamoDB, and other key-value stores do not natively support nested structures. Flattening JSON before storage allows you to store complex objects as flat key-value pairs, then unflatten them when reading back. This pattern is common in caching layers where you need to store API responses or user session data.

MongoDB Dot-Notation Queries

MongoDB uses dot notation to query nested document fields. If you have a document with {"address": {"city": "New York"}}, you query it as {"address.city": "New York"}. Flattening your JSON produces exactly the format MongoDB expects for update operations and queries against nested fields.

CSV and Spreadsheet Export

Spreadsheets and CSV files are inherently flat — each column is a single field. Flattening nested JSON before conversion to CSV produces clean column headers like user.name, user.email, and user.address.city instead of requiring complex column-mapping logic. Combine this tool with the JSON to CSV Converter for a complete workflow.

Diffing and Comparison

Comparing two nested JSON objects can be complex because you need to handle structural differences at every level. Flattening both objects first reduces the comparison to a simple key-by-key diff. Use this tool to flatten your JSON, then paste both versions into the Diff Checker to see exactly which values changed.

Dot Notation vs. Slash Notation

The default dot notation (a.b.c) is the most widely used convention, compatible with JavaScript property access, MongoDB queries, and lodash's _.get() and _.set() functions. Slash notation (a/b/c) follows the JSON Pointer standard (RFC 6901), which is used in JSON Patch (RFC 6902) operations and some REST API path conventions. Choose the notation that matches your downstream tooling.

How Array Flattening Works

When an array is encountered during flattening, each element receives a numeric index as part of its key path. The object {"tags": ["html", "css", "js"]} becomes {"tags.0": "html", "tags.1": "css", "tags.2": "js"} in dot notation, or {"tags[0]": "html", "tags[1]": "css", "tags[2]": "js"} in bracket notation. During unflattening, numeric key segments are automatically detected and converted back into arrays.

Working with Flattened JSON in Code

In JavaScript, you can flatten objects using a simple recursive function or libraries like flat (npm). The core algorithm walks each property: if the value is a primitive, it adds the accumulated key path to the result; if the value is an object or array, it recurses with the extended path. This tool implements that exact algorithm in your browser with zero dependencies.

In Python, you can use the flatten-json library or write a similar recursive function. The pandas library also provides json_normalize() which effectively flattens nested JSON into a flat DataFrame — useful for data analysis workflows.

Related Tools

After flattening your JSON, format it for readability or validate it for syntax errors. Use the jq Playground to run queries against nested JSON structures. Convert between formats with the JSON-YAML Converter. Compare environment variable files with the Env Diff tool.