---
type: "doc"
source: "source/fhirpatch.html"
---
\[%settitle FHIRPath Patch%\] \[%file newheader%\] \[%file newnavbar%\]

## FHIRPath Patch

| Responsible Owner: [\[%wgt fhir%\]]([%wg fhir%]) Work Group | [Standards Status](versions#std-process):[Normative](versions#std-process) |
| --- | --- |

This page defines a FHIR [Parameters](parameters)\-based, syntax-agnostic patch mechanism where elements to be manipulated by the [patch](http#patch) interaction are described using their [FHIRpath](fhirpath) names and navigation.

### Operations

This table documents the FHIR Patch operations that may be used to specify changes to a resource:

| **Type** | **Path** | **Name** | **Value** | **Index** | **source** | **destination** | **Details** |
| --- | --- | --- | --- | --- | --- | --- | --- |
| add | Path at which to add the content | Name of the property to add | Datatype to add at nominated place |  |  |  | The content will be appended to the element identified in the path, using the name specified. Add can used for non-repeating elements as long as they do not already exist |
| insert | Path of the collection in which to insert the content |  | value (Datatype) to add at nominated place | index at which to insert |  |  | The content will be inserted into the nominated list at the index specified (0 based). The index is mandatory and must be equal or less than the number of elements in the list. Note: `add` is easier than `insert` at the end of the list |
| delete | Path of the element to delete (if found) |  |  |  |  |  | Only a single element can be deleted |
| replace | Path of the element to replace |  | value (Datatype) to replace it with |  |  |  |  |
| move | Path of the collection in which to move the content |  |  |  | list index to move from | list index to move to | Move an element within a single list |

There are a few base rules that apply for all operations:

-   The FHIRPath statement must return a single element
-   The FHIRPath statement SHALL NOT cross resources using the `resolve()` function (e.g., like `Observation.subject.resolve().identifier`). `resolve()` SHALL only be used to refer to contained resource within the resource being patched. Servers SHALL NOT allow patch operations to alter other resources than the nominated target, and SHOULD return an error if the patch operation tries
-   The type of the value must be correct for the place at which it will be added/inserted. Servers SHALL return an error if the type is wrong
-   Servers SHALL return an error if the outcome of the patch operation is a not a valid resource
-   Except for the delete operation, it is an error if no element matches the specified path
-   Operations are applied in order, with each operation applied to the result of the previous patch operation

### Parameters Format

The FHIRPath patch operations are encoded in a [Parameters](parameters) resource as follows:

-   Each operation is a Parameter named "operation"
-   Each operation has a series of parts, using the following parameter names from the table above with these types:

A [profile for this has been defined](fhirpath-patch) on the [Parameters resource](parameters).

| Parameter | Type |
| --- | --- |
| type | code |
| path | string |
| name | string |
| value | [\*](datatypes#open) |
| index | integer |
| source | integer |
| destination | integer |

Here is an example of adding an element:

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="operation"/>
    <part>
      <name value="type"/>
      <valueCode value="add"/>
    </part>
    <part>
      <name value="path"/>
      <valueString value="Patient"/>
    </part>
    <part>
      <name value="name"/>
      <valueString value="birthDate"/>
    </part>
    <part>
      <name value="value"/>
      <valueDate value="1930-01-01"/>
    </part>
  </parameter>
</Parameters>

#### Anonymous Types

Only some named datatypes (see [the list](datatypes#open)) are allowed to be used directly in parameters. In order to add or insert other kinds of types - including anonymous elements (e.g., Observation.component, Timing.repeat), the content is defined by defining the name as described above, and instead of providing a value, a set of parts that are values are provided. Here is an example:

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="operation"/>
    <part>
      <name value="type"/>
      <valueCode value="add"/>
    </part>
    <part>
      <name value="path"/>
      <valueString value="Patient"/>
    </part>
    <part>
      <name value="name"/>
      <valueString value="contact"/>
    </part>
    <part>
      <name value="value"/>
      <part>
        <name value="name"/>
        <valueHumanName>
          <text value="a name"/>
        </valueHumanName>
      </part>
    </part>
  </parameter>
</Parameters>

This pattern repeats as deep as necessary.

### Choice Elements

Note that for elements with a choice of data types, the FHIRPath name in the name of the parameter does not include the data type suffix (per the rules in the [FHIRPath](fhirpath) Specification), but the parameter value does. Here's an example:

{
  "resourceType": "Parameters",
  "parameter": \[{
    "name": "operation",
    "part": \[{
      "name": "type",
      "valueCode": "add"
    }, {
      "name": "path",
      "valueString": "Specimen"
    }, {
      "name": "name",
      "valueString": "processing"
    }, {
        "name": "value",
        "part": \[{
                "name": "description",
                "valueString": "testProcessing"
            }, {
                "name": "time",
                "valueDateTime": "2021-08-18T11:32:55.6462761+02:00"
            }\]
            }\]
    }
  \]
}

### Extension Example

An example of adding an extension:

  <Parameters xmlns="http://hl7.org/fhir">
  <parameter>
      <name value="operation"/>
      <part>
        <name value="type"/>
        <valueString value="add"/>
      </part>
      <part>
        <name value="path"/>
        <valueString value="Specimen"/>
      </part>
      <part>
        <name value="name"/>
        <valueString value="processing"/>
      </part>
      <part>
        <name value="value" />
        <part>
          <name value="description" />
          <valueString value="test" />
        </part>
        <part>
          <name value="time" />
          <valueDateTime value="2021-08-13T07:44:38.342+00:00" />
        </part>
        <part>
          <name value="extension" />
          <part>
            <name value="url" />
            <valueUri value="http://example.org/fhir/DeviceExtension" />
          </part>
          <part>
            <name value="value" />
            <valueReference>
              <reference reference="Device/1">
            </valueReference>
          </part>
        </part>
      </part>
  </parameter>
</Parameters>

Applied to an empty Specimen, this would produce:

  <Specimen xmlns="http://hl7.org/fhir">
  <status value="available"/>
  <processing>
    <extension url="http://example.org/fhir/DeviceExtension">
      <valueReference>
        <reference reference="Device/1">
      </valueReference>
    </extension>
    <description value="test"/>
    <timeDateTime value="2021-08-13T07:44:38.342+00:00"/>
  </processing>
</Specimen>

There is a set of test cases for implementers in the [fhir-test-cases](https://github.com/FHIR/fhir-test-cases/releases) repository.

### Complex Path Example

Note that the `path` parameter value is a FHIRPath expression, and not a simple path. For example, in the following patch operation, the `path` parameter value is a FHIRPath expression that selects the `period` element of the `identifier` element with a `use` value of `official`.

{
  "resourceType": "Parameters",
  "parameter": \[
    {
      "name": "operation",
      "part": \[
        {
          "name": "type",
          "valueCode": "add"
        },
        {
          "name": "path",
          "valueString": "Patient.identifier.where(use = 'official').period"
        },
        {
          "name": "name",
          "valueString": "end"
        },
        {
          "name": "value",
          "valueDate": "2021-12-01"
        }
      \]
    }
  \]
}

There is a set of test cases for implementers in the [fhir-test-cases](https://github.com/FHIR/fhir-test-cases/releases) repository.

\[%file newfooter%\]