Compartments API


Each resource may belong to one or more compartments. A compartment is a logical grouping of resources which share a common property. Compartments have two principal roles:

  • Function as an access mechanism for finding a set of related resources quickly (described here)

  • Provide a definitional basis for applying access control to resources quickly

Read more about compartments in the FHIR documentation. All examples in this tutorial are executable in Aidbox REST console.

Aidbox supports 5 default FHIR compartments in FHIR versions 1.4.0, 1.8.0, 3.0.1, 3.2.0, 3.3.0, 4.0.0, 4.0.1

Defining Compartments (FHIR R4)

In order to use compartments, you will need to create CompartmentDefinition resources on your server. Visit FHIR documentation for official CompartmentDefinition examples or use the following REST console snippets to create the resources.

Which CompartmentDefinitionis used is determined by its code or id:

  1. The compartment withid = target resourceTypeis used

  2. Else if not found compartment withcode = target resourceTypeis used

If multiple compartments with the code = traget resourceType are found then it is not determined which one will be used since FHIR spec doesn't specify this case

PUT /fhir/CompartmentDefinition/Patient

resourceType: CompartmentDefinition
id: Patient
experimental: true
name: Base FHIR compartment definition for Patient
status: draft
publisher: FHIR Project Team
version: 4.0.1
date: '2019-11-01T09:29:23+11:00'
search: true
code: Patient
- telecom:
  - {system: url, value: ''}
description: ...
# array that enumerates resources included in the compartment
resource: ... 

Although FHIR specification states that compartment definitions can only be defined by HL7 International, this restriction does not apply to Aidbox. You can define any compartments in your box so long as they are valid.

To search a compartment for either all possible resources or for a particular resource, type respectively:

GET [base]/[Compartment]/[id]/{*?[parameters]{&_format=[mime-type]}}
GET [base]/[Compartment]/[id]/[type]{?[parameters]{&_format=[mime-type]}}

For example, to retrieve all the observation resources for a particular LOINC code associated with a specific encounter:

GET [base]/Encounter/23423445/Observation?code=2951-2  {&_format=[mime-type]}

Example Requests

As an example of compartment usage, to retrieve a list of a patient's conditions, use the URL:

GET [base]/Patient/[id]/Condition

Additional search parameters can be defined, such as this hypothetical search for acute conditions:

GET [base]/Patient/[id]/Condition?code:in=

Our example compartment search is basically equivalent to these standard FHIR search requests:

GET [base]/Condition?patient=[id]
GET [base]/Condition?patient=[id]&code:in=

The outcome of a compartment search is the same as the equivalent FHIR search. For example, both these searches return the same outcome if there is no patient 333:

GET [base]/Patient/333/Condition
GET [base]/Condition?patient=333

If the patient doesn't exist or the user has no access to the patient, both these searches return an empty bundle with no matches.

However, there is a key difference in functionality between compartment-based searches and direct searches with parameters. Consider this search:

GET [base]/Patient/[id]/Communication

Because the definition of the patient compartment for Communication says that a Communication resource is in the patient compartment if the subject, sender, or recipient is the patient, the compartment search is actually the same as the union of these 3 searches:

GET [base]/Communication?subject=[id]
GET [base]/Communication?sender=[id]
GET [base]/Communication?recipient=[id]

Last updated