Skip to main content

How matching works

JamMPI runs three strategies in combination on every Patient/$match call:

1. National ID exact match (CERTAIN)​

If the query patient has a national identity number (NIC, NHS, Aadhaar, SSN), JamMPI checks this against all stored national IDs first. An exact match earns CERTAIN grade (score ≥ 0.95). This is a constant-time comparison — O(1) with an indexed lookup.

"identifier": [{"system": "urn:lk.nic", "value": "851234567V"}]

2. Jaro-Winkler name + DOB similarity (PROBABLE)​

When no national ID match is found, JamMPI scores candidates using a weighted combination of:

  • Jaro-Winkler on family name (prefix-weighted — better for human names)
  • Exact match on date of birth
  • Given name similarity (secondary weight)

Above the configurable threshold (default 0.85), the match is PROBABLE.

GradeScoreTrigger
certain≥ 0.95National ID exact match
probable≥ 0.85Name + DOB above threshold
possible≥ 0.70Partial match, manual review recommended

3. Blocking strategy (performance)​

Without blocking, matching one patient against 50M records requires 50M comparisons. JamMPI pre-filters candidates by:

  • First 3 characters of family name
  • Birth year (±1 year tolerance)

This reduces the comparison space from O(n) to O(k ≈ 200–500) while retaining recall.

Configuring the threshold​

application.yaml
jammpi:
  matching:
    min-grade: PROBABLE          # CERTAIN | PROBABLE | POSSIBLE
    jaro-winkler-threshold: 0.85
    blocking:
      name-prefix-length: 3
      birth-year-tolerance: 1
Raising min-grade to CERTAIN

Setting min-grade: CERTAIN means only patients with a national ID create golden record links. Patients without a national ID get new records rather than linking to existing ones. Only use this if national ID coverage is > 95% in your patient population.