Linkage — Duplicate merge

The declaration that a set of FHIR resources represents the same real-world entity. The preferred tool of MPIs (Master Patient Indexes) and HIEs to resolve duplicates.

Purpose of the resource

Linkage connects several FHIR resources by stating that they all represent the same real-world entity. Where Patient.link is used for in-domain merges within a single jurisdiction, Linkage is used for cross-organisation merges, post-HIE import or data-quality work led by a steward (MPI manager, integrator).

Key fields

JSON example

{
  "resourceType": "Linkage",
  "id": "patient-merge-001",
  "active": true,
  "author": { "reference": "Organization/hospital-mpi-team" },
  "item": [{
    "type": "source",
    "resource": { "reference": "Patient/patient-A" }
  }, {
    "type": "alternate",
    "resource": { "reference": "Patient/patient-B-duplicate" }
  }, {
    "type": "alternate",
    "resource": { "reference": "Patient/patient-C-imported" }
  }]
}

Common pitfalls

• No source — at least one item must be type=source (master reference).
• Circular linkage — two Linkages referring to each other: avoid.
• Confusion with Patient.link — Linkage is external and inter-resource; Patient.link is internal and limited to Patient/RelatedPerson.

Related resources

• Patient — also uses Patient.link.
• Person — cross-domain MPI view.
• Practitioner.
• FHIR R5 hub.