A utility for merging JSON objects that supports fine options and multiple JSON providers.
Pass two previously loaded JSON documents to be merged. The resulting JSON shall contain all exclusive objects from source documents. 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 on one side and simple value or complex object on the other), then a copy of the object from the highest-precedence document will be selected as a 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"
}
]
}
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. Your application must resolve these dependencies 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.3.jar --help
Usage: jsonmerge-cli-1.2.3.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.3</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.