NHS England FHIR Implementation Guide (deprecated)

Important Announcement regarding this Implementation Guide
  • As of 04/10/2023, this implementation guide has been deprecated and all development on the legacy NHS England FHIR Implementation Guide assets has ceased.
  • Therefore, vendors looking to start new implementations or looking to update existing implementations should use the new NHS England Implementation Guide. Vendors continuing to implement legacy NHS England FHIR Implementation Guide based solutions do so at their own risk and on the understanding that no maintenance or support will be available.

FHIR Validation

FHIR Validation SHOULD be used with this implementation guide.

This IG and FHIR Validation currently tests the following:

Aspect Verified Description Notes
Structure ✅ Check that all the content in the resource is described by the specification, and nothing extra is present XML, JSON and RDF
Cardinality ✅ Check that the cardinality of all properties is correct (min & max)
Value Domains ✅ Check that the values of all properties conform to the rules for the specified types (including checking that enumerated codes are valid)
Coding/CodeableConcept bindings ✅ Check that codes/displays provided in the Coding/CodeableConcept types are valid This requires a UK Terminology Server and currently it is not possible to use this directly with FHIR Validation tools.
Is supported in NHS Digital validation-service-fhir-r4
Invariants ✅ Check that the invariants (co-occurrence rules, etc.) have been followed correctly
Profiles ✅ Check that any rules in profiles have been followed (including those listed in the Resource.meta.profile, or in CapabilityStatement, or in an ImplementationGuide, or otherwise required by context)
Questionnaires ✅ Check that a QuestionnaireResponse is valid against its matching Questionnaire
Message Definitions ✅ Check that a Bundle (type=message) is valid against its matching MessageDefinition Not supported in HL7 Validation tools but is supported in NHS Digital validation-service-fhir-r4
Operation Definitions ✘ Support for FHIR Operations Not currently supported.
Business Rules ✘ Business rules are made outside the specification, such as checking for duplicates, checking that references resolve, checking that a user is authorized to do what they want to do, etc. Business rules are beyond the scope of the FHIR Implementation Guide.

HL7 FHIR Validator

When using the FHIR Validator, the general format will be:

java -jar validator_cli.jar [filename] -version 4.0.1 -ig [nhs-digital-ig-package] -profile [profile]

Where

  • filename is the file name of the resource being validated.
  • nhs-digital-ig-package is the url of the NHS Digital IG Package which can be found in the Downloads section
  • profile the URI of the profile to validate against.

e.g.

To validate a patient example against NHS Digital IG profile NHSDigital-Patient

java -jar validator_cli.jar patient-ex.xml -version 4.0.1 -ig uk.nhsdigital.r4 -profile https://fhir.nhs.uk/StructureDefinition/NHSDigital-Patient

To validate a patient example against UKCore IG profile UKCore-Patient

  • using UKCore IG

java -jar validator_cli.jar patient-ex.xml -version 4.0.1 -ig fhir.r4.ukcore.stu1 -profile https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient

Online HL7 FHIR Validation

https://validator.fhir.org/ provides an online method of validating FHIR.

Note: Validation will be performed against base FHIR and international FHIR, UK SNOMED and UK Implementation Guides are configured under Options. The profile is currently specified by adding a meta.profile to the resource. E.g.

{
    "resourceType": "Task",
    "id": "dea023fc-b6ef-4419-b98f-9f209fd25ed4",
    "meta" : {
        "profile" : [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-Task"
        ]
    },

Asking a FHIR Server

See Operation $validate for details.

NHS Digital has implemented this operation as a service and is available on GitHub validation-service-fhir-r4. This project has two branches:

  • main2 which is used CI/CD to validate FHIR Implementation Guides.
  • master which is used currently by Electronic Prescription Service (EPS) to validate incoming FHIR resources.

This is built on top of the HL7 Validator code base and extends this to cover:

  • FHIR Message validation using FHIR MessageDefinition
  • UK Terminology validation using OAuth2 authorisation support

Profiling Approach

NHS Digital Profiles

NHS Digital profiles build on UKCore profiles. They extend the UK definitions by adding England and NHS Digital data models, documentation and constraints. From a FHIR perspective they will have a baseDefinition which will be a UK Core profile.

Diagram below shows the NHS Digital focused additional documentation:

The scope of these profiles is NHS Digital API's and they will have a definition of

https://fhir.nhs.uk/StructureDefinition/NHSDigital-{resourceName}

e.g.

https://fhir.nhs.uk/StructureDefinition/NHSDigital-PractitionerRole

profile constraints

NHS Digital profiles make use of FHIRPath based constraints.

The diagram below shows expressions on NHSDigital-PractitionerRole.practitioner which enforce/test consistency with the NHS Data Dictionary


Note: a more human readable version of these practitioner constraints is available in https://fhir.nhs.uk/StructureDefinition/NHSDigital-Practitioner in the identifier section.


NHS Digital Constraint Profiles

In addition we have constraint profiles which will add API specific constraints to NHS Digital (or UKCore) profiles. They will be of the format:

https://fhir.nhs.uk/StructureDefinition/NHSDigital-{resourceName}-{constraintName}

e.g.

https://fhir.nhs.uk/StructureDefinition/NHSDigital-PractitionerRole-Minimal

This profile has a baseDefinition of https://fhir.nhs.uk/StructureDefinition/NHSDigital-PractitionerRole and adds in mandatory constraints to practitioner plus organization.



Profiles and Implementation Guides

When validating against a NHS Digital IG, the NHS Digital IG package should be used. This can be found in the Downloads section. This package will include the corresponding UKCore package automatically.

Profiles

The UKCore profiles are the default profiles for UK FHIR Validation. For Administration resources such as Patient, Organization, Practitioner, PractitionerRole, etc, NHSDigital profiles should be used instead. These profiles are derivatives of UKCore which contain additional English NHS rules and constraints.

Example Using HL7 Validation using UKCore profile

The local file medicationrequest.json is validated against UKCore-MedicationRequest

java -jar validator_cli.jar medicationrequest.json -version 4.0.1 -tx n/a -ig uk.nhsdigital.r4 -profile https://fhir.hl7.org.uk/StructureDefinition/UKCore-MedicationRequest

Note: the uk.nhsdigital.r4 is used for validation as it contains UKCore.

Example Using HL7 Validation using NHSDigital profile

The local file practitioner.json is validated against NHSDigital-Practitioner

java -jar validator_cli.jar practitioner.json -version 4.0.1 -tx n/a -ig uk.nhsdigital.r4 -profile https://fhir.nhs.uk/StructureDefinition/NHSDigital-Practitioner

To validate against UKCore-Practitioner this becomes:

java -jar validator_cli.jar practitioner.json -version 4.0.1 -tx n/a -ig uk.nhsdigital.r4 -profile https://fhir.hl7.org.uk/StructureDefinition/UKCore-Practitioner


UK SNOMED CT and dm+d

It is not currently possible to validate UK terminology using HL7 Validation. The HL7 Validator will by default validate against international SNOMED CT. This validation can be disabled by via the -tx n/a parameter.

It is recommended to directly use the NHS Digital Terminology Server to validate UK SNOMED and dm+d coding. This is FHIR R4 terminology server which contains UK SNOMED and dm+d CodeSystem. It supports terminology operations such as $validate-code which allows a SNOMED CT code to be checked against a `FHIR (SNOMED) ValueSet.


FHIR Message

FHIR Messaging is a defined collection of resources in a FHIR Bundle. The definition of the message is contained within a FHIR MessageDefinition, E.g. prescription-order.

It is not currently possible to validate against a MessageDefinition in the HL7 Validator.

The recommended approach with the HL7 Validator is to validate the bundle using the -bundle parameter with the profile specified in the MessageDefintion.focus).

Example EPS

The prescription-order MessageDefinition, specifies MedicationRequest should conform to https://fhir.nhs.uk/StructureDefinition/NHSDigital-MedicationRequest-Message.

Screenshot 2022-08-01 at 06.17.01

A prescription-order can be tested with the following command:

java -jar validator_cli.jar prescription.json -version 4.0.1 -tx n/a -ig uk.nhsdigital.r4 -bundle MedicationRequest:0 https://fhir.nhs.uk/StructureDefinition/NHSDigital-MedicationRequest-Message

The -bundle parameter says, test the first occurence of MedicatioRequest against the specified profile.

Example BARS

The bars-message-servicerequest-request-referral main focus resource is ServiceRequest with a profile of https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-referral

An example validation command is:

java -jar validator_cli.jar message.json -version 4.0.1 -tx n/a -ig https://packages.simplifier.net/uk.nhsdigital.r4.test/-/uk.nhsdigital.r4.test-2.6.32-prerelease.tgz -bundle ServiceRequest:0 https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-referral

The ig used is the NHSDigital development version and so the download url is specified, once this version is released this can be replaced with the normal 'uk.nhsdigital.r4' ig.

The -bundle parameter says, test the first occurrence of ServiceRequest against the BARS referral profile.

Message Conformance Profiles

EPS uses message specific profiles, i.e., it uses NHSDigital-MedicationRequest-Message which has additional rules to the normal NHSDigital-MedicationRequest (and also UKCore-MedicationRequest).

Screenshot 2022-08-01 at 06.25.39

These rules will automatically be applied by the FHIR Validator. So, although no Patient profiles were specified in the FHIR MessageDefinition, the Patient resource in the FHIR Bundle MUST contain a nhs-number as required by the NHSDigital-Patient-PDS profile.


contained Resources

Contained resources are not intended to be complete or have independent existence https://www.hl7.org/fhir/references.html#contained.

As a result of this HL7 FHIR Validation may not work as intended. However, schema/structure validation will be performed and if profiled, they will be validated but the results can be difficult to interpret.

The recommendation is to validate each contained resource individually first and then validate the parent resource. E.g. If a MedicationRequest contains a Patient resource, validate the Patient resource and resolve issues and then validate the MedicationRequest resource with the contained Patient resource.

back to top