JSON Expand

What does the JSON Expand Tool do?

The JSON Expand Tool (un-flatten tool) reconstructs deeply nested JSON objects and arrays from flat, single-level dot-notation key-value pairs in real time. Executing 100% in-browser on blueutils.com, it converts compound key path strings (user.contact.email) and numerical array indices (roles.0) into multi-level JSON object hierarchies.

• Real-Time Zero-Latency Parsing: Expands dot-notation JSON as you type with instant syntax validation and error gutter location.
• Automatic Delimiter Detection: Intelligently analyzes input key paths to auto-detect dot (.), underscore (_), slash (/), or hyphen (-) separators without requiring manual configuration.
• Flexible Formatting: Output in Standard mode with configurable indentation (2 Spaces, 4 Spaces, Tab, or Custom) or compact Minified single-line format.
• Array Reconstruction: Automatically detects numerical sub-paths (items.0, items.1) to construct native JSON arrays.

Core Concepts & Technical Specifications

1. Automatic Path Analysis & Hierarchy Building:
   • Auto Delimiter Inference: Scans key strings to identify the dominant delimiter (., _, /, -) across the document.
   • Branch Construction: Instantiates intermediate objects or arrays at each path level and assigns values to terminal leaf keys.
   • Array Recognition: Converts consecutive or non-consecutive integer keys (users.0, users.1) into native JSON array elements.
2. Round-Trip Integrity:
   • Flat datasets can be converted to and from nested structures without data loss when paired with the JSON Flatten Tool.
3. In-Browser Privacy:
   • All tree reconstruction algorithms execute locally in browser memory.
   • No data is transmitted to external servers, logged, or retained.

How to use the tool?

1. Input Flat JSON:
   • Paste flattened JSON key-value pairs into the left editor, click Upload to load a local file, or click Sample to load a pre-configured payload.
2. Choose Formatting:
   • Select your output mode (Standard or Minified) and choose your preferred indentation (2 Spaces, 4 Spaces, Tab, or Custom). Delimiters are detected automatically.
3. Copy or Download:
   • Expanded nested JSON appears instantly in the right editor. Click Copy to copy to your clipboard or Download to save as output.json.

Pipeline & Contextual Workflows

• Flat Form & CSV Ingestion: Reconstruct nested API request bodies from flat HTML form submissions, environment variables, or JSON to CSV Converter tabular imports.
• Bi-Directional Flattening: Flatten nested JSON objects with JSON Flatten Tool and restore them with JSON Expand.
• TypeScript Generation: Generate typed interfaces from expanded JSON payloads using JSON to TypeScript Converter.

REST API Integration

blueutils.com provides a free REST API endpoint (POST https://blueutils.com/api/json/expand) for automated data transformation pipelines, ETL ingestion, and webhook restructuring.

API Request Parameters

API Request Payload Examples

cURL (Using Direct JSON Object & Minify)

curl -X POST https://blueutils.com/api/json/expand \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "user.id": 101,
      "user.contact.email": "jane@example.com"
    },
    "minify": true
  }'

cURL (Using Raw String & Specific Delimiter)

curl -X POST https://blueutils.com/api/json/expand \
  -H "Content-Type: application/json" \
  -d '{
    "rawText": "{\"user_id\":101,\"user_name\":\"Jane\"}",
    "delimiter": "_"
  }'

Python

import requests

url = "https://blueutils.com/api/json/expand"
payload = {
    "json": {
        "user.id": 101,
        "user.name": "Jane"
    },
    "minify": False
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String jsonPayload = """
            {
                "rawText": "{\\"user.id\\":101,\\"user.name\\":\\"Jane\\"}",
                "minify": false
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/json/expand"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

API Response Parameters

API Response Payload Examples

Success Response (HTTP 200 OK)

{
  "isValid": true,
  "result": "{\n  \"user\": {\n    \"id\": 101,\n    \"name\": \"Jane\"\n  }\n}",
  "data": {
    "user": {
      "id": 101,
      "name": "Jane"
    }
  },
  "originalSize": 45,
  "resultSize": 62
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "Invalid JSON syntax: Unexpected token '}' at position 15 (Line 1, Column 16)"
}

Rate Limit Exceeded Response (HTTP 429 Too Many Requests)

{
  "error": "API rate limit exceeded. Please wait or contact support@blueutils.com."
}

Why use an API to expand JSON?

Automating JSON un-flattening streamlines data restructuring across complex workflows:

• Ingestion Preprocessing: Reconstructs flat key-value pairs from SQL query results or CSV rows into hierarchical JSON payloads for REST APIs.
• LLM Context Optimization: LLMs can generate flat dot-notation dictionaries with zero nesting syntax errors; calling the API expands them deterministically.
• Reliable Array Unrolling: Automatically infers numerical path segments into standard JSON arrays without data corruption.

Native Usage

Expand flat JSON locally across terminal environments and programming runtimes:

Linux / macOS (jq)

# Expand flat JSON using jq in terminal
jq -n 'reduce (inputs | to_entries[]) as $i ({}; setpath($i.key | split("."); $i.value))' input.json

Windows (PowerShell)

# Expand flat JSON in PowerShell
$flat = Get-Content flat.json | ConvertFrom-Json
$res = @{}
$flat.psobject.properties | ForEach-Object {
  $parts = $_.Name.Split('.')
  if (-not $res.ContainsKey($parts[0])) { $res[$parts[0]] = @{} }
  $res[$parts[0]][$parts[1]] = $_.Value
}
$res | ConvertTo-Json

Python

import json

def unflatten_json(flat_dict, delimiter="."):
    result = {}
    for key, value in flat_dict.items():
        parts = key.split(delimiter)
        d = result
        for part in parts[:-1]:
            if part not in d:
                d[part] = {}
            d = d[part]
        d[parts[-1]] = value
    return result

flat_data = {"user.name": "Jane", "user.id": 101}
print(json.dumps(unflatten_json(flat_data), indent=2))

Java (Jackson)

import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws Exception {
        Map<String, Object> flat = Map.of("user.name", "Jane", "user.id", 101);
        Map<String, Object> root = new HashMap<>();

        for (Map.Entry<String, Object> entry : flat.entrySet()) {
            String[] parts = entry.getKey().split("\\.");
            Map<String, Object> current = root;
            for (int i = 0; i < parts.length - 1; i++) {
                current = (Map<String, Object>) current.computeIfAbsent(parts[i], k -> new HashMap<>());
            }
            current.put(parts[parts.length - 1], entry.getValue());
        }

        ObjectMapper mapper = new ObjectMapper();
        System.out.println(mapper.writerWithDefaultPrettyPrinter().writeValueAsString(root));
    }
}