. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.0.82: DSTU 1). 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
Resources contain two types of references:
There are 3 cases where elements inside a resource reference each other:
Between a ResourceReference and a contained resource
The ResourceReference's reference element refers to the id of the contained resource using
a fragment identifier, relative to the resource.
See below under 'Contained Resources' for an example.
Between elements in the narrative and structured data elements
This is done using an id/idref based approach, where a source element indicates that it
has the same content as the target element. All references between the xhtml elements and the data elements must
be understood to establish a "derived from" relationship, where the derived content (whether text or data) refers
to the source content. Note that this means some references may be forward references (references to
elements defined later in the instance):
<Patient xmlns="http://hl7.org/fhir">
<text>
<status value="generated"/>
<div xmlns="http://www.w3.org/1999/xhtml">
<p>... <span idref="dob"/>30-11-1972</span>
</div>
</text>
<birthDate id="dob" value="1972-11-30" />
An <img src=""/> reference in the narrative
The image source may be referring to an image found in the resource
(as a contained Media or Binary resource):
<Patient xmlns="http://hl7.org/fhir">
<text>
<status value="generated"/>
<div xmlns="http://www.w3.org/1999/xhtml">
<p>... <img src="#pic1"/>. ....</p>
</div>
</text>
<contained>
<Binary id="pic1" contentType="image/gif">MEKH....SD/Z</Binary>
</contained>
In all three cases, the target element has an attribute "id" which SHALL have a unique value within the resource with regard to any other id attributes: the uniqueness and resolution scope of these id references is within the resource that contains them. If multiple resources are combined into a single piece of XML, such as an atom feed, duplicate values may occur between resources. This SHALL be managed by applications reading the resources. The "id" attribute is not in any namespace. The source element reference SHALL refer to an attribute in the same resource.
Note that internal references work exactly the same in way in JSON, based on the JSON property id which is equivalent to the XML attribute "id".
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.
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. 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).
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 it links to 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 itself. Another way to state this is that the context of the subject is not "inherited" and it does not "conduct" along the relationship to procedure. The only exception to this in the case of contained resources (see below). Note that in practice, the relationships do 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:
<[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]>
Notes:
Constraints
A relative reference to the patient "034AB16" in an element named "context" on a FHIR RESTful server:
<context>
<reference value="Patient/034AB16" />
</context>
An absolute reference to a resource profile in an element named "profile":
<profile>
<reference value="http://fhir.hl7.org/svc/Profilec8973a22-2b5b-4e76-9c66-00639c99e61b" />
</profile>
Note that HL7 has not yet actually created a profile registry, nor decided on a URL for it.
A short display text that provides a human-readable identification of the resource may be provided:
<custodian>
<reference value="Organization/123" />
<display value="HL7, Inc" />
</custodian>
This text can be used by a system that is unable to resolve the reference to an actual resource.
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 the resource is 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 lastname (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 - 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:
<Document xmlns="http://hl7.org/fhir">
<extension>...</extension>
<text>...</text>
<contained>
<Organization id="org1">
<!-- whatever information is available -->
</Organization>
</contained>
<information>
<!-- other attributes -->
<custodian>
<reference value="#org1" />
</custodian>
<!-- other attributes -->
<information>
</Document>
The same example in JSON:
{ "resourceType" : "Document",
"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:
When processing bundles, applications should always search the resources in the bundle first when a resource reference is encountered.
<institution>
<reference value="http://example.org/Organization/23" />
</institution>
<institution>
<reference value="http://example.org/Organization/ex/history/2" />
</institution>
then the application should look for any entry in the bundle where either the entry.id or the entry.link[self] matches the reference URL exactly:
.. feed ..
<entry>
..
<id>http://example.org/Organization/23<id>
..
<content type="text/xml">
<Organization xmlns="http://hl7.org/fhir">
<!-- Content for the resource -->
</Organization>
</content>
<entry>
..
<link rel="self" href="http://example.org/Organization/ex/history/2<"/>
..
<content type="text/xml">
<Organization xmlns="http://hl7.org/fhir">
<!-- Content for the resource -->
</Organization>
</content>
... feed ...
In the second case, the match is based on a specific version of the resource. Applications should check both the entry.id and the self link - only one of the two can be a match. If the resource reference cannot be resolved in the bundle, the application SHOULD be able to retrieve the resource by following the provided URL directly. If it can't, it will have to use some other implementation-specific method for resolving how to find the resource.
Note that internal references are allowed to be URIs rather than literal URLs. A typical case is the use of cid: URIs in a transaction.
If the resource reference is a relative URL, the same basic principle applies: attempt to resolve the reference in the bundle first, and then look outside. However, before this can be done, the relative URL must be converted to an absolute URL, and in order to do this, the logical Service Base URL must be known. This is represented in a link named "fhir-base" on the feed itself:
<feed xmlns="http://www.w3.org/2005/Atom">
<link rel="fhir-base" href="http://example.org"/>
<entry>
<id>http://example.org/Organization/23<id>
..
<content type="text/xml">
<Organization xmlns="http://hl7.org/fhir">
<!-- Content for the resource -->
</Organization>
</content>
<entry>
..
<link rel="self" href="http://example.org/Practitioner/example"/>
..
<content type="text/xml">
<Practitioner xmlns="http://hl7.org/fhir">
<!-- Content for the resource -->
<institution>
<reference value="Organization/23" />
</institution>
<!-- Content for the resource -->
</Practitioner>
</content>
... feed ...
When the application encounters the reference "Organization/23", it looks up the "fhir-base" URL, which is http://example.org. The base service URL is represented without a trailing slash, so the application concatenates the two with a "/" between them, giving and absolute reference of "http://example.org/Organization/23", which it can resolve in this bundle. Note: the method is the same for JSON bundles.
In order to allow relative URLs to be processed properly, there SHALL be a "fhir-base" link on the bundle links if there is any relative links in any of the resources in the bundle.
Note that the application SHOULD not assume that the base service root is actually resolvable. In some circumstances, it will. If the bundle has just been received from a server as a result of a search or a history operation, the service root URL SHOULD match the URL that the client used (it is allowed not to in order to cater for proxies of various kinds). However in other circumstances, where the bundle itself has been exchanged onwards from the point of origin, and/or stored as an entity in its own right (e.g. a clinical document) the service root URL is merely a logical construct that holds within the bundle when resolving resources, and will have no meaning outside the bundle.
© HL7.org 2011+. FHIR DSTU (v0.0.82.2943) generated on Tue, Sep 30, 2014 18:10+1000.
Links:
What's a DSTU? |
Version History |
|
Propose a change