EntityMatcher 1.0.0

EntityMatcher

A .NET library for deterministic, offline entity matching across domains. Compares names, addresses, phones, dates, organizations, countries, and arbitrary text/numeric fields using alias resolution, fuzzy scoring, and tolerance-based matching. Supports single-pair comparison, record-level profile matching, and high-performance set matching.

Features

• 12 domain matchers: GivenName, FamilyName, TitleOrCredential, OrganizationName, USStreetAddress, USStateTerritory, Country, Phone, Date, Exact, Text, Numeric
• Alias resolution: 278 given-name groups (947 names), 249 ISO 3166 countries, 62 US states/territories, 32 title/credential groups, 200+ USPS suffix/unit mappings
• Fuzzy scoring: Jaro-Winkler, Damerau-Levenshtein, token-set similarity
• Tolerance matching: Date (configurable day window), Numeric (absolute or percentage)
• Record-level profiles: Required/Optional/Veto field semantics with weighted scoring
• Set matching (net8.0+): Ad-hoc lookup, 1:1 enrollment comparison, 1:many matching, hybrid exact+fuzzy, confidence-ranked pool matching
• Custom matchers: Extensible via IFieldMatcher -- add your own domain-specific comparison logic
• Zero runtime dependencies: Core package targets netstandard2.0, no I/O, no reflection, no network calls
• Thread-safe: Immutable engine, concurrent-safe set matcher

Quick Start

using EntityMatcher.Core;

// Build an engine (loads compiled-in alias data automatically)
var engine = new EntityMatcherEngineBuilder().Build();

// Compare individual fields
var result = engine.Compare(FieldKind.GivenName, "Bill", "William");
// result.State == Match, Method == Alias, Score == 100

// Fuzzy text matching
engine.Compare(FieldKind.Text, "Accounting", "Acounting");
// Match via Jaro-Winkler fuzzy, score ~97

// Numeric with tolerance
engine.Compare(FieldKind.Numeric, "$99.99", "$100.00",
    new MatchOptions { NumericTolerance = 0.05m });
// Match via tolerance scoring

Record-Level Matching

using EntityMatcher.Profiles;

var profile = new MatchProfile<Person>()
    .Require(p => p.LastName, FieldKind.FamilyName)
    .Optional(p => p.FirstName, FieldKind.GivenName, weight: 2m)
    .Optional(p => p.DOB, FieldKind.Date, weight: 1m)
    .Veto(p => p.SSN, FieldKind.Exact)
    .Threshold(85);

var result = profile.Compare(personA, personB, engine);
// result.IsMatch, result.Score, result.Confidence
// result.Explain() for human-readable breakdown

Set Matching (net8.0+)

using EntityMatcher.SetMatching;

// Build a set matcher for batch operations
var matcher = new EntitySetMatcher<Person, PersonMatchType>(
    databaseRecords, matchDefinitions);

// Ad-hoc lookup against a set
var matches = matcher.FindMatches(incomingRecord, [PersonMatchType.Ssn]);

// 1:1 enrollment comparison with tiered criteria
var result = matcher.CreateTwoWayMatchDictionary(
    enrollmentB,
    tieredCriteria: [[PersonMatchType.Ssn], [PersonMatchType.Name, PersonMatchType.Dob]]);

// 1:many matching (customer to orders)
var multi = matcher.CreateMultiMatchResult(orders, [PersonMatchType.CustomerId]);

// Confidence-ranked pool matching (best matches assigned first, pool drains top-down)
var ranked = matcher.CreateRankedMatchDictionary(
    enrollmentB, profile: fuzzyProfile, engine: engine,
    exactCriteria: [[PersonMatchType.Ssn]]);

// Hybrid: exact dictionary pass + fuzzy profile fallback with blocking
var hybrid = matcher.CreateHybridMatchDictionary(
    enrollmentB,
    exactCriteria: [[PersonMatchType.Ssn]],
    fuzzyProfile: fuzzyProfile,
    engine: engine,
    blockingStrategy: BlockingKeyStrategies.FirstCharOf<Person>(p => p.LastName));

Match Quality

Tested against 10,000 synthetic records with realistic data corruption:

Projects

Data Sources

All alias data is compiled directly into C# source code (zero I/O at runtime):

• Given names: 278 groups from onyxrev/common_nickname_csv (public domain)
• Countries: 249 entries from ISO 3166-1
• US States: 62 entries (50 states + DC + territories + military codes)
• Titles/Credentials: 32 curated groups
• USPS Suffixes: 200+ entries from USPS Publication 28 (public domain)
• USPS Secondary Units: 24 entries from USPS Publication 28

Installation

dotnet add package EntityMatcher
dotnet add package EntityMatcher.DependencyInjection  # optional, for DI integration

Documentation

• Getting Started -- Installation, quick start, configuration
• Field Matchers -- All 12 domain matchers with examples
• Profiles -- Record-level matching with Required/Optional/Veto fields
• Set Matching -- Batch operations, 1:1, 1:many, hybrid, ranked matching
• Custom Matchers -- Extensibility with custom field types
• Data Sources -- Embedded datasets, adding custom aliases
• Performance -- Benchmarks, quality report, optimization guidance

Building

dotnet build EntityMatcher.slnx
dotnet test EntityMatcher.slnx

License

MIT