FHIR Model Factory¶

Main class and utilities for dynamically constructing FHIR resource models.

factory ¶

FHIR Resource Factory — public API package.

Modules:

Name	Description
`assembler`	Module responsible for assembling Pydantic models from the internal definition index using a chain of builders.
`builders`
`context`	Module defining the BuildContext dataclass, which serves as an immutable container for contextual information during the FHIR structure building process in the factory pipeline.
`core`	FHIRModelFactory — the top-level façade for building Pydantic models from FHIR `StructureDefinition` objects.
`element_node`	ElementNode — a frozen, computed-property wrapper around a single FHIR ElementDefinition.
`index`	DefinitionIndex — flat, dict-based index of :class:`ElementNode` objects.
`resolver`	SnapshotResolver — turns any StructureDefinition into a complete

Classes:

Name	Description
`FHIRModelFactory`	FHIRModelFactory constructs Pydantic model classes from FHIR StructureDefinitions.

FHIRModelFactory
Path: `fhircraft.fhir.resources.factory.FHIRModelFactory`
¶

FHIRModelFactory(fhir_release: str, registry: StructureDefinitionRegistry | None = None)

FHIRModelFactory constructs Pydantic model classes from FHIR StructureDefinitions.

The factory manages a registry of StructureDefinitions, supports loading FHIR packages, and caches constructed models to optimise performance.

Attributes:

Name	Type	Description
`fhir_release`	`str`	The FHIR release version (e.g. "R4", "R5") used by the factory.
`definition_registry`	`StructureDefinitionRegistry`	Registry for storing and retrieving StructureDefinitions.
`construction_cache`	`dict[str, type[BaseModel]]`	Cache mapping canonical URLs to constructed Pydantic model classes.

Methods:

Name	Description
`build`	Constructs and returns a Pydantic model class based on a FHIR StructureDefinition.
`register_package`	Download and register all StructureDefinitions from a FHIR npm package.
`register`	Register a StructureDefinition with the factory.
`unregister`	Remove a StructureDefinition from the registry and evict it from the cache.
`reset_cache`	Discard the entire construction cache.
`has_registered_definition`	Return `True` if url is present in the definition registry.
`get_registered_definition`	Retrieve a registered StructureDefinition by canonical URL.
`list_registered_definitions`	Return all canonical URLs registered in the definition registry.
`is_built`	Return `True` if a model for url is present in the construction cache.
`list_built`	Return all canonical URLs whose models are currently cached.
`evict`	Remove a single entry from the construction cache.
`rebuild`	Evict url from the cache and build a fresh model.
`enable_internet_access`	Allow the definition registry to resolve unknown URLs from the internet.
`disable_internet_access`	Prevent the definition registry from making any outgoing HTTP requests.

build ¶

build(structure_definition: Any = None, *, canonical_url: str | None = None, mixins: Sequence[type] | None = None, mode: Literal['auto', 'snapshot', 'differential'] = 'auto') -> type[BaseModel]

Constructs and returns a Pydantic model class based on a FHIR StructureDefinition.

Parameters:

Name	Type	Description	Default
`structure_definition`	`Any`	The FHIR StructureDefinition object to build the model from.	`None`
`canonical_url`	`str`	The canonical URL of the StructureDefinition to retrieve from the registry.	`None`
`mixins`	`Sequence[type]`	Additional mixin classes to include in the generated model.	`None`
`mode`	`Literal['auto', 'snapshot', 'differential']`	The mode for building the model. "auto" selects the best mode automatically, "snapshot" uses the snapshot representation, and "differential" uses the differential representation.	`'auto'`

Returns:

Type	Description
`type[BaseModel]`	type[BaseModel]: The constructed Pydantic model class.

Raises:

Type	Description
`KeyError`	If neither structure_definition nor canonical_url is provided, or if the canonical_url is not found in the registry.

Notes

Uses a cache to avoid rebuilding models for the same StructureDefinition URL.
If both structure_definition and canonical_url are provided, structure_definition takes precedence.

register_package ¶

register_package(package_name: str, version: str, skip_invalid: bool = False, include_dependencies: bool = True) -> None

Download and register all StructureDefinitions from a FHIR npm package.

Parameters:

Name	Type	Description	Default
`package_name`	`str`	Package identifier (e.g. `"hl7.fhir.us.mcode"`).	required
`version`	`str`	Package version string (e.g. `"1.0.0"`).	required
`skip_invalid`	`bool`	Whether to skip invalid StructureDefinitions.	`False`
`include_dependencies`	`bool`	Whether to include dependencies when downloading the package.	`True`

register ¶

register(sd: StructureDefinition | StructureDefinition | StructureDefinition | dict) -> StructureDefinition | StructureDefinition | StructureDefinition

Register a StructureDefinition with the factory.

Accepts a typed StructureDefinition model instance or a plain dict. The normalised, validated SD instance is returned so callers can inspect it.

Parameters:

Name	Type	Description	Default
`sd`	`StructureDefinition \| StructureDefinition \| StructureDefinition \| dict`	A StructureDefinition model instance or a `dict` representation.	required

Returns:

Type	Description
`StructureDefinition \| StructureDefinition \| StructureDefinition`	The normalised StructureDefinition instance that was stored.

Raises:

Type	Description
`ValueError`	If sd is neither a dict nor a StructureDefinition instance.

unregister ¶

unregister(url: str) -> None

Remove a StructureDefinition from the registry and evict it from the cache.

If url is not registered, the call is a no-op.

Parameters:

Name	Type	Description	Default
`url`	`str`	The canonical URL of the StructureDefinition to remove.	required

reset_cache ¶

reset_cache() -> None

Discard the entire construction cache.

has_registered_definition ¶

has_registered_definition(url: str) -> bool

Return True if url is present in the definition registry.

get_registered_definition ¶

get_registered_definition(url: str) -> StructureDefinition | StructureDefinition | StructureDefinition

Retrieve a registered StructureDefinition by canonical URL.

Parameters:

Name	Type	Description	Default
`url`	`str`	The canonical URL of the StructureDefinition.	required

Returns:

Type	Description
`StructureDefinition \| StructureDefinition \| StructureDefinition`	The StructureDefinition instance stored in the registry.

Raises:

Type	Description
`KeyError`	If url is not registered.

list_registered_definitions ¶

list_registered_definitions(kind: str | None = None) -> list[str]

Return all canonical URLs registered in the definition registry.

Parameters:

Name	Type	Description	Default
`kind`	`str \| None`	When provided, only URLs whose StructureDefinition has a matching `kind` field (e.g. `"resource"`, `"complex-type"`) are returned.	`None`

Returns:

Type	Description
`list[str]`	Sorted list of canonical URL strings.

is_built ¶

is_built(url: str) -> bool

Return True if a model for url is present in the construction cache.

list_built ¶

list_built() -> list[str]

Return all canonical URLs whose models are currently cached.

evict ¶

evict(url: str) -> None

Remove a single entry from the construction cache.

If url is not cached, the call is a no-op.

Parameters:

Name	Type	Description	Default
`url`	`str`	Canonical URL of the model to evict.	required

rebuild ¶

rebuild(url: str, *, mixins: Sequence[type] | None = None, mode: Literal['auto', 'snapshot', 'differential'] = 'auto') -> type[BaseModel]

Evict url from the cache and build a fresh model.

Useful when the underlying StructureDefinition has changed after the initial build (e.g. after calling :meth:register again with an updated SD).

Parameters:

Name	Type	Description	Default
`url`	`str`	Canonical URL of the StructureDefinition to rebuild.	required
`mixins`	`Sequence[type] \| None`	Optional mixin classes forwarded to :meth:`build`.	`None`
`mode`	`Literal['auto', 'snapshot', 'differential']`	Build mode forwarded to :meth:`build`.	`'auto'`

Returns:

Type	Description
`type[BaseModel]`	The newly constructed Pydantic model class.

enable_internet_access ¶

enable_internet_access() -> None

Allow the definition registry to resolve unknown URLs from the internet.

disable_internet_access ¶

disable_internet_access() -> None

Prevent the definition registry from making any outgoing HTTP requests.

validators ¶

Functions:

Name	Description
`validate_element_constraint`	Validates a FHIR element constraint based on a FHIRPath expression.
`validate_model_constraint`	Validates a FHIR model constraint based on a FHIRPath expression.
`validate_FHIR_element_pattern`	Validate the FHIR element against a specified pattern and return the element if it fulfills the pattern.
`validate_FHIR_model_pattern`	Validate the FHIR model against a specified pattern and return the model if it fulfills the pattern.
`validate_FHIR_element_fixed_value`	Validate the FHIR element against a specified constant value and return the element if it fulfills the constant.
`validate_FHIR_model_fixed_value`	Validate the FHIR model against a specified constant value and return the model if it fulfills the constant.
`validate_type_choice_element`	Validate the type choice element for a given instance.
`validate_slicing_cardinalities`	Validates the cardinalities of FHIR slices for a specific field within a FHIR resource.
`get_type_choice_value_by_base`	Retrieve the value of a type-choice field in an instance based on the field

validate_element_constraint ¶

validate_element_constraint(instance: T, elements: Sequence[str], expression: str, human: str, key: str, severity: str) -> T

Validates a FHIR element constraint based on a FHIRPath expression.

Parameters:

Name	Type	Description	Default
`instance`	`T`	The instance to be validated.	required
`elements`	`Sequence[str]`	The elements to be validated.	required
`expression`	`str`	The FHIRPath expression to evaluate.	required
`human`	`str`	A human-readable description of the constraint.	required
`key`	`str`	The key associated with the constraint.	required
`severity`	`str`	The severity level of the constraint ('warning' or 'error').	required

Returns:

Name	Type	Description
`Any`	`T`	The validated value.

Raises:

Type	Description
`PydanticCustomError`	If the validation fails and severity is not `warning`.
`Warning`	If the validation fails and severity is `warning`.

validate_model_constraint ¶

validate_model_constraint(instance: T, expression: str, human: str, key: str, severity: str) -> T

Validates a FHIR model constraint based on a FHIRPath expression.

Parameters:

Name	Type	Description	Default
`instance`	`T`	Instance of the model to be validated.	required
`expression`	`str`	The FHIRPath expression to evaluate.	required
`human`	`str`	A human-readable description of the constraint.	required
`key`	`str`	The key associated with the constraint.	required
`severity`	`str`	The severity level of the constraint ('warning' or 'error').	required

Returns:

Name	Type	Description
`instance`	`type[T]`	The validated model instance.

Raises:

Type	Description
`PydanticCustomError`	If the validation fails and severity is not `warning`.
`Warning`	If the validation fails and severity is `warning`.

validate_FHIR_element_pattern ¶

validate_FHIR_element_pattern(cls: Any, element: Union[FHIRBaseModel, List[FHIRBaseModel], Any], pattern: Union[FHIRBaseModel, List[FHIRBaseModel], Any]) -> Any

Validate the FHIR element against a specified pattern and return the element if it fulfills the pattern.

Parameters:

Name	Type	Description	Default
`cls`	`Any`	Placeholder for an argument that is not used in the function.	required
`element`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The FHIR element to validate against the pattern.	required
`pattern`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The pattern to validate the element against.	required

Returns:

Type	Description
`Any`	Union[FHIRBaseModel, List[FHIRBaseModel]]: The validated FHIR element.

Raises:

Type	Description
`PydanticCustomError`	If the element does not fulfill the specified pattern.

validate_FHIR_model_pattern ¶

validate_FHIR_model_pattern(model: Union[FHIRBaseModel, List[FHIRBaseModel], Any], pattern: Union[FHIRBaseModel, List[FHIRBaseModel], Any]) -> Any

Validate the FHIR model against a specified pattern and return the model if it fulfills the pattern.

Parameters:

Name	Type	Description	Default
`model`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The FHIR model to validate against the pattern.	required
`pattern`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The pattern to validate the model against.	required

Returns:

Type	Description
`Any`	Union[FHIRBaseModel, List[FHIRBaseModel]]: The validated FHIR model.

Raises:

Type	Description
`PydanticCustomError`	If the model does not fulfill the specified pattern.

validate_FHIR_element_fixed_value ¶

validate_FHIR_element_fixed_value(cls: Any, element: Union[FHIRBaseModel, List[FHIRBaseModel], Any], constant: Union[FHIRBaseModel, List[FHIRBaseModel], Any]) -> Any

Validate the FHIR element against a specified constant value and return the element if it fulfills the constant.

Parameters:

Name	Type	Description	Default
`cls`	`Any`	Placeholder for an argument that is not used in the function.	required
`element`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The FHIR element to validate against the constant.	required
`constant`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The constant value to validate the element against.	required

Returns:

Type	Description
`Any`	Union[FHIRBaseModel, List[FHIRBaseModel]]: The validated FHIR element.

Raises:

Type	Description
`PydanticCustomError`	If the element does not fulfill the specified constant.

validate_FHIR_model_fixed_value ¶

validate_FHIR_model_fixed_value(model: Union[FHIRBaseModel, List[FHIRBaseModel], Any], constant: Union[FHIRBaseModel, List[FHIRBaseModel], Any]) -> Any

Validate the FHIR model against a specified constant value and return the model if it fulfills the constant.

Parameters:

Name	Type	Description	Default
`model`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The FHIR model to validate against the constant.	required
`constant`	`Union[FHIRBaseModel, List[FHIRBaseModel]]`	The constant value to validate the model against.	required

Returns:

Type	Description
`Any`	Union[FHIRBaseModel, List[FHIRBaseModel]]: The validated FHIR element.

Raises:

Type	Description
`PydanticCustomError`	If the element does not fulfill the specified constant.

validate_type_choice_element ¶

validate_type_choice_element(instance: T, field_types: List[Any], field_name_base: str, required: bool = False, non_allowed_types=[]) -> T

Validate the type choice element for a given instance.

Parameters:

Name	Type	Description	Default
`instance`	`T`	The instance to validate.	required
`field_types`	`List[Any]`	List of field types to check.	required
`field_name_base`	`str`	Base name of the field.	required
`required`	`bool`	Whether the type choice element is required.	`False`
`non_allowed_types`	`List[Any] \| None`	List of types that are not allowed for this element (for negative checks).	`[]`

Returns:

Name	Type	Description
`T`	`T`	The validated instance.

Raises:

Type	Description
`PydanticCustomError`	If more than one value is set for the type choice element or if a non-allowed type is set.

validate_slicing_cardinalities ¶

validate_slicing_cardinalities(cls: Any, values: List[Any] | None, field_name: str) -> List[FHIRSliceModel] | None

Validates the cardinalities of FHIR slices for a specific field within a FHIR resource.

Parameters:

Name	Type	Description	Default
`cls`	`Any`	The Pydantic FHIR model class.	required
`values`	`List[Any]`	List of values for the field.	required
`field_name`	`str`	The name of the field to validate.	required

Returns:

Type	Description
`List[FHIRSliceModel] \| None`	List[FHIRSliceModel]: The validated list of values.

Raises:

Type	Description
`AssertionError`	If cardinality constraints are violated for any slice.

get_type_choice_value_by_base ¶

get_type_choice_value_by_base(instance: BaseModel, base: str) -> Any

Retrieve the value of a type-choice field in an instance based on the field name starting with a specific base string.

Parameters:

Name	Type	Description	Default
`instance`	`object`	The instance object to retrieve the value from.	required
`base`	`str`	The base string that the field name should start with.	required

Returns:

Name	Type	Description
`value`	`Any`	The value of the first field found in the instance that starts with the specified base string, or `None` if no such field exists or the value is `None`.

FHIR Model Factory¶

factory ¶

FHIRModelFactory Path: fhircraft.fhir.resources.factory.FHIRModelFactory ¶

build ¶

register_package ¶

register ¶

unregister ¶

reset_cache ¶

has_registered_definition ¶

get_registered_definition ¶

list_registered_definitions ¶

is_built ¶

list_built ¶

evict ¶

rebuild ¶

enable_internet_access ¶

disable_internet_access ¶

validators ¶

validate_element_constraint ¶

validate_model_constraint ¶

validate_FHIR_element_pattern ¶

validate_FHIR_model_pattern ¶

validate_FHIR_element_fixed_value ¶

validate_FHIR_model_fixed_value ¶

validate_type_choice_element ¶

validate_slicing_cardinalities ¶

get_type_choice_value_by_base ¶

FHIRModelFactory
Path: `fhircraft.fhir.resources.factory.FHIRModelFactory`
¶