TOP-KT-029 - Documenten delen

Beschrijving

De inzet van eHealth en blended care is breed ingebed in de zorg. Digitale interventies leveren waardevolle documenten op — zoals rapportages, ongestructureerde vragenlijst-uitkomsten en voortgangsverslagen — die essentieel zijn voor goede behandelbeslissingen. In de praktijk zijn deze documenten echter vaak opgesloten binnen afzonderlijke applicaties, wat leidt tot informatieversnippering en extra administratieve lasten.

Door documenten delen expliciet te ondersteunen binnen Koppeltaal ontstaat een uniforme en gestandaardiseerde manier om documenten uit interventies veilig en geautoriseerd over te dragen van de bronapplicatie (module) naar de dossierhouder (EPD). Hierbij wordt aangesloten op bestaande MedMij- en Nictiz-standaarden. Koppeltaal fungeert als orkestratie-, transport- en autorisatielaag — niet als opslagsysteem.

User stories

Met deze uitbreiding worden de volgende user stories mogelijk gemaakt:

• Als module-applicatie kan ik een document (bijvoorbeeld een rapportage of voortgangsverslag) dat voortkomt uit een digitale interventie beschikbaar stellen aan de dossierhouder.

• Als zorgverlener kan ik in de toewijzende applicatie (ECD/EPD) vooraf zien dat een digitale interventie een document oplevert, zodat ik weet dat mijn applicatie dit moet kunnen verwerken.

• Als dossierhouder (EPD) kan ik nieuwe documenten detecteren, veilig en geautoriseerd ophalen bij de bron, en archiveren in het patiëntdossier.

• Als bronhouder behoud ik de fysieke controle over het document en kan ik zien wanneer en door wie het is opgehaald.

FHIR Resources

Deze uitbreiding wordt gerealiseerd door toepassing van het DocumentReference resource; de documentinhoud zelf wordt als bestand door de bronapplicatie aangeboden. Het DocumentReference resource wordt aanvullend ingezet op de in de basis gedefinieerde resources (zie Topic 09).

De inhoud wordt uitgewisseld via één variant: externe referentie. attachment.url ("Uri where the data can be found") verwijst rechtstreeks naar het bestand zelf bij de bronapplicatie; een GET op die URL levert de ruwe bestandsinhoud, met een Content-Type die overeenkomt met attachment.contentType. Het document-endpoint is een regulier HTTPS-download-endpoint, geen FHIR-endpoint: attachment.url MAG NIET naar een FHIR Binary resource verwijzen (zie Overwogen alternatieven voor de onderbouwing); de bronapplicatie hoeft geen FHIR-server te zijn. De data blijft daarmee aan de bron; de Koppeltaal FHIR store bevat alleen de metadata in de DocumentReference. Inline base64 (attachment.data) wordt binnen Koppeltaal niet ondersteund.

De module genereert het document — typisch bij afronding van de interventie, maar desgewenst ook tussentijds.

Overwegingen

Uitwisselingspatroon: direct ophalen via de Koppeltaal FHIR store

Voor het overdragen van documenten van de module naar het EPD geldt direct ophalen via de Koppeltaal FHIR store als aangewezen route:

1. De module publiceert een DocumentReference in de Koppeltaal FHIR store.

2. Het EPD detecteert de nieuwe DocumentReference — via polling of een FHIR Subscription (zie Topic 06).

3. Het EPD haalt een access_token op bij de Koppeltaal authorization server en doet daarmee een GET naar de attachment.url bij de bronapplicatie (token als Authorization: Bearer …).

4. De bronapplicatie valideert het token via token introspection bij dezelfde authorization server (RFC 7662 /introspect; zie Topic 21). Pas na een geldige respons (active: true plus passende scopes) wordt het document geleverd.

Autorisatie blijft daarmee centraal bij Koppeltaal — de bronapplicatie hoeft geen eigen vertrouwensmodel te onderhouden. Dit patroon kent de minste orkestratie — er is geen aparte Notification Task — en houdt de data aan de bron: de fysieke controle over het bestand blijft bij de bronhouder, terwijl de DocumentReference — en daarmee alle metadata, autorisatie en signalering — in de Koppeltaal FHIR store blijft.

De PlantUML-bron van het sequencediagram is beschikbaar in input/images-source/documenten-delen-direct-ophalen.plantuml.

Overwogen alternatieven

Twee andere patronen zijn overwogen, maar niet aangewezen als standaardroute; daarnaast is een FHIR Binary-endpoint bij de bron als implementatie van het document-endpoint overwogen en vervallen. Ze worden hier gedocumenteerd zodat de afweging traceerbaar blijft en het onderwerp opnieuw opgepakt kan worden mocht de scope van Koppeltaal veranderen.

Notified Pull (niet gekozen)

In dit patroon — gebaseerd op de TA Notified Pull v1.0.1 van Nictiz — neemt de module het initiatief door het EPD actief te notificeren via een Notification Task. De Notification Task bevat verwijzingen naar de op te halen FHIR resources; het EPD haalt op eigen initiatief en tempo de data op bij de bron.

Notified Pull is aantrekkelijk door de aansluiting op de door Nictiz beheerde publieke standaard (netwerkzorg) en omdat het EPD geen polling of eigen Subscription hoeft in te richten. In de huidige Koppeltaal-scope — interventies binnen een al bekend behandelnetwerk waarin het EPD al synchroniseert via de Koppeltaal-store — voegt de Notification Task echter een extra orkestratielaag toe, terwijl detectie via Subscription/polling op de Koppeltaal-store volstaat. Mocht netwerkzorg- of cross-organisatie-uitwisseling later expliciet in scope komen, dan kan Notified Pull alsnog als optionele aanvulling worden gespecificeerd; de twee patronen sluiten elkaar niet uit.

De PlantUML-bron van het sequencediagram is beschikbaar in input/images-source/documenten-delen-notified-pull.plantuml.

Binary als losse resource in de Koppeltaal-store (niet gekozen)

In een eerder ontwerp is overwogen om het document niet als bestand bij de bronapplicatie te laten staan, maar als Binary resource — naast de DocumentReference — in de Koppeltaal FHIR store te plaatsen. Argumenten waren onder meer centrale token-validatie, automatische AuditEvents en geen eigen resource-server bij de bronapplicatie. Bij nadere beschouwing wegen zwaarwegende bezwaren hier tegenop:

• Dataminimalisatie en bronverantwoordelijkheid: gevoelige gezondheidsdata buiten de bronhouder plaatsen vergroot het aanvalsoppervlak en ondermijnt het principe dat de bronhouder verantwoordelijk blijft voor zijn data tijdens de uitwisseling.

• Verlies van het pull-signaal: bij direct ophalen weet de bronhouder wanneer en door wie het document is opgehaald — een nuttig signaal voor archiveringsstatus, bewaartermijnen en eigen audit. Bij dit alternatief verdwijnt dat signaal.

Dit alternatief blijft denkbaar als uitwijkmogelijkheid voor specifieke gevallen (bijvoorbeeld een bron die geen stabiel publiek endpoint kan aanbieden), maar is geen standaardroute van de Koppeltaal-specificatie.

FHIR Binary-endpoint bij de bron (vervallen)

In een eerdere versie was het toegestaan (geen eis) om het document-endpoint te implementeren als FHIR Binary-endpoint bij de bronapplicatie. Deze optie is volledig vervallen: attachment.url MAG NIET naar een FHIR Binary resource verwijzen. De overwegingen:

• Dubbel content type. Zowel Binary.contentType als attachment.contentType beschrijven het formaat van dezelfde inhoud. Dat is redundant en introduceert een conflictrisico: wat als de attachment een PDF aankondigt en de Binary een Word-document bevat? Zonder Binary is er één bron van waarheid — attachment.contentType, bevestigd door de Content-Type-header van het document-endpoint.

• Een FHIR resource wekt de verwachting van een FHIR API. Een Binary-URL suggereert dat de bron een FHIR-server is, met bijbehorende semantiek: versiegeschiedenis (_history/vread), zoekgedrag, een CapabilityStatement en FHIR-foutafhandeling (OperationOutcome). Van moduleleveranciers zou dan aanzienlijk meer verwacht worden dan het aanbieden van een enkele download-URL.

• Contentonderhandeling via de Accept-header. Een FHIR Binary-endpoint levert afhankelijk van de Accept-header óf de ruwe inhoud óf een FHIR-wrapper (JSON/XML met base64-inhoud); zie Binary — REST behavior. Dit gedrag moet door zowel bron als afnemer correct geïmplementeerd worden en is een bekende bron van interoperabiliteitsproblemen.

Samengenomen maakt dit de Binary-optie onnodig complex voor moduleleveranciers, terwijl een regulier HTTPS-download-endpoint volstaat.

Onveranderlijk en self-contained

Het bestand waarnaar een DocumentReference verwijst, moet onveranderlijk en self-contained zijn: de inhoud staat op zichzelf, zonder externe afhankelijkheden, en wijzigt na publicatie niet meer.

Er is geen verplicht bestandsformaat. Het kan een PDF/A-rapport zijn, maar net zo goed een geluidsopname, video of ander bestand — zolang het maar onveranderlijk en self-contained is. PDF/A is voor tekstdocumenten een goede keuze (fonts en resources zijn ingesloten en het is geschikt voor duurzame archivering in het EPD), maar het is geen eis.

Uit de onveranderlijkheid volgt een concrete regel: zodra een bestand is gepubliceerd, mag de inhoud op die attachment.url niet meer worden gewijzigd. Een eenmaal gepubliceerde versie is definitief. Een EPD dat het bestand heeft opgehaald en gearchiveerd, kan er zo op vertrouwen dat de inhoud achter die URL niet stilzwijgend verandert.

Ontstaat er binnen de beschikbaarheidstermijn (zie Beschikbaarheidstermijn en levenscyclus) een nieuwe versie, dan:

• publiceert de module het nieuwe bestand op een nieuwe URL — het bestaande bestand blijft ongewijzigd;

• werkt de module de bestaande DocumentReference bij (PUT of PATCH) zodat content.attachment.url naar het nieuwe bestand verwijst — inclusief een bijgewerkte attachment.hash en een nieuwe masterIdentifier (versie-identifier), indien die worden meegegeven;

• detecteert het EPD de bijgewerkte DocumentReference (polling of Subscription) en haalt de nieuwe versie op.

Binnen de beschikbaarheidstermijn wordt versiehistorie dus niet via aparte resources vastgelegd: een update van de bestaande DocumentReference naar een nieuwe bestands-URL volstaat; de store-interne historie blijft opvraagbaar via _history/vread. Een herziening ná de beschikbaarheidstermijn — bijvoorbeeld wanneer de patiënt in een draaideurscenario na maanden terugkeert — is wél een nieuwe DocumentReference, met een relatesTo-verwijzing naar haar voorganger; zie Versionering en versiestreams.

Versionering en versiestreams

Een documentreeks — "Diagnose Jan Jansen", met opeenvolgende versies over meerdere jaren — moet voor het EPD herkenbaar zijn als één stream. FHIR R4 biedt daarvoor twee complementaire identifier-elementen:

• identifier (0..*) — "Other identifiers associated with the document, including version independent identifiers." Hier hoort de reeks-identifier thuis: één versie-onafhankelijke identifier die alle versies in de stream delen, uitgegeven door de oorspronkelijke bron (bijvoorbeeld een UUID onder het naamsysteem van de module). Dit is het CDA-setId-patroon.

• masterIdentifier (0..1) — "Document identifier as assigned by the source of the document. This identifier is specific to this version of the document." De versie-identifier: door de bron uitgegeven en bij elke inhoudelijke versie vernieuwd — óók bij een update-in-place, waar de resource-id gelijk blijft.

Toegepast op de reeks "Diagnose Jan Jansen" — de situatie ná de herziening van 2025, waarbij dezelfde module de eerdere versies op superseded heeft gezet (zie hieronder voor het geval van een andere module):

Het EPD herkent de stream door te groeperen op de reeks-identifier — niet op title of bestandsnaam, die zijn mensgericht en instabiel — sorteert op date/creation, en gebruikt relatesTo als expliciete voorganger-verwijzing. De mechanismen versterken elkaar: de reeks-identifier groepeert óók wanneer een schakel in de relatesTo-keten ontbreekt; de versie-identifier maakt exacte herkenning en deduplicatie in het archief mogelijk, onafhankelijk van Koppeltaal-resource-ids. In FHIR R5 is masterIdentifier opgegaan in identifier en is een apart version-element toegevoegd; het hier gekozen patroon mapt daar één-op-één op.

Herziening na de beschikbaarheidstermijn. De oude DocumentReference is dan uitgedoofd (zie Beschikbaarheidstermijn en levenscyclus), maar bestaat nog. De module publiceert een nieuwe DocumentReference met dezelfde reeks-identifier, een nieuwe masterIdentifier en een relatesTo-relatie (code replaces) met een gewone, oplosbare referentie naar de oude; desgewenst draagt target.identifier daarnaast de masterIdentifier van de voorganger. Komt de herziening van dezelfde module (de eigenaar van de oude resource), dan zet die de oude DocumentReference op status = superseded; komt zij van een andere module, dan kan dat niet (resource-origin) en volstaat de relatesTo.

Toegestane relatiecodes. relatesTo.code heeft in R4 een required binding op DocumentRelationshipType — een gesloten set van vier codes; eigen codes zijn niet-conformant. Het profiel staat alle vier de codes toe. Drie ervan hebben een functie in de Koppeltaal-workflow: replaces (vervanging/herziening), appends (addendum; het origineel blijft geldig) en transforms (bewerking of omzetting, bijvoorbeeld formaat- of taalconversie). signs (ondertekening) is toegestaan — de code hoort bij de required binding — maar heeft binnen Koppeltaal geen logische functie: er is geen workflow die erop reageert; ontvangers mogen de relatie tonen of negeren. Relaties met een ándere semantiek passen niet in relatesTo; daarvoor is context.related het aangewezen element.

Herziening door een andere module. Een andere module(leverancier) kent de eerdere DocumentReference niet uit eigen administratie. Die kennis ligt bij het EPD: de toewijzer van de nieuwe interventie én de archiefhouder van het eerdere document. Het EPD reikt bij de toewijzing zowel de referentie naar het eerdere document als de reeks-identifier aan — kandidaat-mechanismen zijn Task.input en de launch-context (zie Open punten). De module hoeft de oude DocumentReference daarvoor niet te kunnen lezen: zij heeft alleen de referentie nodig, en die krijgt ze aangereikt.

Aanpassingen aan het DocumentReference-profiel

Koppeltaal definieert een eigen DocumentReference-profiel (KT2_DocumentReference) met de volgende aanvullende verplichtingen ten opzichte van het standaard FHIR R4 DocumentReference-resource:

Deze regels worden vastgelegd in het KT2_DocumentReference-profiel (FSH), met bijbehorende validatie via de IG-publisher. Niet-conformante resources worden op deze regels afgewezen.

Autorisatie

Let op — huidig versus toekomstig model. In het huidige Koppeltaal-autorisatiemodel worden applicaties geautoriseerd, niet individuele personen (zie Topic 05). Toegang tot een DocumentReference loopt daarmee via de applicatie-autorisatiematrix en is op dit moment niet gebonden aan de behandelrelatie. De binding aan de behandelrelatie hieronder beschrijft het toekomstige model; die wordt pas werkelijkheid zodra de persoonsgebonden autorisatie is geïmplementeerd.

In het toekomstige model is toegang tot documenten gebonden aan de behandelrelatie:

• Zorgverleners: alleen zorgverleners met een geldige behandelrelatie — vastgelegd in het CareTeam (zie Topic 27) — krijgen toegang tot documenten.

• RelatedPerson: personen betrokken bij de behandeling (ouders, mantelzorgers, wettelijk vertegenwoordigers; zie Topic 26) kunnen beperkte, doelgebonden en tijdgebonden inzage krijgen in documenten. Toegang vervalt automatisch bij het eindigen van de relatie, het intrekken van toestemming of het afsluiten van de behandeling.

• Logging: alle inzage en overdracht van documenten wordt gelogd en is auditeerbaar.

Het Koppeltaal-scope-model is gebaseerd op SMART on FHIR v2 scopes met query-parameters (zie Topic 16). Het patroon system/Resource.[crud]?param=value — al toegepast voor resource-origin — maakt het mogelijk om in een toekomstige iteratie filtering op bijvoorbeeld DocumentReference.type te ondersteunen. De concrete scope-syntax voor DocumentReference wordt vastgelegd in de Koppeltaal-autorisatiematrix (zie Open punten).

Token-validatie en data-owner-verificatie

Wanneer het EPD een externe attachment.url aanroept, ontvangt de bronapplicatie een GET-request met een Koppeltaal-uitgegeven access_token. De bronapplicatie introspecteert het token bij de Koppeltaal authorization server (zie Topic 21) en krijgt een set scopes terug. De regel is: de scope die het EPD nodig heeft om de DocumentReference te lezen geldt ook als toestemming om het bijbehorende bestand op te halen. Dezelfde permissie dekt zowel metadata als inhoud.

Data-owner verification — een succesvolle introspect (active: true plus passende scopes) is een noodzakelijke maar geen voldoende voorwaarde voor levering. De bronapplicatie MAY na een geldige introspect alsnog toegang weigeren of intrekken op basis van eigen beleid (bijvoorbeeld ingetrokken patiënt-toestemming, bron-specifieke regels, vermoeden van misbruik). In dat geval reageert de bron met 403 Forbidden en logt de afwijzing zelf.

Twee alternatieven zijn overwogen en niet gekozen:

• Een nieuwe, expliciete scope voor de documentinhoud (bijvoorbeeld documenten/content.read): zou toegang tot de inhoud loskoppelen van DocumentReference-toegang. Verworpen omdat het een onduidelijke status institutionaliseert (wel toegang tot de reference, niet tot de data) zonder een gebruiksscenario dat dat onderscheid nodig maakt.

• Uitbreiding van het introspect-endpoint met een scope-parameter (de bron vraagt aan Koppeltaal "mag deze client dit bestand ophalen?"): valt af. RFC 7662 definieert /introspect strikt als token-introspectie en kent geen request-parameters voor een per-resource autorisatiebeslissing. Een policy-decision-point hoort, indien ooit nodig, in een aparte voorziening (UMA-/PDP-pattern), niet in /introspect.

Beschikbaarheidstermijn en levenscyclus

De DocumentReference wordt niet na een vaste termijn uit de Koppeltaal FHIR store verwijderd. De 30-dagentermijn is een beschikbaarheidstermijn van de inhoud, geen bewaartermijn van de resource:

• Gedurende 30 dagen na publicatie (date) garandeert de bronapplicatie dat attachment.url de inhoud levert. Het EPD moet het document binnen deze termijn detecteren (polling of Subscription) en ophalen; daarna wordt de inhoud niet langer aangeboden.

• Na afloop van de termijn verwijdert de bronapplicatie — als resource-origin-eigenaar — de attachment.url uit de DocumentReference (een reguliere PUT/PATCH; de leegmaak-update). Zij mag het bestand daarna offline halen. De overige attachment-metadata (contentType, title, creation, size, hash) blijft staan.

• De DocumentReference zelf blijft bestaan als metadata-anker — nodig voor de relatesTo-verwijzingen bij langlopende versionering (zie Versionering en versiestreams) — en volgt de reguliere patiënt-levenscyclus: zij wordt opgeruimd via het opschoningsproces voor Patient-data, met de $purge-cascade als vangnet. Er is geen apart verwijderproces per DocumentReference.

De korte inhoudstermijn weerspiegelt de rol van Koppeltaal als orkestratie- en transportlaag, niet als langetermijn-archief: zodra het document is opgehaald en gearchiveerd in het EPD-dossier, hoeft de inhoud niet meer via de bron beschikbaar te zijn. Dat beperkt het aanvalsoppervlak, voorkomt dat de Koppeltaal-store de facto een tweede dossierstore wordt, en sluit aan op het principe dat de bronhouder verantwoordelijk blijft voor de inhoud.

FHIR-basis. De leegmaak-update steunt op de expliciete semantiek van het Attachment-datatype: alle elementen zijn optioneel (0..1), en over het ontbreken van data én url zegt de specificatie letterlijk: "If neither data nor a URL is provided, the value should be understood as an assertion that no content for the specified mimeType and/or language is available." Een attachment zonder url en zonder data betekent dus precies wat wij willen uitdrukken: het document bestaat (bestond), maar de inhoud is hier niet (meer) beschikbaar. De achterblijvende hash en size beschrijven de oorspronkelijke inhoud, waardoor de dossierhouder zijn gearchiveerde kopie blijvend kan verifiëren tegen wat de bron destijds heeft aangekondigd.

De levenscyclus in drie fasen: