Name matching: examples, ambiguity and human review

Separate similarity from identity

Two records can spell a name differently and still concern the same person. Two different people can also share exactly the same name. A matching component helps compare the text; the broader decision depends on the purpose of the workflow and the information available.

Keep that distinction visible to the people designing the system. A convenient label such as “match” should not silently turn a text-comparison result into a claim that identity has been established.

Four examples checked against the public library

We ran the following constructed inputs against node-name-matching 0.3.0. These are reproducible examples of behaviour, not an accuracy benchmark or results from customer identities.

The reordered full name produces an exact match in this example. The common given name on its own remains possible. The company candidate is recognised separately, and the account-like string is not treated as a person’s name.

You can download the captured example outputs and inspect the fingerprints and candidate types returned by the package.

Reproduce an example

npm install node-name-matching@0.3.0

import { matchNames } from 'node-name-matching';

const result = matchNames('JOHN', 'DOE', 'DOE JOHN');
console.log(result.score, result.verdict);
// 100 EXACT

The version is pinned so the example has a defined reference point. When evaluating a different version or changing options, rerun your examples and compare the behaviour.

An exact textual result still does not establish that two records concern the same person. The decision to continue, request more information or review a record belongs to the wider workflow and its requirements.

Build a test set that matches the actual decision

Include intended matches, clearly different records and ambiguous examples. Record what your workflow should do with each one before testing. Look at the errors and disagreements by type, rather than reporting one flattering number across a convenient sample.

The four outputs above establish only those four behaviours. They do not establish performance across languages, a population, nickname variations or every organisation-name format. That is the work an application-specific evaluation needs to address.

Choose examples that expose ambiguity

Evaluate straightforward matches alongside changes in word order, punctuation, spacing and spelling. Include common names and clearly different people as well. Constructed examples can reveal behaviour, but they should not be presented as a measured accuracy rate for real users.

Write down the expected handling of each example before comparing tools. That makes disagreement useful: the team can discuss what the workflow actually requires rather than assuming that a higher score is always better.

Make the next action explicit

Decide what happens after the comparison. Does a possible connection go to a person for review? Should the system ask for more information? What should be recorded so the decision can be understood later?

The appropriate handling depends on the consequences of being wrong. A similarity component alone does not provide the full controls needed for an identity or screening process. Those requirements need to be established for the application.

Evaluate changes as well as the first integration

When a library, configuration or matching rule changes, rerun the examples the team relies on. Look for cases whose handling changes and understand why before releasing them into the workflow.

• What exactly does the comparison return?
• Which examples does the team consider ambiguous?
• What happens to an uncertain result?
• Can someone explain why a decision was taken?
• How will changes to the component be evaluated?

Inspect a public part of our engineering work

The public node-name-matching package (opens in a new tab) and its source documentation (opens in a new tab) provide something concrete to evaluate. The four constructed examples in this guide were run against the pinned version, rather than estimated from a description of the algorithm.

Use that same approach for your own workflow: define expected handling, run the examples and inspect disagreements. The package is MIT licensed. Its availability and the demonstrated outputs are evidence of the component; they are not a claim that name comparison alone completes identity verification.