☯️ Json::Merge

if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know on Discord or RubyForum, as I may have missed the notification.

---

if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.

👣 How will this project approach the September 2025 hostile takeover of RubyGems? 🚑️

I've summarized my thoughts in this blog post.

🌻 Synopsis

Json::Merge intelligently merges two versions of a JSON, JSONC, or JSON5 file using the StructuredMerge Ruby stack. It is built on ast-merge and tree_haver, with parser capability reported through the shared backend registry.

JSONC and JSON5 use the same Json::Merge API as JSON; use require "json/merge" for all three dialects.

JSONC Support

The JSON merge provider supports JSON, JSONC, and JSON5 dialects through Json::Merge. Pass JSONC content to the same merger API used for JSON.

JSONC-specific behavior:

- **Single API**: JSON and JSONC both use `Json::Merge`
- **Comment-Aware**: Preserves `//` and `/* */` comments when the parser exposes them
- **Trailing Commas**: Accepts trailing commas in JSONC objects and arrays
- **JSONC Boundaries**: Rejects JSON5-only syntax such as unquoted keys,
single-quoted strings, and JSON5 numeric literals
- **Freeze Blocks**: Uses the `json-merge` freeze token by default, with a custom token available when needed

JSON5 Support

JSON5 uses the same structural merge engine with dialect: :json5. It accepts JSON5 syntax, including comments, trailing commas, unquoted object keys, single-quoted strings, hexadecimal and signed numeric literals, Infinity, and NaN. JSONC remains intentionally narrower: it accepts comments and trailing commas, but rejects the JSON5-only forms.

Key Features

- **Tree-Sitter Powered**: Uses tree-sitter-json for strict JSON and the
normalized JSON5 tree for JSONC and JSON5 syntax
- **JSONC-Aware**: Preserves `//` and `/* */` comments when the parser exposes them
- **Intelligent**: Matches objects and arrays by structural signatures
- **Fuzzy Property Matching**: `ObjectMatchRefiner` matches similar property names
(e.g., `databaseUrl` ↔ `database_url`) using Levenshtein distance for naming convention differences
- **Full Provenance**: Tracks origin of every node
- **StructuredMerge Native**: Depends on `ast-merge` and `tree_haver`; parser availability comes from registered backend providers
- **Customizable**:
  - `signature_generator` - callable custom signature generators
  - `preference` - setting of `:template`, `:destination`, or a Hash for per-node-type preferences
  - `node_splitter` - Hash mapping node types to callables for per-node-type merge customization (see [ast-merge][ast-merge] docs)
  - `add_template_only_nodes` - setting to retain nodes that do not exist in destination
  - `match_refiners` - array of refiners for fuzzy matching (e.g., `ObjectMatchRefiner`)

Supported Node Types

Node Type	Signature Format	Matching Behavior
Object	[:object, key_signatures...]	Objects match by their key structure
Array	[:array, element_count]	Arrays match by position and type
Pair	[:pair, key_name]	Key-value pairs match by key name
String	[:string, value]	Strings match by value
Number	[:number, value]	Numbers match by value
Boolean	[:boolean, value]	Booleans match by value
Null	[:null]	Null values always match

Example

require "json/merge"

template = File.read("template.json")
destination = File.read("destination.json")

merger = Json::Merge::SmartMerger.new(template, destination)
result = merger.merge

File.write("merged.json", result.to_json)

💡 Info you can shake a stick at

Tokens to Remember
Works with MRI Ruby 4
Support & Community
Source
Documentation
Compliance
Style
Maintainer 🎖️
... 💖	🧊 🐙 🛖 🧪

Compatibility

Compatible with MRI Ruby 4.0.0+, and concordant releases of JRuby, and TruffleRuby. CI workflows and Appraisals are generated for MRI Ruby 4.0.0+. This test floor is configured by ruby.test_minimum in .kettle-jem.yml and may be higher than the gem's runtime compatibility floor when legacy Rubies are not practical for the current toolchain.

The amazing test matrix is powered by the kettle-dev stack.

How kettle-dev manages complexity in tests

Gem	Source	Role	Total downloads
appraisal2	GitHub	multi-dependency Appraisal matrix generation
appraisal2-rubocop	GitHub	RuboCop Appraisal generator integration
kettle-dev	GitHub	development, release, and CI workflow tooling
kettle-jem	GitHub	Appraisals & CI workflow templates
kettle-soup-cover	GitHub	SimpleCov coverage policy and reporting
kettle-test	GitHub	standard test runner and coverage harness
rubocop-lts	GitHub	Ruby-version-aware linting
turbo_tests2	GitHub	parallel test execution

✨ Installation

Install the gem and add to the application's Gemfile by executing:

bundle add json-merge

If bundler is not being used to manage dependencies, install the gem by executing:

gem install json-merge

⚙️ Configuration

Signature Match Preference

Control which version to use when nodes have matching signatures but different content:

# Use template version (for config updates)
merger = Json::Merge::SmartMerger.new(
  template,
  destination,
  preference: :template,
)

# Use destination version (default - preserve customizations)
merger = Json::Merge::SmartMerger.new(
  template,
  destination,
  preference: :destination,
)

Template-Only Nodes

Control whether to add nodes that only exist in the template:

# Add template-only nodes
merger = Json::Merge::SmartMerger.new(
  template,
  destination,
  add_template_only_nodes: true,
)

Object Match Refiner

When JSON object properties (key-value pairs) don't match by exact key name, the ObjectMatchRefiner uses fuzzy matching to pair entries with:

- Similar key names (e.g., `databaseUrl` vs `database_url`)
- Keys with typos or different naming conventions (camelCase vs snake\_case)
- Array elements with similar structure or content

# Enable object fuzzy matching
merger = Json::Merge::SmartMerger.new(
  template,
  destination,
  match_refiners: [
    Json::Merge::ObjectMatchRefiner.new(threshold: 0.5),
  ],
)

ObjectMatchRefiner Options

Option	Default	Description
threshold	0.5	Minimum similarity score (0.0-1.0) to accept a match
key_weight	0.7	Weight for key name similarity
value_weight	0.3	Weight for value similarity

# Custom weights for key-centric matching
refiner = Json::Merge::ObjectMatchRefiner.new(
  threshold: 0.6,
  key_weight: 0.8,   # Focus more on key names
  value_weight: 0.2,  # Less focus on values
)

Debug Logging

Enable debug logging to see merge decisions:

export JSON_MERGE_DEBUG=1

JSONC and JSON5 Options

JSONC and JSON5 files use the same options as JSON files. Set dialect when constructing a direct merger:

merger = Json::Merge::SmartMerger.new(
  template_content,
  dest_content,
  # Which version to prefer when nodes match
  # :destination (default) - keep destination values
  # :template - use template values
  preference: :destination,

  # Whether to add template-only nodes to the result
  # false (default) - only include properties that exist in destination
  # true - include all template properties
  add_template_only_nodes: false,

  # :json (strict), :jsonc (comments and trailing commas), or :json5
  dialect: :jsonc,

  # Token for freeze block markers
  # Default: "json-merge"
  # Looks for: // json-merge:freeze / // json-merge:unfreeze
  freeze_token: "json-merge",

  # Custom signature generator (optional)
  # Receives a node, returns a signature array or nil
  signature_generator: ->(node) { [:pair, node.key] if node.type == :pair },
)

🔧 Basic Usage

Merging Two JSON Files

require "json/merge"

template_content = File.read("template.json")
dest_content = File.read("destination.json")

merger = Json::Merge::SmartMerger.new(template_content, dest_content)
result = merger.merge

File.write("merged.json", result.to_json)

Analyzing a JSON File

require "json/merge"

source = File.read("config.json")
analysis = Json::Merge::FileAnalysis.new(source)

# Iterate over all top-level nodes
analysis.statements.each do |node|
  sig = analysis.generate_signature(node)
  puts "#{node.class}: #{sig.inspect}"
end

Fuzzy Property Matching

When property names differ between template and destination (e.g., naming convention changes), use the ObjectMatchRefiner:

require "json/merge"

template = <<~JSON
  {
    "databaseUrl": "postgres://localhost/app",
    "cacheTimeout": 3600,
    "apiEndpoint": "https://api.example.com"
  }
JSON

destination = <<~JSON
  {
    "database_url": "postgres://localhost/custom",
    "cache_ttl": 7200,
    "api_endpoint": "https://custom.example.com"
  }
JSON

# Default merge won't match keys (names differ - camelCase vs snake_case)
# Use ObjectMatchRefiner for fuzzy matching
merger = Json::Merge::SmartMerger.new(
  template,
  destination,
  match_refiners: [
    Json::Merge::ObjectMatchRefiner.new(threshold: 0.5),
  ],
)
result = merger.merge

# Properties are matched despite naming convention differences:
# - databaseUrl ↔ database_url (similar when normalized)
# - cacheTimeout ↔ cache_ttl (similar: "cache")
# - apiEndpoint ↔ api_endpoint (similar when normalized)

Array Element Matching

The ObjectMatchRefiner also handles array elements with similar structure:

template = <<~JSON
  {
    "users": [
      { "id": 1, "userName": "alice" },
      { "id": 2, "userName": "bob" }
    ]
  }
JSON

destination = <<~JSON
  {
    "users": [
      { "id": 1, "user_name": "alice_custom" },
      { "id": 3, "user_name": "charlie" }
    ]
  }
JSON

merger = Json::Merge::SmartMerger.new(
  template,
  destination,
  match_refiners: [
    Json::Merge::ObjectMatchRefiner.new(threshold: 0.5),
  ],
)
# Array elements with matching IDs or similar structure are paired

Merging JSONC Files

require "json/merge"

template = File.read("template.jsonc")
destination = File.read("destination.jsonc")

merger = Json::Merge::SmartMerger.new(template, destination)
result = merger.merge

File.write("merged.jsonc", result)

Merging JSON5 Files

require "json/merge"

template = File.read("template.json5")
destination = File.read("destination.json5")

merger = Json::Merge::SmartMerger.new(template, destination, dialect: :json5)
result = merger.merge

File.write("merged.json5", result)

JSONC Freeze Blocks

Freeze blocks protect sections from being overwritten during merge:

{
  "name": "my-app",

  // json-merge:freeze Secret configuration
  "api_key": "my_production_api_key",
  "api_secret": "super_secret_value",
  // json-merge:unfreeze

  "debug": false
}

Content between // json-merge:freeze and // json-merge:unfreeze markers is preserved from the destination file, regardless of what the template contains.

Adding Template-Only JSONC Properties

merger = Json::Merge::SmartMerger.new(
  template,
  destination,
  add_template_only_nodes: true,
)
result = merger.merge
# Result includes properties from template that do not exist in destination

🔐 Security

See SECURITY.md.

🤝 Contributing

If you need some ideas of where to help, you could work on adding more code coverage, or if it is already 💯 (see below) check issues or PRs, or use the gem and think about how it could be better.

We so if you make changes, remember to update it.

See CONTRIBUTING.md for more detailed instructions.

Code Coverage

Coverage service badges

📌 Versioning

This library follows for its public API where practical. For most applications, prefer the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("json-merge", "~> 7.0")

📌 Is "Platform Support" part of the public API? More details inside.

Dropping support for a platform can be a breaking change for affected users. If a release changes supported platforms, it should be called out clearly in the changelog and versioned with that impact in mind.

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

• "Major Version Numbers are Not Sacred"

See CHANGELOG.md for a list of releases.

📄 License

The gem is available under the following licenses: AGPL-3.0-only, PolyForm-Small-Business-1.0.0. See LICENSE.md for details.

If none of the available licenses suit your use case, please contact us to discuss a custom commercial license.