{"id":22282071,"url":"https://github.com/oswaldobapvicjr/jsonmerge","last_synced_at":"2025-09-09T00:39:48.669Z","repository":{"id":56782956,"uuid":"524247697","full_name":"oswaldobapvicjr/jsonmerge","owner":"oswaldobapvicjr","description":"Utility for merging JSON objects supporting multiple JSON providers","archived":false,"fork":false,"pushed_at":"2025-09-01T00:59:13.000Z","size":238,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-01T02:39:45.302Z","etag":null,"topics":["gson","jackson","java","json","json-merge","json-merger","json-org","json-smart","jsonpath","merge"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oswaldobapvicjr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-08-12T23:18:20.000Z","updated_at":"2025-09-01T00:59:13.000Z","dependencies_parsed_at":"2023-02-15T19:15:59.978Z","dependency_job_id":"fd14b970-964a-405e-a06f-0edce638324f","html_url":"https://github.com/oswaldobapvicjr/jsonmerge","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/oswaldobapvicjr/jsonmerge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oswaldobapvicjr%2Fjsonmerge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oswaldobapvicjr%2Fjsonmerge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oswaldobapvicjr%2Fjsonmerge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oswaldobapvicjr%2Fjsonmerge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oswaldobapvicjr","download_url":"https://codeload.github.com/oswaldobapvicjr/jsonmerge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oswaldobapvicjr%2Fjsonmerge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231107,"owners_count":25245687,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gson","jackson","java","json","json-merge","json-merger","json-org","json-smart","jsonpath","merge"],"created_at":"2024-12-03T16:25:16.074Z","updated_at":"2025-09-09T00:39:48.659Z","avatar_url":"https://github.com/oswaldobapvicjr.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON Merge\n\n[![Java 8+](https://img.shields.io/badge/Java-8%2B-blue.svg)](https://openjdk.java.net/)\n[![License](https://img.shields.io/badge/license-apache%202.0-brightgreen.svg)](https://opensource.org/licenses/Apache-2.0)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/oswaldobapvicjr/jsonmerge/maven.yml?branch=main)](https://github.com/oswaldobapvicjr/jsonmerge/actions/workflows/maven.yml)\n[![Coverage](https://img.shields.io/codecov/c/github/oswaldobapvicjr/jsonmerge)](https://codecov.io/gh/oswaldobapvicjr/jsonmerge)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.obvj/jsonmerge-core/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.obvj/jsonmerge-core)\n[![Javadoc](https://javadoc.io/badge2/net.obvj/jsonmerge-core/javadoc.svg)](https://javadoc.io/doc/net.obvj/jsonmerge-core)\n[![Vulnerabilities](https://snyk.io/test/github/oswaldobapvicjr/jsonmerge/badge.svg?targetFile=jsonmerge-core/pom.xml)](https://snyk.io/test/github/oswaldobapvicjr/jsonmerge?targetFile=jsonmerge-core/pom.xml)\n\n\nA utility for merging JSON objects that supports **fine options** and **multiple JSON providers**.\n\n\u003e ℹ️ [Find examples in the wiki.](https://github.com/oswaldobapvicjr/jsonmerge/wiki/Examples/)\n\n---\n \n## How it works\n\nPass 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:\n\n- For **simple values**, such as strings, numbers, and boolean values, the value from the highest-precedence JSON document will be selected\n- If the value is a **JSON object** in both documents, the two objects will be merged recursively\n- 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\n- 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\n\n\u003e ℹ️ **Note:** The first JSON document is always considered to have **higher precedence** than the second one.\n\n\n\n## Define custom behavior for child elements\n\nThe operation accepts an arbitrary number of options for parts of the document defined by [JSONPath Expressions](https://goessner.net/articles/JsonPath/index.html#e2).\n\n```java\nJsonMergeOption.onPath(\"$.params\")\n          .findObjectsIdentifiedBy(\"key\")\n          .thenDoADeepMerge();\n```\n\n\u003e :bulb: Call `JsonMergeOption.onPath(String)` then let the API guide you through the additional builder methods.\n\nThis is particularly useful to define distinct elements during the merge of an array of objects, such as the following:\n\n```json\n{\n  \"params\": [\n    {\n      \"key\": \"language\",\n      \"value\": \"pt-BR\"\n    },\n    {\n      \"key\": \"country\",\n      \"value\": \"Brazil\"\n    }\n  ]\n}\n```\n\n\u003e ℹ️ [Find more examples in the wiki.](https://github.com/oswaldobapvicjr/jsonmerge/wiki/Examples/)\n\n\n## Use your favorite JSON Provider\n\nThe 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.\n\nThe Project supports the most popular JSON providers available in the community today.\n\n![Supported JSON providers](resources/jsonmerge%20-%20Json%20Providers%20diagram%20-%201.2-A.svg)\n\n\u003e :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.\n\n### How to use\n\n#### Using json-smart as JSON Provider\n\n\u003e The choice for those looking for simplicity and good performance\n\n```java\nimport net.minidev.json.JSONObject;\n...\nJsonMerger\u003cJSONObject\u003e merger = new JsonMerger\u003c\u003e(JSONObject.class);\n                       /* or... new JsonMerger\u003c\u003e(new JsonSmartJsonProvider()); */\n````\n\n#### Using Gson as JSON Provider\n\n\u003e Google implementation with enhanced conversion capabilities\n\n```java\nimport com.google.gson.JsonObject;\n...\nJsonMerger\u003cJsonObject\u003e merger = new JsonMerger\u003c\u003e(JsonObject.class);\n                       /* or... new JsonMerger\u003c\u003e(new GsonJsonProvider()); */\n````\n\n#### Using Jackson as JSON Provider\n\n\u003e The #1 JSON library in Maven Central\n\n```java\nimport com.fasterxml.jackson.databind.JsonNode;\n...\nJsonMerger\u003cJsonNode\u003e merger = new JsonMerger\u003c\u003e(JsonNode.class);\n                     /* or... new JsonMerger\u003c\u003e(new JacksonJsonNodeJsonProvider()); */\n\n````\n\n#### Using json.org as JSON Provider\n\n\u003e The reference implementation for Java\n\n```java\nimport org.json.JSONObject;\n...\nJsonMerger\u003cJSONObject\u003e merger = new JsonMerger\u003c\u003e(JSONObject.class);\n                       /* or... new JsonMerger\u003c\u003e(new JsonOrgJsonProvider()); */\n````\n\n#### Using Vert.x as JSON Provider\n\n\u003e Vert.x is a reactive programming toolkit used by 1K+ projects which uses a dedicated JSON implementation\n\n```java\nimport io.vertx.core.json.JsonObject;\n...\nJsonMerger\u003cJsonObject\u003e merger = new JsonMerger\u003c\u003e(JsonObject.class);\n                       /* or... new JsonMerger\u003c\u003e(new VertxJsonProvider()); */\n````\n\n## JSON Merge CLI\n\nThis is a command-line tool for merging JSON files directly from the terminal.\n\n```help\n$ java -jar jsonmerge-cli-1.2.4.jar --help\n\nUsage: jsonmerge-cli-1.2.4.jar [-hp] [-t \u003ctarget\u003e] [-d \u003cexp=key\u003e]... \u003cFILE1\u003e \u003cFILE2\u003e\n\nParameters:\n\n      \u003cFILE1\u003e                The first file to merge\n      \u003cFILE2\u003e                The second file to merge\n\nOptions:\n\n  -d, --distinct \u003cexp=key\u003e   Defines one or more distinct keys inside a child path\n                             For example: -d $.agents=name\n                                          -d $.files=id,version\n  -h, --help                 Displays a help message\n  -p, --pretty               Generates a well-formatted result file\n  -t, --target \u003ctarget\u003e      The target file name (default: result.json)\n```\n\n## Downloading\n\n### JSON Merge Core\n\nIf you are using Maven, add `jsonmerge-core` as a dependency in your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003enet.obvj\u003c/groupId\u003e\n    \u003cartifactId\u003ejsonmerge-core\u003c/artifactId\u003e\n    \u003cversion\u003e1.2.4\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003e 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).\n\n### JSON Merge CLI\n\nTo use **JSON Merge CLI**, [download the latest version here](https://repo1.maven.org/maven2/net/obvj/jsonmerge-cli/1.2.4/jsonmerge-cli-1.2.4.jar) (JRE 8+ required).\n\n## Contributing\n\nIf you want to contribute to the **JSON Merge** project, check the [issues](http://obvj.net/jsonmerge/issues) page, or send an e-mail to [oswaldo@obvj.net](mailto:oswaldo@obvj.net).\n\n**JSON Merge** uses [GitHub Actions](https://docs.github.com/actions) for CI/CD.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foswaldobapvicjr%2Fjsonmerge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foswaldobapvicjr%2Fjsonmerge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foswaldobapvicjr%2Fjsonmerge/lists"}