Understanding compartments

Compartments are concepts in FHIR which are important to understand when making use of Fire Arrow's request validators. Compartments form logical groups of FHIR resources. These logical groups don't exist physically in the FHIR database, they are mere views into existing data, very similar to an SQL view of a table.

Not all FHIR resources belong to a compartment, however, some resources can belong to multiple compartments at the same time. Association to a compartment is defined via rules. Compartments can serve as mechanism to find related resources but they also serve as access control mechanism.

Fire Arrow makes use of FHIR's compartments and extends their definition into a powerful tool for request validation.

HL7 FHIR compartment definitions

The offical specification about how compartments are defined, which compartments HL7 FHIR defines and association rules between resources and compartments can be found here.

HL7 FHIR specifies a number of compartments, one example is the Patient compartment. The Patient compartment's intention is to group all FHIR resources that refer to the same patient into the same logical box. This is done through a set of association rules, in the case of the Patient compartment usually the subject field of a FHIR resource:

• A DiagnosticReport belongs to the Patient compartment if DiagnosticReport.subject matches Patient.id.
• A MedicationRequest belongs to the Patient compartment if MedicationRequest.subject matches Patient.id.

Assuming that you are looking at the Patient compartment for Patient/12345, all resources that refer back to Patient/12345 are contained in that compartment.

Using compartments for validation

Compartments form one of the basic concepts of Fire Arrow's request validation. We will use the patient compartment to illustrate the concept. The membership rules are found in the HL7 FHIR documentation.

Assume the following entities exist in a FHIR database:

• A Patient resource with ID 12345, referenced as `Patient/12345``
• A CarePlan and DiagnosticReport resource, both pointing back to Patient/12345 as the subject

According to the official patient compartment definition, both CarePlan and DiagnosticReport are associated to a patient's PatientCompartment via their subject property. This means that both entities shown above belong to the patient compartment of Patient/12345. However, they do not belong to the patient compartment of a different patient, such as Patient/67890.

Let's assume we have the following validation strategy in config.json:

{
    "client_role": "Patient",
    "entity_name": "DiagnosticReport",
    "operation": "read",
    "validator": "PatientCompartment",
}

This instructs Fire Arrow to validate read requests to DiagnosticReport entities by checking if the resource belongs to the client's patient compartment, assuming the client has the Patient role.

If a client successfully authenticated as Patient/12345, they would be able to read the DiagnosticReport entity contained in the FHIR database. That same DiagnosticReport resource will not be readable by a client successfully authenticated as Patient/67890, because the DiagnosticReport resource belongs to Patient/12345.

All of Fire Arrows request validators try to express some form of association between an authenticated client and a FHIR resource.

Fire Arrow's organization compartment

Fire Arrow adds a custom "organization compartment" which doesn't exist in the official HL7 FHIR specification. The organization compartment is a collection of arbitrary resources that are linked to an organization via an organization-specific extension tag.

Any resource can be tagged with an extension with the url https://fire-arrow.evoleen.com/fhir/Extensions/organization-compartment and the value set to a FHIR reference to the organization resource. As soon as this extension exists on a resource, the resource becomes part of the corresponding organization's organization compartment.

The use case is to support multi-tenant deployments where the data of multiple organizations is contained in a single FHIR server. Some FHIR resources (for example Library) do not have a meaningful link to an organization. It is not possible to control access to these resources with any of the official compartments or with LegitimateInterest.

By tagging these resources with an extension, Fire Arrow creates the possibility to identify who controls the resource and then offer dedicated access validation strategies.