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-04-01 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.

Who This Guide Is For

  • system integrators who need to submit BgZ or dependent Dutch STU3 resources for translation
  • API consumers who need a clear wire contract for transform and validate requests
  • maintainers who need the published contract to stay aligned with the Ktor runtime and mapping registry

Read This Guide In This Order

  1. Getting Started for local and hosted usage
  2. Transform for the cross-version translation contract
  3. Validate for the R4 validation contract
  4. Target Profiles for the meaning of nl-core 2020 and eu-base
  5. Logical Models for the intermediate semantic layer
  6. Structure Maps for the concrete mapping files
  7. Translation Matrix for supported source and target profile pairs
  8. Implementation Notes for the translation model and mapping architecture

Service Summary

The public API is split into two surfaces:

  • /fhir/stu3-r4 for cross-version translation operations and discovery
  • /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/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 the center of the design:

  • Patient
  • Problem (Condition)
  • Procedure

The service also currently supports:

  • FunctionalOrMentalStatus
  • AllergyIntolerance
  • Encounter
  • CareTeam
  • Appointment
  • MedicationRequest
  • MedicationStatement
  • MedicationDispense
  • Metadata to R4 Provenance

The Translation Matrix page lists the exact source and target profile combinations.