Merge JSON Configuration Files

Result: Merged JSON config

The override updates only specific fields:

• server.port changed from 3000 → 8080
• database.host updated for production
• nested settings like database.pool remain unchanged

This behavior is called a deep merge — only the fields you override are updated, while the rest of the configuration is preserved.

Why this matters: use this pattern when you need to merge nested JSON config, deep merge environment config, or combine base and override JSON while preserving defaults.

{
  "server": {
    "port": 8080,
    "cors": {
      "enabled": true,
      "origins": ["https://myservice.com"]
    }
  },
  "database": {
    "host": "db.prod.internal",
    "pool": {
      "min": 2,
      "max": 10
    }
  }
}

If you also need to clean JSON before deployment or compare JSON config changes before merging, the same pipeline approach can help you prepare the data.

What is JSON config merging?

JSON config merging is the process of combining a base JSON file with an override file where matching fields are updated and unchanged nested defaults are preserved.

Unlike a shallow merge, a deep merge can update nested values without replacing the entire parent object.

Environment-specific files usually change only a few values, but those values often live inside nested objects like server, database, logging, and features.

Common use cases include building production configs, merging CI/CD settings, and assembling app configuration from shared defaults.

Example (Before / After)

Before: a base config has development defaults.

{
  "server": {
    "port": 3000,
    "cors": {
      "enabled": true,
      "origins": ["http://localhost:3000"]
    }
  },
  "database": {
    "host": "localhost",
    "pool": {
      "min": 2,
      "max": 10
    }
  }
}

Override: production-specific values update only part of the config.

{
  "server": {
    "port": 8080,
    "cors": {
      "origins": ["https://myservice.com"]
    }
  },
  "database": {
    "host": "db.prod.internal"
  }
}

How it works

You can merge JSON configs online by pasting the base config, adding the environment override, selecting Deep Merge, and previewing the final config.

1. Paste the base JSON config into the primary input
2. Paste the override config into the merge input
3. Select Deep Merge
4. Choose conflict and array behavior
5. Export, download, or reuse the workflow

You can export and download the final merged config for deployments, CI/CD pipelines, app settings, or internal automation.

To merge JSON configuration files, load the base config first, apply the override second, and define how conflicts and arrays should be handled.

The Deep Merge utility can apply the same merge rules repeatedly once the method is clear.

You can copy this setup:

{
  "conflictStrategy": "deepMerge",
  "arrayStrategy": "replace"
}

For this example, the workflow does:

1. Load the base JSON config as the primary input.
2. Load the environment override as the merge input.
3. Deep merge matching objects while replacing arrays according to the config.

Result

You end up with:

• production values for server.port and database.host
• preserved nested defaults that the override does not mention
• predictable array behavior for fields like CORS origins
• one final JSON config ready for deployment

If the merged output is too broad, adjust the array strategy or split the merge into smaller config layers.

The pipeline example below shows the generated workflow that combines the base config and production override.

Common problems when merging JSON configs

JSON config gets messy because shared defaults, local settings, staging overrides, and production overrides evolve separately.

Common problems include:

• shallow merges replacing entire nested objects
• arrays needing clear replace or merge rules
• environment overrides accidentally removing defaults
• final configs that are hard to review before deployment

Without a repeatable workflow, config merging often becomes fragile build-time logic that is hard to review and harder to reuse.

Unlike simple object assignment, this approach should account for nested defaults, conflict rules, arrays, and repeatable output.

Limitations of JSON config merging

JSON config merging can break down when conflict behavior is unclear or when arrays need custom handling.

Common limitations include:

• arrays may need replace, concat, or custom merge behavior
• null values may mean remove, override, or keep depending on the system
• multiple override layers can be hard to reason about
• large config sets may require chunking or validation steps

For very large JSON files, consider streaming or chunked processing before running the full merge workflow.

For these cases, compare configs first, validate the final schema, or split config layers into smaller steps.

When to use a JSON config merge tool

You can merge JSON configs using scripts or online tools. Scripts give control but require maintenance. Tools are faster for repeated workflows, especially with nested environment overrides.

Use this when:

• you have base + environment configs
• you want to preserve nested defaults
• you need predictable deployment configs

Use scripts when config rules are stable and code-owned. Use a visual workflow when teams need to review merged output or adjust array/conflict rules safely.

For simple objects, a short script may be enough. For nested configs, programmatic merging needs extra rules for arrays, null values, conflict priority, and validation.

A visual JSON pipeline can help developers prototype merge rules, test the output, and reuse the workflow through an API. See the OpenAPI reference for repeatable API-based workflows.

The best approach should support:

• nested JSON
• conflict strategies
• array behavior
• previewable output
• reusable pipelines

Forge Json is designed for these use cases. Use it when JSON config files are nested, environment-specific, reused across teams, or need repeatable merge behavior rather than a one-off script.

Related JSON workflows

• Flatten nested JSON → Flatten nested JSON
• Compare JSON changes → Compare JSON changes
• Clean API responses → Clean API responses

FAQ

How do I merge JSON configuration files?

Merge JSON configuration files by loading a base config, applying an override config, and using deep merge rules to preserve untouched nested defaults.

What is a deep merge in JSON?

A deep merge updates nested fields without replacing the entire parent object, so defaults like database.pool can survive environment overrides.

How should arrays be handled when merging JSON?

Arrays need an explicit strategy, such as replace or concatenate. For environment configs, replacing arrays is often safer and easier to review.

Should I merge JSON configs with scripts or tools?

Use scripts for stable config rules. Use tools or reusable workflows when teams need to preview output, adjust array behavior, or reuse merge logic.