Cumuluz Translate Implementation Guide
0.1.0 - ci-build

Cumuluz Translate Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Home

Official URL: https://translate-ig.cumuluz.dev/ig/ImplementationGuide/org.cumuluz.translate.ig Version: 0.1.0
Draft as of 2026-05-27 Computable Name: CumuluzTranslateIG

Cumuluz Translate

Purpose

This Implementation Guide describes the public FHIR contract for cumuluz-translate.

The service accepts Dutch STU3 source content, translates that content through an explicit logical layer, and returns R4 output that fits one of the supported target profiles.

This is a focused translation service. It is not a general FHIR repository and it is not a generic STU3-to-R4 converter.

The public contract is intentionally narrow. Multiple standards and versions may coexist during migration, but this guide documents only the routes the service actually supports.

For the source code and development history, see the source repository on dev.cumuluz.org.

Prototype warning

This repository is a prototype and must not be relied on in any production environment or for any production decision-making.

The mappings are development/prototype mappings. They are exercised by automated tests and runtime checks, but they have not been clinically certified or approved for production use.

The underlying specifications, target profiles, and implementation details may change completely without notice.

Any feedback is welcome! If you spot a gap, confusing page, or other improvement point, please report it in the source repository.

Who This Guide Is For

  • healthcare system integrators who need a bridge between different FHIR versions and profiles, so they can communicate through one uniform standard
  • parties defining FHIR information standards who want to understand how a focused translation service can sit between source and target profile families
  • maintainers who need the published contract to stay aligned with the Ktor runtime and mapping registry

It is also useful for teams that need to understand controlled version overlap: a current route can remain supported while the next route is introduced, but the service does not infer arbitrary translation pairs.

Read This Guide In This Order

  1. Getting Started for local and hosted usage
  2. Transform for the cross-version translation contract
  3. QuestionnaireResponse for extracting supported form responses into R4 resources
  4. Validate for the R4 validation contract
  5. Target Profiles for the meaning of nl-core 2020, eu-base, EPS, and PZP 2020 targets
  6. EHDS / EPS Coverage for implemented EHDS/EPS mappings and gaps across BgZ and PZP sources
  7. Logical Models for the intermediate semantic layer
  8. Structure Maps for the concrete mapping files
  9. Translation Matrix for supported source and target profile pairs
  10. Implementation Notes for the translation model and mapping architecture

Service Summary

The public API is split into three surfaces:

  • /fhir/stu3-r4 for cross-version translation operations and discovery
  • /fhir for QuestionnaireResponse extraction
  • /fhir/r4 for R4 validation and R4-facing metadata

The main endpoints are:

  • POST /fhir/stu3-r4/$transform
  • GET /fhir/stu3-r4/metadata
  • GET /fhir/stu3-r4/OperationDefinition/bgz-transform
  • GET /fhir/stu3-r4/translation-index
  • POST /fhir/$extract-questionnaire-response
  • GET /fhir/OperationDefinition/extract-questionnaire-response
  • POST /fhir/r4/$validate
  • GET /fhir/r4/metadata

If you need to understand the target families first, read Target Profiles before the translation matrix.

Design Principles

The service keeps the wire contract FHIR-shaped:

  • Parameters for transform requests and transform responses
  • CapabilityStatement for metadata
  • OperationDefinition for the transform contract
  • Bundle for the translation index
  • OperationOutcome for validation and errors

The runtime keeps mapping logic visible:

  • local logical models define the internal semantic handoff
  • StructureMaps define the source-to-logical and logical-to-target routes
  • profile choice is explicit in the request
  • the application layer orchestrates the route but does not hide mapping rules in controller code

Current Coverage

The first implemented concept set remains stable and heavily documented:

  • Patient
  • Problem (Condition)
  • Procedure

The service also currently supports:

  • FunctionalOrMentalStatus
  • AllergyIntolerance
  • Encounter
  • CareTeam
  • Appointment
  • MedicationRequest
  • MedicationStatement
  • MedicationDispense
  • Metadata to R4 Provenance
  • EPS Patient Summary resource targets and document Bundle assembly for supported source entries, with unsupported EHDS models tracked separately
  • PZP 2017 ACP profile-pair routes to matching PZP 2020 ACP targets
  • explicit PZP ACP routes to supported generic parent targets, including ACP-Patient to nl-core-Patient, patient-eu-core, and patient-eu-eps
  • QuestionnaireResponse extraction, currently registered for PZP ACP ACP-zib2017 STU3 and ACP-zib2020 R4 forms

The implemented resource set is intentionally limited. The guide documents the current supported routes rather than the full set of possible FHIR resources.

The Translation Matrix page lists the exact source and target profile combinations. The QuestionnaireResponse page explains the separate form-extraction workflow, because one completed form can produce multiple R4 clinical resources.