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

Mapping Model

Mapping Model

This page explains how an exact registered route becomes a target resource. Client integrations do not need to execute these artifacts themselves; use this page to review translation semantics or diagnose route evidence.

Execution model

exact source profile
  -> source-profile validation
  -> source-to-logical StructureMap(s)
  -> local Logical* model and logical validation
  -> route governance and loss policy
  -> logical-to-target StructureMap
  -> version-correct target validation
  -> FHIR response with route evidence

The endpoint determines the source and target FHIR versions. The registry then resolves the normalized sourceProfile + targetProfile pair. There is no resource-type fallback and a forward map is never run backwards.

The HTTP layer parses, selects, and returns FHIR resources. Mapping semantics belong in logical models, StructureMaps, and ConceptMaps rather than controllers or services.

Logical models

The local FHIR Logical Models are the semantic intermediate representation for registered STU3-to-R4, STU3-to-STU3, R4-to-STU3, and R4-to-R4 routes. They carry only the semantics needed by those routes. They are designed to align with relevant CumuluZ concepts but are not presented as governed GIM definitions: the registry does not declare a verified GIM canonical and version for every route.

Logical models are shared across profile families. The following rows show data categories, not a selection of supported profile families:

PZP ACP resource coverage

All 18 registered PZP 2017 STU3 to PZP 2020 R4 resource-profile pairs use 12 shared logical models. A logical model represents a resource's transferable semantics, so several ACP profiles can use the same model with different profile-specific StructureMaps. The table names the ACP profiles on both sides of each registered pair; the Translation Matrix lists their exact canonical URLs.

LogicalConsent and LogicalRelatedPerson are source-family-neutral intermediate models. Registered PZP sources also use them for targets such as nl-core-AdvanceDirective, nl-core-TreatmentDirective2, and nl-core-ContactPerson. Their Dutch zib-related semantics are therefore reusable, while ACP-specific qualifications stay explicit in the source and target maps. Reusing a logical model does not automatically register the reverse nl-core to PZP pair or imply that an arbitrary Consent or RelatedPerson meets an ACP target's requirements.

QuestionnaireResponse extraction is a separate operation. It normalizes form answers through LogicalQuestionnaireForm, LogicalQuestionnaireAnswer, and LogicalExtractionBundle; those are not additional single-resource profile-pair routes.

Source FSH is in logical-models/input/fsh. Generated logical StructureDefinition resources are available through Artifacts. The translation index and route evidence identify the logical canonical selected for a concrete route.

StructureMaps

StructureMaps make the source and target field rules inspectable. Shared groups reuse identical rules; they do not create profile inheritance.

All directories are under src/main/resources/mappings/structuremaps. The service parses FHIR StructureMap syntax and executes it with its deterministic local mapping runtime. Another StructureMap engine needs equivalent logical models, parser context, ConceptMaps, and target materialization behavior to produce the same result.

ConceptMaps and terminology

ConceptMaps are invoked by an explicit StructureMap rule when a field requires code translation or normalization. They are not a generic post-processing pass and the service does not infer a replacement code when no mapping exists.

Examples include ICPC-1-NL to SNOMED CT, Problem verification status, Patient relationship and language codes, and PZP answer normalization. ConceptMaps live in src/main/resources/mappings/conceptmaps; local terminology fragments live in src/main/resources/terminology.

Terminology resolution, structural mapping and profile validation are separate concerns. Missing terminology coverage remains visible as a mapping or validation issue.

Review one route

1. Find the exact pair in Discovery or the Translation Matrix.
2. Read every source wrapper and imported source group named by the index and route manifest.
3. Inspect the selected logical model, including cardinalities, choices, references and profile-specific fields.
4. Read the target map and each ConceptMap it invokes.
5. Compare maximal, collision and legacy fixtures with the route's governance and validation evidence.
6. Execute the route and match the returned artifact identities and stages to the reviewed route.

The translationReport groups mapped, changed, added, and deleted describe payload comparison. Semantic loss and permitted use come from the exact route's governance record. See Translation Contract.

Artifact locations