Referencing and Identifiers

References

Resources in Bundles SHOULD NOT use contained resources.

References to other resources in the Bundle SHOULD use the fullUrl uuid. The central broker will replace a urn:uuid with its own ID on create, these will be returned to clients in responses.

"reference": "urn:uuid:66c519dd-423f-4238-89c8-91c5be52f330"

References to other resources not included in the Bundle SHOULD use the path for the resource, including the uuid, if this can be found on the GMS central broker.

This pattern is expected where requests use resources that are shared, such as referencing already existing PractitionerRole resources within Germline Late requests etc. To populate the references, it is expected clients will be required to query the central broker to determine existence of the resource, e.g. by querying for a known identifier, and populate the reference with the returned ID (omitting the referenced resource from the transaction). If the resource is not found, it is expected that the client would create the necessary resource. As at the time of publication, the ifNoneExists parameter (conditional create) will not be supported in the Order Management Private Beta.

"reference": "Specimen/840d075e-0480-4134-ae51-27f572731cc8"

If the resource is hosted on another NHS service, for example patient records on PDS, these should be referenced by identifier using the appropriate system for the identifier, e.g.

For references to Patient resources, reference.identifier SHALL always be provided, even if the resource can be referenced by ID. In this case, the identifier reference is added alongside the resource ID.

"reference": {
  "identifier": {
    "system": "https://fhir.nhs.uk/Id/nhs-number",
    "value": "9999999999"
  }
}

If a resource is contained on another system, outside NHS central services, this SHOULD be referenced with an absolute url. The URL SHALL be resolvable (though these links will not be validated/followed by the central broker) and preferably return a FHIR resource of the appropriate type e.g.

"reference": "https://www.christie.nhs.uk/ehr/LabOrder123456"

Specific instances where each of the above reference types are allowed are defined within the Profiles pages. NOTE: The central broker will not be supporting references by identifier only where the resource exists on the server. In this case, the client SHOULD retrieve the resource via a search on identifier to obtain the logical ID for any resource level interactions.

All profiles within transaction bundles should reference each other i.e. none should be orphaned.

Any additional resources not linked from another resource in a transaction bundle SHALL be excluded, or sent in a separate transaction. The expected list of resources and cardinalities in a typical test order or report transaction are detailed in GraphDefinitions.

It is expected the central broker will check and maintain referential integrity, where these references point to resources stored on the central broker. If a request fails this check, the transaction will fail with the appropriate HTTP error code, e.g. 422. The response will be a 'transaction-response' bundle, including an OperationOutcome FHIR resource for each resource submitted in the transaction Bundle with diagnostics for each. Resources passing validation will return 200 but will not result in resources being created on the server if the transaction contains an error (the transaction will be rejected as a whole).

Identifiers

Identifier Systems

For critical identifiers, the identifier.system SHALL be provided by client systems, this includes systems such as:

• Patient NHS Number
• Organization ODS Code
• Practitioner national identifier, e.g. SDS User ID/GMC Number
• Specimen Lab Sample ID

System URIs for Patients, Organisations and Practitioners are defined within the UK Core NamingSystems IG. There is no national naming scheme for Specimen identifiers though the order management central broker will assign a Genomics-Specimen-Number as an alias to the record. Local identifiers SHALL follow the guidance provided below.

Note on Local Identifiers

Where local identifiers are used, clients SHALL add the identifer.assigner element and populate this with the ODS code for the organisation which set the identifier, or owns the identifier naming scheme. This is to ensure uniqueness and prevent business identifier collision when the same system is used across multiple organisations.

"identifier": {
  "system": "urn:oid:2.16.840.1.113883.2.1.3.2.4.18.24",
  "value": "FoetusA",
  "assigner": {
    "identifier": {
      "system": "https://fhir.nhs.uk/Id/ods-organization-code",
      "value": "RAX"
    }
  }
}

In the case where a local identifier is used, it is preferable that the system URI used is owned and known by the organisation submitting the local identifier, e.g. https://genomicsengland.co.uk/ngis/referral_human_readable_id. In the case where this is now known, or cannot be used, the relevant HL7 UK OID MAY be used, e.g.

Conditional Creates/Updates

While not supported for the alpha or private beta, it is expected the central broker will support conditional create or update operations (as defined in transaction request objects). This will allow clients to only create resources, such as Patient/PractitionerRole, where no resource containing their identifier already exists. Responses where conditional criteria are not satisfied are still under discussion as of the time of publication.

Resource Reference (Duo/Trio Tests)

When the test type is Duo or Trio there will usually be specimens from more than one patient that may need to be processed in parallel. Each Task resource related to processing of a Specimen will reference the relevant Specimen resource for within the “input” element, as well as referencing the Patient the Task is for. Each specimen will reference the patient it relates to using the “subject” element.