---
type: "resource"
title: "Linkage"
resource: "Linkage"
---
# Linkage


## Introduction


## Scope and Usage

This resource allows the assertion of linkages between multiple resource instances (generally of the same type) that refer to the same underlying business objects. For example, multiple Condition records that refer to the same underlying problem/issue for a Patient; multiple AllergyIntolerance records that refer to the same reaction susceptibility; multiple Patient, Practitioner and/or RelatedPerson records that refer to the same human being or animal.

FHIR supports a process for sharing electronic records. It is common for multiple records to exist that deal with the same real-world phenomenon. This can result from information being captured by different systems or information being captured within a single system by different users (either deliberately to represent distinct perspectives or accidentally when a new record is created rather than updating an existing record). These multiple records may be referred to as "duplicate" records, but in practice they aren't often actually "duplicate" in that the data represented (and the history of the records) will be at least somewhat distinct.

In some cases, the solution after identifying duplicates is to deprecate one of the records (e.g. by changing the status to "Entered in Error") and to move all relevant information to the surviving record. In other cases, both records may need to persist, perhaps because the resources live on different servers or have different 'owners'.

\[%stu-note dstu%\] While the Maturity Level did not change, the Standards Status did change to Draft for consistency with the current Maturity Level of 0. The Patient Care Work Group welcomes feedback [here](http://hl7.org/fhir-issues) whether implementers believe the resource is substantially complete, tested across its scope, and implemented in production. \[%end-note%\]

## Boundaries and Relationships

Do not use Linkage for Patient, Person, and Encounter, see [the explanation on Patient](patient#linking) for more details. The [Person](person) resource should be used to link a person independent of a specific health-related context. Linkage can be used for all other use cases.

## Background and Context

Provides additional detail on exactly how the resource is to be used

## StructureDefinition

### Elements (Simplified)

- **[Linkage](/linkage-definitions#Linkage)** [0..*]: - Links records for 'same' item
- **[Linkage.active](/linkage-definitions#Linkage.active)** [0..1]: [boolean](/boolean) Whether this linkage assertion is active or not
- **[Linkage.author](/linkage-definitions#Linkage.author)** [0..1]: [Reference(Practitioner](/Reference(Practitioner), [PractitionerRole](/PractitionerRole), [Organization)](/Organization)) Who is responsible for linkages
- **[Linkage.item](/linkage-definitions#Linkage.item)** [1..*]: [BackboneElement](/BackboneElement) Item to be linked
- **[Linkage.item.type](/linkage-definitions#Linkage.item.type)** [1..1]: [code](/code) required:[linkage-type](/valueset-linkage-type) source | alternate | historical
- **[Linkage.item.resource](/linkage-definitions#Linkage.item.resource)** [1..1]: Reference([Resource](/Resource)) Resource being linked

## Mappings

- [Linkage Mappings](/linkage-mappings) — 4 mapping entries

## Resource Packs


### list-Linkage-packs.xml



```xml
<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="Linkage-packs"/>
  <status value="current"/>
  <mode value="working"/>
</List>
```


## Search Parameters

- [author](/linkage-search#author) — **reference** — Author of the Linkage — `Linkage.author`
- [item](/linkage-search#item) — **reference** — Matches on any item in the Linkage — `Linkage.item.resource`
- [source](/linkage-search#source) — **reference** — Matches on any item in the Linkage with a type of 'source' — `Linkage.item.resource`

[Full Search Parameters](/linkage-search)

## Examples

- [example](/linkage-example-example) — linkage-example — Example of linkage
- [linkage-example](/linkage-example-linkage-example) — linkage-example
- [linkage-examples-header](/linkage-example-linkage-examples-header) — linkage-examples-header

[Full Examples](/linkage-examples)

## Mapping Exceptions


### linkage-fivews-mapping-exceptions.xml

### Divergent Elements
- **FiveWs.status** → **Linkage.active**

### Unmapped Elements
- **FiveWs.what** — Unknown
- **FiveWs.recorded** — Unknown
- **FiveWs.actor** — Unknown
- **FiveWs.cause** — Unknown
- **FiveWs.version** — Unknown
- **FiveWs.witness** — Unknown
- **FiveWs.class** — Unknown
- **FiveWs.where** — Unknown
- **FiveWs.context** — Unknown
- **FiveWs.init** — Unknown
- **FiveWs.why** — Unknown
- **FiveWs.identifier** — Unknown
- **FiveWs.source** — Unknown
- **FiveWs.who** — Unknown
- **FiveWs.grade** — Unknown
- **FiveWs.planned** — Unknown
- **FiveWs.done** — Unknown
- **FiveWs.subject** — Unknown