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.