Use the FHIR $convert operation to transform a resource from one format or version to another, and handle version-specific differences between FHIR R4 and R4B resources
domain: hl7.org/fhir/R4 · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
POST to /\$convert with the source resource in the request body and Content-Type indicating the source format (e.g., application/fhir+json for FHIR R4)
Set Accept to the target format or include a targetFormat parameter if the server supports version-targeted conversion (e.g., from R4 to R4B)
Compare the converted resource against the source to identify fields that changed, were removed, or were mapped differently between versions
Focus on known R4-to-R4B differences: Citation, Evidence, and EvidenceReport are new in R4B; MedicinalProduct resources were restructured; Subscription moved to topic-based model
Validate the converted resource against the target version's profile using $validate on a server running the target FHIR version
Known gotchas
$convert is an optional FHIR operation and is not implemented by most production FHIR servers; it is primarily available in HAPI FHIR and similar open-source implementations
R4 to R4B version differences are relatively minor compared to R4 to R5; R5 introduced breaking changes in Subscription, DeviceDefinition, and several workflow resources that cannot be losslessly round-tripped
Format conversion (JSON to XML) is more widely supported than version conversion; do not assume a server that supports format $convert also supports version conversion
Give your agent this knowledge — and 16,300+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?