Skip to content

FHIR Mapping Language

FHIR Mapping Language parser and transformation utilities.

engine

Modules:

Name Description
abstract
core

FHIR Mapping Language Engine
group
registry

Registry for FHIR StructureMap resources.
rule
scope
source
target
transforms

Classes:

Name Description
FHIRMappingEngine

FHIRMappingEngine is responsible for executing FHIR StructureMap-based transformations
StructureMapRegistry

Registry for managing FHIR StructureMap resources.

FHIRMappingEngine

Path: fhircraft.fhir.mapper.engine.FHIRMappingEngine 

FHIRMappingEngine(structure_definition_registry: StructureDefinitionRegistry | None = None, structure_map_registry: StructureMapRegistry | None = None, factory: FHIRModelFactory | None = None, fhir_release: str = 'R5')

FHIRMappingEngine is responsible for executing FHIR StructureMap-based transformations between FHIR resources.

This engine validates, processes, and applies mapping rules defined in a StructureMap to transform source FHIR resources into target resources, supporting complex mapping logic, rule dependencies, and FHIRPath-based expressions.

Attributes:

Name Type Description
structure_definition_registry StructureDefinitionRegistry

Registry for resolvingFHIR StructureDefinitions.
structure_map_registry StructureMapRegistry

Registry for resolving FHIR StructureMaps.
factory FHIRModelFactory

Factory for constructing FHIR resource models.

Methods:

Name Description
execute

Executes a FHIR StructureMap transformation using the provided sources and optional targets.

execute 

execute(structure_map: StructureMap | StructureMap | StructureMap, sources: tuple[BaseModel | dict], targets: tuple[BaseModel | dict] | None = None, group: str | None = None) -> tuple[BaseModel | dict, ...]

Executes a FHIR StructureMap transformation using the provided sources and optional targets.

This method resolves structure definitions, validates input data, sets up the mapping scope, binds source and target instances to group parameters, and processes the entrypoint group to produce the mapped target instances.

Parameters:

Name Type Description Default
structure_map StructureMap | StructureMap | StructureMap

The StructureMap resource defining the transformation rules.

 required
sources tuple[BaseModel | dict]

Source data to be mapped, as a tuple of Pydantic models or dictionaries.

 required
targets tuple[BaseModel | dict] | None

Optional target instances to populate. If not provided, new instances are created as needed.

 None
group str | None

The name of the entrypoint group to execute. If not specified, the first group is used.

 None

Returns:

Name Type Description
tuple tuple[BaseModel | dict, ...]

A tuple of resulting target instances after the transformation, which can be a mixture of BaseModel instances and/or dictionaries.

Raises:

Type Description
MapperRegistryNotFoundError

If a non-wildcard import URL is not registered in the StructureMapRegistry.
ValueError

If a constant in the StructureMap is missing a name or conflicts with a model name.
RuntimeError

If the number of provided sources or targets does not match the group parameters, or if required targets are missing.
TypeError

If provided sources or targets do not match the expected types for the group parameters.

StructureMapRegistry

Path: fhircraft.fhir.mapper.engine.StructureMapRegistry 

StructureMapRegistry(fhir_release: FHIRRelease)

Registry for managing FHIR StructureMap resources.

Operates offline by default, caching StructureMaps in memory. When internet access is enabled it will fall back to downloading a StructureMap from its canonical URL if it is not already in-memory.

The public API mirrors :class:~fhircraft.fhir.resources.definitions.registry.StructureDefinitionRegistry.

Attributes:

Name Type Description
fhir_release FHIRRelease

FHIR release used when validating raw dicts (e.g. "R4", "R4B", "R5").
structure_maps_by_url Dict[str, StructureMapUnion]

In-memory manifest, keyed

Methods:

Name Description
add

Add a StructureMap instance to the registry.
from_dict

Validate a raw dictionary as a StructureMap, then add it to the registry.
get

Retrieve a StructureMap by its canonical URL.
enable_internet_access

Enable automatic internet download of unregistered StructureMaps.
disable_internet_access

Disable automatic internet download of StructureMaps.
download_url

Download JSON content from url, respecting proxy/certificate settings.
parse_canonical_url

Split a canonical URL into its base URL and optional version.

add 

add(structure_map: StructureMapUnion, fail_if_exists: bool = False) -> None

Add a StructureMap instance to the registry.

Parameters:

Name Type Description Default
structure_map StructureMapUnion

A validated StructureMap model instance.

 required
fail_if_exists bool

If True, raise :class:ValueError when the canonical URL is already registered.

 False

Raises:

Type Description
ValueError

If structure_map.url is not set, or if the map is already registered and fail_if_exists is True.

from_dict 

from_dict(data: Dict[str, Any], fail_if_exists: bool = False) -> StructureMapUnion

Validate a raw dictionary as a StructureMap, then add it to the registry.

Parameters:

Name Type Description Default
data Dict[str, Any]

Raw FHIR resource dict (or a Pydantic model).

 required
fail_if_exists bool

Forwarded to :meth:add.

 False

Returns:

Type Description
StructureMapUnion

The validated StructureMap model instance.

Raises:

Type Description
ValueError

If the dict does not conform to the expected StructureMap schema for the configured FHIR release.

get 

get(canonical_url: str) -> StructureMapUnion

Retrieve a StructureMap by its canonical URL.

Resolution order:

  1. In-memory manifest (version stripped from URL before lookup).
  2. Internet download — only when internet access is enabled (:meth:enable_internet_access).

Parameters:

Name Type Description Default
canonical_url str

The canonical URL of the StructureMap, optionally suffixed with a pipe-separated version (url|version).

 required

Returns:

Type Description
StructureMapUnion

The resolved StructureMap model instance.

Raises:

Type Description
MapperRegistryNotFoundError

If the StructureMap cannot be resolved and internet access is disabled (or the download fails).

enable_internet_access 

enable_internet_access() -> None

Enable automatic internet download of unregistered StructureMaps.

disable_internet_access 

disable_internet_access() -> None

Disable automatic internet download of StructureMaps.

download_url staticmethod 

download_url(url: str) -> Dict[str, Any]

Download JSON content from url, respecting proxy/certificate settings.

Uses the same environment variable conventions as :class:~fhircraft.fhir.resources.definitions.registry.StructureDefinitionRegistry.

Parameters:

Name Type Description Default
url str

The URL to fetch.

 required

Returns:

Type Description
Dict[str, Any]

Parsed JSON response body as a dictionary.

Raises:

Type Description
HTTPError

If the server returns an error status code.

parse_canonical_url staticmethod 

parse_canonical_url(canonical_url: str) -> Tuple[str, Optional[str]]

Split a canonical URL into its base URL and optional version.

Parameters:

Name Type Description Default
canonical_url str

URL of the form http://example.org/map or http://example.org/map|1.0.0.

 required

Returns:

Type Description
Tuple[str, Optional[str]]

A (base_url, version) tuple; version is None when absent.