NHS Digital FHIR Medicines

Referencing FHIR Resources

The method by which other FHIR resources, e.g. Medication or Patient, can be referenced is done in several ways:

There are three options;

  1. Identifier or CodeableConcept Reference
  2. Resource Reference to a resource within the FHIR Bundle or a remote server
  3. Resource Reference to a “contained” resource within the resource

Identifier and CodeableConcept Reference

Using references by identifier is the preferred option in FHIR Messaging (and EPS). This is focused on using codes from either NHS Data Dictionary or SNOMED CT. It is recommended that the reference.display is populated with appropriate text as per the guidance within this document.

{
    "resourceType": "MedicationRequest",
    "medicationCodeableConcept": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "323465006",
                "display": "Flucloxacillin 500mg capsules"
            }
        ]
    },
    "subject": {
        "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "2245386903"
        },
        "display": "Joe Bloggs"
    }
}

Resource Reference to a resource

FHIR Message Bundles should be self contained and they should not require an external FHIR Server to process the message. In these cases referenced resources should be contained in the Bundle. It is suggested to use UUID references to navigate the resources in the Bundle, mainly to distinguish between resources within the Bundle and externally referenced resources.

{
    "resourceType": "Bundle",
    "entry": [
        {
            "fullUrl": "urn:uuid:5fe0dde7-2cdc-43c1-b346-11dda63b51d2",
            "resource": {
                "resourceType": "Patient",
                "id": "2245386903"
            }
        },
        {
            "fullUrl": "urn:uuid:3e2097b7-3b28-4954-bded-d6af82a10c40",
            "resource": {
                "resourceType": "Medication",
                "id": "87652004",
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "87652004",
                            "display": "Atenolol"
                        }
                    ]
                }
            }
        },
        {
            "resource": {
                "resourceType": "MedicationRequest",
                "medicationReference": {
                    "reference": "urn:uuid:3e2097b7-3b28-4954-bded-d6af82a10c40",
                    "display": "Atenolol"
                },
                "subject": {
                    "reference": "urn:uuid:5fe0dde7-2cdc-43c1-b346-11dda63b51d2",
                    "display": "Joe Bloggs"
                }
            }
        }
    ]
}

Within EPS the preference is to move to identifier references as this provides the key information a consumer requires. This also avoids large messages exchanging a considerable amount of reference data. The exception to this is likely to be the Patient resource which will normally be included in the FHIR Message Bundle.

FHIR RESTful API's may make references to resources held on FHIR Servers.


{
    "resourceType": "MedicationRequest",
    "medicationReference": {
        "reference": "https://fhir.midyorks.nhs.uk/Medication/87652004",
        "display": "Atenolol"
    },
    "subject": {
        "reference": "https://fhir.midyorks.nhs.uk/Patient/2245386903",
        "display": "Joe Bloggs"
    }
}

Not the use of baseUrl / resource / resource.id. Local references, i.e. referencing a resource on the same server, may omit the baseUrl.

{
    "resourceType": "MedicationRequest",
    "medicationReference": {
        "reference": "Medication/87652004",
        "display": "Atenolol"
    },
    "subject": {
        "reference": "Patient/2245386903",
        "display": "Joe Bloggs"
    }
}

Resource reference to contained resource

This SHOULD NOT be used as an alternative to FHIR RESTful API using resources. This should only be used when the resource is not complete, for example only the name of the patient or medication is known. This is not used in EPS.

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

{
    "resourceType": "MedicationRequest",
    "contained": [
        {
            "resourceType": "Patient",
            "id": "1"
        },
        {
            "resourceType": "Medication",
            "id": "2"
        }
    ],
    "medicationReference": {
        "reference": "#2",
        "display": "Atenolol"
    },
    "subject": {
        "reference": "#1",
        "display": "Joe Bloggs"
    }
}

Identifier and Resource References

The two approaches to referencing can be used together. E.g.

An identifier reference such as

{
    "resourceType": "MedicationRequest",
    "subject": {
        "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "2245386903"
        },
        "display": "Joe Bloggs"
    }
}

can be combined with a resource reference


{
    "resourceType": "MedicationRequest",
    "subject": {
        "reference": "https://fhir.midyorks.nhs.uk/Patient/2245386903",
        "display": "Joe Bloggs"
    }
}

Resulting in this example


{
    "resourceType": "MedicationRequest",
    "subject": {
        "reference": "https://fhir.midyorks.nhs.uk/Patient/2245386903",
        "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "2245386903"
        },
        "display": "Joe Bloggs"
    }
}

In this example a receiving system has a choice.

If NHS Number and patient name is sufficient they can process the MedicationRequest without any further API calls or have to resolve the reference within the Bundle.

If they need more Patient details, they can either follow the reference https://fhir.midyorks.nhs.uk/Patient/2245386903, or use the NHS Number to query a local such as PAS/MPI or Patient Demographic Service(PDS).

back to top