relatedperson-compartment

relatedperson_compartment Validator Documentation
FHIR Compartment-Based Access Control for Caregivers & Relatives

---

Intent

The relatedperson_compartment validator restricts access to resources linked to a patient associated with the authenticated RelatedPerson user. This enables caregivers, family members, or legally authorized representatives to access specific patient data with tighter controls than full patient accounts.

Key Use Cases:

• A parent managing a child’s immunization records (Immunization).
• A legal guardian reviewing care plans (CarePlan).
• A spouse viewing upcoming appointments (Appointment).

---

Key Features

1. Role Enforcement:
   • Requires the client to have the RelatedPerson role. Requests from other roles (e.g., Patient or Practitioner) are denied.
2. Compartment Membership Check:
   • Validates that the resource type belongs to the FHIR RelatedPerson compartment (e.g., CarePlan, Appointment, Communication).
3. Reference Validation:
   • For write operations, ensures the resource references the RelatedPerson’s linked patient (e.g., CarePlan.subject = Patient/<id> AND CarePlan.actor = RelatedPerson/<id>).

---

Validation Logic

Step	Action	Error If Failed
1	Check client_role is RelatedPerson.	403 Forbidden (Invalid role)
2	Verify resource type is in the RelatedPerson compartment.	403 Forbidden (Invalid compartment)
3	For write operations, validate references to both the patient and RelatedPerson (e.g., subject AND actor).	403 Forbidden (Reference mismatch)

---

Example Configurations

1. Read Access to Lab Reports

{
  "client_role": "RelatedPerson",
  "entity_name": "DiagnosticReport",
  "operation": "read",
  "validator": "relatedperson_compartment"
}

Explanation: The RelatedPerson can read DiagnosticReport resources only if:

• DiagnosticReport.subject.reference matches Patient/<linked_patient_id>.
• The RelatedPerson is explicitly associated with the patient (e.g., via Patient.contact or a dedicated mapping table).

2. Create a Care Plan

{
  "client_role": "RelatedPerson",
  "entity_name": "CarePlan",
  "operation": "create",
  "validator": "relatedperson_compartment"
}

Requirements: The CarePlan body must include:

"subject": { "reference": "Patient/<patient_id>" },
"actor": { "reference": "RelatedPerson/<related_person_id>" }

Otherwise, the request is denied.

---

FHIR References

1. RelatedPerson Compartment Definition:
   FHIR R4 RelatedPerson Compartment (HL7 documentation).
2. Resource Examples:
   • CarePlan.actor
   • Appointment.participant

---

Use Case: Pediatric Care Management

A parenting app uses this validator to allow guardians to:

1. View vaccination records: Reads Immunization resources where patient matches their linked child’s ID.
2. Schedule checkups: Creates Appointment resources with both patient and actor references.

Error Handling:

• A guardian attempting to access another patient’s CarePlan receives a 403 Forbidden error.