Foundation
This
page
is
part
of
the
FHIR
Specification
(v3.3.0:
R4
Ballot
2).
The
current
version
which
supercedes
this
version
is
5.0.0
.
For
a
full
list
Continuous
Integration
Build
of
available
versions,
see
FHIR
(will
be
incorrect/inconsistent
at
times).
See
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
R3
R2
|
Responsible
Owner:
FHIR
Infrastructure
Work
Group
|
|
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).
The
corresponding
reverse
relationship
from
the
target
to
the
source
exists
in
a
logical
sense,
but
is
not
typically
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,
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
Procedure
resource
references
a
particular
Patient
as
its
subject,
and
references
has
a
Procedure
Condition
resource
as
its
cause,
reason,
there
is
no
automatic
rule
or
implication
that
the
procedure
condition
has
or
must
have
the
same
patient
for
its
subject.
Instead,
the
subject
of
the
procedure
condition
must
be
established
directly
in
the
Procedure
Condition
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.
condition.
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,
and
profiles
subjects.
Profiles
and/or
implementation
guides
may
make
rules
about
this
(and
(also
see
GraphDefinition
).
Resolving
This
specification
describes
the
use
of
references
to
other
resources
that
have
the
same
FHIR
version
as
the
source
of
the
reference.
Expected
behavior
for
references
across
FHIR
versions
is
discussed
below.
presently
undefined.
References are made to resource based on their identity; there are several different identities to refer to.
Resources contain two types of references to other resources:
For
canonical
references,
see
below.
The
general
references
are
handled
by
the
Reference
type.
which
See also Detailed Descriptions , Profiles and Extensions
The
Reference
type
contains
at
least
one
of
a
reference
(literal
reference),
an
identifier
(logical
reference),
and
a
display
(text
description
of
target).
In
addition,
it
may
a
contain
a
target
type
.
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
Reference
|
Σ
|
Element |
A
reference
from
one
resource
to
another
+ Rule: SHALL have a contained resource if a local reference is provided + Rule: At least one of reference, identifier and display SHALL be present (unless an extension is provided). Elements defined in Ancestors: id , extension |
|
reference
|
Σ
|
0..1 | string |
Literal
reference,
Relative,
internal
or
absolute
URL
|
|
type
|
Σ | 0..1 | uri |
Type
the
reference
refers
to
(e.g.
"Patient")
-
must
be
a
resource
in
resources
|
identifier
|
Σ C | 0..1 | Identifier |
Logical
reference,
when
literal
reference
is
not
known
|
display
|
Σ T C | 0..1 | string |
Text
alternative
for
the
resource
|
|
Documentation
for
this
format
|
||||
UML Diagram ( Legend )
XML Template
< xmlns="http://hl7.org/fhir"><Reference xmlns="http://hl7.org/fhir"> <!-- from Element: extension -->< <<a href="references-definitions.html#Reference.type" title="The expected type of the target of the reference. If both Reference.type and Reference.reference are populated and Reference.reference is a FHIR URL, both SHALL be consistent. The type is the Canonical URL of Resource Definition that is the type this reference refers to. References are URLs that are relative to http://hl7.org/fhir/StructureDefinition/ e.g. "Patient" is a reference to http://hl7.org/fhir/StructureDefinition/Patient. Absolute URLs are only allowed for logical models (and can only be used in references in logical models, not resources)." class="dict"> <</identifier> < </[name]><reference value="[string]"/><!-- I 0..1 Literal reference, Relative, internal or absolute URL --> <type value="[uri]"/><!-- 0..1 Type the reference refers to (e.g. "Patient") - must be a resource in resources --> <identifier><!-- I 0..1 Identifier Logical reference, when literal reference is not known --></identifier> <display value="[string]"/><!-- I 0..1 Text alternative for the resource --> </Reference>
JSON Template
{
// from Element: extension
"
"<a href="references-definitions.html#Reference.type" title="The expected type of the target of the reference. If both Reference.type and Reference.reference are populated and Reference.reference is a FHIR URL, both SHALL be consistent.
The type is the Canonical URL of Resource Definition that is the type this reference refers to. References are URLs that are relative to http://hl7.org/fhir/StructureDefinition/ e.g. "Patient" is a reference to http://hl7.org/fhir/StructureDefinition/Patient. Absolute URLs are only allowed for logical models (and can only be used in references in logical models, not resources)." class="dict">type
"
"
"reference" : "<string>", // I Literal reference, Relative, internal or absolute URL
"type" : "<uri>", // Type the reference refers to (e.g. "Patient") - must be a resource in resources
"identifier" : { Identifier }, // I Logical reference, when literal reference is not known
"display" : "<string>" // I Text alternative for the resource
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [# from Element: fhir: fhir:<a href="references-definitions.html#Reference.type" title="The expected type of the target of the reference. If both Reference.type and Reference.reference are populated and Reference.reference is a FHIR URL, both SHALL be consistent. The type is the Canonical URL of Resource Definition that is the type this reference refers to. References are URLs that are relative to http://hl7.org/fhir/StructureDefinition/ e.g. "Patient" is a reference to http://hl7.org/fhir/StructureDefinition/Patient. Absolute URLs are only allowed for logical models (and can only be used in references in logical models, not resources)." class="dict">Reference.type fhir: fhir:# from Element: fhir:extension fhir:l [ IRI
Changes
since
DSTU2
Release
4
Changes from both R4 and R4B
| Reference | |
| Reference.type |
|
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
|
Reference
|
Σ
|
Element |
A
reference
from
one
resource
to
another
+ Rule: SHALL have a contained resource if a local reference is provided + Rule: At least one of reference, identifier and display SHALL be present (unless an extension is provided). Elements defined in Ancestors: id , extension |
|
|
reference
|
Σ
|
0..1 | string |
Literal
reference,
Relative,
internal
or
absolute
URL
|
|
type
|
Σ | 0..1 | uri |
Type
the
reference
refers
to
(e.g.
"Patient")
-
must
be
a
resource
in
resources
|
|
identifier
|
Σ C | 0..1 | Identifier |
Logical
reference,
when
literal
reference
is
not
known
|
|
display
|
Σ T C | 0..1 | string |
Text
alternative
for
the
resource
|
|
Documentation
for
this
format
|
||||
XML Template
< xmlns="http://hl7.org/fhir"><Reference xmlns="http://hl7.org/fhir"> <!-- from Element: extension -->< <<a href="references-definitions.html#Reference.type" title="The expected type of the target of the reference. If both Reference.type and Reference.reference are populated and Reference.reference is a FHIR URL, both SHALL be consistent. The type is the Canonical URL of Resource Definition that is the type this reference refers to. References are URLs that are relative to http://hl7.org/fhir/StructureDefinition/ e.g. "Patient" is a reference to http://hl7.org/fhir/StructureDefinition/Patient. Absolute URLs are only allowed for logical models (and can only be used in references in logical models, not resources)." class="dict"> <</identifier> < </[name]><reference value="[string]"/><!-- I 0..1 Literal reference, Relative, internal or absolute URL --> <type value="[uri]"/><!-- 0..1 Type the reference refers to (e.g. "Patient") - must be a resource in resources --> <identifier><!-- I 0..1 Identifier Logical reference, when literal reference is not known --></identifier> <display value="[string]"/><!-- I 0..1 Text alternative for the resource --> </Reference>
JSON Template
{
// from Element: extension
"
"<a href="references-definitions.html#Reference.type" title="The expected type of the target of the reference. If both Reference.type and Reference.reference are populated and Reference.reference is a FHIR URL, both SHALL be consistent.
The type is the Canonical URL of Resource Definition that is the type this reference refers to. References are URLs that are relative to http://hl7.org/fhir/StructureDefinition/ e.g. "Patient" is a reference to http://hl7.org/fhir/StructureDefinition/Patient. Absolute URLs are only allowed for logical models (and can only be used in references in logical models, not resources)." class="dict">type
"
"
"reference" : "<string>", // I Literal reference, Relative, internal or absolute URL
"type" : "<uri>", // Type the reference refers to (e.g. "Patient") - must be a resource in resources
"identifier" : { Identifier }, // I Logical reference, when literal reference is not known
"display" : "<string>" // I Text alternative for the resource
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [# from Element: fhir: fhir:<a href="references-definitions.html#Reference.type" title="The expected type of the target of the reference. If both Reference.type and Reference.reference are populated and Reference.reference is a FHIR URL, both SHALL be consistent. The type is the Canonical URL of Resource Definition that is the type this reference refers to. References are URLs that are relative to http://hl7.org/fhir/StructureDefinition/ e.g. "Patient" is a reference to http://hl7.org/fhir/StructureDefinition/Patient. Absolute URLs are only allowed for logical models (and can only be used in references in logical models, not resources)." class="dict">Reference.type fhir: fhir:# from Element: fhir:extension fhir:l [ IRI
Changes
since
DSTU2
from
both
R4
and
R4B
| Reference | |
| Reference.type |
|
See the Full Difference for further information
Constraints
At
least
one
of
reference
,
identifier
and
display
SHALL
be
present
(unless
an
extension
is
provided).
| id | Level | Location | Description | Expression |
ref-1
| Rule | (base) |
SHALL
have
a
contained
resource
if
a
local
reference
is
provided
|
|
|
ref-2
| Rule | (base) | At least one of reference, identifier and display SHALL be present (unless an extension is provided). | reference.exists() or identifier.exists() or display.exists() or extension.exists() |
Also
note
that
in
resources,
a
Reference
SHALL
point
to
another
resource,
and
Reference.type,
if
it
is
present,
SHALL
be
a
valid
non-abstract
resource
(references
and
reference.type
MAY
refer
to
non-resource
content
in
logical
models).
In
resources,
a
Reference
always
point
points
to
another
resource,
which
has
a
fixed
and
known
type.
If
appropriate,
this
type
can
be
specified
in
the
reference
itself.
In
principle,
the
type
of
the
target
reference
can
be
determined
by
resolving
the
reference
(using
the
approaches
described
below),
and
examining
the
content
returned
to
determine
the
type;
for
this
reason
reason,
specifying
the
type
is
almost
always
duplication
of
information.
However
However,
resolving
references
may
be
a
very
slow
operation,
or
impossible
in
practice
due
to
various
practical
concerns.
For
this
reason,
the
reference
may
indicate
directly
the
target
resource
type:
"subject": {
"reference" : "http://someserver/some-path",
"type" : "Patient"
}
When the type is provided directly, it SHALL agree with the type determined by resolving the resource.
Note
that
in
practice,
if
a
literal
reference
to
a
FHIR
resource
is
used,
it
is
often
not
necessary
duplicative
to
know
include
the
type
of
in
the
target
resource
is,
unless
it's
going
to
be
resolved
anyway,
so
reference.
However,
in
many
cases,
specifying
cases
such
as
above,
using
Reference.identifier
including
the
type
of
the
target
resource
is
unnecessary.
useful.
In
order
to
support
Logical
Models
,
the
type
element
has
the
type
of
"uri".
Whenever
type
appears
in
resources,
the
uri
is
represented
relative
to
the
base
URI
http://hl7.org/fhir/StructureDefinition/
.
For
resources,
then,
resources
(and
including
additional
resources
),
the
value
is
simply
a
code
that
is
the
type
of
resource
-
e.g.
e.g.,
"Patient".
The
reference
is
the
key
element
-
resources
are
identified
and
addressed
by
their
URL.
It
contains
a
URL
that
is
either
Bundle.entry.fullUrl
(see
Resolving
References
in
Bundles
)
Notes:
((http|https)://([A-Za-z0-9\\\.\:\%\$]*\/)*)?(Account|ActivityDefinition|AdverseEvent|AllergyIntolerance|Appointment|AppointmentResponse|AuditEvent|Basic|Binary|BiologicallyDerivedProduct|BodyStructure|Bundle|CapabilityStatement|CarePlan|CareTeam|ChargeItem|Claim|ClaimResponse|ClinicalImpression|CodeSystem|Communication|CommunicationRequest|CompartmentDefinition|Composition|ConceptMap|Condition|Consent|Contract|Coverage|DetectedIssue|Device|DeviceComponent|DeviceMetric|DeviceRequest|DeviceUseStatement|DiagnosticReport|DocumentManifest|DocumentReference|EligibilityRequest|EligibilityResponse|Encounter|Endpoint|EnrollmentRequest|EnrollmentResponse|EntryDefinition|EpisodeOfCare|EventDefinition|ExampleScenario|ExpansionProfile|ExplanationOfBenefit|FamilyMemberHistory|Flag|Goal|GraphDefinition|Group|GuidanceResponse|HealthcareService|ImagingStudy|Immunization|ImmunizationEvaluation|ImmunizationRecommendation|ImplementationGuide|Invoice|ItemInstance|Library|Linkage|List|Location|Measure|MeasureReport|Media|Medication|MedicationAdministration|MedicationDispense|MedicationRequest|MedicationStatement|MedicinalProduct|MedicinalProductAuthorization|MedicinalProductClinicals|MedicinalProductDeviceSpec|MedicinalProductIngredient|MedicinalProductPackaged|MedicinalProductPharmaceutical|MessageDefinition|MessageHeader|NamingSystem|NutritionOrder|Observation|ObservationDefinition|OccupationalData|OperationDefinition|OperationOutcome|Organization|OrganizationRole|Patient|PaymentNotice|PaymentReconciliation|Person|PlanDefinition|Practitioner|PractitionerRole|Procedure|ProcessRequest|ProcessResponse|ProductPlan|Provenance|Questionnaire|QuestionnaireResponse|RelatedPerson|RequestGroup|ResearchStudy|ResearchSubject|RiskAssessment|Schedule|SearchParameter|Sequence|ServiceRequest|Slot|Specimen|SpecimenDefinition|StructureDefinition|StructureMap|Subscription|Substance|SubstancePolymer|SubstanceReferenceInformation|SubstanceSpecification|SupplyDelivery|SupplyRequest|Task|TerminologyCapabilities|TestReport|TestScript|UserSession|ValueSet|VerificationResult|VisionPrescription)\/[A-Za-z0-9\-\.]{1,64}(\/_history\/[A-Za-z0-9\-\.]{1,64})?((http|https):\/\/([A-Za-z0-9\-\\\.\:\%\$]*\/)+)?(Account|ActivityDefinition|ActorDefinition|AdministrableProductDefinition|AdverseEvent|AllergyIntolerance|Appointment|AppointmentResponse|ArtifactAssessment|AuditEvent|Basic|Binary|BiologicallyDerivedProduct|BodyStructure|Bundle|CapabilityStatement|CarePlan|CareTeam|Claim|ClaimResponse|ClinicalUseDefinition|CodeSystem|Communication|CommunicationRequest|CompartmentDefinition|Composition|ConceptMap|Condition|Consent|Contract|Coverage|CoverageEligibilityRequest|CoverageEligibilityResponse|DetectedIssue|Device|DeviceAlert|DeviceAssociation|DeviceDefinition|DeviceMetric|DeviceRequest|DiagnosticReport|DocumentReference|Encounter|Endpoint|EnrollmentRequest|EnrollmentResponse|EpisodeOfCare|EventDefinition|Evidence|EvidenceVariable|ExampleScenario|ExplanationOfBenefit|FamilyMemberHistory|Flag|Goal|Group|GuidanceResponse|HealthcareService|ImagingSelection|ImagingStudy|Immunization|ImplementationGuide|Ingredient|InsurancePlan|InsuranceProduct|Invoice|Library|List|Location|ManufacturedItemDefinition|Measure|MeasureReport|Medication|MedicationAdministration|MedicationDispense|MedicationRequest|MedicationStatement|MedicinalProductDefinition|MessageDefinition|MessageHeader|NamingSystem|NutritionIntake|NutritionOrder|NutritionProduct|Observation|ObservationDefinition|OperationDefinition|OperationOutcome|Organization|OrganizationAffiliation|PackagedProductDefinition|Patient|PaymentNotice|PaymentReconciliation|Permission|Person|PlanDefinition|Practitioner|PractitionerRole|Procedure|Provenance|Questionnaire|QuestionnaireResponse|RegulatedAuthorization|RelatedPerson|RequestOrchestration|Requirements|ResearchStudy|ResearchSubject|RiskAssessment|Schedule|SearchParameter|ServiceRequest|Slot|Specimen|SpecimenDefinition|StructureDefinition|StructureMap|Subscription|SubscriptionStatus|SubscriptionTopic|Substance|SubstanceDefinition|Task|TerminologyCapabilities|ValueSet|VisionPrescription)\/[A-Za-z0-9\-\.]{1,64}(\/_history\/[A-Za-z0-9\-\.]{1,64})?(#[A-Za-z0-9\-\.]{1,64})?
|[version]
syntax
part
of
the
canonical
reference
is
not
supported
A
relative
reference
to
the
Patient
"034AB16"
in
an
element
named
on
a
FHIR
RESTful
server:
context
subject
<patient><subject> <reference value="Patient/034AB16" /></patient></subject>
An
absolute
reference
to
a
Structure
Definition
in
an
element
named
profile
:
{
"profile" : {
"reference" : "http://fhir.hl7.org/svc/StructureDefinition/c8973a22-2b5b-4e76-9c66-00639c99e61b"
}
}
Note
that
in
a
bundle
during
a
transaction
,
reference
URLs
may
actually
contain
logical
URIs
(e.g.
(e.g.,
OIDs
it
or
UUIDSs)
that
resolve
within
the
transaction.
When
processing
the
transaction,
the
server
replaces
the
logical
URL
with
what
is
the
correct
literal
URL
at
the
completion
of
the
transaction.
References
are
allowed
to
can
be
version
specific
-
that
is,
a
reference
may
point
to
a
specific
version
of
a
resource.
e.g.
:
e.g.:
<target>
<reference value="http://example.org/fhir/Observation/1x2/_history/2" />
</target>
or
<target>
<reference value="Observation/1x2/_history/2" />
</target>
This
is
usually
associated
with
audit
trail
or
provenance
information
where
it
is
important
to
reference
a
particular
specific
version
of
a
record,
not
the
most
current
information.
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 directly references an actual resource. This situation may arise for several reasons:
For further discussion of the use of identifiers on resources, see Consistent Resource Identification . In these 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
exposed
or
exists
as
a
FHIR
instance
(except,
of
course,
that
the
reference
will
need
to
be
resolved
to
a
target
resource
if
any
information
from
it
is
required
in
a
FHIR
context).
The
reference
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
For
example,
it
would
not
be
legitimate
to
send
the
identifier
for
a
drug
prescription
if
the
type
were
Reference(Observation|DiagnosticReport).
One
of
the
use-cases
for
Reference.identifier
is
the
situation
where
no
FHIR
representation
exists
(where
the
type
is
Reference
(Any).
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 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.
(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.
reference,
nor
does,
for
example,
aggregation
restrictions.
Servers
may
accept
an
identifier
based
reference
untouched,
resolve
it,
and/or
reject
it
-
see
CapabilityStatement.rest.resource.referencePolicy
.
When
both
an
identifier
logical
and
a
literal
reference
references
are
provided,
the
literal
reference
is
preferred.
Applications
processing
the
resource
are
allowed
-
but
not
required
-
to
check
that
the
identifier
matches
the
literal
reference,
if
they
understand
how
to
resolve
the
logical
reference.
Applications
converting
a
logical
reference
to
a
literal
reference
may
choose
to
leave
the
logical
reference
present,
present;
or
may
remove
it.
Irrespective
of
whether
a
literal
and/or
logical
reference
is
provided,
or
neither,
the
display
element
may
be
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
any
application
that
cannot
resolve
the
reference
to
fill
out
the
text
portion
of
a
hyperlink
referring
to
the
target
resource,
for
instance.
It
can
also
save
time
fetching
a
target
resource,
resource
and
determining
how
to
convert
it
to
a
very
short
textual
description.
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.
Sometimes there is a need to communicate a reference to a resource that is not a defined target for the element in the version of FHIR being used. There are two common situations for this:
In
both
of
these
cases,
the
solution
is
to
use
the
alternate-reference
extension.
It
allows
referencing
any
type
of
resource
-
including
additional
resources.
The
targetProfile
used
when
profiling
this
extension
is
free
to
point
to
a
narrower
profile
than
a
resource
-
e.g.,
a
specific
inter-version
resource
profile
on
Basic.
In
some
cases,
an
additional
resource
may
migrate
to
be
a
core
resource
and
become
allowed
as
a
target
resource.
Systems
that
have
not
yet
updated
to
support
that
new
core
resource
may
struggle
with
the
migration
of
the
reference
from
the
additional-reference
to
the
standard
Reference.reference
element.
Communication
partners
will
need
to
manage
this
transition."
Many
resource
types
have
a
defined
element
"url"
which
is
the
canonical
URI
URL
that
always
identifies
the
resource.
These
include
resource
across
all
the
contexts
of
use.
Typically,
terminology
,
conformance
and
or
knowledge
resources
(most
of
the
resources
not
found
in
the
Patient
Compartment
).
Note
that
have
canonical
URLs.
The
canonical
URL
is
the
element
actually
contains
preferred
way
to
reference
a
URI,
but
resource
instance
for
the
resource
types
on
which
it
is
named
url
defined.
See
Canonical
Resource
Identity
for
legacy
reasons.
further
information.
Canonical
references
References
to
canonical
URLs
use
the
canonical
.
type
to
refer
to
the
url
element
on
the
conformance/knowledge
resources
(which
has
the
type
uri
):
<valueSetCanonical value="http://hl7.org/fhir/ValueSet/my-valueset"/><valueSet value="http://hl7.org/fhir/ValueSet/my-valueset"/>
The
canonical
URI
remains
the
same
when
Note
the
resource
is
copied
from
server
exception
to
server,
while
the
logical
id
of
the
resource
-
its
local
identifier
-
usually
changes
as
this
rule:
if
the
target
resource
is
copied.
The
canonical
URI
serves
as
a
stable
logical
identifier
for
the
conformance
artifact,
and
contained
in
another
resource,
which
is
referencing
it,
then
the
preferred
way
to
reference
a
conformance
or
knowledge
resource
.
The
canonical
URI
SHOULD
also
the
location
where
the
master
copy
of
the
artifact
is
found,
though
it
is
not
always
possible
to
arrange
this.
The
canonical
URL
SHALL
NOT
contain
some
other
resource
(though
it
may
resolve
to
is
a
different
version
of
fragment
identifier
referring
to
the
same
resource).
target
resource
by
its
id
(
see
below
).
Canonical
URLs
References
of
type
canonical
may
include
a
version,
in
order
to
be
precise
about
which
version
of
the
resource
is
being
referred
to.
To
do
this,
append
the
version
to
the
canonical
url
reference
with
a
'|'
like
this:
<valueSetCanonical value="http://hl7.org/fhir/ValueSet/my-valueset|0.8"/><valueSet value="http://hl7.org/fhir/ValueSet/my-valueset|0.8"/>
This
Resolving
this
pipe
('|')
syntax
is
a
version
specific
reference
equivalent
to
using
a
value
set.
Note
that
this
refers
to
GET
with
the
version
parameter:
GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/my-valueset&version=0.8
Both
of
these
examples
specify
version
0.8
of
the
value
set,
by
ValueSet.version
(The
canonical
URL
full
format
is
{{CanonicalResource.url}}|{{CanonicalResource.version}}).
Note
that
these
examples
do
not
the
relate
to
ValueSet.meta.versionId
.
Searching
for
this
on
a
FHIR
server
would
look
like
this:
Note that if a canonical URL reference does not have a 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 by automatically detecting the presence of a |[version] and performing the appropriate search. Additional notes about searching on versioned references to canonical URLs:
url
element
of
type
uri
that
acts
as
the
canonical
URL
for
that
resource
(see
list
below)
In
order
to
work
with
Canonical
Resources,
it
is
necessary
to
be
able
to
match
version
strings
from
versioned
references
SHOULD
to
canonical
resources
to
the
resources
themselves.
Among
other
places,
versioned
references
arise
in
the
following
contexts:
If
there
is
no
stated
version
for
the
reference,
or
the
version
is
a
wildcard
(see
below),
and
if
the
reference
is
found
in
a
resource
in
an
NPM
Package
,
then
any
application
looking
for
the
correct
version
SHALL
first
try
look
through
the
package
and
its
dependencies
when
resolving
the
reference.
If
no
matching
version
is
found
in
the
package
or
its
dependencies,
the
application
can
then
look
through
any
other
resources
it
has
available.
This
rule
applies
even
once
the
resource
is
removed
from
the
package.
Systems
could
consider
using
the
package-source
extension
to
track
which
resources
came
from
which
packages
to
support
this.
Some
contexts
of
use
require
that
applications
consult
a
manifest
that
provides
a
default
or
mandatory
version
to
use
for
each
canonical
resource.
In
these
contexts,
the
application
SHALL
use
the
version
specified
in
the
manifest
when
resolving
the
reference.
This
specification
itself
defines
no
such
contexts,
but
implementation
guides
based
on
this
specification
can
detail
how
a
manifest
is
applied
to
any
particular
context
of
us.
Two
examples
of
use
of
manifests
are
the
CRMI
IG,
and
in
the
terminology
ecosystem
,
which
both
use
a
Parameters
resource
for
this
purpose.
Typically,
these
manifests
must
be
consulted
before
looking
through
the
package
dependencies.
Other ways target resources might be made available to applications:
Applications are not required to look through external sources and registries, and production systems typically do not.
If the reference has a version, then matching of version strings depends on the format of the string. The format can be determined either by looking at the versionAlgorithm[x] (if present) or inferred from the provided version.
,
then
semver
wildcard
logic
applies.
Specifically:
2.0
will
not
match
anything
(not
valid
semver,
and
no
wildcard
specified)
2.0.0
matches
2.0.0
and
not
2.0.1
or
2.0.0-something
or
2.0.0+something
2.x.x
matches
2.0.1
and
2.1.0
,
etc.
but
not
2.0.1-something
2.0.*
matches
2.0.0
,
2.0.1
,
and
not
2.0.0-something
or
2.0.0+something
2.0.0-*
matches
2.0.0-prerelease
or
any
other
label
but
not
2.0.0+build
2.0.0+*
matches
2.0.0+build
or
any
other
build
but
not
2.0.0
or
2.0.0-prerelease
2.0.x-x
matches
2.0.1-prerelease
or
2.0.1-prerelease
but
not
2.0.0
or
2.0.1
2.0?
matches
2.0.1
,
2.0.0-build
etc
-
any
valid
semver
that
starts
with
2.0
2.0.1?
matches
2.0.1
,
2.0.1-release
,
2.0.1+build
etc
-
anything
that
starts
with
2.0.1
YYYY
,
YYYYMM
,
YYYY-MM
,
etc.
The
separators
specified
must
match
the
format
of
the
date.
e.g.,
If
the
version
is
2024-01-05
,
then
202401
won't
match,
but
2024-01
will.
On
the
other
hand,
if
the
version
is
20240105
,
then
202401
will
match
and
2024/01
will
not
http://foo.com/bar
would
match
http://foo.com/bar/1
,
but
would
not
match
http://foo.com/bar1
If
the
stated
or
inferred
versionAlgorithm[x]
differs
between
two
different
versions
of
the
same
canonical
resource
(i.e.,
the
url
)
properties
match),
applications
generally
follow
the
fallback
approach,
but
may
choose
some
other
approach.
The following resources have canonical URLs and are allowed to be the target of references to a canonical URLs:
In addition, some types of Additional Resources
A
few
elements
that
have
references
to
canonical
URLs
have
a
targetProfile
of
http://hl7.org/fhir/StructureDefinition/Resource
,
which
is
shown
as
canonical(Any)
in
this
specification.
Such
references
SHALL
only
reference
one
of
these
types
of
resources.
When evaluating a canonical reference, a server may find that it has multiple matching resources. This may arise because:
http://example.org/CodeSystem/abc
http://example.org/CodeSystem/abc|1.2.x
matches
both
versions
1.2.1
and
1.2.3-draft
http://example.org/CodeSystem/abc|1.2.2
and
the
server
had
two
different
resources
for
version
1.2.2
The last case is generally regarded as an error - if the content of the resource changes, the version should too. But in this case the error is likely with the editorial process, not the server handling the content (this specific situation has happened by mistake several times in the FHIR Implementation Guide publishing ecosystem in spite of process safeguards intended to prevent it). But the other two cases are not considered errors; they are how the system is intended to work, and the client is purposefully delegating to the server the task of determining the correct version to use. In general, the correct version to use is the latest version approved for production use. This specification does not define the algorithm for servers to use to determine the latest version (except as noted above with regard to packages). In principle, the server chooses based on the following information from the resources:
Version
practices,
dateTime,
etc.
Canonical
resources
are
not
required
to
use
Semver
,
though
HL7
recommends
using
it,
and
follows
SemVer
for
its
own
content.
However,
other
publishers
of
canonical
resources
follow
other
practices,
and
some
kind
of
date
based
versioning
schemes
are
not
unusual.
Servers
may
have
access
to
additional
information
or
policy
guidance
that
determines
which
resource
to
choose
as
the
default,
and
additional
knowledge
about
how
to
reason
with
the
versioning
scheme
in
use.
Because determining the 'current' version when the algorithm is unknown is problematic, canonical resources SHOULD declare the versionAlgorithm[x] as described above. In the absence of this element, servers MAY choose to guess the algorithm or use their own default logic to determine which resource to return in the event there are multiple candidate instances with the same canonical URL.
Canonical references may include a fragment when the reference is to a contained resource. When the target of a canonical reference is a contained resource, the canonical reference will have a fragment as part of the URL:
<valueSet value="http://fhir.acme.com/Questionnaire/example|1.0#vs1"/>
This is a reference to the value set with id "vs1" in version 1.0 of the identified questionnaire. The common case for this is internal references:
<answerValueSet value="#vs1"/>
Which is the form for references to the contained value set inside the above example questionnaire.
If the type of an element is Reference and there is a need to point to a canonical resource, the 'standard' mechanism for referencing is pointing to a server-specific location the same as any non-canonical resource. Reference.reference MAY be populated by the canonical url for the resource, though this will only function if the canonical URL resolves. Note that this style of referencing cannot convey the 'version' element using the '|' suffix convention. It's also possible to specify a canonical url using Reference.identifier, where the system is 'urn:ietf:rfc:3986' and the value is the url (note that the version can't be conveyed this way either.) Systems that attempt to resolve references via Reference.identifier SHOULD resolve identifiers expressed this way, even if the canonical url is not included in the .identifier list of the canonical resource.
References between resources create a challenge when rendering resource narratives: the narrative includes information from the target resources. As an example, consider an Observation with a patient reference:
{
"resourceType" : "Observation",
"subject" : {
"reference" : "Patient/example"
}
}
When represented in XHTML, this reference will generally become something like:
... <p>Patient: <a href="Patient/example">Peter James CHALMERS (12345)</a></p> ...
This implies that the system generating the resource narrative will need to resolve the reference and generate a summary, or that the reference will contain the information (generated by an application that is able to resolve the reference):
{
"resourceType" : "Observation",
"subject" : {
"reference" : "Patient/example",
"display" : "Peter James CHALMERS (12345)"
}
}
Narrative that contains information derived from other resources like this is still regarded as 'generated' (for Narrative.status ).
It's not mandatory to generate narrative this way. Narrative may be generated like this:
... <p>Patient: <a href="Patient/example">(link)</a></p> ...
However, users generally prefer a more informative narrative, so this is not always acceptable.
Applications (and networks of applications) will need some kind of systematic approach for resolving references and/or maintaining the currency of narratives as the resources they reference are changed. The exact details of this are out of scope for the FHIR standard.
Applications
are
encouraged
to
use
the
Reference.display
element
to
store
a
user
presentable
representation
of
the
resource
for
when
the
resource
cannot
be
resolved
(e.g.,
due
to
network
errors).
The
canonical
type
does
not
have
a
display
element
because
applications
are
generally
expected
to
carry
cached
copies
of
the
resources
that
are
the
target
of
the
canonical
references.
If
this
functionality
is
still
needed
or
desired
anyway,
the
Rendered
Value
extension
can
be
used.
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
V2
message,
and
the
only
information
about
the
primary
surgeon
is
her
first
name
and
last
name
(REL-7.2
&
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. The FHIR version of a contained resource SHALL always be the same as the resource that contains it.
An example of a contained resource:
<Condition xmlns="http://hl7.org/fhir">
<contained>
<Practitioner>
<id value="p1"/>
<name>
<family value="Person"/>
<given value="Patricia"/>
</name>
</Practitioner>
</contained>
<!-- other attributes -->
<asserter>
<reference value="#p1" />
<reference value="#p1" />
</asserter>
<!-- other attributes -->
</Condition>
The same example in JSON:
{
"resourceType" : "Condition",
"contained": [
{
"resourceType" : "Practitioner",
"id" : "p1",
"name" : [{
"family" : "Person",
"given" : ["Patricia"]
}]
}],
"asserter" : {
"reference" : "#p1"
"contained": [{
"resourceType" : "Practitioner",
"id" : "p1",
"name" : [{
"family" : "Person",
"given" : ["Patricia"]
}]
}],
"asserter" : {
"reference" : "#p1"
}
}
DesignImplementation Note: Contained resources are still a reference rather than being inlined directly into the element that is the reference(e.g. "custodian"(e.g., "asserter" 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(/f:reference/@value, '#')]ancestor::f:[not(parent::f:*)]/f:contained/[f:id/@value=substring-after(current()/f:reference/@value, '#')]
Some notes about use and interpretation of contained resources:
contained
element
SHALL
NOT
have
extensions
on
it
(though
contained
resources
can
still
contain
extensions).
Reference
and
canonical
types
may
refer
to
contained
resources
meta.versionId
,
meta.lastUpdated
,
or
meta.security
.
meta.tag
,
though
there
are
many
tags
that
do
not
make
sense
on
contained
resources.
[type]/[id]/_history/[version]#[containedId]
),
but
it's
not
possible
to
refer
to
a
version
of
a
contained
resource
(i.e.,
this
is
invalid:
[type]/[id]#[containedId]/_history/[version]
)
Like other resources, contained resources can contain narrative. However, when rendering the containing resource, the narrative of the contained resources is ignored, so relevant information about contained resources SHALL appear in the narrative of the containing resource.
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, or if the contained resource references the container 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.
For a resource that references the container, the reference is "#", like this:
<Patient xmlns="http://hl7.org/fhir">
<id value="something"/>
<contained>
<Provenance>
<!-- no id necessary (though still allowed) -->
<target>
<reference value="#"/>
</target>
</Provenance>
</contained>
<!-- other attributes -->
</Patient>
Note to Implementers: There is no way to search for contained resources that reference their container. Is this a problem?
Feedback is welcome here
Some references are circular - that is, the reference points to another resource of the same type. There are several reasons why a resource may refer to other resources of the same type:
For
parameters
where
the
relationship
is
a
strict
hierarchy
(i.e.
(i.e.,
where
it
would
be
wrong
to
have
circular
references,
even
transitively),
there
is
additional
search
support
for
traversing
the
hierarchy
using
:above
and
:below
modifiers
on
the
search
parameters.
Hierarchical references with search parameters (can have :above and :below modifiers on search parameters):
References that may refer back to the source instance:
References for which the hierarchical behavior is not specified:
See also Detailed Descriptions , Profiles and Extensions
A common pattern in healthcare records is that a single element may refer to either a concept in principle, or a specific instance of the concept as seen in practice. For instance, a medication may be prescribed because the patient has a headache - e.g., to refer to a headache by a SNOMED CT code for a kind of headache. Alternatively, the record may refer to a specific observation or problem in the problem list as evidence for the patient's headache, which conveys details specific to the patient. This is a particular example of a more general pattern; e.g., it also applies to locations (something happened 'in a hospital', vs something happened in a particular identified hospital).
The
CodeableReference
datatype
represents
this
pattern,
and
may
be
bound
to
a
value
set
to
allow
for
a
conceptual
representation.
In
such
cases,
the
value
set
binding
actually
applies
to
the
concept
element
as
it
usually
would
for
a
CodeableConcept
.
Alternatively,
the
CodeableReference
datatype
can
refer
to
another
resource,
and
the
list
of
valid
target
types
for
the
CodeableReference
resource
applies
to
the
Reference
as
described
above.
In principle, this datatype allows for either a reference or a concept, or both. If both are present, they are expected to be consistent with each other - e.g., the concept is to a code for headache, and the resource reference describes a headache. Note that it is not generally computably provable whether this is true or not.
The
targetProfile
and
binding
constraints
on
the
CodeableReference
apply
to
the
CodeableReference.reference
or
the
CodeableReference.concept
respectively
as
appropriate
and
they
SHALL
NOT
be
specified
directly
on
the
.reference
or
.concept
elements.
This datatype can be constrained in profiles so that only concept or reference are allowed, and profiles can restrict the bound value sets and allowed target resource types.
This datatype is mostly used for reason for an action.
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
|
CodeableReference
| Σ N | Element |
Reference
to
a
resource
or
a
concept
Elements defined in Ancestors: id , extension | |
|
concept
| Σ | 0..1 | CodeableConcept |
Reference
to
a
concept
(by
class)
|
reference
| Σ | 0..1 | Reference () |
Reference
to
a
resource
(by
instance)
|
|
Documentation
for
this
format
| ||||
UML Diagram ( Legend )
XML Template
<CodeableReference xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <concept><!-- 0..1 CodeableConcept Reference to a concept (by class) --></concept> <reference><!-- 0..1 Reference Reference to a resource (by instance) --></reference> </CodeableReference>
JSON Template
{
// from Element: extension
"concept" : { CodeableConcept }, // Reference to a concept (by class)
"reference" : { Reference } // Reference to a resource (by instance)
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: fhir:extension fhir:concept [ CodeableConcept ] ; # 0..1 Reference to a concept (by class) fhir:reference [ Reference ] ; # 0..1 Reference to a resource (by instance) ]
Changes since Release 4
Changes from both R4 and R4B
This complex-type did not exist in Release R4
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
|
CodeableReference
| Σ N | Element |
Reference
to
a
resource
or
a
concept
Elements defined in Ancestors: id , extension | |
|
concept
| Σ | 0..1 | CodeableConcept |
Reference
to
a
concept
(by
class)
|
|
reference
| Σ | 0..1 | Reference () |
Reference
to
a
resource
(by
instance)
|
|
Documentation
for
this
format
| ||||
UML Diagram ( Legend )
XML Template
<CodeableReference xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <concept><!-- 0..1 CodeableConcept Reference to a concept (by class) --></concept> <reference><!-- 0..1 Reference Reference to a resource (by instance) --></reference> </CodeableReference>
JSON Template
{
// from Element: extension
"concept" : { CodeableConcept }, // Reference to a concept (by class)
"reference" : { Reference } // Reference to a resource (by instance)
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> . [ # from Element: fhir:extension fhir:concept [ CodeableConcept ] ; # 0..1 Reference to a concept (by class) fhir:reference [ Reference ] ; # 0..1 Reference to a resource (by instance) ]
Changes from both R4 and R4B
This complex-type did not exist in Release R4
See the Full Difference for further information
Constraints
FHIR
®©
HL7.org
2011+.
FHIR
Mixed
Nomative/Trial
Use
Ballot
(v3.3.0-13671)
R6
hl7.fhir.core#6.0.0-ballot3
generated
on
Tue,
Apr
3,
2018
12:19+1000.
QA
Page
Fri,
Nov
14,
2025
21:00+0000.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
Glossary
|
QA
|
Compare
to
DSTU3
R4
|
Compare
to
R5
|
Compare
to
Last
Ballot
|
|
Propose
a
change