FUME Community (fume-fhir-converter) — v3

FUME Community is an open-source FHIR® conversion + mapping engine (and a standalone HTTP server) built around the FUME language.

What’s new in v3

This is a major release focused on correctness, diagnostics, and runtime scalability:

• Better automatic conformance (injecting system and display values), deeper structural and terminology validations
• Better diagnostics and behavior-control knobs (validation thresholds, throwLevel, etc.)
  • verbose mode returns a detailed evaluation report
• Improved caching and concurrency support
• Syntax improvements in the FUME language
• Accurate position pointers in errors
• File-based mappings (*.fume files) in addition to server-hosted StructureMap resources
• Improved performance

Quick links

• FUME Playground: https://try.fume.health
• Getting started (deployment + usage): docs/getting-started.md
• Migration guide (v2 → v3): docs/migration-guide.md
• Environment variables: docs/env-vars.md
• HTTP API (endpoints + verbose mode): docs/http-api.md
• Release notes: https://www.fume.health/docs/release-notes/community

TL;DR: a full FHIR resource from 3 numbers

This example turns a tiny JSON payload into a fully-conformant Blood Pressure Observation (InstanceOf: bp) and demonstrates FUME's automatic conformance (injected codes, units, etc.).

Expression:

Instance: $uuid()
InstanceOf: bp
* status = 'final'
* effectiveDateTime = $now()
* subject.identifier.value = mrn
* component[SystolicBP].value = systolic
* component[DiastolicBP].value = diastolic

Input:

{
	"mrn": "PP875023983",
	"systolic": 120,
	"diastolic": 80
}

Example output (one run). Note: id and effectiveDateTime will differ because they come from $uuid() and $now():

{
	"resourceType": "Observation",
	"id": "3c91d1da-894c-4e5e-b400-93121a2043e9",
	"meta": {
		"profile": [
			"http://hl7.org/fhir/StructureDefinition/bp"
		]
	},
	"status": "final",
	"category": [
		{
			"coding": [
				{
					"system": "http://terminology.hl7.org/CodeSystem/observation-category",
					"code": "vital-signs",
					"display": "Vital Signs"
				}
			]
		}
	],
	"code": {
		"coding": [
			{
				"system": "http://loinc.org",
				"code": "85354-9"
			}
		]
	},
	"subject": {
		"identifier": {
			"value": "PP875023983"
		}
	},
	"effectiveDateTime": "2026-02-16T23:50:49.527Z",
	"component": [
		{
			"code": {
				"coding": [
					{
						"system": "http://loinc.org",
						"code": "8480-6"
					}
				]
			},
			"valueQuantity": {
				"value": 120,
				"unit": "millimeter of mercury",
				"system": "http://unitsofmeasure.org",
				"code": "mm[Hg]"
			}
		},
		{
			"code": {
				"coding": [
					{
						"system": "http://loinc.org",
						"code": "8462-4"
					}
				]
			},
			"valueQuantity": {
				"value": 80,
				"unit": "millimeter of mercury",
				"system": "http://unitsofmeasure.org",
				"code": "mm[Hg]"
			}
		}
	]
}

How to run this example:

• Use the public playground. Paste input in the left pane, expression in the top-right pane, and watch the results in bottom-right pane
• HTTP server (ad-hoc): POST / with { fume, input }
• HTTP server (saved mapping): configure a mapping folder, save the expression as bpDemo.fume and POST /Mapping/bpDemo
• Node library: engine.transform(input, expression) or engine.transformVerbose(...)

See docs/getting-started.md and docs/http-api.md for copy/paste invocation snippets.

Use as a library (Node)

Create a FumeEngine and call transform():

import { FumeEngine } from 'fume-fhir-converter';

const engine = await FumeEngine.create({
	config: {
		FHIR_SERVER_BASE: 'n/a',
		FHIR_VERSION: '4.0.1',
		FHIR_PACKAGES: '[email protected]'
	}
});

const out = await engine.transform(input, expression);

Note: when embedding as a module, FUME does not read process.env / .env automatically. Pass config explicitly.

Run as an HTTP server

See docs/getting-started.md for deployment options, including Docker.

The HTTP API is documented here: docs/http-api.md

License

AGPL-3.0