This page is part of the FHIR Specification (v1.2.0: STU 3 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• References
• Detailed Descriptions

1.14.0 Resource References

FHIR Infrastructure Work Group

Maturity Level: 3

Ballot Status: DSTU 2

Many of the defined elements in a resource are references to other resources. Using these references, the resources combine to build a web of information about healthcare.

Resources contain two types of references:

• Internal "contained" references - references to other resources packaged inside the source resource
• External references - references to resources found elsewhere

References are always defined and represented in one particular direction - from one resource (source) to another (target). References are provided as a URL, which may either be absolute or relative. Resolving the references is discussed below.

The corresponding reverse relationship from the target to the source exists in a logical sense, but is not represented explicitly in the resource. For external references, navigating these reverse relationships requires some external infrastructure to track the relationship between resources (the REST API provides one such infrastructure by providing the ability to search the reverse relationship by naming search parameters for the references, and by providing support for reverse includes).

Because resources are processed independently, relationships are not considered to be transitive. For example, if a Condition resource references a particular Patient as its subject, and references a Procedure resource as its cause, there is no automatic rule or implication that the procedure has the same patient for its subject. Instead, the subject of the procedure must be established directly in the Procedure resource itself. Another way to state this is that the context of the subject is not "inherited", nor does it "conduct" along the relationship to procedure. The only exception to this is the case of contained resources (see below). Note that in practice, the relationships need to describe a logical and coherent record, and in the case of the Condition and Procedure described here, they would usually be required to have the same patient for their subjects.

In a resource, references are represented with a reference and a text description. The reference is the key element - resources are identified and addressed by their URL. The actual reference looks like this:

• Structure
• UML
• XML
• JSON
• All

Structure

Name	Flags	Card.	Type	Description & Constraints
Reference	Σ I		Element	A reference from one resource to another SHALL have a local reference if the resource is provided inline
reference	Σ I	0..1	string	Relative, internal or absolute URL reference
display	Σ	0..1	string	Text alternative for the resource
Documentation for this format

UML Diagram

XML Template

<[name] xmlns="http://hl7.org/fhir"> 
 <!-- from Element: extension -->
 <reference value="[string]"/><!--  0..1 Relative, internal or absolute URL reference -->
 <display value="[string]"/><!-- 0..1 Text alternative for the resource -->
</[name]>

JSON Template



{
  // from Element: extension
  "reference" : "<string>", // C? Relative, internal or absolute URL reference
  "display" : "<string>" // Text alternative for the resource
}

Structure

Name	Flags	Card.	Type	Description & Constraints
Reference	Σ I		Element	A reference from one resource to another SHALL have a local reference if the resource is provided inline
reference	Σ I	0..1	string	Relative, internal or absolute URL reference
display	Σ	0..1	string	Text alternative for the resource
Documentation for this format

UML Diagram

XML Template

<[name] xmlns="http://hl7.org/fhir"> 
 <!-- from Element: extension -->
 <reference value="[string]"/><!--  0..1 Relative, internal or absolute URL reference -->
 <display value="[string]"/><!-- 0..1 Text alternative for the resource -->
</[name]>

JSON Template

{
  // from Element: extension
  "reference" : "<string>", // C? Relative, internal or absolute URL reference
  "display" : "<string>" // Text alternative for the resource
}

Notes:

• The reference element contains a url that is either
  • an absolute URL
  • a relative URL, which is relative to the Service Base URL, or, in a bundle, the Bundle.entry.fullUrl (see Resolving References in Bundles)
  • an internal fragment reference (see "Contained Resources" below)
• Using absolute URLs provides a stable, scalable approach suitable for a cloud/web context, while using relative/logical references provides a flexible approach suitable for use when trading across closed ecosystem boundaries. (see implementation issues for further discussion)
• Absolute URLs do not need to point to a FHIR RESTful server, though this is the preferred approach. Whether or not the reference is to a FHIR RESTful server, the reference SHALL point to a Resource as defined by this specification.
  Note: This regex is true if the reference to a resource is consistent with a FHIR API:

     ((http|https)://([A-Za-z0-9\\\/\.\:\%\$])*)?(Account|AllergyIntolerance|Appointment|AppointmentResponse|AuditEvent|Basic|Binary|BodySite|Bundle|CarePlan|Claim|ClaimResponse|ClinicalImpression|Communication|CommunicationRequest|Composition|ConceptMap|Condition|Conformance|Contract|Coverage|DataElement|DecisionSupportRule|DecisionSupportServiceModule|DetectedIssue|Device|DeviceComponent|DeviceMetric|DeviceUseRequest|DeviceUseStatement|DiagnosticOrder|DiagnosticReport|DocumentManifest|DocumentReference|EligibilityRequest|EligibilityResponse|Encounter|EnrollmentRequest|EnrollmentResponse|EpisodeOfCare|ExpansionProfile|ExplanationOfBenefit|FamilyMemberHistory|Flag|Goal|Group|GuidanceResponse|HealthcareService|ImagingObjectSelection|ImagingStudy|Immunization|ImmunizationRecommendation|ImplementationGuide|Library|List|Location|Measure|Media|Medication|MedicationAdministration|MedicationDispense|MedicationOrder|MedicationStatement|MessageHeader|ModuleDefinition|ModuleMetadata|NamingSystem|NutritionOrder|Observation|OperationDefinition|OperationOutcome|Order|OrderResponse|OrderSet|Organization|Patient|PaymentNotice|PaymentReconciliation|Person|Practitioner|Procedure|ProcedureRequest|ProcessRequest|ProcessResponse|Provenance|Questionnaire|QuestionnaireResponse|ReferralRequest|RelatedPerson|RiskAssessment|Schedule|SearchParameter|Sequence|Slot|Specimen|StructureDefinition|Subscription|Substance|SupplyDelivery|SupplyRequest|TestScript|ValueSet|VisionPrescription)\/[A-Za-z0-9\-\.]{1,64}(\/_history\/[A-Za-z0-9\-\.]{1,64})?
     

  
  However conformance with this regex is no guarantee that the end-point is a FHIR server
• URLs are always considered to be case-sensitive
• In general, the display, if populated, does not have identical content to the Resource.text of the referenced resource. The purpose is to identify what's being referenced, not to more fully describe it

  <context>
    <reference value="Patient/034AB16" />
  </context>

  <profile>
    <reference value="http://fhir.hl7.org/svc/StructureDefinition/c8973a22-2b5b-4e76-9c66-00639c99e61b" />
  </profile>

  <custodian>
    <reference value="Organization/123" />
    <display value="HL7, Inc" />
  </custodian>

Note that some elements have the type uri instead of Reference. URIs may point to resources, to elements inside a resource by their id property, or (most often) to some other content that is not a resource. The Reference type is only used to refer to resources directly, by their logical id.

1.14.0.1 Contained Resources

In some circumstances, the content referred to in the resource reference does not have an independent existence apart from the resource that contains it - it cannot be identified independently, and nor can it have its own independent transaction scope. Typically, such circumstances arise where resources are being assembled by a secondary user of the source data, such as a middleware engine. If the data available when the resource is constructed does not include record keys or absolute identification information, then a properly identified resource cannot be assembled, and even if an arbitrary identification was associated with it, the resource could never be the subject of a transaction outside the context of the resource that refers to it.

For example, consider a situation where an interface engine is creating a Condition record on a patient from an HL7 v2 message, and the only information about the primary surgeon is her first name and last name (REL-7.2 & RES-7.3). In the absence of a controlled practitioner directory, this is not enough information to create an identified Practitioner resource since more than one practitioner might have the same name.

In these circumstances, the resource is placed directly in-line in the resource. This SHOULD NOT be done when the content can be identified properly, as once the identification is lost, it is extremely difficult (and context dependent) to restore it again.

   
 <Composition xmlns="http://hl7.org/fhir">
  <extension>...</extension>
  <text>...</text>
  <contained>
    <Organization>
      <id value="org1"/>
      <!-- whatever information is available -->
    </Organization>
  </contained>
  <information>
    <!-- other attributes -->
    <custodian>
      <reference value="#org1" />
    </custodian>
    <!-- other attributes -->
  <information>
 </Composition>

{ "resourceType" : "Composition",
  "extension" : { ... },
  "text" : { .. },
  "contained: [
    {
      "resourceType" : "Organization",
      "id" : "org1",
      .. whatever information is available ...
	}  ]
  "information: {
    ... other attributes ...
    "custodian" : {
      "reference" : "#org1"
	}
    ... other attributes ...
  }
}

Design Note: Contained resources are still a reference rather than being inlined directly into the element that is the reference (e.g. "custodian" above) to ensure that a single approach to resolving resource references can be used. Though direct containment would seem simpler, it would still be necessary to support internal references where the same contained resource is referenced more than once. In the end, all that it would achieve is creating additional options in the syntax. For users using XPath to process the resource, the following XPath fragment resolves the internal reference:

ancestor::f:*[not(parent::f:*)]/f:contained/*[@id=substring-after(current()/f:reference/@value, '#')]

Some notes about use and interpretation of contained resources:

• The contained element SHALL NOT have extensions on it (though contained resources can still contain extensions)
• Contained resources share the same internal id resolution space as the parent resource (for id attributes, see below)
• Contained resources SHALL NOT contain additional contained resources
• Contained resources SHALL NOT contain any narrative
• A contained resource SHALL only be included in a resource if something in that resource (potentially another contained resource) has a reference to it

Resources that are contained inline do not "inherit" context from their parent resource. For instance, if the parent resource contains a "subject", and the contained resource also has a "subject" element defined, there is no implication that the contained resource has the same subject as the parent resource.

Resources can only be contained in other resources if there is a reference from the resource to the contained resource. This is intended to ensure that the meaning of the contained resource is clear, and that there is no confusion as to its significance.

DSTU Note: There are some identified use cases where it would be useful to include resources that refer to the contained resource rather than the container referring to the contained resource, but this has a series of structural ramifications for the API. Whether these can be resolved is an open issue for investigation during the period of trial use.

Feedback is welcome here .