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.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
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!
API - Previous
Encryption API
Next - API
GraphQL API
Last modified 7mo ago
Copy link
Contents
Overview
Defining Compartments (FHIR R4)
Compartment Search
Example Requests