JSON Flatten Tool

What is JSON Flattening?

JSON flattening is the process of taking a deeply nested JSON structure and transforming it into a single-level object where every value is directly accessible by a single composite key. The key encodes the full path to the value through the original hierarchy.

Consider this nested JSON:

{
  "user": {
    "name": "Alice",
    "address": {
      "city": "London",
      "zip": "EC1A"
    }
  }
}

After flattening, the result is:

{
  "user.name": "Alice",
  "user.address.city": "London",
  "user.address.zip": "EC1A"
}

The structure is completely preserved — just expressed differently. Every piece of information is still there; it is simply reorganized into a flat dictionary where the dot-separated key tells you exactly where that value originally lived in the hierarchy.

Dot Notation Explained

Dot notation is the standard naming convention for flattened keys. Each level of nesting in the original JSON is separated by a period character. This convention is borrowed from how most programming languages access nested object properties.

• a.b.c means the value at obj.a.b.c in the nested version
• Array indices are typically represented as numbers: items.0.name
• Some implementations use bracket notation for arrays: items[0].name

Our JSON Flatten Tool uses dot notation by default, which is the most widely supported format across libraries, databases, and query languages. If your target system requires a different separator (such as double underscore __ or forward slash /), you can configure the separator in the tool settings.

Dot notation is used natively in:

• Elasticsearch field mappings and queries
• MongoDB dot notation for nested document queries
• Python's glom and jmespath libraries
• JavaScript's lodash.get / lodash.set functions
• Azure Cosmos DB and AWS DynamoDB path expressions

When to Flatten JSON

There are several practical scenarios where flattening JSON is not just convenient but necessary:

Elasticsearch Indexing

Elasticsearch's default mapping handles nested objects, but there are cases where you need to index documents with explicit flat field paths — particularly when you want to avoid the overhead of the nested type and instead store a flattened representation. The flattened field type in Elasticsearch directly accepts pre-flattened JSON objects.

CSV Export and Spreadsheet Import

CSV files are inherently two-dimensional — columns and rows. They cannot represent nested structures. When you need to export JSON data into a spreadsheet or CSV file, flattening is the essential first step. Each dot-notation key becomes a column header, and each value fills the corresponding cell.

HTML Form Data

HTML forms submit data as flat key-value pairs. Many server-side frameworks (like PHP, Laravel, and Rails) support dot or bracket notation in form field names to reconstruct nested objects server-side. Flattening your JSON to understand what form field names to use is a common debugging task for developers building dynamic forms.

Comparing Two JSON Objects

Diffing two nested JSON objects visually is difficult. Flattening both objects first and then comparing them side-by-side as flat dictionaries makes it easy to spot exactly which keys changed, were added, or were removed — without having to mentally traverse nested structures.

Configuration Management

Tools like Helm (Kubernetes), Terraform, and various CI/CD systems accept flat key-value overrides using dot-notation paths. When you want to override a single deeply nested value in a large configuration, knowing its flattened key path is essential.

Unflattening JSON

Unflattening is the reverse operation: taking a flat dictionary of dot-notation keys and reconstructing the original nested JSON structure. This is equally important in practice.

Common use cases for unflattening include:

• Rebuilding nested API request bodies from form submissions
• Reconstructing configuration objects from environment variables that use __ or . as separators
• Converting spreadsheet data back into structured JSON for database insertion
• Restoring a snapshot stored in a flat key-value store (like Redis or DynamoDB) to its original nested shape

Our tool handles both directions. Paste a flat object and click Unflatten to get back the nested representation. The round-trip is lossless as long as your keys were created by flattening in the first place.

Frequently Asked Questions

What does flattening a JSON object mean?

Flattening a JSON object means converting its nested hierarchy into a single level of key-value pairs. Nested keys are combined using a separator — typically a dot — so every value is addressable by a single composite key string. For example, {"a":{"b":1}} becomes {"a.b":1}.

Does flattening JSON work with arrays?

Yes. Array elements are included in flattened output using their numeric index as part of the key path. For example, {"tags":["json","api"]} flattens to {"tags.0":"json","tags.1":"api"}. Some implementations use bracket notation instead of dot notation for array indices.

When should I flatten JSON?

Flatten JSON when you need to work with systems that expect flat key-value pairs: Elasticsearch flat field types, CSV export, spreadsheet imports, environment variable configuration, or HTML form field names. It is also useful for diffing two JSON documents by comparing their flat representations line by line.

Can I unflatten a previously flattened JSON?

Yes. Unflattening reconstructs the original nested structure from dot-notation keys. Our tool supports both directions. Simply paste your flat JSON and select Unflatten to restore the original hierarchy. The operation is lossless as long as the flat keys were originally produced by a consistent flatten operation.

JSON Flattening: Nested to Flat

Flattening JSON converts deeply nested objects into a single-level key-value map where nested paths become compound keys. This is essential for loading JSON into SQL tables, Elasticsearch, or spreadsheets.

Before and After Flattening

// Nested (3 levels deep)
{
  "user": {
    "name": "Alice",
    "address": {
      "city": "London",
      "zip": "EC1A 1BB"
    }
  }
}

// Flattened (dot notation)
{
  "user.name": "Alice",
  "user.address.city": "London",
  "user.address.zip": "EC1A 1BB"
}

Flattening in Code

// JavaScript
function flatten(obj, prefix = "") {
  return Object.keys(obj).reduce((acc, key) => {
    const path = prefix ? `${prefix}.${key}` : key;
    if (typeof obj[key] === "object" && !Array.isArray(obj[key])) {
      Object.assign(acc, flatten(obj[key], path));
    } else {
      acc[path] = obj[key];
    }
    return acc;
  }, {});
}

// Python (using pandas)
import pandas as pd
pd.json_normalize(nested_data)

Delimiter Options

What Does Flattening JSON Mean?

Flattening JSON means taking a deeply nested JSON object — one where values are nested inside objects inside objects — and transforming it into a single-level object where every value is directly accessible by a single composite key. The composite key encodes the entire path through the original hierarchy, with each level separated by a delimiter (usually a dot or underscore).

A flat JSON object has no nesting: every key maps directly to a primitive value (string, number, boolean, or null). There are no nested objects and no arrays — just key-value pairs at one level.

Before and After: Nested to Flat JSON

// Before: Nested JSON (3 levels deep)
{
  "user": {
    "id": 42,
    "name": "Alice Johnson",
    "address": {
      "street": "123 Main St",
      "city": "Portland",
      "state": "OR",
      "zip": "97201"
    },
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  },
  "account": {
    "plan": "pro",
    "seats": 5
  }
}

// After: Flat JSON (dot notation, all values at one level)
{
  "user.id": 42,
  "user.name": "Alice Johnson",
  "user.address.street": "123 Main St",
  "user.address.city": "Portland",
  "user.address.state": "OR",
  "user.address.zip": "97201",
  "user.preferences.theme": "dark",
  "user.preferences.notifications": true,
  "account.plan": "pro",
  "account.seats": 5
}

No information is lost during flattening — the complete structure is preserved in the key names. You can always reconstruct the original nested JSON from the flat version by splitting the keys on the delimiter and rebuilding the object tree. This reverse operation is called unflattening.

Use Cases: When to Use a JSON Flattener Online

Flattening is not always the right choice — it depends on what you need to do with the data. Here are the most common situations where using a JSON flattener online is the right tool:

Loading JSON into a SQL Database

Relational databases store data in flat tables with typed columns. To insert a nested JSON object into a SQL table, you must first flatten it so that each key maps to a column name. The flat keys like user_address_city become column headers.

Exporting JSON to CSV or Excel

CSV files are inherently flat: every row has the same set of column names. Nested JSON objects cannot be directly exported to CSV. Flattening the JSON first converts the hierarchy into column headers, making a direct CSV export possible. Our JSON to CSV converter can handle this automatically.

Elasticsearch Flat Field Type

Elasticsearch's flattened field type maps a whole object to a single flat field and is suitable for deeply nested or dynamic objects. Pre-flattening your data before indexing can simplify mappings and improve query performance for dynamic schemas.

Comparing Two JSON Objects

Diffing nested JSON visually is difficult. Flattening both objects to single-level dictionaries first and comparing them line-by-line makes it trivial to identify exactly which keys changed, were added, or were removed — without navigating a deep tree. Try our JSON diff tool for a visual comparison.

Environment Variable Configuration

Tools like Helm (Kubernetes), Terraform, and many CI/CD systems accept flat key-value overrides using dot-notation paths. Knowing a value's flattened key path is required to override just that one nested value without rewriting the entire config object. The JSON to .env converter uses a similar flattening approach.

Flatten vs Unflatten JSON

Both operations are equally important and this flatten JSON online tool supports both directions. Here is a detailed comparison: