# Diff Operation

The `$diff` operation can be used to generate a differential between two versions of a resource, or even two different resources of the same type.

Differentials generated by this operation are in [FHIR Patch](https://www.hl7.org/fhir/fhirpatch.html) format.

In generated differentials, where a value has changed (i.e. a **replace** operation), an additional part value will be present on the given operation called `previousValue`. This part shows the value as it was in the *from* version of the resource. 

# Diff Instance

When the $diff operation is invoked at the instance level (meaning it is invoked on a specific resource ID), it will compare two versions of the given resource.

## Parameters

* `[[${T(ca.uhn.fhir.rest.server.provider.ProviderConstants).DIFF_FROM_VERSION_PARAMETER}]]=[versionId]`: (*optional*) If specified, compare using this version as the source. If not specified, the immediately previous version will be compared.
* `[[${T(ca.uhn.fhir.rest.server.provider.ProviderConstants).DIFF_INCLUDE_META_PARAMETER}]]=true`: (*optional*) If specified, changes to Resource.meta will be included in the diff. This element is omitted by default.  

To invoke:

```http
GET http://fhir.example.com/baseR4/Patient/123/$diff
```

The server will produce a response resembling the following:

```json
{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "operation",
    "part": [ {
      "name": "type",
      "valueCode": "replace"
    }, {
      "name": "path",
      "valueString": "Patient.name.family"
    }, {
      "name": "previousValue",
      "valueId": "Smyth"
    }, {
      "name": "value",
      "valueId": "SmithB"
    } ]
  } ]
}
```

# Diff Instance

When the $diff operation is invoked at the instance level (meaning it is invoked on a specific resource ID), it will compare two versions of the given resource.

## Parameters

* `[[${T(ca.uhn.fhir.rest.server.provider.ProviderConstants).DIFF_FROM_PARAMETER}]]=[reference]`: Specifies the source of the comparison. The value must include a resource type and a resource ID, and can optionally include a version, e.g. `Patient/123` or `Patient/123/_history/2`.
* `[[${T(ca.uhn.fhir.rest.server.provider.ProviderConstants).DIFF_TO_PARAMETER}]]=[reference]`: Specifies the target of the comparison. The value must include a resource type and a resource ID, and can optionally include a version, e.g. `Patient/123` or `Patient/123/_history/2`.
* `[[${T(ca.uhn.fhir.rest.server.provider.ProviderConstants).DIFF_INCLUDE_META_PARAMETER}]]=true`: (*optional*) If specified, changes to Resource.meta will be included in the diff. This element is omitted by default.  

To invoke:

```http
GET http://fhir.example.com/baseR4/$diff?[[${T(ca.uhn.fhir.rest.server.provider.ProviderConstants).DIFF_FROM_PARAMETER}]]=Patient/1&[[${T(ca.uhn.fhir.rest.server.provider.ProviderConstants).DIFF_TO_PARAMETER}]]=Patient/2
```

The server will produce a response resembling the following:

```json
{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "operation",
    "part": [ {
      "name": "type",
      "valueCode": "replace"
    }, {
      "name": "path",
      "valueString": "Patient.id"
    }, {
      "name": "previousValue",
      "valueId": "1"
    }, {
      "name": "value",
      "valueId": "2"
    } ]
  } ]
}
```


