DSTU2 FHIR Release 3 (STU)

This page is part of the FHIR Specification (v1.0.2: DSTU (v3.0.2: STU 2). 3). 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 R3 R2

1.14.0 2.3.0 Resource References

FHIR Infrastructure Work Group Maturity Level : 3 5 Ballot Status : DSTU 2 Trial Use

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 either provided as a literal URL, which may either be absolute or relative. relative, or as a logical identifier. 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 target 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. subjects, and profiles may make rules about this.

In a resource, references are represented with a reference (literal reference), an identifier (logical 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: display (text description of target).

Structure

Name Flags Card. Type Description & Constraints doco
. . Reference Σ I Element A reference from one resource to another
+ SHALL have a contained resource if a local reference if the resource is provided inline
Elements defined in Ancestors: id , extension
. . . reference Σ I 0..1 string Literal reference, Relative, internal or absolute URL
. . . identifier Σ 0..1 Identifier Logical reference, when literal reference is not known
. . . display Σ 0..1 string Text alternative for the resource

doco Documentation for this format

XML Template 

<

<[name] xmlns="http://hl7.org/fhir"> doco

 <!-- from Element: extension -->
 <
 <

 <reference value="[string]"/><!-- ?? 0..1 Literal reference, Relative, internal or absolute URL -->
 <identifier><!-- 0..1 Identifier Logical reference, when literal reference is not known --></identifier>
 <display value="[string]"/><!-- 0..1 Text alternative for the resource -->

</[name]>

Turtle Template

 

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:Reference.reference [ string ]; # 0..1 Literal reference, Relative, internal or absolute URL
  fhir:Reference.identifier [ Identifier ]; # 0..1 Logical reference, when literal reference is not known
  fhir:Reference.display [ string ]; # 0..1 Text alternative for the resource
]

Changes since DSTU2


Reference
Reference.identifier
  • Added Element

See the Full Difference for further information

Structure

Name Flags Card. Type Description & Constraints doco
. . Reference Σ I Element A reference from one resource to another
+ SHALL have a contained resource if a local reference if the resource is provided inline
Elements defined in Ancestors: id , extension
. . . reference Σ I 0..1 string Literal reference, Relative, internal or absolute URL
. . . identifier Σ 0..1 Identifier Logical reference, when literal reference is not known
. . . display Σ 0..1 string Text alternative for the resource

doco Documentation for this format

XML Template 

<

<[name] xmlns="http://hl7.org/fhir"> doco

 <!-- from Element: extension -->
 <
 <

 <reference value="[string]"/><!-- ?? 0..1 Literal reference, Relative, internal or absolute URL -->
 <identifier><!-- 0..1 Identifier Logical reference, when literal reference is not known --></identifier>
 <display value="[string]"/><!-- 0..1 Text alternative for the resource -->

</[name]>

Turtle Template 


@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:Reference.reference [ string ]; # 0..1 Literal reference, Relative, internal or absolute URL
  fhir:Reference.identifier [ Identifier ]; # 0..1 Logical reference, when literal reference is not known
  fhir:Reference.display [ string ]; # 0..1 Text alternative for the resource
]

  Changes since DSTU2

Reference
Reference.identifier
  • Added Element

See the Full Difference for further information

 

Constraints

At least one of reference , identifier and display SHALL be present (unless an extension is provided).

  • ref-1 : SHALL have a contained resource if a local reference if the resource is provided inline (xpath: ( expression : not(starts-with(f:reference/@value, '#')) or exists(ancestor::*[self::f:entry reference.startsWith('#').not() or self::f:parameter]/f:resource/f:*/f:contained/f:*[f:id/@value=substring-after(current()/f:reference/@value, '#')]|/*/f:contained/f:*[f:id/@value=substring-after(current()/f:reference/@value, '#')]) (reference.substring(1).trace('url') in %resource.contained.id.trace('ids')) )

2.3.0.1 Literal References

Notes: The reference is the key element - resources are identified and addressed by their URL. It contains a url that is either

Notes:

  • 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 "Managing Resource Identity" for further discussion ) 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|DetectedIssue|Device|DeviceComponent|DeviceMetric|DeviceUseRequest|DeviceUseStatement|DiagnosticOrder|DiagnosticReport|DocumentManifest|DocumentReference|EligibilityRequest|EligibilityResponse|Encounter|EnrollmentRequest|EnrollmentResponse|EpisodeOfCare|ExplanationOfBenefit|FamilyMemberHistory|Flag|Goal|Group|HealthcareService|ImagingObjectSelection|ImagingStudy|Immunization|ImmunizationRecommendation|ImplementationGuide|List|Location|Media|Medication|MedicationAdministration|MedicationDispense|MedicationOrder|MedicationStatement|MessageHeader|NamingSystem|NutritionOrder|Observation|OperationDefinition|OperationOutcome|Order|OrderResponse|Organization|Patient|PaymentNotice|PaymentReconciliation|Person|Practitioner|Procedure|ProcedureRequest|ProcessRequest|ProcessResponse|Provenance|Questionnaire|QuestionnaireResponse|ReferralRequest|RelatedPerson|RiskAssessment|Schedule|SearchParameter|Slot|Specimen|StructureDefinition|Subscription|Substance|SupplyDelivery|SupplyRequest|TestScript|ValueSet|VisionPrescription)\/[A-Za-z0-9\-\.]{1,64}(\/_history\/[A-Za-z0-9\-\.]{1,64})?

   ((http|https)://([A-Za-z0-9\\\.\:\%\$]\/)*)?(Account|ActivityDefinition|AdverseEvent|AllergyIntolerance|Appointment|AppointmentResponse|AuditEvent|Basic|Binary|BodySite|Bundle|CapabilityStatement|CarePlan|CareTeam|ChargeItem|Claim|ClaimResponse|ClinicalImpression|CodeSystem|Communication|CommunicationRequest|CompartmentDefinition|Composition|ConceptMap|Condition|Consent|Contract|Coverage|DataElement|DetectedIssue|Device|DeviceComponent|DeviceMetric|DeviceRequest|DeviceUseStatement|DiagnosticReport|DocumentManifest|DocumentReference|EligibilityRequest|EligibilityResponse|Encounter|Endpoint|EnrollmentRequest|EnrollmentResponse|EpisodeOfCare|ExpansionProfile|ExplanationOfBenefit|FamilyMemberHistory|Flag|Goal|GraphDefinition|Group|GuidanceResponse|HealthcareService|ImagingManifest|ImagingStudy|Immunization|ImmunizationRecommendation|ImplementationGuide|Library|Linkage|List|Location|Measure|MeasureReport|Media|Medication|MedicationAdministration|MedicationDispense|MedicationRequest|MedicationStatement|MessageDefinition|MessageHeader|NamingSystem|NutritionOrder|Observation|OperationDefinition|OperationOutcome|Organization|Patient|PaymentNotice|PaymentReconciliation|Person|PlanDefinition|Practitioner|PractitionerRole|Procedure|ProcedureRequest|ProcessRequest|ProcessResponse|Provenance|Questionnaire|QuestionnaireResponse|ReferralRequest|RelatedPerson|RequestGroup|ResearchStudy|ResearchSubject|RiskAssessment|Schedule|SearchParameter|Sequence|ServiceDefinition|Slot|Specimen|StructureDefinition|StructureMap|Subscription|Substance|SupplyDelivery|SupplyRequest|Task|TestReport|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 References SHALL be a reference to an actual FHIR resource, and SHALL be resolveable (allowing for access control, temporary unavailability, etc). Resolution can be either by retrieval from the Resource.text of the referenced resource. The purpose is to identify what's being referenced, not to more fully describe URL, or, where applicable by resource type, by treating an absolute reference as a canonical URL ( see below ) and looking it up in a local registry/repository

A relative reference to the Patient "034AB16" in an element named context on a FHIR RESTful server:

<context> 
  <patient>

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

  </patient>

An absolute reference to a Structure Definition in an element named profile : 

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

Note 2.3.0.2 Logical References

In many contexts where FHIR is used, applications building a resource may know an identifier for the target of the reference, but there is no way for the application to convert this to a literal reference that HL7 directly references an actual resource. This situation may arise for several reasons:

  • There is no server exposing any such resource. This is often the case with national identifiers (e.g. US SSN or NPI), and such identifiers are widely used
  • The server that exposes the resource is not available to the source application, so it has no way to resolve an identifier to a reference
  • The application is not yet in a RESTful environment - it is creating a message or a document

In this cases, the source application may provide the identifier as a logical reference to the entity that the target resource would describe.

A logical reference to the Patient with an SSN of 000111111: 


  <patient>
    <identifier>
      <system value="http://hl7.org/fhir/sid/us-ssn" />
      <value value="000111111" />
    </identifier>
  </patient>

There is no requirement that a Reference.identifier point to something that is actually created exposed as a profile registry, nor decided FHIR instance, but it SHALL point to a business concept that would be expected to be exposed as a FHIR instance, and that instance would need to be of a FHIR resource type allowed by the reference.

When processing a resource, an application may be able to use the identifier directly, on the grounds that all it needs is the identifier, or it may be able to resolve the identifier directly. Alternatively, it may be able to use a URL server to resolve the logical reference to a literal reference to a resource.

Irrespective of how the resolution occurs, any system processing a logical reference will only be able to resolve the identifier to a reference if it understands the business context in which the identifier is used. Sometimes this is global (e.g. a national identifier) but often it is not.

For this reason, none of the useful mechanisms described for working with references (e.g. chaining , includes ) are possible, nor should servers be expected to be able to automatically resolve the reference. Servers may accept an identifier based reference untouched, resolve it, and/or reject it . - see CapabilityStatement.rest.resource.referencePolicy .

A short display text When both an identifier and a literal reference are provided, the literal reference is preferred. Applications processing the resource are allowed - but not required - to check that provides the identifier matches the literal reference, if they understand how to resolve the logical reference.

Applications converting a human-readable identification logical reference to a literal reference may choose to leave the logical reference present, or remove it.

2.3.0.3 Reference Description

Irrespective of whether a literal and/or logical reference is provided, or neither, the resource display element may be provided: used to provide a very short description of the target resource. 

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

This text can be used by a system any application that is unable to cannot resolve the reference to an actual resource. fill out the text portion of a hyperlink referring to the target resource, for instance. It can also save time fetching a target resource, and determining how to convert it to a very short textual description.

Note that some elements 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.

2.3.0.4 Canonical URLs

Many resource types have a defined element "url" which is the canonical URL that always identifies the resource. These include all the conformance and knowledge resources (most of the resources not found in the Patient Compartment ).

The canonical URL remains the same when the resource is copied from server to server, while the logical id of the resource - its local identifier - usually changes as the resource is copied. The canonical URL serves as a stable logical identifier for the conformance artifact, and is the preferred way to reference a conformance or knowledge resource . The canonical URL is also the location where the master copy of the artifact is found.

References to these resources may use the Reference type described above, but they can also be referenced using a uri instead .

When the type of the canonical reference is a Reference . URIs uri , the URL may point include a version, in order be precise about which version of the resource is being referred to. To do this, append the version to resources, the canonical url with a '|' like this: 


<valueSetUri value="http://hl7.org/fhir/StructureDefinition/my-profile|0.8"/>

This is a version specific reference to elements inside a resource by their profile. Note that this is the id StructureDefinition.version property, or (most often) to some other content not the StructureDefinition.meta.versionId . Searching for this on a FHIR server would look like this: 


GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/clinical-findings&version=0.8

Note that is if a canonical reference does not have a resource. The Reference type is only used to refer version, and the server finds multiple versions for the value set, the system using the reference should pick the latest version of the target resource and use that. Servers SHOULD support version specific searching for canonical URLs but automatically detecting the presence of a |[version] and performing the appropriate search.

Systems resolving references to resources directly, by that might have canonical URLs SHOULD first try to resolve the reference using the canonical URL, and then fall back to direct resolution using the URL as a literal reference if a local version of the canonical resource cannot be found. This approach is safe because the local version cannot be a different artifact than the master copy, though implementations will need to make appropriate arrangements regarding the currency of their logical id. local copy of the artifact.

1.14.0.1 2.3.0.5 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). REL-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.

An example of a contained resource:

<Composition xmlns="http://hl7.org/fhir"> <extension>...</extension> <text>...</text> 
 <Condition xmlns="http://hl7.org/fhir">

  <contained>
    <Organization>
      <id value="org1"/>
      <!-- whatever information is available -->
    </Organization>

    <Practitioner>
      <id value="p1"/>
      <name>
        <family value="Person"/>
        <given value="Patricia"/>
      </name>
    </Practitioner>

  </contained>
  <information>
    <!-- other attributes -->
    <custodian>
      <reference value="#org1" />
    </custodian>
    <!-- other attributes -->
  <information>
 </Composition>

  <!-- other attributes -->
  <asserter>
    <reference value="#p1" />
  </asserter>
  <!-- other attributes -->
 </Condition>

The same example in JSON:

{ "resourceType" : "Composition", "extension" : { ... }, "text" : { .. }, "contained: [ 
{
  "resourceType" : "Condition",
  "contained": [

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

      "resourceType" : "Practitioner",
      "id" : "p1",
      "name" : [{
        "family" : "Person",
        "given" : ["Patricia"]
      }]
	  }],
   "asserter" : {
     "reference" : "#p1"

  }
}

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) extensions).
  • The contained resource can be put in any resource that inherits from DomainResource. The contained element is then located at the beginning of the resource after any text narrative and before any extension.
  • Contained resources share the same internal id resolution space as the parent resource (for id attributes, see below) below).
  • When resolving references, references are resolved by looking through the 'container' resource - the one that contains the other resources. Since there are no nested contained resources, there is only one container resource.
  • References to contained resources are never resolved outside the container resource. Specifically, resolution stops at the elements Bundle.entry.resource and Parameters.parameter.resource, but not at DomainResource.contained.
  • Contained resources SHALL NOT contain additional contained resources resources.
  • Contained resources SHALL NOT contain any narrative 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 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 STU 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 .