FHIR🔥 API Extensions

$diff operation

The $diff operation can be used to determine the difference between two versions of a resource or any two resources of the same type.

The difference return by the operation is in FHIR Patch format.

This implementation is derived from the $diff operation implemented in the HAPI Server (see Diff Operation).

Deleted and missing Resources

In both forms below, a deletion stands for “the Resource did not exist”:

  • deleted from (or no earlier version): a single insert of the whole to Resource
  • deleted to: a single delete of the whole from Resource
  • both deleted: an empty patch

A Resource or version that never existed is an error (HTTP 404).

Diff on a Resource instance

Optional Parameters

  1. fromVersion=[version] – see below for details
  2. includeMeta=(true|false) – defaults to false and determines whether the Resources' meta elements are included in the difference or not.

Diff with default version

GET /[type]/[id]/$diff

Determines the changes from version m to version n, where n is the latest version of the Resource and m is the nearest existing version numerically below n. If there is no such version, or m is a deletion, the result is a single insert of the whole Resource.

GET /[type]/[id]/$diff?fromVersion=[version]

Determines the changes from version version to version n, where n is the latest version of the Resource. If version is a deletion, the result is a single insert of the whole Resource.

Diff with specific version

GET /[type]/[id]/_history/[version]/$diff

Determines the changes from version n to version version, where n is the nearest existing version of the Resource numerically below version. If there is no such version (i.e., version is the earliest), or n is a deletion, the result is a single insert of the whole Resource.

GET /[type]/[id]/_history/[version]/$diff?fromVersion=[fromVersion]

Determines the changes from version fromVersion to version version. If fromVersion is a deletion, the result is a single insert of the whole Resource.

Diff any two Resource instances of the same type

Required Parameters

  1. from=[id]
  2. to=[id]

The ids may be versioned or not. That is of either form:

  • [type]/[id]
  • [type]/[id]/_history/[version]

Optional Parameters

  1. includeMeta=(true|false) – defaults to false and determines whether the Resources' meta elements are included in the difference or not.

from and to must be the same Resource type (otherwise HTTP 400). Deleted and missing Resources are handled as described above.

GET /$diff?from=[type]/[id1]&to=[type]/[id2]

GET /$diff?from=[type]/[id1]&to=[type]/[id2]/_history/1

Result

The output is in FHIRPatch format. This is a Parameters Resource where each Parameter represents one of several FHIRPatch operations. Currently these include:

  • add
  • insert
  • delete
  • replace

Example result

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "operation",
    "part": [{
     "name": "type",
      "valueCode": "replace"
    }, {
      "name": "path",
      "valueString": "CodeSystem.concept[6].display"
    }, {
      "name": "previousValue",
      "valueString": "nonsmoker"
    }, {
      "name": "value",
      "valueString": "non-smoker"
    }]
  }]
}