Skip to content

Bundles & References

Referencing FHIR resources when POSTing Bundles

Some FHIR resources may contain references to other resources. For example, MedicationRequest.subject is a reference to a Patient or Group. References are expressed using at least one of the following:

  • Reference.reference: literal reference (full url or resourceType/resource_id)
  • Reference.identifier: queries for a resource with a matching identifier
  • Reference.display: text description of the target (unlikely to be resolvable)

When a reference is being made to an existing resource, the behaviour is typically straightforward. However, given users will not have the ability to specify ids upon creation, there are restrictions on how references can be made within a bundle when referencing a resource created in the bundle. Currently, only posting a transaction bundle will resolve resource references.

Posting Transaction Bundles

To reference a resource in the same bundle, the target resource must come before the source resource (resource doing the referencing) in the bundle. Note: this goes against spec at the moment which says resources can be in any order within the transaction. We are working to fix it.

Reference.reference

The target resource’s bundle entry must have a url which matches resource.id, and the source resource will reference reference.reference: <target_resource_entry.url>.

The urls here are used only to resolve the references. When the resource is created, bend will assign it a new id.

Example:

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:2e27c71e-30c8-4ceb-8c1c-5641e066c0a4",
      "request": {
        "method": "POST",
        "url": "Patient"
      },
      "resource": {
        "resourceType": "Patient"
      }
    },
    {
      "fullUrl": "urn:uuid:c9dc7d7e-f83e-4c38-8193-2ad42364d620",
      "request": {
        "method": "POST",
        "url": "Encounter"
      },
      "resource": {
        "resourceType": "Encounter",
        "subject": {
          "reference": "urn:uuid:2e27c71e-30c8-4ceb-8c1c-5641e066c0a4"
        }
      }
    }
  ]
}

Reference.identifier

References by identifier also works in a transaction since identifiers can be specified.

Example:

"medicationReference": {
  "identifier": {
    "use": "official",
    "system": "https://raylytic.com/fhir/identifiers/Medication",
    "value": "ATORVASTATIN 20 MG TABLET"
  }
}

Posting Batch Bundles

There is currently no way to resolve references when posting a batch bundle, if the target resource is being created in the same bundle.

reference.identifier: <resourceType>/<resourceId> will allow the batch to post successfully, but the references will not be resolvable since resourceIds are reassigned.

reference: <uuid:urn:….<full-url>> would fail at creation of target resources.