Foundation
This
page
is
part
of
the
FHIR
Specification
(v5.0.0:
R5
-
STU
v6.0.0-ballot4:
Release
6
Ballot
(1st
Full
Ballot)
(see
Ballot
Notes
).
This
is
the
The
current
published
version
in
it's
permanent
home
(it
will
always
be
available
at
this
URL).
is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
for
published
versions
.
Page
versions:
R5
R4B
R4
R3
R2
|
Responsible
Owner:
FHIR
Infrastructure
Work
Group
|
Standards Status : Normative |
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 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 and by providing support for reverse includes ).
Because
resources
are
processed
independently,
relationships
are
not
considered
to
be
transitive.
For
example,
if
a
Procedure
resource
references
a
Patient
as
its
subject,
and
has
a
Condition
resource
as
its
reason,
there
is
no
automatic
rule
or
implication
that
the
condition
has
the
same
patient
for
its
subject.
Instead,
the
subject
of
the
condition
must
be
established
directly
in
the
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
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.
Profiles
and/or
implementation
guides
may
make
rules
about
this
(also
see
GraphDefinition
).
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 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.
See
also
Detailed
Descriptions
,
Profiles
,
Extensions
and
R4
Conversions
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
contain
a
target
type
.
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
Reference
|
Σ N | 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
|
Σ C | 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
Binding: Resource Types ( Extensible ) |
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
<Reference xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <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
"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:# from Element: fhir:extension fhir:l [ IRI
Changes
since
Release
3
from
R5
to
R6
| Reference |
|
Changes
from
both
R4
and
R4B
to
R6
| Reference | |
| Reference.type |
|
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type |
Description
&
Constraints
Filter:
|
|---|---|---|---|---|
|
Reference
|
Σ N | 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
|
Σ C | 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
Binding: Resource Types ( Extensible ) |
|
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
<Reference xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <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
"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:# from Element: fhir:extension fhir:l [ IRI
Changes
since
Release
3
from
R5
to
R6
| Reference |
|
Changes
from
both
R4
and
R4B
to
R6
| Reference | |
| Reference.type |
|
See the Full Difference for further information
Constraints
| id | Level | Location | Description | Expression |
ref-1
|
Rule | (base) | SHALL have a contained resource if a local reference is provided | reference.exists() implies (reference.startsWith('#').not() or (reference.substring(1).trace('url') in %rootResource.contained.id.trace('ids')) or (reference='#' and %rootResource!=%resource)) |
|
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
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,
specifying
the
type
is
almost
always
duplication
of
information.
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|ActorDefinition|AdministrableProductDefinition|AdverseEvent|AllergyIntolerance|Appointment|AppointmentResponse|ArtifactAssessment|AuditEvent|Basic|Binary|BiologicallyDerivedProduct|BiologicallyDerivedProductDispense|BodyStructure|Bundle|CapabilityStatement|CarePlan|CareTeam|ChargeItem|ChargeItemDefinition|Citation|Claim|ClaimResponse|ClinicalImpression|ClinicalUseDefinition|CodeSystem|Communication|CommunicationRequest|CompartmentDefinition|Composition|ConceptMap|Condition|ConditionDefinition|Consent|Contract|Coverage|CoverageEligibilityRequest|CoverageEligibilityResponse|DetectedIssue|Device|DeviceAssociation|DeviceDefinition|DeviceDispense|DeviceMetric|DeviceRequest|DeviceUsage|DiagnosticReport|DocumentReference|Encounter|EncounterHistory|Endpoint|EnrollmentRequest|EnrollmentResponse|EpisodeOfCare|EventDefinition|Evidence|EvidenceReport|EvidenceVariable|ExampleScenario|ExplanationOfBenefit|FamilyMemberHistory|Flag|FormularyItem|GenomicStudy|Goal|GraphDefinition|Group|GuidanceResponse|HealthcareService|ImagingSelection|ImagingStudy|Immunization|ImmunizationEvaluation|ImmunizationRecommendation|ImplementationGuide|Ingredient|InsurancePlan|InventoryItem|InventoryReport|Invoice|Library|Linkage|List|Location|ManufacturedItemDefinition|Measure|MeasureReport|Medication|MedicationAdministration|MedicationDispense|MedicationKnowledge|MedicationRequest|MedicationStatement|MedicinalProductDefinition|MessageDefinition|MessageHeader|MolecularSequence|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|SubstanceNucleicAcid|SubstancePolymer|SubstanceProtein|SubstanceReferenceInformation|SubstanceSourceMaterial|SupplyDelivery|SupplyRequest|Task|TerminologyCapabilities|TestPlan|TestReport|TestScript|Transport|ValueSet|VerificationResult|VisionPrescription)\/[A-Za-z0-9\-\.]{1,64}(\/_history\/[A-Za-z0-9\-\.]{1,64})?(#[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|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
subject
on
a
FHIR
RESTful
server:
<subject>
<reference value="Patient/034AB16" />
</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
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 can be version specific - that is, a reference may point to a specific version of a resource. 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 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, 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 logical and literal 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; 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 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 URL that always identifies the resource across all contexts of use. Typically, terminology , conformance or knowledge resources have canonical URLs. The canonical URL is the preferred way to reference a resource instance for the resource types on which it is defined. See Canonical Resource Identity for further information.
References
to
canonical
URLs
use
the
canonical
type
to
refer
to
the
url
element
on
the
conformance/knowledge
resources
(which
has
the
type
uri
):
<valueSet value="http://hl7.org/fhir/ValueSet/my-valueset"/>
Note
the
exception
to
this
rule:
if
the
target
resource
is
contained
in
another
resource,
which
is
referencing
it,
then
the
canonical
URL
is
a
fragment
identifier
referring
to
the
target
resource
by
its
id
(
see
below
).
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
reference
with
a
'|'
like
this:
<valueSet value="http://hl7.org/fhir/ValueSet/my-valueset|0.8"/>
Resolving this pipe ('|') syntax is equivalent to using a 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
relate
to
ValueSet.meta.versionId
.
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
In order to work with Canonical Resources, it is necessary to be able to match version strings from versioned references to canonical resources to the resources themselves. Among other places, versioned references arise in the following contexts:
Systems
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
look
through
the
package
and
its
dependencies
when
resolving
references
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
URLs
SHOULD
first
try
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
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.
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
unsual.
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]
element
to
instruct
servers
on
what
altorithm
to
use
for
comparison.
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.
(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
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"
}
}
Implementation Note: Contained resources are still a reference rather than being inlined directly into the element that is the reference
(e.g.(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/[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
[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
,
Extensions
and
R4
Conversions
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.
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.
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.
e.g.,
the
concept
is
to
a
code
for
headache,
and
the
resource
reference
describes
a
headache.
Note
that
it
is
not
generally
computably
proveable
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.
When
we
have
experience
with
implementation
practice,
we
will
evaluate
changing
the
SHOULD
NOT
to
a
SHALL
NOT.
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
|
Σ
|
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:# 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
3
from
R5
to
R6
| CodeableReference |
|
Changes
from
both
R4
and
R4B
to
R6
| CodeableReference |
|
Changes from R4 to R6
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
|
Σ
|
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
|
||||
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:# 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
3
from
R5
to
R6
| CodeableReference |
|
Changes
from
both
R4
and
R4B
to
R6
| CodeableReference |
|
Changes from R4 to R6
This complex-type did not exist in Release R4
See the Full Difference for further information
Constraints
FHIR
®©
HL7.org
2011+.
FHIR
R5
hl7.fhir.core#5.0.0
R6
hl7.fhir.core#6.0.0-ballot4
generated
on
Sun,
Mar
26,
2023
15:26+1100.
Thu,
Dec
18,
2025
07:15+1100.
Links:
Search
|
Version
History
|
Contents
|
Glossary
|
QA
|
Compare
to
R4
|
Compare
to
R4B
R5
|
Compare
to
Last
Ballot
|
|
Propose
a
change