# Reading material

## 1. What are contained resources
A contained resource is a resource that is embedded in another resource. A contained resource only exists in the context of the containing resource, and it cannot exist on its own. This means that a contained resource is not externally identifiable. 

A contained resource only has meaning when it is referenced from the containing resource. For this reason, resources can only be contained if a reference to the contained resource is present. This is to ensure that the meaning of the contained resource is clear and to avoid confusion about its significance. References to resources packaged inside the containing resource are called internal contained references. 

## 2. When to use contained resources
You can use contained resources when the content referred to in the resource reference does not have an independent existence apart from the resource that contains it. Typically, this is the case when resources are being assembled by a secondary user of the source data, such as a middleware engine. For example, in some cases there may be insufficient (identifying) information to create unique, resolvable resource instances. Resources without any identification information (or even resources with arbitrary identification information) can never be subject of a transaction outside the context of a containing resource and should always be contained. 

<p class="roundbox">
<b>Example 1</b><br>
It is quite common that a medication order contains medication names only, without any identifying information. In this case, you should send the Medication resources as contained resources in the MedicationRequest resource. 
</p>

<p class="roundbox">
<b>Example 2</b><br>
Suppose you want to capture the name of a practitioner who diagnosed the patient in a DiagnosticReport or Condition resource. You don’t have any additional (identifying) information of this practitioner. You should send the Practioner resource as a contained resource of the DiagnosticReport or Condition resource. 
</p>

## 3. When not to use contained resources
You should be careful with the use of contained resources when there is sufficient identifying information. Once the identification is lost, it is very hard (and context dependent) to restore it. Contained resources should never be used simply as a way to serialize content inline - look into [Bundles](https://www.hl7.org/fhir/bundle.html), [Lists](https://www.hl7.org/fhir/list.html), or [Documents](https://www.hl7.org/fhir/documents.html) for that.

## 4. How to use contained resources
You can add one or more contained resources in any resource inheriting [DomainResource]( https://www.hl7.org/fhir/domainresource.html) (which would be most except for Bundle) using the `contained` element. In the XML representation, contained resources should be added at the top of the resource after any text narrative and before any extension. Contained resources have no narrative, but they can have extensions inside them (just not on the `contained` element itself). Nesting of contained resources is not allowed, so it is not possible to add contained resources to a resource that is already a contained resource itself. 

Below is an incomplete example of a contained Practitioner resource in XML:

```xml
<DiagnosticReport xmlns="http://hl7.org/fhir">
  <contained>
    <Practitioner>
      <id value="practitioner1"/>
      <name>
        <family value="Practitioner"/>
        <given value="James"/>
      </name>
    </Practitioner>
  </contained>
```

The next step is to add a reference to the contained resource (i.e. an internal contained reference). Below is an example of the XML code for an internal contained reference to the contained Practitioner resource we just created. An internal contained reference always starts with `#` followed by the id of the contained resource. Note that this id does not exist outside the containing resource. So it is not possible to run a GET request on Practitioner/practitioner1 to achieve the contained resource from your server.

```xml
  <performer>
    <actor>
    	<reference value="#practitioner1" />
    </actor>  
  </performer>
```

The final result would look like this:

```xml
<DiagnosticReport xmlns="http://hl7.org/fhir">
  <contained>
    <Practitioner>
      <id value="practitioner1"/>
      <name>
        <family value="Practitioner"/>
        <given value="James"/>
      </name>
    </Practitioner>
  </contained>

  <!-- ... -->

  <performer>
    <actor>
    	<reference value="#practitioner1"/>
    </actor>  
  </performer>
```

## 5. Interpretation of contained resources
The meaning of a contained resource depends on its context. References are resolved by looking through the containing resource. For example, suppose a DiagnosticReport contains a contained Practitioner and a couple of contained Observations. It is possible to reference to the contained Practitioner from the contained Observations using an internal contained reference. 

Contained resources do not inherit context from the containing resource. For example, suppose that both the containing resource and contained resource have a subject. In this case, you cannot assume that the contained resource has the same subject as the containing resource.