This is the Continuous Integration Build of FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions
FHIR Infrastructure Work Group | Maturity Level: 0 | Standards Status: Draft |
This page defines three operations that allow for efficient maintenance of very large Group and List resources. These operations make it possible to add and remove items from the list or group, and to retrieve a focused subset of the information in the list and group without having to transmit the entire resource.
Adding and deleting from the resource can also be done using the PATCH interaction. Implementers are welcome to use the patch interaction but these operations provide more certainty and simplicity, since they are tailored directly to the List and Group resources. Similarly, Implementers can retrieve a subset of a List or Group resources using GraphQL, but not all servers support GraphQL, and these operations are simpler than using GraphQL to filter the data (and potentially quicker for the server than using GraphQL).
$add
operation This instance-level operation merges array entries into an existing ("target") resource, based on values from a supplied ("input") resource, ignoring any values that are already present in the target.
This example adds up to 2 new members to the member array of Group 123, based on whether these entity/period combinations already exist.
POST /Group/123/$add
Content-Type: application/fhir+json
If-Match: W/"4"
{
"resourceType": "Group",
"type": "Person",
"actual": true,
"member": [{
"entity": {"reference": "Patient/123"},
"period": {"start": "2020-07-10"},
}, {
"entity": {"reference": "Patient/456"}
}]
}
This example adds up to 2 entries to the entry array of List 123, based on whether these item/date combinations already exist.
POST /List/123/$add
Content-Type: application/fhir+json
If-Match: W/"4"
{
"resourceType": "List",
"status": "current",
"mode": "working",
"entry": [{
"item": {"reference": "Patient/123"},
"date": "2020-01-05"
}, {
"item": {"reference": "Patient/456"}
}]
}
$add
operation details There is a formal definition for this operation
Instance-level operation, invoked by
POST /Group/123/$add
to grow Group.member
POST /List/123/$add
to grow List.entry
Input Parameter:
additions
: an input resource matching the type of the target resource. The client SHALL populate
all required top-level elements in a way that matches the target resource, to ensure the resource is technically
valid. The server SHALL ignore all elements except for the relevant array (e.g., Group.member
or
List.entry
).Behavior:
Clients MAY supply an If-Match
header with an ETag reflecting the current version of the target
resource. Servers SHALL NOT proceed if a supplied ETag does not match the current version of the target resource,
following the scheme described at https://hl7.org/fhir/http.html#concurrency.
$remove
operation This instance-level operation removes array entries from an existing ("target") resource, based on a supplied ("input") resource, ignoring any values that are already absent in the target.
This example removes elements from the member array of Group 123 if they match the supplied combinations of entity/period.
POST /Group/123/$remove
Content-Type: application/fhir+json
If-Match: W/"4"
{
"resourceType": "Group",
"type": "Person",
"actual": true,
"member": [{
"entity": {"reference": "Patient/123"},
"period": {"start": "2020-07-10"},
}, {
"entity": {"reference": "Patient/456"},
}]
}
This example removes elements from the entry array of List 123 if they match the supplied combinations of item/date.
POST /List/123/$remove
Content-Type: application/fhir+json
If-Match: W/"4"
{
"resourceType": "List",
"status": "current",
"mode": "working",
"entry": [{
"item": {"reference": "Patient/123"},
}, {
"item": {"reference": "Patient/456"},
"date": "2020-01-12"
}]
}
$remove
operation details There is a formal definition for this operation
Instance-level operation, invoked by
POST /Group/123/$remove
to shrink Group.member
POST /List/123/$remove
to shrink List.entry
Input Parameter:
removals
: an input resource matching the type of the target resource. The client SHALL populate all
required top-level elements in a way that matches the target resource, to ensure the resource is technically
valid. The server SHALL ignore all elements except for the relevant array (e.g., Group.member
or
List.entry
).Behavior:
Clients MAY supply an If-Match
header with an ETag reflecting the current version of the target
resource. Servers SHALL NOT proceed if a supplied ETag does not match the current version of the target resource,
following the scheme described at https://hl7.org/fhir/http.html#concurrency.
$filter
operation This example filters List 123 to return items referencing Patient 456 (on any day) Patient 789 (in July 2022.
POST /List/123/$filter
Content-Type: application/fhir+json
{
"resourceType": "List",
"status": "current",
"mode": "working",
"entry": [{
"item": {"reference": "Patient/456"},
}, {
"item": {"reference": "Patient/789"},
"date": "2022-07"
}]
}
If this list included two items (with any date) referencing Patient 456, and one item with a date in July 2022 referencing Patient 789, then three subsetted entries would be returned:
{
"resourceType": "List",
"id": "123",
"meta": {
"tag": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
"code": "SUBSETTED"
}]
},
"status": "current",
"mode": "working",
"title": "Patient waiting list",
"entry": [{
"date": "2022-07-01",
"flag": {"text": "Registered"},
"item": {"reference": "Patient/456/_history/1"}
}, {
"date": "2022-07-02T11:00:00Z",
"flag": {"text": "Escalated"},
"item": {"reference": "Patient/456/_history/2"}
}, {
"date": "2022-07-02T12:00:00Z",
"flag": {"text": "Escalated"},
"item": {"reference": "Patient/789"}
}]
}
$filter
operation details There is a formal definition for this operation
Instance-level operation, invoked by
POST /Group/123/$filter
to return a filtered subset of Group.member
POST /List/123/$filter
to return a filtered subset of List.entry
Input Parameter:
probes
: an input resource matching the type of the target resource. The client SHALL populate all
required top-level elements in a way that matches the target resource, to ensure the resource is technically
valid. The server SHALL ignore all elements except for the relevant array (e.g., Group.member
or
List.entry
).Behavior:
SUBSETTED
Coding in .meta.tag
Applies to: $add
, $remove
, and $filter
.
This algorithm determines whether an entry in the target resource array "matches" an entry in the input resource array. An entry is considered to "match" if:
Entry in input resource:
{
"item": {"reference": "Patient/123"}
}
Entry in target resource:
{
"date": "2022-07-01",
"item": {"reference": "Patient/123/_history/2"}
}
Result: this is a match, because the target entry contains a matching element for the input
entry’s elements (item
and item.reference
). The presence of an additional
date
element in the target resource does not affect the result.
Now consider the same inputs from Example (1), but swap their roles (input / target) as follows.
Entry in input resource:
{
"date": "2022-07-01",
"item": {"reference": "Patient/123/_history/2"}
}
Entry in target resource:
{
"item": {"reference": "Patient/123"}
}
Result: this is not a match, because the target entry contains no match for the input entry’s
date
element, and also no match for the input entry’s version-specific item.reference
element. This example shows that the comparision operation is not symmetric; inputs match more-specific targets,
not less-specific targets.