# Care Services Directory - Netherlands - Generic Functions for data exchange Implementation Guide v0.1.0

* [**Table of Contents**](toc.md)
* **Care Services Directory**

## Care Services Directory

| |
| :--- |
| *Page standards status:*[Draft](http://hl7.org/fhir/R4/versions.html#std-process) |

### Solution overview

Generic Function Addressing (GFA) follows the IHE [mCSD profile](https://profiles.ihe.net/ITI/mCSD/index.html) ([GF-Adressering, ADR-0](https://github.com/minvws/generiekefuncties-adressering/issues/166)). The [mCSD profile](https://profiles.ihe.net/ITI/mCSD/index.html) provides multiple options for deployment. This guide specifies the choices made for The Netherlands. Most impactful/striking choice are:

* using a combination of 'NL-core' and 'IHE mCSD' for the FHIR-profiles in this IG.
* using the Landelijke Register Zorgaanbieders (LRZa) as the source/master-list of all other sources.

Here is a brief overview of the processes that are involved:

1. Every care provider registers its addressable entities in an 'Administration Directory'. This IG distinguishes the actor['****Administration**** Directory'](#administration-directory)and the['****Query**** Directory'](#query-directory); in the IHE mCSD specification, these are both called a 'Directory'.
1. Every care provider registers the endpoint (URL) of its 'Administration Directory' at the LRZa registry (also an 'Administration Directory').
1. An 'Update Client' uses the LRZa ([GF-Adressering, ADR-7](https://github.com/minvws/generiekefuncties-adressering/issues/155)) and the care provider Administration Directories to consolidate all data into a 'Query Directory.'
1. A practitioner and/or system (EHR) can now use the Query Directory to search for resources defined within mCSD (for example: a practitioner searching for a healthcare service or a system searching for a specific endpoint)

![](careservices-overview-transactions.png)

This overview implies a decentralized architecture for many components. An important central component is the LRZa Administration Directory. For more detail on the topology of GF Adressing, see [GF-Adressering, ADR-5](https://github.com/minvws/generiekefuncties-adressering/issues/153). 
 Each component, data model, and transaction will be discussed in more detail.

#### Interoperability boundary

The **interoperability boundary** in this architecture lies at the Administration Directory. The Administration Directory is the publicly facing, standardized interface through which organizations expose their care services data to the ecosystem. Update Clients from any party can pull data from any Administration Directory using the standardized FHIR `_history` operation.

The Query Directory, by contrast, is a **local component**. Each party (vendor, region, network) runs its own Query Directory as a local cache of the consolidated data. The interface between an Update Client and its Query Directory, and between a Query Client and its Query Directory, are internal to that party's infrastructure. This is why these interfaces are specified as MAY rather than SHALL.

This design is analogous to mCSD [Use Case #3 (Cross-jurisdictional Site Management)](https://profiles.ihe.net/ITI/mCSD/volume-1.html#146423-use-case-3-cross-jurisdictional-site-management), where multiple Directories expose data and a central Update Client aggregates it. In GFA, every party can act as their own aggregator.

Note that when a party chooses to offer a Query Directory as a **publicly accessible service** (e.g., for a region or network), that Query Directory takes on the role of an mCSD Directory and should expose a standard FHIR query interface conforming to [ITI-90](https://profiles.ihe.net/ITI/mCSD/ITI-90.html).

#### Conformance to IHE mCSD

The table below maps GFA components to IHE mCSD actors and transactions. GFA constrains and extends the mCSD profile for the Dutch context; it does not relax required mCSD transactions on the interoperability boundary.

| | | | | | |
| :--- | :--- | :--- | :--- | :--- | :--- |
| Administration Directory | Directory (Update Option) | — | R (via`_history`) | — | Publicly facing; the interoperability boundary |
| Query Directory (internal) | — | — | — | — | Internal component; interface not prescribed |
| Query Directory (public) | Directory | R | O | — | When offered as a service, SHALL support ITI-90 |
| Update Client | Update Client | — | R | — | Pulls from Administration Directories |
| Query Client | Query Client | R | — | — | Queries a (local or public) Query Directory |
| LRZa | Directory (Update Option) | — | R (via`_history`) | O (subset) | Root registry; authoritative for URA-identified Organizations. May support ITI-130 for a subset of resources (Organization, Endpoint) |

**Data model conformance:** All FHIR resource profiles in this IG are based on both IHE mCSD profiles and NL-core profiles, adding Dutch-specific constraints (value sets, required identifiers) without relaxing mCSD requirements. See [Data models](#data-models) for details.

#### Participation by international implementers

An international party that implements IHE mCSD can participate in GFA in several ways:

* **As an Administration Directory:** Expose care services data via the FHIR `_history` operation so that Update Clients in the ecosystem can pull the data. This requires implementing the Administration Directory [capabilities](./CapabilityStatement-nl-gf-admin-directory-update-client.md) and registering at the LRZa.
* **As a consumer (self-hosted):** Run an Update Client and Query Directory to pull data from the ecosystem's Administration Directories. Open source implementations of these components are available (e.g., [Nuts-knooppunt](https://github.com/nuts-foundation/nuts-knooppunt/)) and can be deployed as a container, lowering the adoption barrier.
* **As a consumer (via a shared Query Directory):** The architecture allows for regional organizations, networks, or other parties to offer a shared Query Directory as a service. Such a publicly accessible Query Directory exposes a standard FHIR query interface conforming to [ITI-90](https://profiles.ihe.net/ITI/mCSD/ITI-90.html), meaning any mCSD-compliant Query Client can query it directly without needing to run its own Update Client or Query Directory. This also applies to national or sector-wide initiatives that choose to offer a Directory-as-a-Service.

The architecture does not prescribe whether Query Directories are operated locally, regionally, or nationally — it supports all models. This flexibility means that the ecosystem can evolve over time: parties can start with local Query Directories and later migrate to shared services, or vice versa.

### Components (actors)

#### Administration Directory

The Administration Directory persist all addressable entities of one or more healthcare organizations. The Administration Directory MAY implement [these capabilities](./CapabilityStatement-nl-gf-admin-directory-admin-client.md) for a client (e.g. a webportal for users) to create, update and delete resources.

The Administration Directory MUST implement [these capabilities](./CapabilityStatement-nl-gf-admin-directory-update-client.md) to publish changes of addressable entities. These changes are consumed by an [Update Client](#update-client). If the Administration directory also acts as the [Query Directory](#query-directory) locally, please make sure the Administration Directory only exposes data (externally) for which it is the original source (author/custodian). In other words; data that has been copied from the original source, SHOULD NOT be exposed to other organizations.

#### Update Client

The Update Client is responsible for aggregating and synchronizing addressable entity data from multiple Administration Directories. It periodically retrieves updates, including new, modified, or deleted records, and consolidates this information into a Query Directory.

The Update Client uses a [FHIR 'history-type' operation](http://hl7.org/fhir/R4/http.html#history) and (optionally) parameter `_since` to get updates from Administration Directories, for example:

```
GET https://somecareprovider.nl/fhirR4/Organization/_history?_since=2025-02-07T13:28:17.239+02:00&_format=application/fhir+json

```

Besides using the 'history-type' operation, the Update Client should be able to query all instances in the Administration Directory using a search operation. Either for the initial load or periodically for a full reload to fix edge-case scenario's (e.g. Administration Directory backup restores). ([GF-Adressering, ADR-14](https://github.com/minvws/generiekefuncties-adressering/issues/163))

During consolidation, multiple Administration Directories may have overlapping or conflicting entities. An Update Client MUST only use data from authoritative data sources ([GF-Adressering, ADR#186](https://github.com/minvws/generiekefuncties-adressering/issues/186)) and MUST obey these guidelines:

* The LRZa Administration Directory is authoritative for Organization instances with `identifier` of system `http://fhir.nl/fhir/NamingSystem/ura` (URA) and its `name`. When the healthcare provider's Administration Directory also provides a `name` value (for an Organization-instance with a URA-identifier), these values should be ignored. Other elements from the healthcare provider's Administration Directory should be added. This way, a healthcare provider can add an `alias` or `endpoint` using it's own Administration Directory.
* The LRZa Administration Directory contains a list of Organization resources (identified by a URA) and Endpoint resources referencing the Administration Directory endpoint (URL). An Administration Directory is only authoritative for the healthcare providers that registered this Administration Directory endpoint (URL) at the LRZa. Information about other healthcare providers MUST be disregarded. For example, if the LRZa Administration Directory has 20.000 Organization-records, of which 2 Organizations (identified by 'URA-1' and 'URA-2') use the same Administration Directory endpoint ('https://admindirectory.example.com/'). This Endpoint MAY contain other resources (e.g. Organization/Location/HealthcareService-records), not authored by URA-1 and URA-2. These other resources MUST be disregarded by update clients as this Administration Directory is not the authoritative source.
* All HealthcareServices, Locations, PractitionerRoles and Organization-entities of a single healthcare provider MUST (indirectly) link to a top-level Organization-instance with a URA-identifier: 
* All HealthcareService, Location, PractitionerRole entities MUST be directly linked to an Organization-instance (could be 'sub-Organization' like a department).
* All Organization-instances MUST either link to a parent-Organization or have a URA-identifier (being a top-level Organization instance)
* All Endpoint-instances MUST be linked to from one of the HealthcareService or Organization-instances.
 

After consolidation, the Update Client writes the updates to a Query Directory. The Update Client MAY use the same interactions a Administration Client uses to register entities in an Administration Directory.

##### Update Client Sync Example

The following sequence diagram illustrates how an Update Client performs a synchronization operation to consolidate data from multiple Administration Directories into a Query Directory:

#### Query Directory

The Query Directory persist all addressable entities it receives from the Update Client. The Query Directory MAY implement [these capabilities](./CapabilityStatement-nl-gf-admin-directory-admin-client.md) for an Update Client to create, update and delete resources. Due to the consolidation process of the Update Client, not all (intermediate) changes are replicated between Administration Directories and Query Directory

The Query Directory serves/exposes all addressable entities to one or more query clients (e.g. a webportal for users). The Query Directory MAY implement [these capabilities](./CapabilityStatement-nl-gf-query-directory-query-client.md) for a client to search and read resources.

The Query Directory interface is specified as MAY because it is a local component: each party runs their own instance and can optimize the query interface for their internal use case. When a Query Directory is offered as a publicly accessible service (e.g., for a region, network, or as a shared service), it SHOULD implement [these capabilities](./CapabilityStatement-nl-gf-query-directory-query-client.md) conforming to [ITI-90](https://profiles.ihe.net/ITI/mCSD/ITI-90.html). See [Interoperability boundary](#interoperability-boundary) for more context.

#### Query Client

The Query Client is used to search and retrieve information from the Query Directory, which contains consolidated data from all Administration Directories. It enables practitioners, EHR systems, and other healthcare applications to discover healthcare services, organizations, departments, locations, endpoints, or practitioners across the entire ecosystem. By querying the Query Directory, users can efficiently find up-to-date and authoritative addressable entities for care coordination, referrals, and electronic data exchange.

### Data models

Within GF Addressing, profiles are used to validate data. They are based on both mCSD-profiles and nl-core-profiles (TODO: use Nictiz nl-core package as soon as dependency-bug is fixed)([GF-Adressering, ADR#188](https://github.com/minvws/generiekefuncties-adressering/issues/188)). Ideally, these profiles are merged in the nl-core-profiles in the future. An overview of the **most common** elements and relations between data models:

![](careservices-datamodel.png)

A brief description of the data models and their profile for this guide:

#### Organization

Organizations are "umbrella" entities; these may be considered the administrative bodies under whose auspices care services are provided. An (top-level)Organization-instance has a URA `identifier`, `type`, `status`, and `name`. It may have additional attributes like `endpoint`. Departments of an institution, or other administrative units, may be represented as child Organizations of a parent Organization. The [NL-GF-Organization profile](./StructureDefinition-nl-gf-organization.md) is based on the NL-Core-Healthcare-Provider-Organization profile, adds the CBS Standaard Bedrijfsindeling (SBI) valueset, adds constraints from the mCSD-Organization profile and requires an author-assigned identifier.

#### Endpoint

An Organization may be reachable for electronic data exchange through electronic Endpoint(s). An Endpoint may be a FHIR server, an DICOM web services, or some other mechanism. The [NL-GF-Endpoints profile](./StructureDefinition-nl-gf-endpoint.md) has an extra value set constraint on `.payloadType` ([GF-Adressering, ADR-8](https://github.com/minvws/generiekefuncties-adressering/issues/156)) and adds constraints from the mCSD-Endpoint profile.

#### HealthcareService

Healthcare services are used to publish which (medical) services are provided by a (child) Organization. Examples include surgical services, antenatal care services, or primary care services. These services in `HealthcareService.type` can be extended by references to specific ActivityDefinitions and PlanDefinitions that are supported. The combination of a HealthcareService offered at a Location may have specific attributes including contact person, hours of operation, etc. The [NL-GF-HealthcareService profile](./StructureDefinition-nl-gf-healthcareservice.md) contains a value set constraint on `.type` and `.specialty` and an extension on `.type` to refer to Activity/PlanDefinitions. This profile also adds constraints from the mCSD-HealthcareService profile.

#### Location

Locations are physical places where care can be delivered such as buildings (NL: Vestiging), wards, rooms, or vehicles. A Location may have geographic attributes (address, geocode), attributes regarding its hours of operation, etc. Each Location is related to one (child) Organization. A location may have a hierarchical relationship with other locations (e.g. building > floor > room). The [NL-GF-Location profile](./StructureDefinition-nl-gf-location.md) is based on the NL-Core-Healthcare-Provider profile, adds constraints from the mCSD-Location profile and requires an author-assigned identifier.

#### PractitionerRole

PractitionerRole resources are used to define the specific roles, specialties, and responsibilities that a Practitioner holds within an Organization. PractitionerRole enables precise modeling of relationships between practitioners and organizations, supporting scenarios like assigning practitioners to departments, specifying their roles (e.g., surgeon, nurse), and linking them to particular healthcare services or locations. A PractitionerRole may have contact details for phone, mail, or direct messaging. The [NL-GF-PractitionerRole profile](./StructureDefinition-nl-gf-practitionerrole.md) is based on the NL-Core-HealthProfessional-PractitionerRole profile, adds constraints from the mCSD-PractitionerRole profile and requires an author-assigned identifier.

#### Practitioner

****This resource type is out-of-scope for this IG-version**** Practitioner is a health worker such as physician, nurse, pharmacist, community health worker, district health manager, etc. Practitioners have a name and may have qualifications (like in the Dutch BIG-register). The registry (Administration Directory) of Practitioners may be operated by the Dutch BIG-register or similar organizations. The [NL-GF-Practitioner profile](./StructureDefinition-nl-gf-practitioner.md)is based on the NL-Core-HealthProfessional-Practitioner profile and adds constraints from the mCSD-Practitioner profile.

#### OrganizationAffiliation

****This resource type is out-of-scope for this IG-version (waiting for [GF-Adressering, ADR#169](https://github.com/minvws/generiekefuncties-adressering/issues/169))****

OrganizationAffiliation resources are used to represent relationships between organizations, such as a software vendor managing the Endpoint that is used by a care provider. It could also be used the represent multiple care providers working together under some agreement (e.g. in a region). The [NL-GF-OrganizationAffiliation profile](./StructureDefinition-nl-gf-organizationaffiliation.md) is based on the mCSD-OrganizationAffiliation profile and requires an author-assigned identifier

### Security

The service provider of an Administration Directory must require mTLS. Qualified certificates from Qualified Trusted Service Providers (like PKIoverheid) should be trusted. ([GF-Adressering, ADR#178](https://github.com/minvws/generiekefuncties-adressering/issues/178))

### Example use cases

#### Use Case #1: Healthcare service Query

The patient, Vera Brooks, consults with her physician who recommends surgery. The physician can assist the patient in finding a suitable care provider, taking into consideration the location and specialty for orthopedic surgeons.

* Vera Brooks sees her family physician, Dr. West, regarding a recent knee injury.
* Dr. West diagnoses the problem as a torn ACL and decides to refer Vera to an clinic that provides orthopedic specialists.
* Dr. West uses her EHR query tool, which implements a Query Client to search for orthopedic healthcare services within 30km of Vera's home.
* The EHR retrieves the information from a Query Directory and displays it to Dr. West.
* Vera and Dr. West decide on the Orthopedic department at Hospital East; Dr. West prepares a referral.

#### Use Case #2: Endpoint Discovery

Dr. West just created a referral (for patient Vera Brooks from use case #1). The EHR has to notify Hospital East and the Orthopedic department of this referral. This may include some recurring requests:

* The EHR looks up the HealthcareService instance of the Orthopedic department at the Query Directory, fetches the related endpoints and checks if these support a 'Transfer of care' payload. The EHR sends the notification and referral-workflow continues.

### Roadmap for Care Services

#### Alternative Administration Directories

Currently, two types of Administration Directories are supported; LRZa as 'Root Administration Directory' and Care Providers having their 'Administration Directory'. In the Netherlands, there are other registries that don't fit in these two types, e.g.:

* [BIG-register](https://www.bigregister.nl/) is the authoritative source for (a part of the) Physicians/Practitioners and their qualifications.
* Medmij has a register (OCL) that lists (qualified) Endpoints for certain data exchanges. Registers like the Medmij-OCL may form the authoritative source for element Endpoint.payloadType.

These sources contain valuable information and may be added/integrated in the future.

#### Practitioner resource

Practitioner instances may contain private data (e.g. the name of a physician) and should be registered at an authoritative source (see [Alternative Administration Directories](#alternative-administration-directories)). This is currently out of scope.

#### OrganizationAffiliation resource

The OrganizationAffiliation resource may be added in the future to publish relationships between organizations. ([GF-Adressering, ADR#169](https://github.com/minvws/generiekefuncties-adressering/issues/169))

