Patch

Patch is an Instance Level Interaction. As an alternative to updating an entire resource, clients can perform a patch operation. This can be useful when a client is seeking to minimize its bandwidth utilization, or in scenarios where a client has only partial access or support for a resource. The patch interaction is performed by the graphql update mutations by simply passing just the fields that the client wishes to update. There are caveats to the model such as working with collections.

The resource update mutation's follow a patching model. In such a model with various integrations manipulating the same data, lists can be a challenge. List properties (e.g. 0..* cardinality) can be difficult to work with in this scenario. For example, are we updating an entry in the list? Do we want to remove an entry? And of course do we want to add an entry?

To make this more easily interpreted the Directory will evaluate the Id property of the list element in question. Most data types in FHIR are of an element type at it's base. Identifer type for example, per the FHIR specification has a base type of Element, and element ancestors include id, and extension.

If an id value is not provided, the Directory service will assign a uuid as a default. Integrating clients; and the Directory, may choose to implement a more deterministic id based on uniqueness. For example with Practitioner, the name property is a list of HumanNames, and per the profile there can only be one of each type (e.g. use), therefore the use value can serve as the id value as well. Use caution here though, this must be carefully considered.

Adding List Items

Simply supply the list item in the resource input with or without id. For example, to add a Practitioner nickname where the directory assigns the id property, it would look like this:

mutation { updatePractitioner (id: "437b8439-7ae2-47ac-8035-fdebfdef1d0e" practitioner: { name: { use: NICKNAME given: [ "Batman" ] text: "Batman" } ) { resource { id } }

Updating List Items

Simply supply the list item in the resource input with existing element id. For example, to update a Practitioner nickname from "Batman" to "Spiderman", it would look like this:

mutation { updatePractitioner (id: "437b8439-7ae2-47ac-8035-fdebfdef1d0e" practitioner: { name: { id: "nickname" use: NICKNAME given: [ "Spiderman" ] text: "Spiderman" } ) { resource { id } }

Note: The above example assumes an existing nickname with the id "nickname". If this id did not exist a new nickname would be added to the list.

Removing List Items

There will be resource specific input parameters for update mutations that will allow for specific list item removal. For example all resources support "Identifier" which is a collection, or list type. The resources will implement a removeIdentifier input parameter that will accept a list of identifier element id's of the identifiers that you wish to remove from the list. See Resources for a list of supported input parameters per resource.

Deterministic List Id's

As mentioned above, the Directory in some cases uses a deterministic id value to make it easier for integrating applications to reference the id in patching operations without having to look it up. The following are cases where the id is deterministic:

ContactPoint Elements (e.g. telecom)

The id will consist of lowercase value (e.g jdoe@baxter.com). The Directory will supply the id on create mutations. The definition of this id makes the value property required. Since value is the id and value is a likely candidate for update, the proper method to update a targeted telecom is to a) include the updated telecom in the resource input, and b) add the id of the identifier you are targeting to replace in the removeTelecom input.

CodeableConcept Elements

The id will consist of lowercase coding[0].code. The Directory will supply the id on create mutations.

Group Member Backbone Element

The id will consist of lowercase entity.reference (id portion only). The Directory will supply the id on create mutations. The definition of this id makes the reference property required.

HumanName Element

The id will consist of lowercase use (e.g official). The Directory will supply the id on create mutations. The definition of this id makes the use property required.

Identifier Element

The id will consist of lowercase type.coding[0].code and value colon delimited (e.g. facility association identifier id 1.1:02ef). The Directory will supply the id on create mutations. The definition of this id makes the code and value elements required in the identifier. Since value is part of the id and value is a likely candidate for update, the proper method to update a targeted identifier is to a) Include the updated identifier in the resource input, and b) add the id of the identifier you are targeting to replace in the removeIdentifier input.

Reference Element

The id will consist of lowercase entity.reference (id portion only). The Directory will supply the id on create mutations. The definition of this id makes the reference property required.