Foundation
This page is part of the FHIR Specification (v1.6.0:
STU
3 Ballot 4). The current version which supercedes this version is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
. For a full list of available versions, see the
Directory of published versions 
.
Page
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
parameters
for
the
references,
and
by
providing
support
for
reverse
includes
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
).
Because resources are processed independently, relationships are not considered to be transitive. For example, if a
Condition
resource
references
a
particular
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
as its subject, and references a
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
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
looks
like
this:
is the key element - resources are identified and addressed by their URL. The actual reference looks like this:
Structure
| Name | Flags | Card. | Type |
|
|---|---|---|---|---|
Reference
|
Σ I | Element |
|
|
reference
|
Σ I | 0..1 | string |
|
display
|
Σ | 0..1 | string |
|
|
Documentation for this format
|
||||
UML
Diagram
UML Diagram
(
Legend
)
XML
Template
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
JSON Template
{
{
// from Element: extension
"
"
"reference" : "<string>", // C? Relative, internal or absolute URL reference
"display" : "<string>" // Text alternative for the resource
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: Element.extension fhir:Reference.reference [ string ]; # 0..1 Relative, internal or absolute URL reference fhir:Reference.display [ string ]; # 0..1 Text alternative for the resource ]
Changes since DSTU2
| Reference | No Changes |
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type |
|
|---|---|---|---|---|
|
Reference
|
Σ I | Element |
|
|
|
reference
|
Σ I | 0..1 | string |
|
|
display
|
Σ | 0..1 | string |
|
|
Documentation for this format
|
||||
XML
Template
XML Template
<
<[name] xmlns="http://hl7.org/fhir">< <<reference value="[string]"/><!--
JSON
Template
JSON Template
{
{
// from Element: extension
"
"
"reference" : "<string>", // C? Relative, internal or absolute URL reference
"display" : "<string>" // Text alternative for the resource
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: Element.extension fhir:Reference.reference [ string ]; # 0..1 Relative, internal or absolute URL reference fhir:Reference.display [ string ]; # 0..1 Text alternative for the resource ]
Constraints
:
reference.startsWith('#').not() or (reference.substring(1).trace('url') in %resource.contained.id.trace('ids'))
)
Notes:
The
reference
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
(see
Resolving References in Bundles
)
((http|https)://([A-Za-z0-9\\\/\.\:\%\$])*)?(Account|ActivityDefinition|AllergyIntolerance|Appointment|AppointmentResponse|AuditEvent|Basic|Binary|BodySite|Bundle|CarePlan|CareTeam|Claim|ClaimResponse|ClinicalImpression|CodeSystem|Communication|CommunicationRequest|CompartmentDefinition|Composition|ConceptMap|Condition|Conformance|Consent|Contract|Coverage|DataElement|DecisionSupportServiceModule|DetectedIssue|Device|DeviceComponent|DeviceMetric|DeviceUseRequest|DeviceUseStatement|DiagnosticReport|DiagnosticRequest|DocumentManifest|DocumentReference|EligibilityRequest|EligibilityResponse|Encounter|Endpoint|EnrollmentRequest|EnrollmentResponse|EpisodeOfCare|ExpansionProfile|ExplanationOfBenefit|FamilyMemberHistory|Flag|Goal|Group|GuidanceResponse|HealthcareService|ImagingManifest|ImagingStudy|Immunization|ImmunizationRecommendation|ImplementationGuide|Library|Linkage|List|Location|Measure|MeasureReport|Media|Medication|MedicationAdministration|MedicationDispense|MedicationOrder|MedicationStatement|MessageHeader|NamingSystem|NutritionRequest|Observation|OperationDefinition|OperationOutcome|Organization|Patient|PaymentNotice|PaymentReconciliation|Person|PlanDefinition|Practitioner|PractitionerRole|Procedure|ProcedureRequest|ProcessRequest|ProcessResponse|Provenance|Questionnaire|QuestionnaireResponse|ReferralRequest|RelatedPerson|RiskAssessment|Schedule|SearchParameter|Sequence|Slot|Specimen|StructureDefinition|StructureMap|Subscription|Substance|SupplyDelivery|SupplyRequest|Task|TestScript|ValueSet|VisionPrescription)\/[A-Za-z0-9\-\.]{1,64}(\/_history\/[A-Za-z0-9\-\.]{1,64})?
display
A relative reference to the
Patient
"034AB16"
in
an
element
named
"034AB16" in an element named
context
on a FHIR RESTful server:
on
a
FHIR
RESTful
server:
<context>
<reference value="Patient/034AB16" />
</context>
An
absolute
reference
to
a
Structure
Definition
in
an
element
named
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
that
HL7
has
not
yet
actually
created
a
profile
registry,
nor
decided
on
a
URL
for
it
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:
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.
Note
that
some
elements
have
the
type
This text can be used by a system that is unable to resolve the reference to an actual resource.
Note that some elements have the type
uri
instead
of
instead of
Reference
. URIs may point to resources, to elements inside a resource by their .
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. 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.
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
record
on
a
patient
from
an
HL7
v2
).
The canonical URL remains the same when the resource is copied from server to server, while the logical id of the resource - it's 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.
Systems resolving references to resources that might have cannonical URLs SHOULD first try to resolve the reference using the cannonical URL, and then fall back to direct resolution against the URL if a local version of the canonical resource cannot be found. This approach is safe because the local version cannot be a different artifact that the master copy, though implementations will need to make appropriate arrangements regarding the currency of their local copy of the artifact.
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.
An
example
of
a
contained
resource:
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>
<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:
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:
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
Some notes about use and interpretation of contained resources:
contained
DSTU Note: It might be necessary to allow for the reverse (that is, for a contained resource to reference the container). However this would cause many difficult consequences on the API. Feedback on this issue is welcome here
. © HL7.org 2011+. FHIR DSTU2 (v1.0.2-7202) generated on Sat, Oct 24, 2015 07:44+1100. Links: Search.
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
| Version History | Table of Contents | Compare to DSTU1.
© HL7.org 2011+. FHIR STU3 Ballot (v1.6.0-9663) generated on Thu, Aug 11, 2016 17:07+1000.
QA Page
Links:
Search
|
|
Version History
|
Table of Contents
|
Compare to DSTU2
|
|
Propose
a
change
try
{
var
currentTabIndex
=
sessionStorage.getItem('fhir-resource-tab-index');
}
catch(exception){
}
if
(!currentTabIndex)
currentTabIndex
=
'0';
$(
'#tabs-Reference'
).tabs({
active:
currentTabIndex,
activate:
function(
event,
ui
)
{
store(ui.newTab.index());
}
});
function
store(currentTab)
{
document.activeElement.blur();
try
{
sessionStorage.setItem('fhir-resource-tab-index',
currentTab);
}
catch(exception){
}
$(
'#tabs-Reference'
).tabs('option',
'active',
currentTab);
}
|
Propose a change