JSON Merge

What does the JSON Merge Tool do?

The JSON Merge Tool performs deep, recursive merging of two or more JSON objects into a single unified JSON document in real time. Executing 100% in-browser on blueutils.com, it merges nested object trees without overwriting sibling keys, providing configurable strategies for array reconciliation (replace, concat, union), null value overrides (skipNull), and custom indentation.

• Real-Time Zero-Latency Merging: Merges baseline and override JSON payloads as you type with live key metrics (X Keys).
• Array Resolution Strategies: Select Replace (overwrite target arrays), Concat (append items), or Union (deduplicate values).
• Null Safety: Enable Skip Nulls to prevent null fields in patch objects from overwriting existing baseline properties.

Core Concepts & Technical Specifications

1. Recursive Deep Merging vs. Shallow Assignment:
   • Shallow Merge (Object.assign): Overwrites entire nested child objects with the incoming source object.
   • Deep AST Merging: Recursively traverses nested keys down to primitive leaves, merging sibling branches while cleanly replacing or joining leaves.
2. Array Conflict Strategies:
   • replace: Replaces target arrays entirely with the override array.
   • concat: Concatenates source array elements to the end of the base array.
   • union: Concatenates arrays and performs deep value deduplication using structural hashing.
3. In-Browser Privacy:
   • All recursive object merge algorithms execute locally in browser memory.
   • No data is transmitted to external servers, logged, or retained.

How to use the tool?

1. Input Baseline & Override JSON:
   • Paste your base target JSON object into the left editor and your override patch object into the right editor, or click Sample.
2. Configure Strategy & Indentation:
   • Choose your Array Strategy (Replace Arrays, Concat Arrays, or Deduplicate Union), toggle Skip Nulls, and select your indentation (2 Spaces, 4 Spaces, Tab, or Custom).
3. Copy or Download:
   • Merged JSON appears instantly in the bottom editor. Click Copy to copy to your clipboard or Download to save as output.json.

Pipeline & Contextual Workflows

• Configuration Layering: Merge base application configurations (config.default.json) with environment overrides (config.production.json).
• Structural Diffing: Inspect merged differences side-by-side using JSON Diff Tool.
• TypeScript Generation: Generate typed interfaces from merged schemas using JSON to TypeScript Converter.

REST API Integration

blueutils.com provides a free REST API endpoint (POST https://blueutils.com/api/json/merge) for automated CI/CD config generation, Kubernetes manifest patching, and data pipelines.

API Request Parameters

API Request Payload Examples

cURL (Using Direct JSON Objects & Union Array Strategy)

curl -X POST https://blueutils.com/api/json/merge \
  -H "Content-Type: application/json" \
  -d '{
    "jsonSources": [
      {
        "appName": "Blueutils",
        "settings": { "timeout": 5000 },
        "tags": ["dev"]
      },
      {
        "settings": { "debug": true },
        "tags": ["tools"]
      }
    ],
    "arrayStrategy": "union",
    "skipNull": false,
    "indent": 2
  }'

cURL (Using Left / Right Aliases)

curl -X POST https://blueutils.com/api/json/merge \
  -H "Content-Type: application/json" \
  -d '{
    "left": { "version": "1.0.0", "active": true },
    "right": { "version": "2.0.0" },
    "arrayStrategy": "replace"
  }'

Python

import requests

url = "https://blueutils.com/api/json/merge"
payload = {
    "jsonSources": [
        {"appName": "Blueutils", "settings": {"timeout": 5000}},
        {"settings": {"debug": True}}
    ],
    "arrayStrategy": "concat",
    "skipNull": False,
    "indent": 2
}
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 = """
            {
                "jsonSources": [
                    {"appName": "Blueutils", "settings": {"timeout": 5000}},
                    {"settings": {"debug": true}}
                ],
                "arrayStrategy": "replace",
                "skipNull": false,
                "indent": 2
            }
            """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://blueutils.com/api/json/merge"))
            .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,
  "mergedObject": {
    "appName": "Blueutils",
    "settings": {
      "timeout": 5000,
      "debug": true
    }
  },
  "data": {
    "appName": "Blueutils",
    "settings": {
      "timeout": 5000,
      "debug": true
    }
  },
  "result": "{\n  \"appName\": \"Blueutils\",\n  \"settings\": {\n    \"timeout\": 5000,\n    \"debug\": true\n  }\n}",
  "originalSize": 92,
  "resultSize": 112,
  "keyCount": 2
}

Validation Failure Response (HTTP 400 Bad Request)

{
  "isValid": false,
  "error": "At least two JSON objects are required for merging."
}

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 merge JSON?

Automating JSON object merging streamlines multi-environment infrastructure:

• Configuration Layering: Merges baseline manifests with cluster-specific patches in CI/CD deployment pipelines.
• LLM Context Optimization: LLMs can output focused delta patches; calling the API combines the patch with the base object without token hallucination.
• Deterministic Array Merging: Guarantees deterministic array union deduplication and key precedence across batch jobs.

Native Usage

Deep-merge JSON objects locally across terminal environments and programming runtimes:

Linux / macOS (jq)

# Using jq CLI to deep-merge JSON files
jq -s '.[0] * .[1]' f1.json f2.json

Windows (PowerShell)

# Deep-merge JSON files using Node.js in PowerShell
node -e "const deepmerge=(t,s)=>{for(let k of Object.keys(s)){if(s[k] instanceof Object&&k in t)Object.assign(s[k],deepmerge(t[k],s[k]));}Object.assign(t||{},s);return t;}; const f1=JSON.parse(require('fs').readFileSync('f1.json')); const f2=JSON.parse(require('fs').readFileSync('f2.json')); console.log(JSON.stringify(deepmerge(f1,f2),null,2));"

Python

import json

def deep_merge(dict1, dict2):
    result = dict1.copy()
    for key, value in dict2.items():
        if isinstance(value, dict) and key in result and isinstance(result[key], dict):
            result[key] = deep_merge(result[key], value)
        else:
            result[key] = value
    return result

with open("f1.json") as f1, open("f2.json") as f2:
    doc1 = json.load(f1)
    doc2 = json.load(f2)

merged = deep_merge(doc1, doc2)
print(json.dumps(merged, indent=2))

Java (Jackson)

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;

public class Main {
    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        JsonNode mainNode = mapper.readTree(new File("f1.json"));
        JsonNode updateNode = mapper.readTree(new File("f2.json"));

        JsonNode merged = mapper.readerForUpdating(mainNode).readValue(updateNode);
        System.out.println(merged.toPrettyString());
    }
}