CompartmentDefinition — FHIR compartments

The Patient scope: every resource that speaks about them, and which parameter to find them by. The rule that makes GET /Patient/123/$everything deterministic.

Purpose

A FHIR compartment groups the resources linked to a common subject: the Patient compartment contains all the patient's clinical resources, the Practitioner compartment all resources where the practitioner acts. The FHIR spec defines 5 compartments: Patient, Practitioner, Encounter, Device, RelatedPerson. CompartmentDefinition formalizes which search parameters allow retrieving the resources of a compartment.

Key fields

API usage and security

Compartments enable scoped search: GET [base]/Patient/123/Observation returns all Observations in the Patient/123 compartment. It is also a security primitive: SMART on FHIR uses patient/*.read scopes implemented via compartments.

JSON example

Patient compartment definition:

{
  "resourceType": "CompartmentDefinition",
  "id": "patient",
  "url": "http://hl7.org/fhir/CompartmentDefinition/patient",
  "version": "5.0.0",
  "name": "PatientCompartment",
  "title": "Patient Compartment",
  "status": "active",
  "experimental": false,
  "date": "2023-03-26",
  "publisher": "HL7 (FHIR Project)",
  "description": "Compartment grouping all clinical resources associated with a patient: Observation, Condition, Encounter, MedicationRequest, etc.",
  "code": "Patient",
  "search": true,
  "resource": [{
    "code": "Observation",
    "param": ["subject", "performer"]
  }, {
    "code": "Condition",
    "param": ["patient", "asserter"]
  }, {
    "code": "Encounter",
    "param": ["patient", "subject"]
  }, {
    "code": "MedicationRequest",
    "param": ["subject"]
  }, {
    "code": "AllergyIntolerance",
    "param": ["patient", "recorder"]
  }, {
    "code": "Procedure",
    "param": ["patient", "performer"]
  }, {
    "code": "ImagingStudy",
    "param": ["patient"]
  }, {
    "code": "DiagnosticReport",
    "param": ["subject"]
  }, {
    "code": "AuditEvent",
    "param": ["patient"]
  }]
}

Common pitfalls

• Defining a custom non-standard compartment — the spec lists 5 valid codes: Patient, Encounter, RelatedPerson, Practitioner, Device. Custom = non-interoperable.
• Non-existent param — each param must exist as a SearchParameter on the target resource.
• Confusing search=true and implementation — search=true announces the capability; the server must implement it (often forgotten).
• No $everything — GET /Patient/123/$everything depends on the Patient compartment; without CompartmentDefinition, undetermined.
• CompartmentDefinition versioning — the FHIR spec evolves, compartments too. Keep in sync with the FHIR version of the server.

Related resources

• SearchParameter — parameters used.
• CapabilityStatement — declares supported compartments.
• OperationDefinition — $everything operates on a compartment.
• AuditEvent — often indexed by Patient compartment for HIPAA exports.