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-07-11				Computable Name: CumuluzTranslateIG

Cumuluz Translate

One Sentence

cumuluz-translate translates registered profile-to-profile routes between Dutch STU3 and R4 healthcare exchange content, validates R4 output where applicable, and keeps the mapping rules visible.

What Is In Scope

The service has supported input families across multiple directions:

Input family	Main use	Operation
BgZ 2017 and dependent Dutch STU3 resource profiles	Translate one resource or a source Bundle to R4	POST /fhir/stu3-r4/$transform
PZP 2017 ACP resource profiles	Translate one ACP resource or supported Bundle entries to R4	POST /fhir/stu3-r4/$transform
Supported Dutch STU3 resource profiles	Translate one resource to a registered Dutch STU3 target	POST /fhir/stu3/$transform
Supported R4 resource profiles	Translate one resource back to a registered Dutch STU3 target	POST /fhir/r4-stu3/$transform
Supported R4 resource profiles	Translate one resource to another registered R4 target profile	POST /fhir/r4/$transform
PZP ACP QuestionnaireResponses	Extract one completed form into multiple R4 clinical resources	POST /fhir/$extract-questionnaire-response

The supported R4 output families are:

Output family	Use when
nl-core	The receiver expects Dutch R4 nl-core output
eu-base	The receiver expects European base/core profile output
EPS	The receiver expects European Patient Summary resources or an EPS document Bundle
PZP 2020 ACP	The receiver expects the matching PZP ACP R4 profile
base R4	No implemented nl-core, eu-base, EPS, or PZP target profile exists for that route

The exact supported pairs are listed in Translation Matrix. A route is supported only when that exact source profile and target profile pair is registered.

What Is Not In Scope

The service is not:

• a FHIR repository
• a generic resource or profile converter
• a generic QuestionnaireResponse converter
• a free-form mapping engine
• a service that silently changes target family when the requested route is missing

Unsupported input families, profile pairs, questionnaire definitions, and target profiles return a FHIR OperationOutcome.

Main Operations

Need	Endpoint	Result
Translate a supported STU3 resource or Bundle	POST /fhir/stu3-r4/$transform	FHIR Parameters with R4 result, translationReport, and optional validation outcome
Translate a supported PZP STU3 resource to Dutch STU3	POST /fhir/stu3/$transform	STU3 FHIR Parameters with STU3 result and optional logical Binary
Reverse translate a supported R4 resource	POST /fhir/r4-stu3/$transform	STU3 FHIR Parameters with STU3 result and optional logical Binary
Translate a supported R4 resource to R4	POST /fhir/r4/$transform	FHIR Parameters with R4 result, translationReport, and optional validation outcome
Extract resources from a supported ACP form	POST /fhir/$extract-questionnaire-response	FHIR Parameters with R4 Bundle result and OperationOutcome
Validate an R4 resource	POST /fhir/r4/$validate	FHIR OperationOutcome
Discover routes	GET /fhir/stu3-r4/translation-index	FHIR Bundle with registered source and target profile pairs
Discover STU3 routes	GET /fhir/stu3/translation-index	FHIR Bundle with registered Dutch STU3 profile pairs
Discover reverse routes	GET /fhir/r4-stu3/translation-index	FHIR Bundle with registered reverse source and target profile pairs
Discover R4 routes	GET /fhir/r4/translation-index	FHIR Bundle with registered R4 source and target profile pairs

Operation definitions are available at:

Operation	Endpoint
Transform	GET /fhir/stu3-r4/OperationDefinition/bgz-transform
STU3 transform	GET /fhir/stu3/OperationDefinition/stu3-transform
Reverse transform	GET /fhir/r4-stu3/OperationDefinition/r4-stu3-transform
R4 transform	GET /fhir/r4/OperationDefinition/r4-transform
QuestionnaireResponse extraction	GET /fhir/OperationDefinition/extract-questionnaire-response
R4 validation	GET /fhir/r4/OperationDefinition/r4-validate

CapabilityStatements are available at:

Surface	Endpoint
STU3-to-R4 translation	GET /fhir/stu3-r4/metadata
STU3-to-STU3 translation	GET /fhir/stu3/metadata
R4-to-STU3 reverse translation	GET /fhir/r4-stu3/metadata
R4 translation and validation	GET /fhir/r4/metadata

Mapping Model

All resource translations follow the same logical handoff:

source profile -> logical model -> target profile

STU3-to-R4 routes use:

STU3 source profile -> logical model -> R4 target profile

STU3-to-STU3 routes use:

STU3 source profile -> logical model -> STU3 target profile

Explicit reverse routes use the same logical handoff in the other direction:

R4 source profile -> logical model -> STU3 target profile

R4-to-R4 routes use:

R4 source profile -> logical model -> R4 target profile

The maps are explicit:

• source-to-logical StructureMaps for BgZ, PZP, and dependent Dutch STU3 source profiles
• R4-to-logical StructureMaps for registered reverse sources
• logical-to-target StructureMaps for nl-core, eu-base, EPS, PZP 2020, and base R4
• logical-to-BgZ/STU3 StructureMaps for registered reverse targets
• ConceptMaps for coded value translation, including ICPC-1-NL to SNOMED CT where configured

The HTTP layer selects routes and returns FHIR resources. It does not hide core mapping rules in controller code.

Prototype Status

This guide describes a prototype service. The mappings are tested and inspectable, but they are not clinically certified and must not be treated as production decision support.

Fast Reader Paths

Reader	Start here
Client implementer	Getting Started, then Transform or QuestionnaireResponse Extraction
Interface designer	Target Profiles, then Translation Matrix
XIB reviewer	XIB Profiles, then Artifacts
Validator user	Validate
Mapping reviewer	Mapping and Artifacts, then the generated Artifacts
Terminology reviewer	Concept Translation