Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.15.0 - ci-build
NL
Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.15.0 - ci-build
NL
Koppeltaal 2.0 Implementation Guide (Full Documentation) - Local Development build (v0.15.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Page standards status: Draft |
| Datum | Wijziging |
|---|---|
| 2026-01-06 | Verduidelijking: CareTeam beschrijft zorgcontext, niet het autorisatiemodel zelf |
| 2026-01-06 | Diagram toegevoegd: relatie CareTeam, autorisatiematrix en FHIR resources |
| 2026-01-06 | Rollen en Autorisatiematrix: CareTeam als startpunt, modellen in ontwikkeling |
| 2025-12-02 | Formulering Task.owner/requester aangepast: "minimaal één CareTeam" i.p.v. "het relevante CareTeam" |
| 2025-12-02 | Rol "eerste relatie" verwijderd; RelatedPerson heeft (nog) geen rol |
| 2025-12-01 | HTI token voorbeelden aangepast conform HTI 2.0 specificatie |
| 2025-12-01 | CareTeam als Task.owner toegestaan als bijzondere use case |
Deze pagina beschrijft de rol van het CareTeam als zorgcontext binnen het KoppelMij/Koppeltaal geharmoniseerde model, zoals beschreven in Optie 3 van de Koppeltaal Domeinen documentatie.
Het CareTeam is niet het autorisatiemodel zelf, maar beschrijft de zorgcontext van een patiënt: welke Practitioners en RelatedPersons betrokken zijn en in welke rol. Deze informatie vormt één van de startpunten voor het autorisatiemodel, omdat op basis van deze rollen de rechten worden bepaald.
┌─────────────────────────────────────────────────────────────────────────┐
│ AUTORISATIEMODEL │
│ │
│ ┌─────────────────┐ │
│ │ CareTeam │ Beschrijft zorgcontext: │
│ │ (Zorgcontext) │ • Betrokken Practitioners │
│ │ │ • Betrokken RelatedPersons │
│ │ │ • Rollen van betrokkenen │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Autorisatie- │ Bepaalt rechten op basis van: │
│ │ matrix │ • Rol in CareTeam │
│ │ │ • Resource type │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ FHIR Resources │ Toegang tot resources zoals: │
│ │ │ • Task, Patient, CareTeam │
│ │ │ • ActivityDefinition, etc. │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Samengevat:
Een CareTeam is een groep van personen (Practitioners en/of RelatedPersons) die samenwerken aan de zorg voor een specifieke patiënt of binnen een specifieke organisatiecontext. Het CareTeam resource fungeert als de centrale plek waar wordt vastgelegd:
Er zijn drie hoofdtypen van CareTeams in het systeem:
Dit zijn CareTeams zonder specifieke patiënt, die gebruikt worden voor organisatorische doeleinden.
Kenmerken:
CareTeam.patient is niet gezetVoorbeeld gebruik:
CareTeam voor Afdeling Depressie
├── Patient: (niet gezet)
├── Participants:
│ ├── Practitioner: Dr. Smit
│ ├── Practitioner: Dr. Jansen
│ └── Practitioner: Zorgondersteuner Klaas
Dit zijn CareTeams die gekoppeld zijn aan een specifieke patiënt via CareTeam.patient.
Kenmerken:
CareTeam.patient verwijst naar de specifieke Patient resourceVoorbeeld gebruik:
CareTeam voor Jan Jansen
├── Patient: Jan Jansen
├── Participants:
│ ├── Practitioner: Dr. Smit (rol: behandelaar)
│ ├── Practitioner: Zorgondersteuner Klaas (rol: zorgondersteuner)
│ └── RelatedPerson: Partner van Jan
Dit zijn CareTeams die gebonden zijn aan een specifieke Task en een specifieke patiënt.
Kenmerken:
CareTeam.patient verwijst naar de specifieke Patient resourceTask.ownerVoorbeeld gebruik:
CareTeam voor Intake Gesprek Jan Jansen
├── Patient: Jan Jansen
├── Participants:
│ ├── Practitioner: Dr. Smit (rol: behandelaar)
│ └── Practitioner: Zorgondersteuner Klaas (rol: zorgondersteuner)
├── Gekoppeld aan: Task "Intake gesprek plannen"
Verschil met Patiënt-specifieke CareTeams:
Nadelen van Task level CareTeams:
Het gebruik van het CareTeam als autorisatiemodel is onderdeel van het breder uitzetten van het autorisatiemodel in Koppeltaal 2.0. Het CareTeam is een van de entiteiten betrokken in het autorisatiemodel, maar zeker niet de enige entiteit noch middel betrokken in het autorisatiemodel. Het voorgestelde autorisatiemodel voor CareTeams is gebaseerd op onderstaande principes om een duidelijke en veilige autorisatiestructuur te garanderen:
Ambiguïteit bij meerdere rollen:
Scope van het CareTeam:
Rollen en Autorisatiematrix
Het CareTeam vormt het startpunt voor het autorisatiemodel. De rollen van de betrokkenen in het CareTeam bepalen welke rechten zij hebben op FHIR resources.
Huidige status:
Uitwerking per rol:
Let op: Deze modellen worden in de toekomst verder uitgewerkt en verfijnd op basis van praktijkervaring en feedback van leveranciers.
Task.owner moet lid zijn van minimaal één CareTeam voor de betreffende patiënt (dit kan een Practitioner, RelatedPerson of CareTeam zijn)Task.requester moet lid zijn van minimaal één CareTeam voor de betreffende patiëntTask.for) moet de patiënt zijn waarvoor het CareTeam is opgezetBij het aanmaken of wijzigen van Tasks moeten de volgende validaties plaatsvinden:
Task.owner validatie:
Task.owner MOET verwijzen naar een Practitioner, RelatedPerson of CareTeam
EN deze entiteit MOET lid zijn van (of zelf zijn) een CareTeam van Task.for (patient)
Task.requester validatie:
Als Task.requester is ingevuld:
MOET deze persoon lid zijn van een CareTeam van Task.for (patient)
Task.for (patient) validatie:
Als Task.for verwijst naar een Patient:
MOET er minimaal één CareTeam bestaan met CareTeam.patient = deze Patient
EN Task.owner en Task.requester moeten lid zijn van minimaal één van deze CareTeams
Bij gebruik van SMART on FHIR en HTI (Health Tools Interoperability) launches speelt autorisatie op launch-niveau:
sub (subject) in het HTI token voor de Patient, Practitioner of RelatedPerson die de applicatie startDeze aanpak biedt de flexibiliteit van externe autorisatiebeslissingen (via launch) gecombineerd met de veiligheid van rol-gebaseerde toegang (via CareTeam membership).
Voorbeeld Scenario: Launch van een activiteit
Situatie:
Launch door portaalapplicatie:
Portal initieert SMART on FHIR launch naar dagboek-applicatie
HTI Token bevat:
{
"iss": "https://portal.example.org",
"aud": "https://dagboek-app.example.org",
"jti": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"iat": 1733054400,
"exp": 1733054700,
"sub": "RelatedPerson/zoon-maria",
"patient": "Patient/maria-de-vries",
"resource": "Task/dagboek-invullen"
}
Autorisatie validatie:
sub (Zoon van Maria)Resultaat: De dagboek-applicatie wordt gelanceerd en Zoon van Maria krijgt toegang tot de Task "Dagboek invullen" voor zijn moeder. De autorisatie is gebaseerd op zijn lidmaatschap van het CareTeam, maar de launch beslissing wordt genomen door de portaalapplicatie.
Afwijzing scenario:
Als het token "sub": "RelatedPerson/vriend-van-maria" zou bevatten, en deze persoon is geen lid van het CareTeam, dan zou de launch worden afgewezen:
❌ Ongeldig: Vriend van Maria is geen lid van een CareTeam voor Maria de Vries
→ HTTP 403 Forbidden
→ Foutmelding: "User not authorized for this patient context"
Voor situaties waar meer granulaire autorisatie nodig is, kunnen sub-tasks worden gebruikt:
Deze aanpak biedt de structuur en traceerbaarheid van FHIR (via CareTeam en sub-tasks) voor fijnmazige autorisatiecontrole.
Voorbeeld Scenario: Sub-task voor specifieke toegang
Situatie:
Hoofdtaak met brede toegang:
{
"resourceType": "Task",
"id": "behandelplan-opstellen",
"status": "in-progress",
"intent": "order",
"for": {
"reference": "Patient/jan-jansen"
},
"owner": {
"reference": "Practitioner/dr-smit"
},
"description": "Behandelplan opstellen voor depressie"
}
→ Eigenaar: Dr. Smit (behandelaar) → Zichtbaar voor: Alle leden van CareTeam Jan Jansen met de rol die dat toestaat
Sub-task voor specifieke medewerker:
{
"resourceType": "Task",
"id": "vragenlijst-afnemen",
"status": "ready",
"intent": "order",
"partOf": [{
"reference": "Task/behandelplan-opstellen"
}],
"for": {
"reference": "Patient/jan-jansen"
},
"owner": {
"reference": "Practitioner/zorgondersteuner-klaas"
},
"requester": {
"reference": "Practitioner/dr-smit"
},
"description": "PHQ-9 vragenlijst afnemen"
}
→ Eigenaar: Zorgondersteuner Klaas (specifiek toegewezen) → Aanvrager: Dr. Smit (heeft sub-task gecreëerd)
Launch en autorisatie:
Scenario 1: Zorgondersteuner Klaas lanceert de vragenlijst-applicatie
HTI Token bevat:
{
"iss": "https://portal.example.org",
"aud": "https://vragenlijst-app.example.org",
"jti": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"iat": 1733054400,
"exp": 1733054700,
"sub": "Practitioner/zorgondersteuner-klaas",
"patient": "Patient/jan-jansen",
"resource": "Task/vragenlijst-afnemen"
}
Autorisatie validatie:
1. ✅ Zorgondersteuner Klaas is lid van CareTeam Jan Jansen
2. ✅ Task.owner = Practitioner/zorgondersteuner-klaas (exacte match)
3. ✅ Task.for = Patient/jan-jansen (komt overeen met CareTeam patient)
4. ✅ Launch toegestaan - Klaas is direct eigenaar van deze sub-task
Scenario 2: Dr. Smit (requester) wil de voortgang bekijken
HTI Token bevat:
{
"iss": "https://portal.example.org",
"aud": "https://vragenlijst-app.example.org",
"jti": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"iat": 1733054400,
"exp": 1733054700,
"sub": "Practitioner/dr-smit",
"patient": "Patient/jan-jansen",
"resource": "Task/vragenlijst-afnemen"
}
Autorisatie validatie:
1. ✅ Dr. Smit is lid van CareTeam Jan Jansen
2. ✅ Dr. Smit is requester van deze sub-task
3. ✅ Dr. Smit is owner van de parent task
4. ✅ Launch toegestaan - Smit heeft toegang als requester en behandelaar
Scenario 3: Verpleegkundige Peters probeert toegang te krijgen
HTI Token bevat:
{
"iss": "https://portal.example.org",
"aud": "https://vragenlijst-app.example.org",
"jti": "d4e5f6a7-b8c9-0123-def0-456789012345",
"iat": 1733054400,
"exp": 1733054700,
"sub": "Practitioner/verpleegkundige-peters",
"patient": "Patient/jan-jansen",
"resource": "Task/vragenlijst-afnemen"
}
Autorisatie validatie:
1. ✅ Verpleegkundige Peters is lid van CareTeam Jan Jansen
2. ⚠️ Peters is niet owner van deze specifieke sub-task
3. ⚠️ Peters is niet requester van deze sub-task
Beslissing: Afhankelijk van autorisatiebeleid:
- Optie A (restrictief): ❌ Toegang geweigerd - alleen owner/requester
- Optie B (permissief): ✅ Toegang toegestaan - alle CareTeam leden mogen taken inzien
Voordelen van sub-tasks:
Use cases:
Situatie:
Geldige Task:
{
"resourceType": "Task",
"status": "requested",
"intent": "order",
"for": {
"reference": "Patient/jan-jansen"
},
"owner": {
"reference": "Practitioner/dr-smit"
},
"requester": {
"reference": "Practitioner/zorgondersteuner-klaas"
}
}
✅ Geldig: Zowel owner als requester zijn lid van het CareTeam
Ongeldige Task:
{
"resourceType": "Task",
"status": "requested",
"intent": "order",
"for": {
"reference": "Patient/jan-jansen"
},
"owner": {
"reference": "Practitioner/dr-anderen"
}
}
❌ Ongeldig: Dr. Anderen is geen lid van een CareTeam voor Jan Jansen
De volgende besluiten zijn genomen voor het autorisatiemodel:
Onderscheid CareTeam structuur en autorisatie mechanismen ✅
Het CareTeam is één van de autorisatie-mechanismen, maar niet het enige:
Autorisatie mechanismen in Koppeltaal:
Deze mechanismen kunnen gecombineerd worden. Bijvoorbeeld: een Patiënt-specifiek CareTeam met fijnmazige toegang via sub-tasks en launches.
Voorbeeld combinatie:
CareTeam Type 2 (Patiënt-niveau):
├── CareTeam voor Jan Jansen
│ ├── Dr. Smit (behandelaar)
│ ├── Zorgondersteuner Klaas (zorgondersteuner)
│ └── Verpleegkundige Peters (zorgondersteuner)
│
└── Autorisatie op taak-niveau via:
├── Sub-task: "Vragenlijst PHQ-9"
│ └── Owner: Zorgondersteuner Klaas (specifiek)
│
└── Launch: HTI token met sub: Practitioner/zorgondersteuner-klaas
└── Launch beslissing: toegang tot specifieke sub-task