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

Discovery

Discovery

Discover capabilities and exact route pairs at runtime before constructing a request. The translation indexes are authoritative for executable pairs; the Translation Matrix is a generated human-readable summary.

Endpoints

Direction or operation CapabilityStatement OperationDefinition Translation index
STU3 to R4 GET /fhir/stu3-r4/metadata GET /fhir/stu3-r4/OperationDefinition/bgz-transform GET /fhir/stu3-r4/translation-index
STU3 to STU3 GET /fhir/stu3/metadata GET /fhir/stu3/OperationDefinition/stu3-transform GET /fhir/stu3/translation-index
R4 to STU3 GET /fhir/r4-stu3/metadata GET /fhir/r4-stu3/OperationDefinition/r4-stu3-transform GET /fhir/r4-stu3/translation-index
R4 to R4 GET /fhir/r4/metadata GET /fhir/r4/OperationDefinition/r4-transform GET /fhir/r4/translation-index
R4 validation GET /fhir/r4/metadata GET /fhir/r4/OperationDefinition/r4-validate not applicable
Questionnaire extraction GET /fhir/metadata where available GET /fhir/OperationDefinition/extract-questionnaire-response definition-based

Use a CapabilityStatement to discover operation availability, an OperationDefinition to read parameter cardinalities and FHIR types, and a translation index to select an exact route.

Inspect a translation index

curl -sS \
  -H 'Accept: application/fhir+json' \
  'http://localhost:8080/fhir/stu3-r4/translation-index'

The response is a FHIR Bundle of type collection. Every entry is a Parameters resource describing one executable source/target pair:

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "fullUrl": "urn:uuid:00000000-0000-4000-8000-000000000001",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          { "name": "concept", "valueString": "patient" },
          { "name": "strategy", "valueString": "structure_map" },
          { "name": "sourceProfile", "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/BgZ-Patient" },
          { "name": "logicalModel", "valueCanonical": "https://fhir.cumuluz.org/StructureDefinition/logical/LogicalPatient" },
          { "name": "sourceMap", "valueString": ".../Bgz2017PatientToLogicalPatient.map" },
          { "name": "targetProfile", "valueCanonical": "http://nictiz.nl/fhir/StructureDefinition/nl-core-Patient" },
          { "name": "targetMap", "valueString": ".../LogicalPatientToNlcorePatient.map" }
        ]
      }
    }
  ]
}

The UUID is response-local and must not be used as route identity. Match sourceProfile and targetProfile; retain the remaining fields for technical review. STU3 indexes use version-correct STU3 valueUri fields where R4 uses valueCanonical.

Client algorithm

  1. Choose the endpoint from the source and target FHIR versions.
  2. Fetch or refresh its translation index.
  3. Match normalized source and target canonicals exactly, including a declared version when present.
  4. Reject the client-side request when there is no single match.
  5. Build the operation request using the matching OperationDefinition.

For Bundles, repeat route selection for every entry. The top-level target may be a fallback, but an entry-level target extension and supported family inference can select a more specific route; see Bundle Translation. For the EPS Bundle target, also apply the EPS Document Output contract.