Compartments API

Overview

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. 1.
    The compartment withid = target resourceTypeis used
  2. 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
General Structure
Patient
Encounter
1
PUT /fhir/CompartmentDefinition/Patient
2
​
3
resourceType: CompartmentDefinition
4
id: Patient
5
url: http://hl7.org/fhir/CompartmentDefinition/patient
6
experimental: true
7
name: Base FHIR compartment definition for Patient
8
status: draft
9
publisher: FHIR Project Team
10
version: 4.0.1
11
date: '2019-11-01T09:29:23+11:00'
12
search: true
13
code: Patient
14
contact:
15
- telecom:
16
- {system: url, value: 'http://hl7.org/fhir'}
17
description: ...
18
# array that enumerates resources included in the compartment
19
resource: ...
Copied!
1
PUT /fhir/CompartmentDefinition/Patient
2
​
3
resourceType: CompartmentDefinition
4
id: Patient
5
url: http://hl7.org/fhir/CompartmentDefinition/patient
6
experimental: true
7
name: Base FHIR compartment definition for Patient
8
status: draft
9
publisher: FHIR Project Team
10
version: 4.0.1
11
date: '2019-11-01T09:29:23+11:00'
12
search: true
13
code: Patient
14
contact:
15
- telecom:
16
- {system: url, value: 'http://hl7.org/fhir'}
17
description: There is an instance of the patient compartment for each patient resource, and the identity of the compartment is the same as the patient. When a patient is linked to another patient, all the records associated with the linked patient are in the compartment associated with the target of the link.. The set of resources associated with a particular patient
18
resource:
19
- code: Account
20
param: [subject]
21
- {code: ActivityDefinition}
22
- code: AdverseEvent
23
param: [subject]
24
- code: AllergyIntolerance
25
param: [patient, recorder, asserter]
26
- code: Appointment
27
param: [actor]
28
- code: AppointmentResponse
29
param: [actor]
30
- code: AuditEvent
31
param: [patient]
32
- code: Basic
33
param: [patient, author]
34
- {code: Binary}
35
- {code: BiologicallyDerivedProduct}
36
- code: BodyStructure
37
param: [patient]
38
- {code: Bundle}
39
- {code: CapabilityStatement}
40
- code: CarePlan
41
param: [patient, performer]
42
- code: CareTeam
43
param: [patient, participant]
44
- {code: CatalogEntry}
45
- code: ChargeItem
46
param: [subject]
47
- {code: ChargeItemDefinition}
48
- code: Claim
49
param: [patient, payee]
50
- code: ClaimResponse
51
param: [patient]
52
- code: ClinicalImpression
53
param: [subject]
54
- {code: CodeSystem}
55
- code: Communication
56
param: [subject, sender, recipient]
57
- code: CommunicationRequest
58
param: [subject, sender, recipient, requester]
59
- {code: CompartmentDefinition}
60
- code: Composition
61
param: [subject, author, attester]
62
- {code: ConceptMap}
63
- code: Condition
64
param: [patient, asserter]
65
- code: Consent
66
param: [patient]
67
- {code: Contract}
68
- code: Coverage
69
param: [policy-holder, subscriber, beneficiary, payor]
70
- code: CoverageEligibilityRequest
71
param: [patient]
72
- code: CoverageEligibilityResponse
73
param: [patient]
74
- code: DetectedIssue
75
param: [patient]
76
- {code: Device}
77
- {code: DeviceDefinition}
78
- {code: DeviceMetric}
79
- code: DeviceRequest
80
param: [subject, performer]
81
- code: DeviceUseStatement
82
param: [subject]
83
- code: DiagnosticReport
84
param: [subject]
85
- code: DocumentManifest
86
param: [subject, author, recipient]
87
- code: DocumentReference
88
param: [subject, author]
89
- {code: EffectEvidenceSynthesis}
90
- code: Encounter
91
param: [patient]
92
- {code: Endpoint}
93
- code: EnrollmentRequest
94
param: [subject]
95
- {code: EnrollmentResponse}
96
- code: EpisodeOfCare
97
param: [patient]
98
- {code: EventDefinition}
99
- {code: Evidence}
100
- {code: EvidenceVariable}
101
- {code: ExampleScenario}
102
- code: ExplanationOfBenefit
103
param: [patient, payee]
104
- code: FamilyMemberHistory
105
param: [patient]
106
- code: Flag
107
param: [patient]
108
- code: Goal
109
param: [patient]
110
- {code: GraphDefinition}
111
- code: Group
112
param: [member]
113
- {code: GuidanceResponse}
114
- {code: HealthcareService}
115
- code: ImagingStudy
116
param: [patient]
117
- code: Immunization
118
param: [patient]
119
- code: ImmunizationEvaluation
120
param: [patient]
121
- code: ImmunizationRecommendation
122
param: [patient]
123
- {code: ImplementationGuide}
124
- {code: InsurancePlan}
125
- code: Invoice
126
param: [subject, patient, recipient]
127
- {code: Library}
128
- {code: Linkage}
129
- code: List
130
param: [subject, source]
131
- {code: Location}
132
- {code: Measure}
133
- code: MeasureReport
134
param: [patient]
135
- code: Media
136
param: [subject]
137
- {code: Medication}
138
- code: MedicationAdministration
139
param: [patient, performer, subject]
140
- code: MedicationDispense
141
param: [subject, patient, receiver]
142
- {code: MedicationKnowledge}
143
- code: MedicationRequest
144
param: [subject]
145
- code: MedicationStatement
146
param: [subject]
147
- {code: MedicinalProduct}
148
- {code: MedicinalProductAuthorization}
149
- {code: MedicinalProductContraindication}
150
- {code: MedicinalProductIndication}
151
- {code: MedicinalProductIngredient}
152
- {code: MedicinalProductInteraction}
153
- {code: MedicinalProductManufactured}
154
- {code: MedicinalProductPackaged}
155
- {code: MedicinalProductPharmaceutical}
156
- {code: MedicinalProductUndesirableEffect}
157
- {code: MessageDefinition}
158
- {code: MessageHeader}
159
- code: MolecularSequence
160
param: [patient]
161
- {code: NamingSystem}
162
- code: NutritionOrder
163
param: [patient]
164
- code: Observation
165
param: [subject, performer]
166
- {code: ObservationDefinition}
167
- {code: OperationDefinition}
168
- {code: OperationOutcome}
169
- {code: Organization}
170
- {code: OrganizationAffiliation}
171
- code: Patient
172
param: [link]
173
- {code: PaymentNotice}
174
- {code: PaymentReconciliation}
175
- code: Person
176
param: [patient]
177
- {code: PlanDefinition}
178
- {code: Practitioner}
179
- {code: PractitionerRole}
180
- code: Procedure
181
param: [patient, performer]
182
- code: Provenance
183
param: [patient]
184
- {code: Questionnaire}
185
- code: QuestionnaireResponse
186
param: [subject, author]
187
- code: RelatedPerson
188
param: [patient]
189
- code: RequestGroup
190
param: [subject, participant]
191
- {code: ResearchDefinition}
192
- {code: ResearchElementDefinition}
193
- {code: ResearchStudy}
194
- code: ResearchSubject
195
param: [individual]
196
- code: RiskAssessment
197
param: [subject]
198
- {code: RiskEvidenceSynthesis}
199
- code: Schedule
200
param: [actor]
201
- {code: SearchParameter}
202
- code: ServiceRequest
203
param: [subject, performer]
204
- {code: Slot}
205
- code: Specimen
206
param: [subject]
207
- {code: SpecimenDefinition}
208
- {code: StructureDefinition}
209
- {code: StructureMap}
210
- {code: Subscription}
211
- {code: Substance}
212
- {code: SubstanceNucleicAcid}
213
- {code: SubstancePolymer}
214
- {code: SubstanceProtein}
215
- {code: SubstanceReferenceInformation}
216
- {code: SubstanceSourceMaterial}
217
- {code: SubstanceSpecification}
218
- code: SupplyDelivery
219
param: [patient]
220
- code: SupplyRequest
221
param: [subject]
222
- {code: Task}
223
- {code: TerminologyCapabilities}
224
- {code: TestReport}
225
- {code: TestScript}
226
- {code: ValueSet}
227
- {code: VerificationResult}
228
- code: VisionPrescription
229
param: [patient]
230
​
Copied!
1
PUT /fhir/CompartmentDefinition/Encounter
2
​
3
resourceType: CompartmentDefinition
4
id: Encounter
5
url: http://hl7.org/fhir/CompartmentDefinition/encounter
6
experimental: true
7
name: Base FHIR compartment definition for Encounter
8
status: draft
9
publisher: FHIR Project Team
10
version: 4.0.1
11
date: '2019-11-01T09:29:23+11:00'
12
search: true
13
code: Encounter
14
contact:
15
- telecom:
16
- {system: url, value: 'http://hl7.org/fhir'}
17
description: There is an instance of the encounter compartment for each encounter resource, and the identity of the compartment is the same as the encounter. The set of resources associated with a particular encounter
18
resource:
19
- {code: Account}
20
- {code: ActivityDefinition}
21
- {code: AdverseEvent}
22
- {code: AllergyIntolerance}
23
- {code: Appointment}
24
- {code: AppointmentResponse}
25
- {code: AuditEvent}
26
- {code: Basic}
27
- {code: Binary}
28
- {code: BiologicallyDerivedProduct}
29
- {code: BodyStructure}
30
- {code: Bundle}
31
- {code: CapabilityStatement}
32
- code: CarePlan
33
param: [encounter]
34
- code: CareTeam
35
param: [encounter]
36
- {code: CatalogEntry}
37
- code: ChargeItem
38
param: [context]
39
- {code: ChargeItemDefinition}
40
- code: Claim
41
param: [encounter]
42
- {code: ClaimResponse}
43
- code: ClinicalImpression
44
param: [encounter]
45
- {code: CodeSystem}
46
- code: Communication
47
param: [encounter]
48
- code: CommunicationRequest
49
param: [encounter]
50
- {code: CompartmentDefinition}
51
- code: Composition
52
param: [encounter]
53
- {code: ConceptMap}
54
- code: Condition
55
param: [encounter]
56
- {code: Consent}
57
- {code: Contract}
58
- {code: Coverage}
59
- {code: CoverageEligibilityRequest}
60
- {code: CoverageEligibilityResponse}
61
- {code: DetectedIssue}
62
- {code: Device}
63
- {code: DeviceDefinition}
64
- {code: DeviceMetric}
65
- code: DeviceRequest
66
param: [encounter]
67
- {code: DeviceUseStatement}
68
- code: DiagnosticReport
69
param: [encounter]
70
- code: DocumentManifest
71
param: [related-ref]
72
- code: DocumentReference
73
param: [encounter]
74
- {code: EffectEvidenceSynthesis}
75
- code: Encounter
76
param: ['{def}']
77
- {code: Endpoint}
78
- {code: EnrollmentRequest}
79
- {code: EnrollmentResponse}
80
- {code: EpisodeOfCare}
81
- {code: EventDefinition}
82
- {code: Evidence}
83
- {code: EvidenceVariable}
84
- {code: ExampleScenario}
85
- code: ExplanationOfBenefit
86
param: [encounter]
87
- {code: FamilyMemberHistory}
88
- {code: Flag}
89
- {code: Goal}
90
- {code: GraphDefinition}
91
- {code: Group}
92
- {code: GuidanceResponse}
93
- {code: HealthcareService}
94
- {code: ImagingStudy}
95
- {code: Immunization}
96
- {code: ImmunizationEvaluation}
97
- {code: ImmunizationRecommendation}
98
- {code: ImplementationGuide}
99
- {code: InsurancePlan}
100
- {code: Invoice}
101
- {code: Library}
102
- {code: Linkage}
103
- {code: List}
104
- {code: Location}
105
- {code: Measure}
106
- {code: MeasureReport}
107
- code: Media
108
param: [encounter]
109
- {code: Medication}
110
- code: MedicationAdministration
111
param: [context]
112
- {code: MedicationDispense}
113
- {code: MedicationKnowledge}
114
- code: MedicationRequest
115
param: [encounter]
116
- {code: MedicationStatement}
117
- {code: MedicinalProduct}
118
- {code: MedicinalProductAuthorization}
119
- {code: MedicinalProductContraindication}
120
- {code: MedicinalProductIndication}
121
- {code: MedicinalProductIngredient}
122
- {code: MedicinalProductInteraction}
123
- {code: MedicinalProductManufactured}
124
- {code: MedicinalProductPackaged}
125
- {code: MedicinalProductPharmaceutical}
126
- {code: MedicinalProductUndesirableEffect}
127
- {code: MessageDefinition}
128
- {code: MessageHeader}
129
- {code: MolecularSequence}
130
- {code: NamingSystem}
131
- code: NutritionOrder
132
param: [encounter]
133
- code: Observation
134
param: [encounter]
135
- {code: ObservationDefinition}
136
- {code: OperationDefinition}
137
- {code: OperationOutcome}
138
- {code: Organization}
139
- {code: OrganizationAffiliation}
140
- {code: Patient}
141
- {code: PaymentNotice}
142
- {code: PaymentReconciliation}
143
- {code: Person}
144
- {code: PlanDefinition}
145
- {code: Practitioner}
146
- {code: PractitionerRole}
147
- code: Procedure
148
param: [encounter]
149
- {code: Provenance}
150
- {code: Questionnaire}
151
- code: QuestionnaireResponse
152
param: [encounter]
153
- {code: RelatedPerson}
154
- code: RequestGroup
155
param: [encounter]
156
- {code: ResearchDefinition}
157
- {code: ResearchElementDefinition}
158
- {code: ResearchStudy}
159
- {code: ResearchSubject}
160
- {code: RiskAssessment}
161
- {code: RiskEvidenceSynthesis}
162
- {code: Schedule}
163
- {code: SearchParameter}
164
- code: ServiceRequest
165
param: [encounter]
166
- {code: Slot}
167
- {code: Specimen}
168
- {code: SpecimenDefinition}
169
- {code: StructureDefinition}
170
- {code: StructureMap}
171
- {code: Subscription}
172
- {code: Substance}
173
- {code: SubstanceNucleicAcid}
174
- {code: SubstancePolymer}
175
- {code: SubstanceProtein}
176
- {code: SubstanceReferenceInformation}
177
- {code: SubstanceSourceMaterial}
178
- {code: SubstanceSpecification}
179
- {code: SupplyDelivery}
180
- {code: SupplyRequest}
181
- {code: Task}
182
- {code: TerminologyCapabilities}
183
- {code: TestReport}
184
- {code: TestScript}
185
- {code: ValueSet}
186
- {code: VerificationResult}
187
- code: VisionPrescription
188
param: [encounter]
189
​
Copied!
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.

Compartment Search

To search a compartment for either all possible resources or for a particular resource, type respectively:
1
GET [base]/[Compartment]/[id]/{*?[parameters]{&_format=[mime-type]}}
2
GET [base]/[Compartment]/[id]/[type]{?[parameters]{&_format=[mime-type]}}
Copied!
For example, to retrieve all the observation resources for a particular LOINC code associated with a specific encounter:
1
GET [base]/Encounter/23423445/Observation?code=2951-2 {&_format=[mime-type]}
Copied!

Example Requests

As an example of compartment usage, to retrieve a list of a patient's conditions, use the URL:
1
GET [base]/Patient/[id]/Condition
Copied!
Additional search parameters can be defined, such as this hypothetical search for acute conditions:
1
GET [base]/Patient/[id]/Condition?code:in=http://hspc.org/ValueSet/acute-concerns
Copied!
Our example compartment search is basically equivalent to these standard FHIR search requests:
1
GET [base]/Condition?patient=[id]
2
GET [base]/Condition?patient=[id]&code:in=http://hspc.org/ValueSet/acute-concerns
Copied!
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:
1
GET [base]/Patient/333/Condition
2
GET [base]/Condition?patient=333
Copied!
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:
1
GET [base]/Patient/[id]/Communication
Copied!
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:
1
GET [base]/Communication?subject=[id]
2
GET [base]/Communication?sender=[id]
3
GET [base]/Communication?recipient=[id]
Copied!