# Working with Linkage resources
<a name="resource-matching-linkage-resources"></a>

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](searching-fhir-resources.md)).

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](resource-matching-tracking-history.md)).
+ `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
<a name="resource-matching-linkage-lifecycle"></a>

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.