FHIR Map
Category: Healthcare Standards
Node id: fhir-map
Maturity: beta
Risk tier: C
Standards: HIPAA, GDPR
Declarative table/JSON → FHIR R4 mapper: maps each record to one or more resources (target element path ← column, transform, constant), deterministic ids, references between the resources of a record, and a transaction or collection Bundle. Refused values are reported per record, never dropped.
What it does
- Declarative, reviewable row → FHIR R4 mapping edited in the Studio field mapper
- Several resources per record with references between them (Encounter.subject → Patient)
- Deterministic ids from key columns; repeated rows produce one resource; disagreeing rows are reported as conflicts
- Typed transforms for date, dateTime, instant, decimal, integer, boolean, code, URI and value maps
- FHIR R4 mandatory elements and required code bindings checked for common resources
Use cases
- Map a joined patients/episodes/lab results table to Patient, Encounter and Observation and store them in one transaction
- Map a vendor JSON document to a FHIR Patient for the viewer
- Produce a collection Bundle from landed rows for fhir-to-omop
Runtime
- Performance tier:
fast - Effect:
read
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
records | json | Yes | Rows to map: a list of objects (connector records), one object, or {records:[…]} |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
bundle | fhir-bundle | No | Bundle of every mapped resource; transaction entries are PUT Type/id (POST when no id template) |
resources | json | No | The mapped resources as a list, without bundle wrapping |
errors | json | No | One entry per refused value or rule: record index, resource mapping, element, source column, value, message |
stats | json | No | records, records_mapped, records_failed, resources per type, errors |
success | boolean | No | True when every record mapped without an error |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Resource Mappings | resources | array | Yes | One entry per resource each record produces, in order. References may point to any other entry by name. | ||
| Bundle Type | bundle_type | enum | No | transaction | transaction, collection | transaction to store with fhir-crud (operation transaction); collection to pass resources on (e.g. to fhir-to-omop) |
| Source Timezone | timezone | string | No | IANA zone of timestamps that carry none (e.g. Europe/Madrid). Unset: such timestamps are refused, not assumed UTC |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| On Record Error | on_error | enum | No | skip_record | skip_record, fail | skip_record: the record contributes nothing and is listed on errors; fail: any error fails the node |
Errors
| Code | Description |
|---|---|
INVALID_MAPPING | The mapping config is malformed (unknown resource type, bad path, unknown transform, missing value map, dangling reference) |
NO_RECORDS | Nothing is wired to the records port |
RECORD_REFUSED | With on_error=fail, at least one record had an invalid value, a missing required element or a conflicting id |
Runtime notes
- A record with any error contributes nothing to the bundle and appears on errors; success is false when any record failed
- Element paths are dotted FHIR element names with optional [n] indices; a source path may reach into nested JSON (person.name.family); an exact column name wins over a path
- An empty source leaves the element out unless the pair has a default; a default with no source is a constant
- No transform passes the value through unchanged; use date/dateTime/decimal/code to get validated FHIR primitives
- Patient.gender and other required-binding codes must already be FHIR codes — map local values with value_map; there is no built-in sex mapping (H/M differ between languages)
- A driver time value is taken with the zone the driver gave it; for TIMESTAMP WITHOUT TIME ZONE columns select text (e.g. TO_CHAR) and set timezone, or local times are labelled UTC
- Transaction entries are PUT Type/id when an id template is set (idempotent re-runs), POST otherwise
- Wire bundle to fhir-crud (operation transaction, port bundle) and to fhir-to-omop (port bundle)
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Something unclear? Send documentation feedback by email.