JSON Merge API: The Complete Guide to Deep Object Merging

Need to combine multiple JSON configurations or objects? This guide covers everything you need to know about deep merging JSON via API, including merge strategies for arrays and nested objects.

What is JSON Deep Merge?

JSON deep merge combines multiple objects recursively, preserving nested structures. Unlike shallow merge (Object.assign), deep merge handles nested objects by merging their contents rather than replacing them entirely.

For example, merging {"user": {"name": "John"}} with {"user": {"age": 30}} produces {"user": {"name": "John", "age": 30}}.

Merge Strategies

Different strategies handle conflicts differently:

Last Wins (Default)

Later values overwrite earlier ones. Simple and predictable. Most common strategy.

First Wins

Earlier values take precedence. Useful when base config should not be overridden.

Array Handling

Options: replace (default), concat, union (dedupe). Choose based on your use case.

Using the JSON Merge API

TinyFn provides a simple endpoint to merge JSON objects:

POST https://api.tinyfn.io/v1/json/merge
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "objects": [
    {"user": {"name": "John"}, "settings": {"theme": "dark"}},
    {"user": {"age": 30}, "settings": {"notifications": true}},
    {"user": {"city": "NYC"}}
  ]
}

{
  "merged": {
    "user": {
      "name": "John",
      "age": 30,
      "city": "NYC"
    },
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  },
  "sourceCount": 3
}

Parameters

Code Examples

JavaScript / Node.js

// Deep merge objects
const response = await fetch(
  'https://api.tinyfn.io/v1/json/merge',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      objects: [
        { user: { name: 'John' }, tags: ['admin'] },
        { user: { age: 30 }, tags: ['user'] }
      ],
      arrayStrategy: 'concat'
    })
  }
);
const { merged } = await response.json();
console.log(merged);
// { user: { name: 'John', age: 30 }, tags: ['admin', 'user'] }

Python

import requests

response = requests.post(
    'https://api.tinyfn.io/v1/json/merge',
    json={
        'objects': [
            {'user': {'name': 'John'}, 'tags': ['admin']},
            {'user': {'age': 30}, 'tags': ['user']}
        ],
        'arrayStrategy': 'concat'
    },
    headers={'X-API-Key': 'your-api-key'}
)
merged = response.json()['merged']
print(merged)
# {'user': {'name': 'John', 'age': 30}, 'tags': ['admin', 'user']}

cURL

curl -X POST "https://api.tinyfn.io/v1/json/merge" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "objects": [
      {"user": {"name": "John"}, "tags": ["admin"]},
      {"user": {"age": 30}, "tags": ["user"]}
    ],
    "arrayStrategy": "concat"
  }'

Common Use Cases

• Configuration Layering: Merge default, environment, and user configs
• API Responses: Combine data from multiple endpoints
• State Management: Merge partial state updates
• Form Defaults: Merge form data with default values
• Theme Customization: Overlay custom theme on base theme

Best Practices

1. Order matters: Later objects override earlier ones
2. Choose array strategy carefully: Replace vs concat has big implications
3. Handle undefined vs null: They may be treated differently
4. Validate result: Ensure merged object meets your schema

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-json": {
      "url": "https://api.tinyfn.io/mcp/json/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all json tools available via MCP in our JSON MCP Tools for AI Agents guide.