Skip to main content

Zorginzage V6 hackathon spec

This document is in DRAFT

Purpose

The purpose of the hackathon is to demonstrate a simple implementation of Nuts Zorginzage in Nuts V6. The present Nuts Zorginzage 2022 spec uses Nuts V5, but has several limitations, which is why the intention is to make use of Nuts V6 in the future. This hackathon is the stepping stone towards creating V6 Zorginzage usecases in the future.

Scope

  • add Maarten's draft of the scope with some clarifications what is out of scope and what is optional. To be enriched with more specific plans of participating vendors.

Functional design

Discovery Service (adressbook & use-case whitelist)

The Discovery Service serves the function of an adressbook for the organizations that are compliant and available for this specific usecase. Organizations can periodically publish themselves by presenting a set of Verifiable Credentials to the DS. Which credentials should be presented is part of the governance of the use-case. To automatically select these credentials from the organization wallet a query must be agreed upon and ran on each node. The syntax of this query must follow the Presentation Defenition of the PEX specification

For more info about how the DS works see the following presentation of a Nuts Tech session

Presentation definition

Verifiable Credential

The PDs credibility is determined by the combined assurance level of the required credentials (VC). During the hackathon, only one verifiable credential, NutsUraCredential will be used. This is very similar to the Nuts Organization Credential (RFC012), but the primary difference is that it is no longer issuer by the vendor, but rather issued by a trusted authority. Also it uses the URA number instead of the KVK number as primary identifier.

The contents of the new 2024 version of the NutsUraCredential will be discussed in this Github Issue #3324.

{
  "id":"did:nuts:123#demo-uracredential",
  "type": [
    "VerifiableCredential",
    "NutsUraCredential"
  ],
  "issuer":"did:tdw:cibg-issuer",
  "credentialSubject": {
    "@id":"did:nuts:123",
    "@type":"Organization",
    "legalName": "De Regenboog",
    "memberOf": {
      "@type": "ProgramMembership",
      "membershipNumber": "12345",
      "programName": "UZI Register Abonnee"
    }
  }
}
Credential issuer:

There will be one trusted party that issues these VCs to the organization wallets. The issuer needs a piece of software to issue credentials. There are a few available implementations which can issue such a credential.

TODO: choose a platform for issueing credentials.

The authority that will spin it up and issue the credentials for the hackathon can be anyone.

TODO: choose a party who issues NutsUraCredentials

Zorg bij jou can pick up this role, the needed software is part of https://github.com/nuts-foundation/nuts-admin

Service Definition

TODO: We need to finalize the Service Definition

{
  "id": "hackathon_v2024.10",
  "endpoint": "https://example.com/usecase/hackathon/v2024.10",
  "presentation_max_validity": 259200,
  "presentation_definition": {
    "id": "pd_care_organization",
    "format": {
      "ldp_vc": {
        "proof_type": ["JsonWebSignature2020"]
      },
      "ldp_vp": {
        "proof_type": ["JsonWebSignature2020"]
      }
    },
    "input_descriptors": [
      {
        "id": "1",
        "constraints": {
          "fields": [
            {
              "path": ["$.type"],
              "filter": {
                "type": "string",
                "const": "NutsUraCredential"
              }
            },{
              "id": "name",
              "path": ["$.credentialSubject.legalName"],
              "filter": {
                "type": "string"
              }
            },{
              "id": "ura",
              "path": ["$.credentialSubject.memberOf.ura"],
              "filter": {
                "type": "string"
              }
            }
          ]
        }
      }
    ]
  }
}

PD logistical information

Alongside the VCs in the presentation definition, there following logistical information must also be presented

  • Usecase ID:
  • Max validity: 60 minutes
  • Server endpoint
  • ?

TODO: choose a party who will host the Discovery Service during the Hackathon

Endpoint discovery

In order to request data, the requestor needs to interact with several services. Once a source has been located, the services as defined in the DID Document of the source will be used to discover their endpoints. For more context see the documentation about endpoint-discovery.

{
  "services": [
    {
      "id": "#hackathon_v2024.10",
      "type": "fhir-api",
      "serviceEndpoint": {
        "api": "https://fhir.example.com/api/",
        "auth": "https://auth.example.com/auth"
      }
    }
  ]
}

Localization

By localization we mean “finding out where a patient is in treatment”. That will not be in scope for this hackathon. Instead, we will request directly to the other organizations in the discovery service without checking/finding out if there is a patient file there.

Okay, Zorg bij jou could also host a service where every organization can check which other organizations have a care treatment with the patient by hosting CareTeam FHIR-resources.

Data-access policies

Wheter or not a requestor gets access to the data they are requesting depends on whether they pass the access-polices of the source (bronhouder). To ensure interoperability, a uniform standard for the data-acces policies is described for each usecase. The intention for the hackaton is to define this in the Open Policy Agent (OPA) scripting language. The Policy Decision will be based on input such as the identity of the requesting organisation and practitioner, a legal basis such as a patient consent and if the requestor is part of the care team. During the hackathon we reduce complexity, and only use the organisation identity using the NutsUraCredential.

Practitioner identification & authentication

The practitioner that initiates the request must be identifiable so that it can be verified at a later moment, who initiated what action (in line with NEN7513). Just having the identification information present has been deemed insufficient because that lacks the proof that a human performed an action (as opposed to a machine). To ensure the action is preformed by a human, an Employee Identity Credential can be used and checked in the data-access policy.

During the hackathon we can choose to see this as a nice-to-have and not required.

  • tbd^

Authorization policy (checking legal base)

It is the responsibility of the source to check whether the requestor has a legal-base for accessing the data. A legal-base can be implied or be in the form of a explicit patient consent.

During the hackathon we can choose to see this as a nice-to-have and not required.

  • tbd^

Technical implementation

  • Design an OPA policy
  • Decide on error-responses for authorization

Access token specification

Access tokens follow the format of the Nuts v6 tokens: Example AccessToken introspection

Resources

The aim of the hackathon is model a simple data-request and validate each step in the proces. Therefore the set of resources is deliberately limited to a nl-core-patient.

Technical design

  • Todo: sequence diagrams
  • Todo: architecture map
  • Todo: specifying VC schemas
Back to top