2nd DSTU Draft For Comment
This page is part of the FHIR Specification (v0.4.0: DSTU 2 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
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:
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).
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", nor does it "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:
Notes:
A relative reference to the patient "034AB16" in an element named "context" on a FHIR RESTful server:
0..1
<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/Profile/c8973a22-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:
<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>
The same example in JSON:
{ "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:
Constraints
When processing bundles, applications should always search the resources in the bundle first when a resource reference is encountered.
<institution>
<reference value="Organization/23" />
</institution>
<institution>
<reference value="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:
.. bundle ..
<item>
<Organization xmlns="http://hl7.org/fhir">
<id value="23"/>
<!-- Content for the resource -->
</Organization>
<item>
<item>
<Organization xmlns="http://hl7.org/fhir">
<id value="ex"/>
<meta>
<versionId value="2"/>
</meta>
<!-- Content for the resource -->
</Organization>
<item>
... bundle ...
In the second case, the match is based on a specific version of the resource. 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.
If the resource reference is a absolute 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 absolute URL must be compared to the stated based URL, in Bundle.base; if these do not match, the resource is not in the bundle. todo-bundle: how to mix content?
Note that some elements have the type "uri" instead of "Reference". URIs may point to either resources, elements inside a resource by their "id" property, or (most often) some other content that is not a resource. The Reference type is only used to refer to resources directly, by their logical id.
© HL7.org 2011+. FHIR DSTU (v0.4.0-4167) generated on Mon, Feb 23, 2015 09:24+1100.
Links: What's a DSTU? |
Version History |
Compare to DSTU1 |
|
Propose a change