FHIR Types Registries

Registry classes and functions for managing FHIR types.

TypeRegistry

Path: fhircraft.fhir.resources.datatypes.registry.TypeRegistry

TypeRegistry(release: str)

Per-release index mapping FHIR type names and canonical URLs to Python types.

All classes are imported lazily on first access.

Parameters:

Name	Type	Description	Default
release	str	FHIR release string, e.g. "R4B".	required

Methods:

Name	Description
get_by_name	Return the Python type for a FHIR type name, or None.
get_by_url	Return the Python type for a canonical FHIR URL, or None.
get_entry	Return the :class:ManifestEntry for a canonical URL without loading the class.
all_urls	Return all canonical URLs known to this registry.
all_names	Return all type names known to this registry.

Source code in fhircraft/fhir/resources/datatypes/registry.py

def __init__(self, release: str) -> None:
    self.release = release
    self._manifest: Manifest = Manifest.load(
        _DEFINITIONS_DIR / release / ".manifest.json"
    )
    # name → Python type  (both PascalCase and manifest camelCase for primitives)
    self._by_name: dict[str, type[FHIRBaseModel]] = {}
    # canonical url → Python type
    self._by_url: dict[str, type[FHIRBaseModel]] = {}
    self._lock = Lock()

get_by_name

get_by_name(name: str) -> type[FHIRBaseModel] | None

Return the Python type for a FHIR type name, or None.

Accepts both the Python PascalCase name used in the datatypes modules ("Boolean", "Observation") and the manifest camelCase name used for primitive types ("boolean", "dateTime").

Source code in fhircraft/fhir/resources/datatypes/registry.py

def get_by_name(self, name: str) -> type[FHIRBaseModel] | None:
    """Return the Python type for a FHIR type *name*, or ``None``.

    Accepts both the Python PascalCase name used in the datatypes modules
    (``"Boolean"``, ``"Observation"``) and the manifest camelCase name used
    for primitive types (``"boolean"``, ``"dateTime"``).
    """
    if name in self._by_name:
        return self._by_name[name]

    # Resolve via manifest: try exact name first, then case-insensitive scan
    urls = self._manifest.by_name.get(name)
    if not urls:
        lower = name.lower()
        for manifest_name, manifest_urls in self._manifest.by_name.items():
            if manifest_name.lower() == lower:
                urls = manifest_urls
                break
    if not urls:
        return None

    entry = self._manifest.definitions.get(self._manifest.by_url.get(urls[0], ""))
    if entry is None:
        return None

    python_type = self._load_type(entry)
    if python_type is not None:
        with self._lock:
            self._by_name[name] = python_type
            self._by_url[entry.url] = python_type
    return python_type

get_by_url

get_by_url(url: str) -> type[FHIRBaseModel] | None

Return the Python type for a canonical FHIR URL, or None.

The factory singleton's construction_cache is checked first so that profiled resources built via :class:~fhircraft.fhir.resources.factory.FHIRModelFactory are also reachable by their canonical URL alongside built-in types.

Source code in fhircraft/fhir/resources/datatypes/registry.py

def get_by_url(self, url: str) -> type[FHIRBaseModel] | None:
    """Return the Python type for a canonical FHIR URL, or ``None``.

    The factory singleton's ``construction_cache`` is checked first so that
    profiled resources built via :class:`~fhircraft.fhir.resources.factory.FHIRModelFactory`
    are also reachable by their canonical URL alongside built-in types.
    """
    # Factory construction_cache has priority (includes runtime-profiled resources)
    factory_type = self._check_factory_cache(url)
    if factory_type is not None:
        return factory_type

    if url in self._by_url:
        return self._by_url[url]

    filename = self._manifest.by_url.get(url)
    if not filename:
        return None
    entry = self._manifest.definitions.get(filename)
    if entry is None:
        return None

    python_type = self._load_type(entry)
    if python_type is not None:
        with self._lock:
            self._by_url[url] = python_type
            self._by_name[entry.name] = python_type
    return python_type

get_entry

get_entry(url: str) -> ManifestEntry | None

Return the :class:ManifestEntry for a canonical URL without loading the class.

Useful for inspecting metadata (kind, fhir_version, has_snapshot, etc.) cheaply, without triggering a module import.

Source code in fhircraft/fhir/resources/datatypes/registry.py

def get_entry(self, url: str) -> ManifestEntry | None:
    """Return the :class:`ManifestEntry` for a canonical URL without loading the class.

    Useful for inspecting metadata (``kind``, ``fhir_version``, ``has_snapshot``,
    etc.) cheaply, without triggering a module import.
    """
    filename = self._manifest.by_url.get(url)
    if not filename:
        return None
    return self._manifest.definitions.get(filename)

all_urls

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

Return all canonical URLs known to this registry.

Parameters:

Name	Type	Description	Default
kind	str | None	Optional filter — one of "primitive-type", "complex-type", "resource". When None all URLs are returned.	None

Source code in fhircraft/fhir/resources/datatypes/registry.py

def all_urls(self, kind: str | None = None) -> list[str]:
    """Return all canonical URLs known to this registry.

    Args:
        kind: Optional filter — one of ``"primitive-type"``, ``"complex-type"``,
              ``"resource"``.  When ``None`` all URLs are returned.
    """
    if kind is None:
        return list(self._manifest.by_url.keys())
    return [
        entry.url
        for entry in self._manifest.definitions.values()
        if entry.kind == kind
    ]

all_names

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

Return all type names known to this registry.

Parameters:

Name	Type	Description	Default
kind	str | None	Optional filter — same values as :meth:all_urls.	None

Source code in fhircraft/fhir/resources/datatypes/registry.py

def all_names(self, kind: str | None = None) -> list[str]:
    """Return all type names known to this registry.

    Args:
        kind: Optional filter — same values as :meth:`all_urls`.
    """
    if kind is None:
        return list(self._manifest.by_name.keys())
    return [
        entry.name
        for entry in self._manifest.definitions.values()
        if entry.kind == kind
    ]

get_fhir_type

get_fhir_type(type_str: str, release: str, fail_if_not_found: Literal[True] = True) -> type[FHIRBaseModel]

get_fhir_type(type_str: str, release: str, fail_if_not_found: Literal[False] = False) -> type[FHIRBaseModel] | None

get_fhir_type(type_str: str, release: str, fail_if_not_found: bool = True) -> type[FHIRBaseModel] | None

Get the FHIR type (primitive, complex, or resource) by its string name.

Parameters:

Name	Type	Description	Default
type_str	str	The FHIR type name.	required
release	str	The FHIR release version, e.g. "R4B".	required
fail_if_not_found	bool	Whether to raise an error if the type is not found (default: True).	True

Returns:

Type	Description
type[FHIRBaseModel] | None	The corresponding FHIR type class, or None if not found and fail_if_not_found is False.

Raises:

Type	Description
AttributeError	If the type is not found and fail_if_not_found is True.

Source code in fhircraft/fhir/resources/datatypes/registry.py

def get_fhir_type(
    type_str: str, release: str, fail_if_not_found: bool = True
) -> type[FHIRBaseModel] | None:
    """
    Get the FHIR type (primitive, complex, or resource) by its string name.

    Args:
        type_str (str): The FHIR type name.
        release (str): The FHIR release version, e.g. `"R4B"`.
        fail_if_not_found (bool): Whether to raise an error if the type is not found (default: True).

    Returns:
        The corresponding FHIR type class, or None if not found and fail_if_not_found is False.

    Raises:
        AttributeError: If the type is not found and `fail_if_not_found` is True.
    """
    result = get_registry(release).get_by_name(type_str)
    if fail_if_not_found and result is None:
        raise AttributeError(f"No FHIR {release} type found for name: {type_str}")
    return result

get_fhir_type_by_url

get_fhir_type_by_url(url: str, release, fail_if_not_found: Literal[True] = True) -> type[FHIRBaseModel]

get_fhir_type_by_url(url: str, release, fail_if_not_found: Literal[False] = False) -> type[FHIRBaseModel] | None

get_fhir_type_by_url(url: str, release: str, fail_if_not_found: bool = True) -> type[FHIRBaseModel] | None

Return the FHIR type (primitive, complex, or resource) for a canonical URL.

Parameters:

Name	Type	Description	Default
url	str	The canonical FHIR URL, e.g. "http://hl7.org/fhir/StructureDefinition/Observation".	required
release	str	The FHIR release version, e.g. "R4B".	required
fail_if_not_found	bool	Whether to raise an error if the type is not found (default: True).	True

Returns:

Type	Description
type[FHIRBaseModel] | None	The corresponding Python type class.

Raises:

Type	Description
AttributeError	If no type is found for the given URL and fail_if_not_found is True.

Source code in fhircraft/fhir/resources/datatypes/registry.py

def get_fhir_type_by_url(
    url: str, release: str, fail_if_not_found: bool = True
) -> type[FHIRBaseModel] | None:
    """Return the FHIR type (primitive, complex, or resource) for a canonical URL.

    Args:
        url: The canonical FHIR URL, e.g. `"http://hl7.org/fhir/StructureDefinition/Observation"`.
        release: The FHIR release version, e.g. `"R4B"`.
        fail_if_not_found: Whether to raise an error if the type is not found (default: True).

    Returns:
        The corresponding Python type class.

    Raises:
        AttributeError: If no type is found for the given URL and `fail_if_not_found` is ``True``.
    """
    result = get_registry(release).get_by_url(url)
    if fail_if_not_found and result is None:
        raise AttributeError(f"No FHIR {release} type found for URL: {url}")
    return result

get_registry

get_registry(release: str = 'R4B') -> TypeRegistry

Return the :class:TypeRegistry singleton for the given FHIR release.

Registries are constructed lazily on first access and then reused.

Parameters:

Name	Type	Description	Default
release	str	FHIR release string — one of "R4", "R4B", "R5".	'R4B'

Returns:

Type	Description
TypeRegistry	The singleton :class:TypeRegistry for the requested release.

Source code in fhircraft/fhir/resources/datatypes/registry.py

def get_registry(release: str = "R4B") -> TypeRegistry:
    """Return the :class:`TypeRegistry` singleton for the given FHIR *release*.

    Registries are constructed lazily on first access and then reused.

    Args:
        release: FHIR release string — one of ``"R4"``, ``"R4B"``, ``"R5"``.

    Returns:
        The singleton :class:`TypeRegistry` for the requested release.
    """
    if release not in _registry_cache:
        with _registry_lock:
            if release not in _registry_cache:
                _registry_cache[release] = TypeRegistry(release)
    return _registry_cache[release]