A utility for merging JSON objects that supports fine options and multiple JSON providers.

ℹ️ Find examples in the wiki.

Simply pass two previously loaded JSON documents to be merged. The resulting JSON shall contain all exclusive objects from source documents. And in case of key collision (i.e., the same key appears in both documents), the following rules will be applied:

• For simple values, such as strings, numbers and boolean values, the value from the highest-precedence JSON document will be selected
• If the value is a JSON object in both documents, the two objects will be merged recursively
• If the value is a JSON array in both documents, then all distinct elements (i.e., not repeated ones) will be copied to the resulting array, unless a custom JsonMergeOption is provided specifically for that array path
• If the types are incompatible in the source JSON documents (e.g.: array in one side and simple value or complex object in the other), then a copy of the object from the highest-precedence document will be selected as fallback

ℹ️ Note: The first JSON document is always considered to have higher precedence than the second one.

The operation accepts an arbitrary number of options for parts of the document defined by JSONPath Expressions.

JsonMergeOption.onPath("$.params")
          .findObjectsIdentifiedBy("key")
          .thenDoADeepMerge();

💡 Call JsonMergeOption.onPath(String) then let the API guide you through the additional builder methods.

This is particularly useful to define distinct elements during the merge of an array of objects, such as the following:

{
  "params": [
    {
      "key": "language",
      "value": "pt-BR"
    },
    {
      "key": "country",
      "value": "Brazil"
    }
  ]
}

ℹ️ Find more examples in the wiki.

The algorithm implemented by JSON Merge is provider-agnostic. The actual read/write operations on the JSON objects are delegated to a specialized JsonProvider which must be specified during JsonMerger creation. This design was chosen to eliminate the need for intermediary JSON object type conversions for the different providers.

The Project supports the most popular JSON providers available in the community today.

⚠️ IMPORTANT: JSON Merge does NOT supply the dependencies tagged as "optional" to avoid the burden of unintended transitive dependencies in your application. These dependencies must be resolved by your application if required.

The choice for those looking for simplicity and good performance

import net.minidev.json.JSONObject;
...
JsonMerger<JSONObject> merger = new JsonMerger<>(JSONObject.class);
                       /* or... new JsonMerger<>(new JsonSmartJsonProvider()); */

Google implementation with enhanced conversion capabilities

import com.google.gson.JsonObject;
...
JsonMerger<JsonObject> merger = new JsonMerger<>(JsonObject.class);
                       /* or... new JsonMerger<>(new GsonJsonProvider()); */

The #1 JSON library in Maven Central

import com.fasterxml.jackson.databind.JsonNode;
...
JsonMerger<JsonNode> merger = new JsonMerger<>(JsonNode.class);
                     /* or... new JsonMerger<>(new JacksonJsonNodeJsonProvider()); */

The reference implementation for Java

import org.json.JSONObject;
...
JsonMerger<JSONObject> merger = new JsonMerger<>(JSONObject.class);
                       /* or... new JsonMerger<>(new JsonOrgJsonProvider()); */

Vert.x is a reactive programming toolkit used by 1K+ projects which uses a dedicated JSON implementation

import io.vertx.core.json.JsonObject;
...
JsonMerger<JsonObject> merger = new JsonMerger<>(JsonObject.class);
                       /* or... new JsonMerger<>(new VertxJsonProvider()); */

This is a command-line tool for merging JSON files directly from the terminal.

$ java -jar jsonmerge-cli-1.2.2.jar --help

Usage: jsonmerge-cli-1.2.2.jar [-hp] [-t <target>] [-d <exp=key>]... <FILE1> <FILE2>

Parameters:

      <FILE1>                The first file to merge
      <FILE2>                The second file to merge

Options:

  -d, --distinct <exp=key>   Defines one or more distinct keys inside a child path
                             For example: -d $.agents=name
                                          -d $.files=id,version
  -h, --help                 Displays a help message
  -p, --pretty               Generates a well-formatted result file
  -t, --target <target>      The target file name (default: result.json)

If you are using Maven, add jsonmerge-core as a dependency in your pom.xml file:

<dependency>
    <groupId>net.obvj</groupId>
    <artifactId>jsonmerge-core</artifactId>
    <version>1.2.2</version>
</dependency>

If you use other dependency management systems (such as Gradle, Grape, Ivy, etc.) click here.

To use JSON Merge CLI, download the latest version here (JRE 8+ required).

If you want to contribute to the JSON Merge project, check the issues page, or send an e-mail to oswaldo@obvj.net.

JSON Merge uses GitHub Actions for CI/CD.