You run a FHIR query and a Bundle of results is returned. How do read that Bundle?
Devs new to FHIR often assume that checking the resource type of each entry in the Bundle is enough. Sometimes it is, but sometimes it isn’t.
Here are two examples that illustrate a happy path and a non-happy path.
Example 1
Give me all Encounters and include the corresponding Patient resources.
/Encounter?_include=Encounter:patientIn this example looking at the resource type is enough. Extract the Encounters, extract the Patients, and match them up.
Example 2
Give me all Observations that meet certain criteria and include other resources referenced in the hasMember element.
/Observation?status=final&_include=Observation:has-memberThe logic of example 1 will not always work here as every resource returned might be an Observation — even those included because of the hasMember reference.
So what’s the solution?
You need to look at the search mode of each entry in the Bundle, not the resource type. That search mode will be one of these three values:
- match
- include
- outcome
All the Observations that meet our search criteria will have a mode of “match.” Resources (including Observations) that were included because of the hasMember reference will have a mode of “include.”
And any OperationOutcome resources in the Bundle will have a mode of “outcome.”
But wait a minute, what happens in the above example if an included Observation ALSO matches the search criteria?
“match” takes precedence.
And there is only one search mode per returned resource. Which means you can’t always rely on the search mode when connecting up resources from a Bundle.
The lesson here is that even simple aspects of FHIR such as parsing search results have their edge cases. And you’re unlikely to catch these edge cases during development and test.
---