JSON Flattener & Unflattener

What Does Flatten JSON Mean?

JSON objects are naturally hierarchical, storing structured information through arbitrarily deep nesting of dictionaries, sub-objects, and arrays. While hierarchical nesting is ideal for representing complex domain models, many analytical pipelines, relational databases (RDBMS), business intelligence engines, and spreadsheet tools (such as Microsoft Excel and Google Sheets) require flat two-dimensional tabular data.

JSON flattening is the deterministic process of transforming a multi-level hierarchical tree into a single-level key-value map. Each key in the resulting flat object represents the complete navigational path from the root node to the leaf value, joined by a designated delimiter character (most commonly dot notation, like user.profile.email).

How to Flatten Nested JSON

Follow these simple steps to flatten nested JSON directly in your web browser:

1. Paste or Upload Your JSON: Enter your raw JSON string into the left-hand editor or click Upload to import a .json or .txt file.
2. Select Flatten Mode: Ensure the mode toggle is set to Flatten JSON.
3. Choose Delimiter & Notation: Select Dot Notation (a.b) or Bracket Notation (a['b']). You can also customize the separator character (e.g. ., _, or /).
4. Toggle Array Preservation: Check Preserve Arrays if you want top-level or child arrays kept as native array values instead of being broken down into numeric indexed keys (e.g., items.0).
5. Copy or Download Output: Use Copy or Download to retrieve the clean flattened JSON payload, or review the generated table in the CSV preview container below.

How to Unflatten JSON

Unflattening is the inverse operation. When receiving flat key-value pairs from database queries, CSV exports, or environment configuration files, developers frequently need to restore the nested tree structure expected by web APIs and modern JavaScript/TypeScript applications.

1. Switch the mode toggle to Unflatten JSON.
2. Paste your flat JSON object where keys contain delimited paths (such as "billing.address.postalCode": "10001").
3. Verify that the delimiter setting matches the separator used in your flat keys (default is dot .).
4. The tool automatically reassembles the nested hierarchy, reconstructing nested objects and numeric array indexes into a fully valid tree structure.

Dot Notation Example

Consider the following nested user record containing an inner address object:

{
  "user": {
    "name": "John",
    "address": {
      "city": "New York"
    }
  }
}

{
  "user.name": "John",
  "user.address.city": "New York"
}

In this flattened result, the nested keys name and city are elevated to the top level, prefixed with their respective parents. This makes reading and targeting individual fields trivial without requiring deep recursive tree traversal.

Flattening Arrays

Handling arrays during JSON flattening depends on your target consumer:

• Index Expansion (Default): Each array element is flattened using its zero-based index. For example, {"tags": ["developer", "creator"]} expands into {"tags.0": "developer", "tags.1": "creator"}. This completely flattens every scalar value into its own key-value pair.
• Preserve Arrays: When enabled, lists and arrays remain intact as array primitives (e.g., {"tags": ["developer", "creator"]}), while objects nested inside the root or other objects are still flattened. This is ideal when feeding data into engines that natively support array columns (like PostgreSQL JSONB or BigQuery REPEATED fields).

JSON Flattening for CSV and Spreadsheets

A primary reason software engineers flatten JSON data is preparing API responses for export to comma-separated values (CSV) or Microsoft Excel files. Because CSV files are rigid 2D grids composed of column headers and row cells, nested JSON structures cannot be mapped 1:1 without first establishing flat column names. TinyTools provides an integrated CSV preview and instant CSV download directly below the flattener editor for this exact workflow.

Related Developer Tools

Explore our suite of client-side developer utilities designed for speed and security: