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

Implementation Notes

Implementation Notes

Translation Shape

The runtime follows one consistent route:

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

The service is profile-aware on both sides.

It does not flatten the problem into a generic resource-to-resource conversion where every Patient, Condition, or Procedure is treated as equivalent regardless of profile semantics.

Why The Logical Layer Exists

The logical layer is the semantic handoff between source and target.

It exists to:

• normalize shared meaning across source and target families
• keep STU3 source concerns out of the R4 target maps
• keep Dutch profile-specific deltas visible
• support both nl-core and eu-base targets without pushing exceptions into the HTTP layer

Mapping Assets

The main mapping assets live under:

• src/main/resources/mappings/structuremaps/zib2017-to-logical
• src/main/resources/mappings/structuremaps/nlcore2017-to-logical
• src/main/resources/mappings/structuremaps/bgz2017-to-logical
• src/main/resources/mappings/structuremaps/logical-to-eubase
• src/main/resources/mappings/structuremaps/logical-to-nlcore
• src/main/resources/mappings/structuremaps/logical-to-r4

The logical model definitions live under:

• logical-models/input/fsh

The published IG also includes the generated logical StructureDefinition artifacts so readers can inspect the actual intermediate model pages.

For the concrete map inventory, see Structure Maps. For the intermediate semantic layer, see Logical Models.

Runtime Boundaries

The HTTP layer is intentionally thin.

It is responsible for:

• route handling
• parsing requests
• serializing FHIR responses
• turning failures into OperationOutcome

The translation layer is responsible for:

• finding the exact source and target profile route
• executing the source-to-logical and logical-to-target maps
• optionally invoking validation

The validator is responsible for:

• checking the translated R4 result against the requested target profile
• returning a useful OperationOutcome

Discovery Model

Clients can discover the service in three different ways:

1. CapabilityStatement at /fhir/stu3-r4/metadata
2. OperationDefinition at /fhir/stu3-r4/OperationDefinition/bgz-transform
3. translation-index Bundle at /fhir/stu3-r4/translation-index

The translation-index endpoint is especially useful when a client needs a machine-readable inventory of supported pairs instead of a narrative guide.

Current Practical Limits

This guide documents what the service actually supports now.

That includes:

• a stable core around Patient, Problem, and Procedure
• additional Dutch STU3 dependent profile routes where BgZ exchange depends on them
• base R4 targets where no installed nl-core or eu-base profile is available for that route

This keeps the IG honest. It should describe the current contract first, then leave room for future expansion.