Contained resources


In this module you will learn more about contained resources.

The topics covered in this module are:

  • What are contained resources?
  • When to use and when not to use contained resources?
  • How to use contained resources?
  • Interpretation of contained resources

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.

Example 1
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.

Example 2
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.

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, Lists, or Documents for that.

4. How to use contained resources

You can add one or more contained resources in any resource inheriting DomainResource (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:

<DiagnosticReport xmlns="">
      <id value="practitioner1"/>
        <family value="Practitioner"/>
        <given value="James"/>

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.

    	<reference value="#practitioner1" />

The final result would look like this:

<DiagnosticReport xmlns="">
      <id value="practitioner1"/>
        <family value="Practitioner"/>
        <given value="James"/>

  <!-- ... -->

    	<reference value="#practitioner1"/>

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.

Real-life examples

Study Subject Management

Below is an example of a subject of a research study, where the consent of participating in this study is sent as a contained resource.

Command 'xml' could not render: Project was not found for StudySubjectManagement/ResearchSubject-example-2.


In this exercise you will practice with contained resources. You will start by creating new profiles that you will need in the next steps of the exercise. Finally, you will create some examples that use contained resources. For the first step of this exercise, we will use Forge to create profiles. Download Forge if you have not done this earlier. Start by reading the case description.

    Case description
    Hospital X wants to send medication prescriptions to the pharmacy. The medication prescriptions contains a list of medications with their names and dosing information.

Steps to follow

1. Create profiles

  1. Open Forge and create a profile to capture medication information. The name of the medication is mandatory. Other information will not be present in most cases.
  2. Create another profile to capture medication prescription information.
  3. The medication prescription should contain a reference to the prescribed medication.
  4. The intent of a medication prescription that is send to the pharmacy is always an order.
  5. Dosage information is mandatory (free text is allowed).

2. Create an example

  1. Open a XML or JSON editor.
  2. Create example instances of medication prescriptions including the following medication:
    • Paracetamol - 1 tablet twice a day
    • Diazepam - 1 tablet a day
  3. Notes (read after completing the exercise or if you are having any difficulties):
    • Only one medication is allowed per medication prescription. For this exercise it is sufficient to create two seperate examples, but if you want to send this information all at once you could use a Bundle.
    • You will need to add contained medication resources and add inline references.
    • Note that in these examples, we could have used a CodeableConcept as well to capture the medication name (using its display element). In the next step we will add additional medication information.

3. Add manufacturer information

  1. The hospital wants to add the following manufacturer information: name and type of organization.
  2. In your example(s) add this information.
    • For this step, you don't need to create a profile first, just make sure you conform to a core resource.
    • Note that you will need another contained resource and that nesting of contained resources is not allowed.
  3. Finally, add an inline reference from your medication to the manufacturer.



We are always looking for ways to improve our products. The Profiling Academy was built using our own IG-editor in Simplifier. If you have any feedback on this module or on our Profiling Academy in general, please leave a comment in the Issue Tracker of the project.

Get in touch

Start profiling

Most modules end with an exercise. Use Forge to start profiling yourself. Just contact us at if you need any help.

Learn more

Follow one of our predefined or tailor-made courses. We will make sure you know FHIR inside-out.

Need help or advice?

Let us assist you with your FHIR use case. Visit our company website to know more about our services or get into contact with Rien Wertheim right away.