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

Bundle Translation

Bundle Translation

Bundle translation keeps related STU3 resources together while executing one registered STU3-to-R4 route per entry. It is available only at POST /fhir/stu3-r4/$transform.

Use EPS Document Output when the requested target is an EPS document Bundle. EPS adds Composition and document-completeness rules on top of this generic Bundle behavior.

Wire format

Send one UTF-8 JSON document with Content-Type: application/fhir+json and request the same media type with Accept.

The outer request uses the R4-style transform envelope and therefore uses valueCanonical for top-level profile parameters. The object in parameter[name=source].resource is parsed separately as a STU3 Bundle. Do not send the source as a JSON string, Binary, multipart part or separate HTTP body.

HTTP request body: R4-style Parameters JSON
└─ parameter[source].resource: STU3 Bundle

HTTP 200 body: R4 Parameters JSON
└─ parameter[result].resource: R4 Bundle

The complete synthetic request is published as Bundle transform request.

curl -sS \
  -H 'Accept: application/fhir+json' \
  -H 'Content-Type: application/fhir+json' \
  --data @ig/input/examples/bundle-transform-request.json \
  'http://localhost:8080/fhir/stu3-r4/$transform'

Every Bundle.entry.resource must declare a supported STU3 source profile in meta.profile. Bundle sources cannot use returnLogical, because a mixed Bundle has no single logical representation.

Select entry targets

Target selection follows this order:

1. the entry's translation-target-profile extension;
2. a matching registered PZP profile-pair inference;
3. the registered BgZ or dependent-Dutch default;
4. the top-level targetProfile fallback.

Place an explicit target extension on Bundle.entry.request:

{
  "url": "https://fhir.cumuluz.org/StructureDefinition/translation-target-profile",
  "valueUri": "http://hl7.eu/fhir/base/StructureDefinition/procedure-eu-core"
}

An entry target wins over the top-level fallback. Verify every resolved pair in the STU3-to-R4 translation index before sending the Bundle.

Response

HTTP 200 returns R4 Parameters containing:

The result Bundle is embedded directly in parameter[result].resource. It is not encoded as a string or attachment.

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "result", "resource": { "resourceType": "Bundle", "type": "batch", "entry": [] } },
    { "name": "translationReport", "resource": { "resourceType": "Parameters", "parameter": [] } },
    { "name": "outcome", "resource": { "resourceType": "OperationOutcome", "issue": [] } }
  ]
}

This shortened example shows the envelope. The live result contains the translated entries and full evidence.

Identity and failure behavior

The service preserves fullUrl identities and rebases internal references when needed. Duplicate identities, ambiguous aliases, unresolved references, unsupported entries and incompatible contained resources fail explicitly. Entries are not silently removed.

Request or route failure returns HTTP 400 with one R4 OperationOutcome as the complete response body. A Bundle fails as a unit; clients must not expect partial success entries.

Client checks

1. Parse the response as R4, regardless of the STU3 source version.
2. Confirm that every source entry has a translated result entry.
3. Verify all internal references against the resulting fullUrl set.
4. Inspect per-entry route, validation and loss evidence.
5. Reject report and none results when conforming exchange is required.