Working with Linkage resources

When resource matching finds a match, it creates a FHIR Linkage resource that references the matched resources. The originals are not changed. Resource matching uses a grouped model: all resources determined to be the same entity are collected into a single Linkage, with one source item and one or more alternate items. The oldest resource in the group (by meta.lastUpdated) is the source; newer resources are alternate. A resource belongs to at most one Linkage group. You can retrieve and search Linkage resources using the same FHIR R4 interactions as any other resource type (see Searching FHIR resources).

A Linkage created by resource matching includes:

active – indicates whether the grouping is current. Resource matching sets active to true on live links. When a grouping no longer holds, the Linkage is retained with active set to false, so the history of the grouping remains queryable (see Tracking linkage history).
meta.tag – marks the Linkage as system-generated by AWS HealthLake, so you can distinguish it from Linkage resources you create yourself.
extension – records how the match was made: a linkage-match-tier extension (for example, identifier) and one or more linkage-match-detail extensions, each naming the specific identifier (system|value) that caused a set of resources to be linked.
item – the grouped resources: one source and one or more alternate references.

The following example shows a Linkage resource that groups three Patient resources. Patient/patient-A and Patient/patient-B share a Social Security number, and Patient/patient-A and Patient/patient-C share a hospital medical record number.


{
    "resourceType": "Linkage",
    "id": "linkage-001",
    "meta": {
        "tag": [
            {
                "system": "http://healthlake.amazonaws.com/linkage-source",
                "code": "aws-healthlake"
            },
            {
                "display": "SYSTEM_GENERATED"
            }
        ]
    },
    "extension": [
        {
            "url": "http://healthlake.amazonaws.com/linkage-match-tier",
            "valueCode": "identifier"
        },
        {
            "url": "http://healthlake.amazonaws.com/linkage-match-detail",
            "extension": [
                {
                    "url": "identifier",
                    "valueString": "http://hl7.org/fhir/sid/us-ssn|123-45-6789"
                },
                {
                    "url": "linked-resource",
                    "valueReference": { "reference": "Patient/patient-A" }
                },
                {
                    "url": "linked-resource",
                    "valueReference": { "reference": "Patient/patient-B" }
                }
            ]
        },
        {
            "url": "http://healthlake.amazonaws.com/linkage-match-detail",
            "extension": [
                {
                    "url": "identifier",
                    "valueString": "http://hospital-a.org/mrn|MRN-456"
                },
                {
                    "url": "linked-resource",
                    "valueReference": { "reference": "Patient/patient-A" }
                },
                {
                    "url": "linked-resource",
                    "valueReference": { "reference": "Patient/patient-C" }
                }
            ]
        }
    ],
    "item": [
        {
            "type": "source",
            "resource": { "reference": "Patient/patient-A" }
        },
        {
            "type": "alternate",
            "resource": { "reference": "Patient/patient-B" }
        },
        {
            "type": "alternate",
            "resource": { "reference": "Patient/patient-C" }
        }
    ]
}

Resource matching connects records through Linkage resources. Your original resources are never combined or replaced, and you remain in control of reconciling the linked records.

Linkage resource lifecycle

Links are maintained automatically as data changes. When a resource is created, updated, or deleted, it is re-evaluated and its Linkage group is adjusted. The following example follows a single patient identity through each kind of change.

Create: You write two Patient resources that share a Social Security number: Patient/patient-A and Patient/patient-B, both with SSN 123-45-6789. Because they share an identifier, resource matching creates a Linkage grouping the two, with the older resource (patient-A) as the source.
Join: You then write Patient/patient-C with medical record number MRN-456 in Hospital A's system – the same MRN that also appears on patient-A. Resource matching adds patient-C to the existing group. The Linkage now groups A, B, and C, and records both the SSN match (A-B) and the MRN match (A-C).
Merge: Separately, Patient/patient-D and Patient/patient-E were already grouped in their own Linkage by a shared National Provider Identifier. You now update patient-D to add SSN 123-45-6789. patient-D now bridges the two groups, so resource matching merges them into a single Linkage covering A, B, C, D, and E.
Split: You delete patient-A, the resource whose identifiers connected the SSN set (A, B, D) to the MRN set (A, C). With that bridge gone, the members no longer form one connected group, so resource matching splits them into separate Linkage resources.
Removal: Finally, you update patient-B to correct a data-entry error, removing the SSN it shared with the group. Because patient-B no longer shares any identifier with the other members, it is removed from the group. If a group drops below two members, its Linkage resource is deleted.

Document Conventions

Filtering placeholder values

Querying linked data