Advanced Rule Authoring

The MDM Rule Definition Script is the single JSON document that controls all matching behaviour in your MDM module. Writing it well is the most important configuration task you will perform, because it determines which patient records get linked automatically, which ones are flagged for human review, and which ones are treated as distinct individuals.

This tutorial presents six rule definition scripts in order of increasing complexity. Each example builds on the one before it, introducing new fields, algorithms, and design patterns along the way. By the end you will understand how to combine candidate searches, field comparisons, and result tiers into a rule set that matches confidently on strong evidence while reserving borderline cases for a data steward.

The examples are presented in terms of Golden Record linking, but the same rule definition script drives every MDM matching strategy in Smile CDR, including deduplication on ingestion. See Selecting a deduplication strategy for an overview of the available strategies.

How a Rule Definition Script Works

MDM processes each incoming resource in two phases.

Phase 1 — Candidate Selection. MDM searches the repository for existing resources that share at least one value with the incoming resource on the fields you list in candidateSearchParams. Only those candidates advance to the next phase. Any existing resource that is not retrieved in this search will never be matched against the incoming resource, regardless of how similar it might be. This makes candidate search the most important factor in whether a real match is detected at all.

Phase 2 — Field-Level Matching. MDM compares each candidate against the incoming resource using the algorithms defined in matchFields. It then consults the matchResultMap to decide whether the comparison results constitute a MATCH, a POSSIBLE_MATCH, or no link at all. A MATCH link is created automatically. A POSSIBLE_MATCH link is created but flagged for data steward review.

Every rule definition script requires these six top-level fields:

Example 1: Family Name Matching

This is the simplest useful rule set. It retrieves candidates by birth date and confirms a match only when the family names are phonetically equivalent.

{
  "version": "example-1",
  "mdmTypes": ["Patient"],
  "candidateSearchParams": [
    {
      "resourceType": "Patient",
      "searchParams": ["birthdate"]
    }
  ],
  "candidateFilterSearchParams": [],
  "matchFields": [
    {
      "name": "family-name",
      "resourceType": "Patient",
      "resourcePath": "name.family",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    }
  ],
  "matchResultMap": {
    "family-name": "MATCH"
  }
}

What this does:

1. When a new Patient arrives, MDM searches the repository for all existing Patients that share the same birthdate value. Those are the candidates.
2. For each candidate, MDM compares the incoming Patient's family name to the candidate's family name using the METAPHONE algorithm. Metaphone encodes each name as a phonetic key before comparing, so alternate spellings that sound the same — for example Smith and Smyth, or Dury and Durie — produce the same key and therefore match.
3. If the Metaphone comparison passes, MDM creates a MATCH link automatically.

Why birthdate for the candidate search?

A good candidate search parameter is specific enough to return a small group but not so specific that minor errors cause real matches to be missed. Birth date works well because most people share a birthday with relatively few others, it is present on nearly all patient records, and it is not likely to change over time, as name or address fields might. Avoid broad fields such as gender or address-state, which would return very large candidate pools and slow down processing.

What matches and what does not:

Limitation: Matching on family name alone creates false positives when two different patients share the same birth date and surname. Example 2 addresses this.

Example 2: Requiring Both Family and Given Name

Adding the given name as a second required comparison makes the rule significantly more precise. Both comparisons must pass for a MATCH to be created.

{
  "version": "example-2",
  "mdmTypes": ["Patient"],
  "candidateSearchParams": [
    {
      "resourceType": "Patient",
      "searchParams": ["birthdate"]
    }
  ],
  "candidateFilterSearchParams": [],
  "matchFields": [
    {
      "name": "family-name",
      "resourceType": "Patient",
      "resourcePath": "name.family",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    },
    {
      "name": "given-name",
      "resourceType": "Patient",
      "resourcePath": "name.given",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    }
  ],
  "matchResultMap": {
    "family-name,given-name": "MATCH"
  }
}

The only changes from Example 1 are the addition of the given-name matchField and the updated matchResultMap key. The key "family-name,given-name" means both comparisons must pass simultaneously for the result to be MATCH.

What matches and what does not:

Example 3: Adding a POSSIBLE_MATCH Tier

A rule set with only MATCH outcomes is all-or-nothing: either both names match perfectly and a link is created automatically, or no link is created at all. This means a candidate with a matching family name but a missing or differently-entered given name is simply ignored, even though it might be the same person.

Adding a POSSIBLE_MATCH tier captures these borderline cases and routes them to a data steward for manual review, rather than silently discarding them.

{
  "version": "example-3",
  "mdmTypes": ["Patient"],
  "candidateSearchParams": [
    {
      "resourceType": "Patient",
      "searchParams": ["birthdate"]
    }
  ],
  "candidateFilterSearchParams": [],
  "matchFields": [
    {
      "name": "family-name",
      "resourceType": "Patient",
      "resourcePath": "name.family",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    },
    {
      "name": "given-name",
      "resourceType": "Patient",
      "resourcePath": "name.given",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    }
  ],
  "matchResultMap": {
    "family-name,given-name": "MATCH",
    "family-name": "POSSIBLE_MATCH"
  }
}

The matchFields array is unchanged. The matchResultMap now has two entries:

• "family-name,given-name": "MATCH" — both names match phonetically: create a MATCH link automatically.
• "family-name": "POSSIBLE_MATCH" — only the family name matches: create a POSSIBLE_MATCH link for review.

Precedence rule: MATCH always takes priority over POSSIBLE_MATCH. If a candidate satisfies both map entries simultaneously, only the MATCH link is created. In this example, a candidate that passes both family-name and given-name satisfies the first entry and receives a MATCH link. The second entry is redundant for that candidate and is ignored.

When should you use POSSIBLE_MATCH?

Use POSSIBLE_MATCH when you have weaker evidence — evidence you believe is meaningful but not conclusive enough to link automatically. Common situations include:

• A single identifier type matches but demographic data is sparse
• A family name matches but the given name field is absent on one or both records
• A similarity score falls in a range where the match is plausible but not certain

Patients flagged as POSSIBLE_MATCH appear in the MDM data stewardship view, where a reviewer can confirm or dismiss each one.

Example 4: Multiple Candidate Searches and Identifier Matching

So far all examples rely on birth date as the sole candidate search parameter. If a patient's birth date is entered incorrectly in one source system, that patient will never be found as a candidate, and the match will be missed entirely.

Adding a second candidate search parameter — such as a medical record number (MRN) identifier — provides a second path into the candidate pool. A candidate is retrieved if it matches on either search parameter. This protects against data entry errors in any one field.

{
  "version": "example-4",
  "mdmTypes": ["Patient"],
  "candidateSearchParams": [
    {
      "resourceType": "Patient",
      "searchParams": ["birthdate"]
    },
    {
      "resourceType": "Patient",
      "searchParams": ["identifier"]
    }
  ],
  "candidateFilterSearchParams": [],
  "matchFields": [
    {
      "name": "mrn",
      "resourceType": "Patient",
      "resourcePath": "identifier",
      "matcher": {
        "algorithm": "IDENTIFIER",
        "identifierSystem": "http://example.org/fhir/mrn"
      }
    },
    {
      "name": "family-name",
      "resourceType": "Patient",
      "resourcePath": "name.family",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    },
    {
      "name": "given-name",
      "resourceType": "Patient",
      "resourcePath": "name.given",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    },
    {
      "name": "birthdate",
      "resourceType": "Patient",
      "resourcePath": "birthDate",
      "matcher": {
        "algorithm": "DATE"
      }
    }
  ],
  "matchResultMap": {
    "mrn": "MATCH",
    "family-name,given-name,birthdate": "MATCH"
  }
}

New elements explained:

Second candidateSearchParams entry — The two entries are evaluated independently and in parallel. Any existing Patient that shares either the same birth date or the same identifier value as the incoming Patient is included in the candidate pool. The two result sets are merged before Phase 2 begins.

mrn matchField with the IDENTIFIER algorithm — The IDENTIFIER algorithm compares two FHIR Identifier values by checking that both their system URI and their value are identical. Without the identifierSystem parameter it would match on any matching identifier. Setting "identifierSystem": "http://example.org/fhir/mrn" restricts matching to identifiers in your MRN namespace, preventing accidental matches on identifiers from other namespaces.

Replace http://example.org/fhir/mrn with the actual identifier system URI used in your organization's Patient resources.

birthdate matchField with the DATE algorithm — Unlike a string comparison, DATE is precision-aware. A value recorded as 1985-03 (year-month only) and a value recorded as 1985-03-15 (full date) are treated as a match, because the less precise value is consistent with the more precise one. This handles the common situation where one source system records only the year and month of birth.

Two independent matchResultMap entries:

• "mrn": "MATCH" — An exact MRN match is sufficient on its own to create an automatic link. A shared unique identifier is strong evidence of identity.
• "family-name,given-name,birthdate": "MATCH" — In the absence of an MRN match, both name comparisons plus a birth date comparison together constitute sufficient evidence.

What matches and what does not:

Example 5: Fine-Grained Control with Similarity Scoring

Phonetic algorithms such as METAPHONE encode names into a compact key that can hide subtle differences. Two names receive the same Metaphone key if they sound similar when spoken aloud, but the algorithm cannot tell you how similar they are — a name either matches or it does not. This coarseness can cause false positives.

Similarity algorithms take a different approach: instead of returning a pass/fail result, they return a decimal score between 0.0 (completely different) and 1.0 (identical). You set a matchThreshold that the score must reach for the comparison to pass. Raising the threshold demands more similarity; lowering it tolerates more variation.

This example replaces the phonetic family-name comparison with a JARO_WINKLER similarity comparison and uses the resulting precision difference to create a more meaningful POSSIBLE_MATCH tier.

{
  "version": "example-5",
  "mdmTypes": ["Patient"],
  "candidateSearchParams": [
    {
      "resourceType": "Patient",
      "searchParams": ["birthdate"]
    },
    {
      "resourceType": "Patient",
      "searchParams": ["identifier"]
    }
  ],
  "candidateFilterSearchParams": [],
  "matchFields": [
    {
      "name": "mrn",
      "resourceType": "Patient",
      "resourcePath": "identifier",
      "matcher": {
        "algorithm": "IDENTIFIER",
        "identifierSystem": "http://example.org/fhir/mrn"
      }
    },
    {
      "name": "family-name",
      "resourceType": "Patient",
      "resourcePath": "name.family",
      "similarity": {
        "algorithm": "JARO_WINKLER",
        "matchThreshold": 0.88
      }
    },
    {
      "name": "given-name",
      "resourceType": "Patient",
      "resourcePath": "name.given",
      "matcher": {
        "algorithm": "METAPHONE"
      }
    },
    {
      "name": "birthdate",
      "resourceType": "Patient",
      "resourcePath": "birthDate",
      "matcher": {
        "algorithm": "DATE"
      }
    }
  ],
  "matchResultMap": {
    "mrn": "MATCH",
    "family-name,given-name,birthdate": "MATCH",
    "family-name,birthdate": "POSSIBLE_MATCH"
  }
}

Changes from Example 4:

family-name now uses similarity instead of matcher — The similarity property is used for algorithms that return a score. The matcher property is used for algorithms that return a pass/fail result. Only one of the two may be active at a time per matchField.

JARO_WINKLER is particularly well-suited to name matching because it gives extra weight to shared characters at the beginning of a string. Typographic errors at the end of a name — a transposed letter, a dropped final consonant — produce a small penalty, while errors at the beginning produce a larger one. A threshold of 0.88 is a starting point for family names in English; you should adjust it using representative test data from your own population.

New matchResultMap entry — "family-name,birthdate": "POSSIBLE_MATCH" captures candidates where the family name score meets the threshold and the birth date matches, but the given name comparison fails (perhaps because the given name is missing from one record, or is entered very differently). These cases are worth a data steward's attention.

Choosing a threshold:

Start with a value in the 0.85–0.92 range for family names and test it against real data using the $mdm-evaluate operation, which lets you run a single pair of resources through the matching rules without creating any links. Lower values increase the number of matches found (higher recall) at the cost of more false positives. Higher values reduce false positives (higher precision) but risk missing real matches where names are entered inconsistently.

Example 6: A Production-Grade Rule Set

This example combines all the patterns shown so far — multiple candidate searches, candidate filters, several different field algorithms, a two-tier result map, and an enterprise identifier — into a rule set representative of a production deployment.

{
  "version": "prod-v1",
  "mdmTypes": ["Patient"],
  "eidSystems": {
    "Patient": "http://example.org/fhir/national-patient-id"
  },
  "candidateSearchParams": [
    {
      "resourceType": "Patient",
      "searchParams": ["birthdate"]
    },
    {
      "resourceType": "Patient",
      "searchParams": ["identifier"]
    },
    {
      "resourceType": "Patient",
      "searchParams": ["phone"]
    }
  ],
  "candidateFilterSearchParams": [
    {
      "resourceType": "Patient",
      "searchParam": "active",
      "fixedValue": "true"
    }
  ],
  "matchFields": [
    {
      "name": "national-id",
      "resourceType": "Patient",
      "resourcePath": "identifier",
      "matcher": {
        "algorithm": "IDENTIFIER",
        "identifierSystem": "http://example.org/fhir/national-patient-id"
      }
    },
    {
      "name": "mrn",
      "resourceType": "Patient",
      "resourcePath": "identifier",
      "matcher": {
        "algorithm": "IDENTIFIER",
        "identifierSystem": "http://example.org/fhir/mrn"
      }
    },
    {
      "name": "family-name",
      "resourceType": "Patient",
      "resourcePath": "name.family",
      "similarity": {
        "algorithm": "JARO_WINKLER",
        "matchThreshold": 0.88
      }
    },
    {
      "name": "given-name",
      "resourceType": "Patient",
      "resourcePath": "name.given",
      "matcher": {
        "algorithm": "DOUBLE_METAPHONE"
      }
    },
    {
      "name": "birthdate",
      "resourceType": "Patient",
      "resourcePath": "birthDate",
      "matcher": {
        "algorithm": "DATE"
      }
    },
    {
      "name": "gender",
      "resourceType": "Patient",
      "resourcePath": "gender",
      "matcher": {
        "algorithm": "STRING"
      }
    },
    {
      "name": "phone",
      "resourceType": "Patient",
      "fhirPath": "telecom.where(system='phone').value",
      "matcher": {
        "algorithm": "NUMERIC"
      }
    }
  ],
  "matchResultMap": {
    "national-id": "MATCH",
    "mrn,birthdate": "MATCH",
    "family-name,given-name,birthdate,gender": "MATCH",
    "family-name,given-name,birthdate": "POSSIBLE_MATCH",
    "family-name,birthdate,phone": "POSSIBLE_MATCH"
  }
}

Section-by-section explanation:

eidSystems

"eidSystems": {
  "Patient": "http://example.org/fhir/national-patient-id"
}

Declaring an EID (Enterprise Identifier) system tells MDM that identifiers with this system URI are authoritative unique identifiers. When an incoming Patient carries a national patient ID, MDM first searches for an existing Golden Resource that already holds that identifier. If one is found, MDM links the incoming Patient directly to it without running any further candidate searches or field comparisons. This shortcut makes EID-based matching faster and more reliable than demographic matching alone.

If no Golden Resource with that EID exists, MDM proceeds with the normal candidate search phases.

Where a resource type has more than one authoritative identifier, give an array of systems instead. The incoming resource is then linked directly if any of its EIDs match:

"eidSystems": {
  "Patient": [
    "http://example.org/fhir/national-patient-id",
    "http://example.org/fhir/regional-mrn"
  ]
}

See Using several EID systems for one resource type.

Replace http://example.org/fhir/national-patient-id with the system URI of the national or enterprise patient identifier used in your jurisdiction.

candidateSearchParams

Three parameters are declared. A candidate is retrieved if the incoming Patient matches an existing Patient on any one of them:

• birthdate — Retrieves patients who share the same date of birth.
• identifier — Retrieves patients who share at least one identifier value, regardless of system. This catches cases where a birth date is entered incorrectly in one source system.
• phone — Retrieves patients who share the same phone number. This provides a third independent retrieval path that is resilient to errors in both date and identifier fields.

candidateFilterSearchParams

{
  "resourceType": "Patient",
  "searchParam": "active",
  "fixedValue": "true"
}

This filter is applied to all three candidate searches. Only active Patients are ever considered as candidates. Inactive patients — those that have been merged, deactivated, or marked as test data — are excluded before Phase 2 begins, regardless of how closely they match the incoming resource.

matchFields — national-id and mrn

Two separate IDENTIFIER matchFields cover the national patient ID and the MRN. Each restricts comparison to its own identifierSystem, so each type of identifier can be used independently in the matchResultMap. This also prevents identifiers from any other namespace, which may not be reliable enough to establish patient identity, from contributing to the match.

matchFields — given-name with DOUBLE_METAPHONE

DOUBLE_METAPHONE is used here instead of METAPHONE because this organization's patient population includes names from multiple linguistic backgrounds. Double Metaphone computes two phonetic codes per value — a primary and an alternate — to handle ambiguous pronunciations and non-English name origins. It matches a broader set of spelling variants, including Smith and Schmidt, which standard Metaphone would not match.

matchFields — gender with STRING

Gender is a coded administrative value (male, female, other, unknown) that should match character-for-character. The STRING algorithm compares values as text after normalizing to uppercase, so Male and male are treated as equal. It is appropriate for coded fields where phonetic encoding is meaningless.

Including gender in a MATCH rule alongside three other fields significantly reduces false positives, at the cost of missing a match if one source system records gender differently from another.

matchFields — phone with fhirPath and NUMERIC

{
  "name": "phone",
  "resourceType": "Patient",
  "fhirPath": "telecom.where(system='phone').value",
  "matcher": {
    "algorithm": "NUMERIC"
  }
}

This matchField uses fhirPath rather than resourcePath. The fhirPath expression telecom.where(system='phone').value selects only telecom entries whose system is phone, avoiding false matches between a phone number on one record and an email address or fax number on another.

The NUMERIC algorithm strips all non-digit characters (such as parentheses, hyphens, and spaces) before comparing, so (416) 967-1111 and 416-967-1111 are treated as the same number.

matchResultMap

"matchResultMap": {
  "national-id": "MATCH",
  "mrn,birthdate": "MATCH",
  "family-name,given-name,birthdate,gender": "MATCH",
  "family-name,given-name,birthdate": "POSSIBLE_MATCH",
  "family-name,birthdate,phone": "POSSIBLE_MATCH"
}

The five entries express a deliberate hierarchy of confidence:

1. national-id — A national patient ID match is conclusive on its own. No additional evidence is required.
2. mrn,birthdate — A shared MRN combined with a matching birth date is strong evidence. An MRN alone would not be sufficient because MRN namespaces sometimes overlap across unrelated systems; requiring the birth date to agree as well guards against this.
3. family-name,given-name,birthdate,gender — Four demographic fields all agreeing constitutes an automatic match.
4. family-name,given-name,birthdate — Three demographic fields agreeing is treated as possible but not certain. It may reflect a real match where gender was recorded differently, or two different patients who happen to have similar names and share a birth date. A data steward review is appropriate.
5. family-name,birthdate,phone — A matching phone number combined with a matching family name and birth date is suggestive but not conclusive. Phone numbers are shared and change hands, so this combination alone should not produce an automatic link.

Design Considerations

Choosing Candidate Search Parameters

The candidate search is the most consequential decision in your rule set. A candidate that is never retrieved can never be matched. Choose search parameters that divide your population into small groups and that are reliably populated:

• Good candidates: birthdate, identifier, phone. These are specific enough to return small result sets.
• Avoid: gender, address-state, family. These may match a very large number of records and create performance problems.
• Use at least two independent parameters so that a data entry error in one field does not cause a real match to be missed entirely.

MATCH vs POSSIBLE_MATCH

Use MATCH only when the evidence is strong enough that you are willing to accept occasional false positives without manual review. Use POSSIBLE_MATCH for cases where the evidence is meaningful, but you want a human to confirm.

A practical pattern is: use your strongest available evidence (such as a unique identifier or four demographic fields) for MATCH, and use one or two weaker combinations for POSSIBLE_MATCH. Do not create POSSIBLE_MATCH entries for combinations that will produce large volumes of links, since each one requires a data steward's time to resolve.

Versioning

Change the version string every time you modify the rule definition script, even for small adjustments. Each MDM link stores the version that was active when it was created. Consistent versioning lets you identify which links an older rule set created and understand why, if you need to investigate a suspicious link later.

Use a meaningful value rather than a sequential number — for example, a date string such as v2025-01-15 is easier to reason about than v3 when reviewing a link created months earlier.

Keeping the matchResultMap Clean

Each entry in matchResultMap causes MDM to evaluate the listed fields for every candidate. Entries that are logically redundant slow down matching without producing any additional links. Two common patterns to avoid:

{
  "fieldA,fieldB": "MATCH",
  "fieldA,fieldB,fieldC": "MATCH"
}

The second entry is redundant: whenever fieldA and fieldB both pass, a MATCH link is already created by the first entry regardless of whether fieldC passes.

{
  "fieldA": "MATCH",
  "fieldA,fieldB": "POSSIBLE_MATCH"
}

The second entry is also redundant: whenever fieldA passes, a MATCH is created, and MATCH takes precedence over POSSIBLE_MATCH. A POSSIBLE_MATCH would never actually be created for this combination.

Next Steps

• Test individual field comparisons before deploying a new rule set using the $mdm-evaluate operation. It runs a pair of resources through the matching rules and returns the comparison result for each matchField without creating any links.
• Understand the full algorithm reference — the complete list of matchers and similarity algorithms with guidance on when to use each is documented in Supported Match Algorithms.
• Configure enterprise identifiers — if your organization uses a national patient ID or another authoritative unique identifier, see Using Enterprise Identifiers (EIDs) in MDM Rule Definition for a detailed guide.
• Review the full schema — every field and its allowed values are documented in the MDM Rule Schema reference.
• Resolve POSSIBLE_MATCH links — once your rules are in place and generating links, the MDM data stewardship interface lets reviewers confirm or dismiss each POSSIBLE_MATCH link. See the MDM UI Tutorial for a walkthrough.