Philiprehberger.JsonMerge 0.3.0

Philiprehberger.JsonMerge

Deep merge JSON documents with configurable array strategies and null handling using System.Text.Json.

Installation

dotnet add package Philiprehberger.JsonMerge

Usage

using System.Text.Json.Nodes;
using Philiprehberger.JsonMerge;

var baseDoc = JsonNode.Parse("""{"name": "app", "db": {"host": "localhost", "port": 5432}}""");
var overrideDoc = JsonNode.Parse("""{"db": {"host": "production.db", "ssl": true}, "version": "2.0"}""");

var result = JsonMerge.Merge(baseDoc!, overrideDoc!);
// {"name": "app", "db": {"host": "production.db", "port": 5432, "ssl": true}, "version": "2.0"}

Custom Options

using System.Text.Json.Nodes;
using Philiprehberger.JsonMerge;

var options = new MergeOptions(ArrayStrategy.Concat, NullHandling.Remove);
var result = JsonMerge.Merge(baseDoc!, overrideDoc!, options);

Merge Multiple Documents

using System.Text.Json.Nodes;
using Philiprehberger.JsonMerge;

var result = JsonMerge.MergeAll(defaults, environment, local);

Array Element Matching by Key

using System.Text.Json.Nodes;
using Philiprehberger.JsonMerge;

var baseDoc = JsonNode.Parse("""{"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}""");
var overrideDoc = JsonNode.Parse("""{"users": [{"id": 2, "name": "Robert"}]}""");

var options = new MergeOptions(ArrayMatchKey: "id");
var result = JsonMerge.Merge(baseDoc!, overrideDoc!, options);
// Users matched by "id": Bob becomes Robert, Alice unchanged

Merge Conflict Callback

using System.Text.Json;
using System.Text.Json.Nodes;
using Philiprehberger.JsonMerge;

var options = new MergeOptions(OnConflict: (path, left, right) =>
{
    // Custom resolution: keep the base value for "name" paths
    return path.EndsWith("name") ? left : right;
});
var result = JsonMerge.Merge(baseDoc!, overrideDoc!, options);

Path-Based Selective Merge

using System.Text.Json.Nodes;
using Philiprehberger.JsonMerge;

var options = new MergeOptions(PathFilter: new[] { "db.host", "version" });
var result = JsonMerge.Merge(baseDoc!, overrideDoc!, options);
// Only "db.host" and "version" are merged from override; other paths keep base values

RFC 7396 JSON Merge Patch

using System.Text.Json;
using Philiprehberger.JsonMerge;

var target = JsonDocument.Parse("""{"a": 1, "b": 2, "c": 3}""");
var patch = JsonDocument.Parse("""{"b": null, "c": 4, "d": 5}""");

var result = JsonMerge.MergePatch(target, patch);
// {"a": 1, "c": 4, "d": 5} — "b" removed by null, "c" updated, "d" added

API

JsonMerge

MergeOptions

ArrayStrategy

NullHandling

Development

dotnet build src/Philiprehberger.JsonMerge.csproj --configuration Release

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT