Sembra

Structural similarity scoring for JSON-compatible data

Italian: "sembrare" — to seem, to resemble

The Problem

Existing deep comparison libraries answer only binary questions:

None answer the most natural question:

How similar are these two structures?

When schemas evolve, keys get renamed, or data comes from different sources, binary equality is useless. You need a similarity score.

The Algorithm: Sembra Similarity

Sembra computes a continuous similarity score S(a, b) ∈ [0, 1] for any two JSON-compatible values using a novel multi-phase algorithm:

Phase 1: Type-Aware Primitive Matching

• Strings: Jaro-Winkler distance (handles typos, minor variations)
• Numbers: Relative difference scoring
• Booleans: Exact match (configurable partial mode)
• Null: Always exact

Phase 2: Optimal Array Alignment

Instead of index-by-index comparison, Sembra computes a similarity matrix between all pairs of elements and finds the optimal matching using a greedy assignment algorithm. This handles:

• Reordered elements
• Inserted/deleted elements
• Partially matching elements

Phase 3: Value-Guided Key Rename Detection

This is the key novelty. When object keys differ between two structures, Sembra infers renames by comparing the values at those keys:

a = {"name": "Alice", "age": 30}
b = {"fullName": "Alice", "yearsOld": 30}
# Sembra detects: name → fullName, age → yearsOld
# Score: >0.85

No other library does this.

Phase 4: Recursive Composition

All phases compose recursively — nested arrays, nested objects, and mixed structures are handled uniformly.

Performance

n = number of nodes in the larger structure.

Quick Start

from sembra import sembra, sembra_report, SembraConfig

# Basic similarity
score = sembra({"a": 1, "b": 2}, {"a": 1, "b": 3})
print(score)  # ~0.89

# Key rename detection
score = sembra(
    {"userName": "Alice", "userAge": 30},
    {"name": "Alice", "age": 30}
)
print(score)  # >0.8

# Reordered arrays
score = sembra([1, 2, 3], [3, 1, 2])
print(score)  # 1.0 (all elements match)

# Detailed report
report = sembra_report({"a": 1}, {"a": 2})
print(report.score)
print(report.matches)
print(f"Computed in {report.duration_ns}ns")

# Configuration
config = SembraConfig(
    string_similarity=False,
    object_key_rename=False,
    number_threshold=0.9,
)
score = sembra({"a": "hello"}, {"a": "hallo"}, config)

Configuration Reference

Use Cases

• Test assertions with tolerance for structural variation
• Schema migration — map old API responses to new schemas
• Data deduplication — find structurally similar records
• Configuration comparison — detect drifted configs
• API monitoring — alert on structural drift
• Merge conflict resolution — find best correspondence

Comparison with Existing Libraries

License

MIT — see LICENSE

Author

nhemlos