This page explains how the Cloud Healthcare API supportsFHIR resource references.

Overview

FHIR resource references are directional links from a source resource to atarget resource. FHIR resource references can be used to connect resources. Forexample, the FHIR resource typeObservation has asubject field ofReference type, whichcan be used to link to aPatient resource as the subject of the observation.

FHIR resource references can also be circular. For example, the FHIR resourcetypeCarePlan has areplaces field that can point to anotherCarePlan.

The most important element in the FHIR reference structure isreference.The other elements, such asdisplay andidentifier are persisted as they arein the Cloud Healthcare API.

The supported formats ofReference.reference in the Cloud Healthcare APIinclude:

• Local resource reference
• URI beginning withurn:uuid orurn:oid
• Full external URL
• Fragment reference

Local resource reference

Resource references are defined asRESOURCE_TYPE/RESOURCE_ID.The Cloud Healthcare API also supports prepending the full FHIR store namein front ofRESOURCE_TYPE/RESOURCE_ID. Forexample,FHIR_STORE_NAME/RESOURCE_TYPE/RESOURCE_ID.If you use this format, the store name must match the FHIR store of the request.Otherwise, the request is rejected due to non-local references.

The store configuration optionFhirStore.disableReferentialIntegritycontrols the referential integrity check for local reference validation, whichis enabled by default. For more information on the referential integrity check,seeFHIR referential integrity.

Versioned references

Cloud Healthcare API supports references to a specific version of the targetresource. To link to a specific version of the target resource, use the formatafter theRESOURCE_ID/_history/VERSION_ID] inthe local reference.

When the referential integrity check is enabled, the server verifies that thehistorical version exists in the FHIR store. TheResource-purgemethod removes historical versions regardless of whether they are referenced.

Conditional references

As an alternative to explicitly specifying the target resource ID,executeBundleaccepts aconditional reference search query for the target resource that resolves to the target resource ID atrequest time. For example,Patient?identifier=abc.

If the search query does not resolve to a target resource or resolves to morethan one target resource, the server rejects the request regardless of whetherreferential integrity checking is enabled.

URI beginning withurn:uuid orurn:oid

When using theexecuteBundlemethod with a transaction bundle, universally unique identifier (UUID) or objectidentifier(OID) references can be used to resolve references to other resourcesbeing created or updated in the same bundle. For more information, see theManaging FHIR bundles guide.

Full external URL

Full external URLs such ashttp://www.example.com/abc are stored unmodifiedin the reference field. The Cloud Healthcare API does not resolve the URL ortry to verify its validity.

When the full external URL matches the full URL of the FHIR store of therequest, the reference is treated as a local resource reference.

Fragment reference

A fragment reference points to acontained resource inlined in a resource. For example, if an Observation record mentions ageneral practitioner but there is no controlled practitioner directory, a fullPractitioner resource can't be created. The general practitioner is a containedresource in the Observation record. The Reference fields on a resource can pointto the inlined resources using the form of#[INLINE_RESOURCE_ID].

In the following FHIR R4 sample,p1 andp2 are inline resource IDs that arereferenced as#p1 and#p2:

{"resourceType":"Observation","contained":[{"resourceType":"Patient","id":"p1","generalPractitioner":{"reference":"#p2"}},{"resourceType":"Practitioner","id":"p2"}],"status":"final","subject":{"reference":"#p1"},"performer":[{"reference":"#p2"}]}

The[INLINE_RESOURCE_ID] must exist as a contained resource inside theresource, otherwise the server rejects the request. The contained resource canonly be referenced by its container or other contained resources inside the samecontainer.