Ambiguous duplicate‑key resolution when applying JSON Merge Patch

Direct answer

When a JSON Merge Patch is applied to a target that contains duplicate member names, the value that survives is implementation‑dependent. RFC 7386 does not define behavior for duplicate keys, and popular parsers differ: Jackson (2.15+) usually keeps the last occurrence when parsing into a Map or ObjectNode, Gson’s default lenient parsing also retains the last value, while json‑cpp’s Json::Reader historically keeps the first occurrence but can be configured otherwise. Consequently, which key value is retained after the patch depends on the parser used by the library that processes the patch.

Likely explanation vs confirmed facts

• Likely explanation: Most libraries parse the target JSON into an in‑memory object model before applying patch operations. The duplicate‑key survivor is therefore determined by the parser’s duplicate‑handling policy before any merge logic runs.
• Confirmed facts: RFC 7386 Section 2 explicitly leaves duplicate‑key resolution undefined. Jackson’s default behavior (2.15+) is last‑wins; Gson’s default lenient parsing likewise keeps the last value; json‑cpp’s default keeps the first occurrence but supports a strict mode that can throw or reorder. These behaviors are version‑specific and can change across major releases.

Steps to achieve consistent resolution without downtime

1. Pre‑normalize documents. Run a one‑time migration script that re‑parses every stored document with a strict parser (e.g., Jackson’s JsonParser.Feature.STRICT_DUPLICATE_DETECTION or Gson’s JsonReader.setLenient(false)) and rewrites duplicate keys using a deterministic rule (last‑wins or first‑wins, documented in the run‑book).
2. Enforce a write‑time invariant. Add a lightweight streaming validator that rejects any JSON object containing duplicate member names (RFC 8259 permits but discourages duplicates). Apply this validator on all write paths so future documents never contain duplicates.
3. Standardize read‑path parsing. After migration, configure all services that read the patched documents to use the same strict parser. This guarantees that any future patches see a duplicate‑free target.
4. If pre‑normalization is not feasible. Wrap the patch operation with a deterministic duplicate‑resolution step: parse the target with a known‑last‑wins parser, apply the Merge Patch, then serialize. Document the chosen rule in the migration run‑book so rollback or replay is predictable.

Missing diagnostic detail

To tailor the recommendation (e.g., whether a strict parser can be adopted immediately or a migration script is required), please specify which JSON library and version you are using in production.