How to Flatten Nested JSON into Dot-Notation Keys

Flattening takes a nested JSON structure - objects inside objects, arrays inside objects, objects inside arrays, any combination - and produces a single object with no nesting at all. Every leaf value (a string, number, boolean, or null) keeps its original type, but its location is now encoded directly in the key name as a dot-separated path instead of as actual nesting.

Arrays do not disappear either; each element becomes a numbered segment in the path. So roles: ["admin", "editor"] becomes two flat keys, roles.0 and roles.1, each holding one string. Nothing is summarized, dropped, or reordered - the flat object contains exactly the same information as the nested one, just addressed differently.

{
  "user": {
    "name": "Mira",
    "roles": ["admin", "editor"]
  }
}

{
  "user.name": "Mira",
  "user.roles.0": "admin",
  "user.roles.1": "editor"
}

Most tools outside the JSON world do not understand nesting at all - they understand rows and columns, or flat keys and values. Flattening is the bridge that makes nested data usable in those contexts:

• Spreadsheets and CSV - a flat key like order.items.0.sku becomes one column, so json-flatten output drops straight into a spreadsheet or CSV export.
• Environment variables and config maps - systems like .env files or Kubernetes ConfigMaps only accept flat key-value pairs.
• Key-value stores and caches - Redis, DynamoDB, and similar stores often want a flat map rather than an object graph.
• Simple diffing and search - a flat list of paths makes it trivial to spot exactly which leaf value changed between two versions.

The algorithm is a recursive walk. Starting from the root, the flattener visits every property. If a value is a primitive (string, number, boolean, or null), it writes the accumulated path as a key and the value as-is. If a value is an object, it appends the property name to the current path with the delimiter and recurses into it. If a value is an array, it appends the numeric index instead of a name and recurses the same way.

The delimiter itself is configurable in the JSON Flattener - a dot is the default and the most common convention, but you can switch to a slash, an underscore, or another separator if your target system already reserves dots for something else, or if your keys happen to contain literal dots.

1. Open the JSON Flattener and paste the nested object or array you want to convert.
2. Pick a delimiter - the default dot works for most cases, or choose a slash or underscore to match your target system.
3. Flatten the document. Every leaf value gets a single-level key that encodes its full path, including array indices.
4. Copy the flat result, or feed it straight into a CSV export if you need rows and columns instead of a JSON object.

There is no account, no upload step, and no size limit beyond what your browser can comfortably hold in memory.

• Preparing a nested API response for import into a spreadsheet as ordinary columns.
• Turning a layered config object into flat, environment-variable-style keys.
• Comparing two structures at a glance by listing their flat key paths side by side.
• Loading data into a key-value store or cache that only accepts flat maps.
• Building translation or localization files where each string lives at a dotted path.

Mistaking array indices for object keys

A path like tags.2 means the third element of an array, not a property literally named 2. If you are hand-writing code that consumes flattened output, remember that any purely numeric path segment usually represents an array position, which matters if you later want to reconstruct the original shape.

Delimiter collisions with real key names

If one of your original keys already contains a dot - for example a field literally named first.name - flattening with a dot delimiter makes that path ambiguous with genuine nesting. Switch to a delimiter that does not appear in your data, such as a slash or a pipe, before flattening.

Forgetting there is a way back

Flattening feels like a one-way trip the first time you do it, but it does not have to be. The companion JSON Unflattener reads the same dot-notation keys and rebuilds the original nested object, so you can safely flatten for a spreadsheet edit and reconstruct the structure afterward.

• Stick with the default dot delimiter unless your data or target system genuinely requires something else, so paths stay familiar to other engineers.
• Check your source keys for existing dots or slashes before flattening, and pick a delimiter that avoids collisions.
• Use flattened output for comparison when you want to see exactly which leaf values differ between two versions of a document.
• Pair flattening with the JSON Tree Viewer first if the source structure is unfamiliar - understanding the shape makes the flat key paths much easier to read afterward.
• Keep the original nested JSON around, or remember the delimiter you used, so you can unflatten cleanly later.