https://github.com/oswaldobapvicjr/jsonmerge
Utility for merging JSON objects supporting multiple JSON providers
https://github.com/oswaldobapvicjr/jsonmerge
gson jackson java json json-merge json-merger json-org json-smart jsonpath merge
Last synced: 6 months ago
JSON representation
Utility for merging JSON objects supporting multiple JSON providers
- Host: GitHub
- URL: https://github.com/oswaldobapvicjr/jsonmerge
- Owner: oswaldobapvicjr
- License: apache-2.0
- Created: 2022-08-12T23:18:20.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-05T02:39:02.000Z (about 1 year ago)
- Last Synced: 2024-04-05T03:32:38.127Z (about 1 year ago)
- Topics: gson, jackson, java, json, json-merge, json-merger, json-org, json-smart, jsonpath, merge
- Language: Java
- Homepage:
- Size: 205 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# JSON Merge
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/oswaldobapvicjr/jsonmerge/actions/workflows/maven.yml)
[](https://codecov.io/gh/oswaldobapvicjr/jsonmerge)
[](https://maven-badges.herokuapp.com/maven-central/net.obvj/jsonmerge-core)
[](https://javadoc.io/doc/net.obvj/jsonmerge-core)
[](https://snyk.io/test/github/oswaldobapvicjr/jsonmerge?targetFile=jsonmerge-core/pom.xml)
A utility for merging JSON objects that supports **fine options** and **multiple JSON providers**.
> ℹ️ [Find examples in the wiki.](https://github.com/oswaldobapvicjr/jsonmerge/wiki/Examples/)
---
## How it works
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.
## Define custom behavior for child elements
The operation accepts an arbitrary number of options for parts of the document defined by [JSONPath Expressions](https://goessner.net/articles/JsonPath/index.html#e2).
```java
JsonMergeOption.onPath("$.params")
.findObjectsIdentifiedBy("key")
.thenDoADeepMerge();
```
> :bulb: 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:
```json
{
"params": [
{
"key": "language",
"value": "pt-BR"
},
{
"key": "country",
"value": "Brazil"
}
]
}
```
> ℹ️ [Find more examples in the wiki.](https://github.com/oswaldobapvicjr/jsonmerge/wiki/Examples/)
## Use your favorite JSON Provider
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.
> :warning: **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.
### How to use
#### Using json-smart as JSON Provider
> The choice for those looking for simplicity and good performance
```java
import net.minidev.json.JSONObject;
...
JsonMerger merger = new JsonMerger<>(JSONObject.class);
/* or... new JsonMerger<>(new JsonSmartJsonProvider()); */
````
#### Using Gson as JSON Provider
> Google implementation with enhanced conversion capabilities
```java
import com.google.gson.JsonObject;
...
JsonMerger merger = new JsonMerger<>(JsonObject.class);
/* or... new JsonMerger<>(new GsonJsonProvider()); */
````
#### Using Jackson as JSON Provider
> The #1 JSON library in Maven Central
```java
import com.fasterxml.jackson.databind.JsonNode;
...
JsonMerger merger = new JsonMerger<>(JsonNode.class);
/* or... new JsonMerger<>(new JacksonJsonNodeJsonProvider()); */
````
#### Using json.org as JSON Provider
> The reference implementation for Java
```java
import org.json.JSONObject;
...
JsonMerger merger = new JsonMerger<>(JSONObject.class);
/* or... new JsonMerger<>(new JsonOrgJsonProvider()); */
````
#### Using Vert.x as JSON Provider
> Vert.x is a reactive programming toolkit used by 1K+ projects which uses a dedicated JSON implementation
```java
import io.vertx.core.json.JsonObject;
...
JsonMerger merger = new JsonMerger<>(JsonObject.class);
/* or... new JsonMerger<>(new VertxJsonProvider()); */
````
## JSON Merge CLI
This is a command-line tool for merging JSON files directly from the terminal.
```help
$ java -jar jsonmerge-cli-1.2.3.jar --help
Usage: jsonmerge-cli-1.2.3.jar [-hp] [-t ] [-d ]...
Parameters:
The first file to merge
The second file to merge
Options:
-d, --distinct 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 The target file name (default: result.json)
```
## Downloading
### JSON Merge Core
If you are using Maven, add `jsonmerge-core` as a dependency in your `pom.xml` file:
```xml
net.obvj
jsonmerge-core
1.2.3
```
> If you use other dependency management systems (such as Gradle, Grape, Ivy, etc.) click [here](https://maven-badges.herokuapp.com/maven-central/net.obvj/jsonmerge-core).
### JSON Merge CLI
To use **JSON Merge CLI**, [download the latest version here](https://repo1.maven.org/maven2/net/obvj/jsonmerge-cli/1.2.3/jsonmerge-cli-1.2.3.jar) (JRE 8+ required).
## Contributing
If you want to contribute to the **JSON Merge** project, check the [issues](http://obvj.net/jsonmerge/issues) page, or send an e-mail to [[email protected]](mailto:[email protected]).
**JSON Merge** uses [GitHub Actions](https://docs.github.com/actions) for CI/CD.