Merge JSON Feature Flag Configs with Override Support

The production layer turns checkout on but says nothing about rollout. Deep merge keeps the base's rollout object intact instead of dropping it — the whole reason to deep-merge flag configs.

Input 1 (base): { "checkout": { "enabled": false, "rollout": { "percent": 10 } } }
Input 2 (prod): { "checkout": { "enabled": true } }

Strategy: Deep merge

Output:
{
  "checkout": {
    "enabled": true,
    "rollout": { "percent": 10 }
  }
}

Add a beta-segment layer that pushes the rollout to full. Three inputs fold left-to-right, so the segment (Input 3) wins the rollout leaf while env (Input 2) still owns enabled.

Input 1 (base): { "checkout": { "enabled": false, "rollout": { "percent": 10 } } }
Input 2 (prod): { "checkout": { "enabled": true } }
Input 3 (beta): { "checkout": { "rollout": { "percent": 100 } } }

Strategy: Deep merge

Output:
{
  "checkout": {
    "enabled": true,
    "rollout": { "percent": 100 }
  }
}

A flag's segments array should accumulate across layers, not get overwritten. Deep merge replaces the array; Array append concatenates.

Input 1: { "promo": { "segments": ["us"] } }
Input 2: { "promo": { "segments": ["eu"] } }

Strategy: Deep merge → { "promo": { "segments": ["eu"] } }
Strategy: Array append → { "promo": { "segments": ["us", "eu"] } }

Note: array-append replaces nested OBJECTS last-wins;
only arrays are concatenated.

An experiment layer should introduce its own flags but never override one the base already pins. First wins keeps the base value for any shared key and only adds the new flag.

Input 1 (base):       { "newNav": { "enabled": false } }
Input 2 (experiment): { "newNav": { "enabled": true }, "betaBanner": { "enabled": true } }

Strategy: First wins

Output:
{
  "newNav": { "enabled": false },
  "betaBanner": { "enabled": true }
}
→ newNav NOT flipped; betaBanner added.

Once you've folded the layers, compare the resolved JSON against what production is actually serving to spot drift. Merge here, then move both files to the diff tool.

Step 1 — merge base + prod + segment here → resolved.json
Step 2 — paste resolved.json and live-export.json into json-diff

json-diff output (illustrative):
  ~ checkout.rollout.percent: 100 → 50
  - betaBanner            (present resolved, missing live)

→ live is behind on two flags; redeploy.

If a flag's segments or variations is an array, the default deep strategy replaces it with the later layer's array rather than combining. A segment override with segments: ["eu"] will drop the base's ["us"]. Use Array append when arrays should accumulate, and always verify array-valued flag fields after merging.

Flag exports occasionally arrive with trailing commas or comments from a hand-edited config. JSON.parse rejects those and the merge stops with the parser message. Strip comments and trailing commas, or run the file through the json-format-fixer first.

If the base has { "checkout": { "enabled": true, "rollout": {...} } } but an override has { "checkout": true }, the boolean replaces the whole object (object-vs-primitive is a type mismatch under last-wins). Keep your override shapes consistent with the base — override the leaf (checkout.enabled), not the whole flag, to preserve rollout/targeting.

Base + env + segment is three inputs, which exceeds the free tier's 2-input limit. Pro allows up to 10. Workaround on free: merge base + env, copy the result back into Input 1, then add the segment as Input 2 for a second pass.

Some platforms export flags as a JSON array of flag objects. The merger iterates object keys, so two arrays merge by index (flag at position 0 with flag at position 0) — not by flag key. Convert array exports to a key-by-id object first (e.g. with the json-transposer or a quick reshape), then merge.

If both an env and a segment override set checkout.enabled: true, the result is true either way — there's no conflict to surface. The merger won't flag redundant overrides; use the json-diff between layers if you want to find overrides that change nothing and could be deleted.

A layer with { "oldFlag": null } replaces whatever the base had (object or primitive) with null under last-wins — it does not delete the key. If your loader treats null as 'remove', strip nulls from the merged result afterward with the json-null-stripper.

A blank textarea is skipped — it doesn't count toward the input total and contributes nothing. If every override is empty you'll fall below the 2-input minimum and the tool will ask for at least two non-empty inputs.