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

Logical Models

Logical Models

Why They Matter

The translation service does not map directly from STU3 source semantics into target profiles. It passes through a logical layer that keeps the shared meaning explicit and inspectable.

That logical layer is not an implementation detail hidden in code. The source definitions live in the repository's logical-models/ project, and the published IG includes the complete generated StructureDefinition set for the logical layer.

What Is Published

The published IG includes the full logical-model set from logical-models/input/fsh. The shared Common.fsh rule set is also copied into the IG build, but it does not publish as a StructureDefinition.

Patient:

• LogicalPatient
• LogicalPatientCommunication
• LogicalPatientCommunicationProficiency
• LogicalPatientContact
• LogicalPatientLink
• LogicalPatientNationality

Problem:

• LogicalProblem
• LogicalProblemBodySite
• LogicalProblemEvidence
• LogicalProblemStage

Procedure:

• LogicalProcedure
• LogicalProcedureBodySite
• LogicalProcedureFocalDevice
• LogicalProcedurePerformer

Functional or mental status:

• LogicalFunctionalOrMentalStatus
• LogicalFunctionalOrMentalStatusReferenceRange
• LogicalFunctionalOrMentalStatusComponent

AllergyIntolerance:

• LogicalAllergyIntolerance
• LogicalAllergyIntoleranceReference
• LogicalAllergyIntoleranceNote
• LogicalAllergyIntoleranceReaction

Encounter:

• LogicalEncounter
• LogicalEncounterParticipant
• LogicalEncounterReference
• LogicalEncounterHospitalization

CareTeam:

• LogicalCareTeam
• LogicalCareTeamParticipant

Appointment:

• LogicalAppointment
• LogicalAppointmentParticipant

Medication:

• LogicalMedicationRequest
• LogicalMedicationReference
• LogicalMedicationDosage
• LogicalMedicationStatement
• LogicalMedicationDispense
• LogicalMedicationPerformer

PZP ACP resource routes and reusable whole-resource models:

• LogicalConsent
• LogicalRelatedPerson
• LogicalPractitioner
• LogicalPractitionerRole
• LogicalCommunicationRequest
• LogicalDevice
• LogicalDeviceUseStatement
• LogicalGoal
• LogicalObservation

QuestionnaireResponse extraction:

• LogicalQuestionnaireForm
• LogicalQuestionnaireAnswer
• LogicalQuestionnaireTelecom
• LogicalExtractionBundle
• LogicalExtractionEntry

Metadata:

• LogicalMetadata
• LogicalMetadataAgent

Core Models

The most important logical models for the current implementation are:

• LogicalPatient
• LogicalProblem
• LogicalProcedure

These are the models that matter most for the initial supported concept set and they are the easiest place to understand the translation shape.

Model Shape

The logical models are intentionally close to the target-side meaning.

They:

• keep source-specific STU3 concerns out of the target maps
• carry profile context explicitly through sourceProfile and targetProfile
• normalize the names of shared fields so the target-side map can stay readable
• include Dutch-specific semantic additions only where the current implementation needs them

The PZP ACP profile-pair routes use the same logical-model approach. The models are resource-specific and reusable, not PZP-specific containers: for example, Consent routes pass through LogicalConsent, observation-based ACP choices pass through LogicalObservation, and health-professional routes pass through LogicalPractitioner or LogicalPractitionerRole.

QuestionnaireResponse extraction adds a small generic form layer. LogicalQuestionnaireForm stores named normalized answers and grouped telecom answers; the PZP maps assign names for the differing ACP-zib2017 and ACP-zib2020 linkIds. LogicalExtractionBundle is not a target resource model; it is an explicit extraction manifest that carries the logical clinical resource bodies that can be safely materialized before the logical-to-PZP 2020 maps run.

Where To Inspect The Artifacts

After a build, the generated logical model artifacts are available in the IG output and published as StructureDefinition pages for the full logical-model set.

The build also stages the generated JSON into a gitignored input folder so the IG Publisher can include them without polluting the repository history.

Recommended Reading Order

1. Target Profiles
2. Translation Matrix
3. Implementation Notes

That order shows the semantic contract before the concrete model details.