R4 Ballot #1 (Mixed Normative/Trial use)
FoundationThis 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 of available versions, see the Directory of published versions 
. Page versions: R5 R4B R4 R3 R2
| FHIR Infrastructure Work Group | Maturity Level: 5 | Ballot Status: Normative |
Normative Candidate Note: This page is candidate normative content for R4 in the Infrastructure Package. Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.
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 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 Condition 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 or must have 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, and profiles and/or implementation guides may make rules about this (and see GraphDefinition).
Resolving the references is discussed below.
Resources contain two types of references to other resources:
For canonical references, see below. The general references are handled by the Reference type.
which 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 |
|---|---|---|---|---|
  Reference | ΣIN | Element | A reference from one resource to another + SHALL have a contained resource if a local reference is provided Elements defined in Ancestors: id, extension | |
  reference | ΣI | 0..1 | string | Literal reference, Relative, internal or absolute URL |
| type | Σ | 0..1 | uri | Type the reference refers to (e.g. "Patient") ResourceType (Extensible) |
 identifier | Σ | 0..1 | Identifier | Logical reference, when literal reference is not known |
 display | Σ | 0..1 | string | Text alternative for the resource |
| Documentation for this format | ||||
UML Diagram (Legend)
XML Template
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <reference value="[string]"/><!--0..1 Literal reference, Relative, internal or absolute URL --> <type value="[uri]"/><!-- 0..1 Type the reference refers to (e.g. "Patient") --> <identifier><!-- 0..1 Identifier Logical reference, when literal reference is not known --></identifier> <display value="[string]"/><!-- 0..1 Text alternative for the resource --> </[name]>
JSON Template
{
// from Element: extension
"reference" : "<string>", // C? Literal reference, Relative, internal or absolute URL
"type" : "<uri>", // Type the reference refers to (e.g. "Patient")
"identifier" : { Identifier }, // Logical reference, when literal reference is not known
"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 Literal reference, Relative, internal or absolute URL fhir:Reference.type [ uri ]; # 0..1 Type the reference refers to (e.g. "Patient") fhir:Reference.identifier [ Identifier ]; # 0..1 Logical reference, when literal reference is not known fhir:Reference.display [ string ]; # 0..1 Text alternative for the resource ]
Changes since DSTU2
| Reference | |
| Reference.type |
|
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
| Reference | ΣIN | Element | A reference from one resource to another + SHALL have a contained resource if a local reference is provided Elements defined in Ancestors: id, extension | |
| reference | ΣI | 0..1 | string | Literal reference, Relative, internal or absolute URL |
| type | Σ | 0..1 | uri | Type the reference refers to (e.g. "Patient") ResourceType (Extensible) |
| identifier | Σ | 0..1 | Identifier | Logical reference, when literal reference is not known |
| display | Σ | 0..1 | string | Text alternative for the resource |
| Documentation for this format | ||||
XML Template
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <reference value="[string]"/><!--
JSON Template
{
// from Element: extension
"reference" : "<string>", // C? Literal reference, Relative, internal or absolute URL
"type" : "<uri>", // Type the reference refers to (e.g. "Patient")
"identifier" : { Identifier }, // Logical reference, when literal reference is not known
"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 Literal reference, Relative, internal or absolute URL fhir:Reference.type [ uri ]; # 0..1 Type the reference refers to (e.g. "Patient") fhir:Reference.identifier [ Identifier ]; # 0..1 Logical reference, when literal reference is not known fhir:Reference.display [ string ]; # 0..1 Text alternative for the resource ]
Changes since DSTU2
| 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).
: reference.startsWith('#').not() or (reference.substring(1).trace('url') in %resource.contained.id.trace('ids')))
In resources, a Reference always point 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, it is often not necessary to know the type of the target resource is, unless it's going to be resolved anyway, so in many cases, specifying the type of the target resource is unnecessary.
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, the
value is simply a code that is the type of resource - 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})?
A relative reference to the Patient "034AB16" in an element named context on a FHIR RESTful server:
<patient>
<reference value="Patient/034AB16" />
</patient>
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 in a bundle during a transaction, reference URLs may actually contain logical URIs (e.g. OIDs it 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 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>
This is usually associated with audit trail or provenance information where it is important to reference a particular 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. 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. Servers may accept an identifier based reference untouched, resolve it, and/or reject it - see CapabilityStatement.rest.resource.referencePolicy.
When both an identifier and a literal reference 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 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.
Many resource types have a defined element "url" which is the canonical URI that always identifies the
resource. These include all the terminology, conformance and knowledge resources (most of the resources
not found in the Patient Compartment). Note that the
element actually contains a URI, but is named url for legacy reasons.
Canonical references use the canonical.
<valueSetCanonical value="http://hl7.org/fhir/ValueSet/my-valueset"/>
The canonical URI remains the same when the resource is copied from server to server, while the logical id of the resource - its local identifier - usually changes as the resource is copied. The canonical URI serves as a stable logical identifier for the conformance artifact, and is 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 a different version of the same resource).
Canonical URLs may include a version, in order be precise about which version of the resource is being referred to. To do this, append the version to the canonical url with a '|' like this:
<valueSetCanonical value="http://hl7.org/fhir/ValueSet/my-valueset|0.8"/>
This is a version specific reference to a value set. Note that this refers to the ValueSet.version
not the ValueSet.meta.versionId. Searching for this on a FHIR server would look like this:
GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/my-valueset&version=0.8
Note that if a canonical 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.
Systems resolving canonical references SHOULD first try to resolve the reference using the canonical URL (e.g. search on a known registry of terminology, conformance, or knowledge resources as appropriate), and then fall back to direct resolution using the URL as a literal reference if a local version of the canonical resource cannot be found. This approach is safe because the approaches must refer to the same artifact, though implementations will need to make appropriate arrangements regarding the version and/or 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 & 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.
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" />
</asserter>
<!-- other attributes -->
</Condition>
The same example in JSON:
{
"resourceType" : "Condition",
"contained": [
{
"resourceType" : "Practitioner",
"id" : "p1",
"name" : [{
"family" : "Person",
"given" : ["Patricia"]
}]
}],
"asserter" : {
"reference" : "#p1"
}
}
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:
contained element SHALL NOT have extensions on it (though contained resources can still contain extensions).Reference and canonical types may refer to contained resourcesResources 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>
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. 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:
®© HL7.org 2011+. FHIR Mixed Nomative/Trial Use Ballot (v3.3.0-13671) generated on Tue, Apr 3, 2018 12:19+1000. QA Page
Links: Search |
Version History |
Table of Contents |
Credits |
Compare to DSTU3 |
|
Propose a change