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

Translation Contract

Translation Contract

This page defines the technical rules shared by every registered translation route. Integrators need these rules to decide whether a response may continue through their system. Mapping and clinical reviewers use them to connect an API execution to the exact profiles, artifacts, validation stages and governance decisions that produced it.

Contract boundary

The service translates only an exact registered source-profile and target-profile pair. It supports registered STU3-to-R4, STU3-to-STU3, R4-to-STU3 and R4-to-R4 routes. A shared resource type, installed package, compatible base profile or logical model does not create a route.

The endpoint fixes the source and target FHIR versions. The normalized sourceProfile + targetProfile pair then selects one route. Unsupported or ambiguous pairs fail without resource-type fallback.

The service performs route selection, JSON parsing, explicit mapping, validation and route evidence. Transport security, authorization, filtering, persistence, pseudonymisation, orchestration and clinical acceptance belong to the integrating system.

Executable route

One route consists of:

• one exact source profile and source FHIR version;
• one local logical model;
• the ordered source-to-logical StructureMaps;
• one exact target profile and target FHIR version;
• one logical-to-target StructureMap;
• any explicitly invoked ConceptMaps;
• versioned validation, loss and use-context policy;
• maximal, collision, legacy and matrix test evidence.

The executable flow is:

FHIR Parameters -> version-specific source parser -> exact registry route
-> source-profile validation -> source-to-logical StructureMap(s)
-> logical-model validation -> route governance/loss policy
-> logical-to-target StructureMap -> target-profile validation
-> version-correct FHIR response and route evidence

Shared StructureMap groups are rule reuse, not profile inheritance. Forward maps are never automatically inverted. QuestionnaireResponse extraction has a separate form-normalization and extraction contract.

Semantic position

CumuluZ specifications use a GIM as the conceptual semantic anchor. This implementation executes through local FHIR Logical* models:

registered source profile -> local Logical* model -> registered target profile

The models carry the semantics required by registered routes and are designed to align with relevant CumuluZ concepts. They are not asserted to be governed GIM definitions because the registry does not identify a verified GIM canonical and version for every route. See Mapping Model.

Assurance and governance

The TranslationRegistry is the executable route selector. The checked governance catalog is the policy source. The generated registry manifest joins the route, profile and mapping artifacts with versioned evidence. Translation-index endpoints project the executable pairs for clients; the Translation Matrix is their readable summary.

Each route has a stable routeId, routeVersion, manifest version, artifact identities, lifecycle and ownership metadata, validation policy, use contexts and loss decisions.

R4-target routes return a translationReport. STU3-target routes carry equivalent route and stage evidence in their STU3 OperationOutcome. The mapped, changed, added and deleted groups compare payload values; they do not determine semantic loss.

Technical conformance means that the selected route passed its applicable technical gates in enforce mode. It does not mean clinical certification, fitness for every use context or clinical acceptance by the receiver.

What an integrator must verify

1. The exact profile pair exists in the direction-specific translation index.
2. The request and response use the endpoint's documented FHIR versions and JSON envelope.
3. The returned targetProfile is the intended profile.
4. No blocking OperationOutcome.issue is present.
5. The conformance mode and route identity match the intended workflow.
6. The route's loss decision and use context permit the receiving use case.
7. Bundle identities and references remain complete when multiple resources are exchanged.

What a reviewer must verify

1. The registry pair resolves through the declared profile hierarchy.
2. Every named source map, logical model, target map and ConceptMap matches the returned artifact identity.
3. Cardinality, choices, slices, extensions, terminology and references are covered by the maps.
4. Maximal, collision and legacy cases exercise the route-specific risks.
5. Source, logical, governance and target stages are visible in execution evidence.
6. Documented relaxations are narrow, logged and tied to a removal condition.
7. Clinical acceptance is recorded separately from executable technical status.

Specification status