Ga naar hoofdinhoud

Localization Structure

(c) Stichting Decentrale Communicatie in de Zorg (Decozo), 2026.

Distribution of this documentation other than via the Decozo website decozo.org is not allowed, see https://drafts.decozo.org/docs/licentie (in Dutch) for more information.

This page is part of the Push authorisation (PA) documentation. It describes the structure of a Localization Structure (LS) as exchanged through PA-URLs.

It does not describe how localization structures are created, managed, or registered. It only defines the document structure that a source returns when a PA-URL refers to an indirect reference.

Concept​

A localization structure is a document that contains a set of PA-URLs.

Instead of pointing directly to a single source document, a PA-URL can point to an indirect reference. The indirect reference is resolved by fetching the localization structure. The recipient then processes the PA-URLs listed in that structure.

This allows one authorization to represent a collection of source references, for example a set of records for the same patient that are held by different systems or that use different document types.

The PA-URL schema itself is described separately in the Decozo draft: https://drafts.decozo.org/docs/push-authorization-schema.

Indirect Reference PA-URL​

A localization structure is retrieved through a PA-URL whose document type indicates an indirect reference.

For example:

https://dvpa-s.example.test/mdlink-rc0/8f3a9c4d1e2f4567890abcdeffedcba0/r:dtype=INDIR-REF/r:dformat=JSON/expiry=1767225600

The exact PA-URL path format is defined by the PA-URL schema. For localization structures, the important semantic property is that the PA-URL identifies an indirect reference rather than a regular source document.

JSON Structure​

A localization structure is represented as JSON.

{
  "id": "localization-structure-123",
  "urls": [
    "https://dvpa-s-a.example.test/mdlink-rc0/11111111111111111111111111111111/r:dtype=PS%2BAMO/r:dformat=MEDEUR/expiry=1767225600",
    "https://dvpa-s-b.example.test/mdlink-rc0/22222222222222222222222222222222/r:dtype=AMH/r:dformat=MEDEUR/expiry=1767225600"
  ]
}

Fields​

  • id (string) required
    Identifier of this localization structure. The identifier is assigned by the source that serves the localization structure.
  • urls ([]string) required
    List of PA-URLs contained in the localization structure. Each URL is an independent PA-URL and must be processed according to the PA-URL API and the PA-URL schema.

URL Semantics​

Each entry in urls is a complete PA-URL.

Clients MUST treat every URL as an opaque authorization endpoint. Clients MUST NOT rewrite, reorder, normalize, or otherwise modify the path segments of these URLs.

Each PA-URL in the list can point to a different source system. Each PA-URL has its own document type, document format, expiry, binding rules, and policy.

The localization structure itself does not grant access to the underlying documents independently of the PA-URLs it contains. Access to each referenced document is still governed by the policy and binding rules of that specific PA-URL.

Processing Model​

A recipient processes a localization structure as follows:

  1. Retrieve the indirect-reference PA-URL.
  2. Parse the returned JSON object.
  3. Iterate over the urls array.
  4. For each URL, treat it as an independent PA-URL.
  5. Use the PA-URL API to fetch the document or perform allowed actions.

A recipient may store the contained PA-URLs as separate authorizations. In that case, each contained PA-URL should keep its own metadata derived from the PA-URL and from any metadata supplied alongside the original authorization flow.

Example Flow​

The recipient receives an indirect-reference PA-URL:

https://dvpa-s.example.test/mdlink-rc0/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/r:dtype=INDIR-REF/r:dformat=JSON/expiry=1767225600

The recipient retrieves it:

GET /mdlink-rc0/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/r:dtype=INDIR-REF/r:dformat=JSON/expiry=1767225600
Host: dvpa-s.example.test

The source returns the localization structure:

200 OK
Content-Type: application/json
{
  "id": "locstruct-2026-001",
  "urls": [
    "https://dvpa-s-gp.example.test/mdlink-rc0/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/r:dtype=PS%2BAMO/r:dformat=MEDEUR/expiry=1767225600",
    "https://dvpa-s-pharmacy.example.test/mdlink-rc0/cccccccccccccccccccccccccccccccc/r:dtype=AMH/r:dformat=MEDEUR/expiry=1767225600"
  ]
}

The recipient then treats both URLs as separate PA-URLs:

GET /mdlink-rc0/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb/r:dtype=PS%2BAMO/r:dformat=MEDEUR/expiry=1767225600
Host: dvpa-s-gp.example.test
GET /mdlink-rc0/cccccccccccccccccccccccccccccccc/r:dtype=AMH/r:dformat=MEDEUR/expiry=1767225600
Host: dvpa-s-pharmacy.example.test

Notes​

The order of URLs in the urls array does not imply priority.

A localization structure may contain PA-URLs issued by the same source as the localization structure, or copied PA-URLs that point to other sources.

Laatst bijgewerkt op