Referencing FHIR Resources

The method by which other FHIR resources, e.g. Medication or Patient, are referenced within a FHIR resource will be a local implementation decision.

There are three options;

Referenced by URL to a FHIR Server
Referenced by an identifier to a resource within the same FHIR Bundle
Referenced by an identifier to a “contained” resource within the resource

FHIR snippets using XML notation are as follows:

URL to a FHIR server

Using references by URL is the recommended / target solution where FHIR servers are available. These may be future nationally available FHIR servers or locally implemented FHIR servers. When referencing by URL it is recommended that the reference.display is populated with appropriate text as per the guidance within this document.

<MedicationRequest xmlns="http://hl7.org/fhir">
	<subject>
		<reference value="https://acmefhirserver/patient/2245386903"/> 
		<!-- where 2245386903 is the NHS number for Joe Bloggs held as the 'id' -->
		<display value="Joe Bloggs"/>
	</subject>
	<medicationReference>
		<reference value="https://acmefhirserver/medication/87652004"/> 
		<!-- where 87652004 is the dm+d concept code for Atenolol held as the 'id' -->
		<display value="Atenolol"/>
	</medicationReference>
	<!-- other elements of the MedicationRequest resource -->
</MedicationRequest>

This method of referencing other FHIR Resources allows for a truly RESTful implementation with end-points handling individual Resources. This is because the referenced Resources are not included within the transaction either in a Bundle or as Contained Resources. For example;

POST {base}/MedicationRequest

GET {base}/MedicationRequest

Identifier within the Bundle

Where a FHIR server is not available or not used within an implementation, the reference by identifier within the same Bundle is the next recommended implementation option.

<Bundle xmlns="http://hl7.org/fhir">
	<entry>
		<fullUrl value="patient-2245386903"/>
		<resource>
			<Patient>
			<!-- patient details for Joe Bloggs -->
			</Patient>
	 	</resource>
	</entry>
	<entry>
		<fullUrl value="medication-87652004"/>
		<resource>
			<Medication>
			<!-- medication details for Atenolol -->
			</Medication>
		</resource>
	</entry>
	<entry>
		<resource>
			<MedicationRequest>
				<subject>
					<reference value="patient-2245386903"/>
					<display value="Joe Bloggs"/>
				</subject>
				<medicationReference>
					<reference value="medication-87652004"/>
					<display value="Atenolol"/>
				</medicationReference>
				<!-- other elements of the MedicationRequest resource -->
			</MedicationRequest>
		</resource>
	</entry>
</Bundle>

The use of a Bundle means an implementation is using a messaging approach. If a FHIR MessageHeader Resource is included then it becomes an implementation of a FHIR Message.

A typical implementations of a FHIR Messaging end-point would use the $process-message operation, e.g.

POST {base}/$process-message

The definition of each FHIR Message implemented would be defined outside the FHIR standard.

An alternative RESTful implementation would be to POST to a generic Bundle end-point.

POST {base}/Bundle

The definition of which Resources are supported by such an end-point would have to be defined outside the FHIR specification.

Identifier to contained resource

The use of a contained FHIR resource should be the last option considered.

For resources like Patient this could introduce duplication within the complete FHIR payload.

[Resource].text elements should not be populated when using contained resources. When resources are contained inside another resource then all text should be represented in the [Resource].text element, including data from the contained resources. This would make the [Resource].text element a concatination of many strings, likely unreadable and confusing.

<MedicationRequest xmlns="http://hl7.org/fhir">
	<contained>
		<Patient>
			<id value="patient-2245386903"/>
			<!-- patient details for Joe Bloggs -->
		</Patient>
	</contained>
	<contained>
		<Medication>
			<id value="medication-87652004"/>
			<!-- medication details for Atenolol -->
		</Medication>
	</contained>
	<subject>
		<reference value="#patient-2245386903"/>
		<display value="Joe Bloggs"/>
	</subject>
	<medicationReference>
		<reference value="#medication-87652004"/>
		<display value="Atenolol"/>
	</medicationReference>
	<!-- other elements of the MedicationRequest resource -->
</MedicationRequest>

This method of referencing other FHIR Resources still allows for a truly RESTful implementation with end-points handling individual Resources. For example;