Structure Definitions Registry

Main class and utilities for managing FHIR structure definitions.

Manifest

Path: fhircraft.fhir.resources.definitions.registry.Manifest

dataclass

Manifest(definitions: Dict[str, ManifestEntry] = dict(), by_url: Dict[str, str] = dict(), by_name: Dict[str, List[str]] = dict())

Manifest index for StructureDefinitions in a FHIR version.

Parameters:

Name	Type	Description	Default
definitions	Dict[str, ManifestEntry]	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)	<class 'dict'>
by_url	Dict[str, str]	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)	<class 'dict'>
by_name	Dict[str, List[str]]	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)	<class 'dict'>

Methods:

Name	Description
to_dict	Convert manifest to dictionary for JSON serialization.
from_dict	Create manifest from dictionary.
save	Save manifest to JSON file.
load	Load manifest from JSON file.

to_dict

to_dict() -> Dict[str, Any]

Convert manifest to dictionary for JSON serialization.

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

def to_dict(self) -> Dict[str, Any]:
    """Convert manifest to dictionary for JSON serialization."""
    return {
        "definitions": {
            filename: asdict(entry) for filename, entry in self.definitions.items()
        },
        "by_url": self.by_url,
        "by_name": self.by_name,
    }

from_dict classmethod

from_dict(data: Dict[str, Any]) -> Manifest

Create manifest from dictionary.

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

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Manifest":
    """Create manifest from dictionary."""
    manifest = cls()

    # Reconstruct definitions
    for filename, entry_dict in data.get("definitions", {}).items():
        entry = ManifestEntry(**entry_dict)
        manifest.definitions[filename] = entry

    # Reconstruct indexes
    manifest.by_url = data.get("by_url", {})
    manifest.by_name = data.get("by_name", {})

    return manifest

save

save(path: Path) -> None

Save manifest to JSON file.

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

def save(self, path: Path) -> None:
    """Save manifest to JSON file."""
    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "w", encoding="utf-8") as f:
        json.dump(self.to_dict(), f, indent=2)

load classmethod

load(path: Path) -> Manifest

Load manifest from JSON file.

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

@classmethod
def load(cls, path: Path) -> "Manifest":
    """Load manifest from JSON file."""
    if not path.exists():
        return cls()
    with open(path, "r", encoding="utf-8") as f:
        data = json.load(f)
    return cls.from_dict(data)

ManifestEntry

Path: fhircraft.fhir.resources.definitions.registry.ManifestEntry

dataclass

ManifestEntry(url: str, name: str, fhir_version: str, kind: str, filename: str, has_snapshot: bool = False, has_differential: bool = False)

Metadata entry for a single StructureDefinition in the manifest.

Parameters:

Name	Type	Description	Default
url	str	Canonical URL (primary key)	required
name	str	StructureDefinition name	required
fhir_version	str	FHIR version (e.g., "4.0.1", "4.3.0", "5.0.0")	required
kind	str	Kind (resource, complex-type, primitive-type, etc.)	required
filename	str	Filename where this definition is stored (e.g., "Patient.json")	required
has_snapshot	bool	Whether snapshot is present	False
has_differential	bool	Whether differential is present	False

Attributes:

Name	Type	Description
url	str	Canonical URL (primary key)
name	str	StructureDefinition name
fhir_version	str	FHIR version (e.g., "4.0.1", "4.3.0", "5.0.0")
kind	str	Kind (resource, complex-type, primitive-type, etc.)
filename	str	Filename where this definition is stored (e.g., "Patient.json")
has_snapshot	bool	Whether snapshot is present
has_differential	bool	Whether differential is present

url instance-attribute

url: str

Canonical URL (primary key)

name instance-attribute

name: str

StructureDefinition name

fhir_version instance-attribute

fhir_version: str

FHIR version (e.g., "4.0.1", "4.3.0", "5.0.0")

kind instance-attribute

kind: str

Kind (resource, complex-type, primitive-type, etc.)

filename instance-attribute

filename: str

Filename where this definition is stored (e.g., "Patient.json")

has_snapshot class-attribute instance-attribute

has_snapshot: bool = False

Whether snapshot is present

has_differential class-attribute instance-attribute

has_differential: bool = False

Whether differential is present

StructureDefinitionNotFoundError

Path: fhircraft.fhir.resources.definitions.registry.StructureDefinitionNotFoundError

Bases: FileNotFoundError

Raised when a required structure definition cannot be resolved.

StructureDefinitionRegistry

Path: fhircraft.fhir.resources.definitions.registry.StructureDefinitionRegistry

StructureDefinitionRegistry(fhir_release: str)

Registry for managing indexed StructureDefinitions.

Methods:

Name	Description
enable_internet_access	Enable internet access for downloading structure definitions.
disable_internet_access	Disable internet access for downloading structure definitions.
download_url	Download JSON content from a URL.
download_package	Download a package from the registry and add its structure definitions to the registry.
set_registry_base_url	Change the package registry base URL.
parse_canonical_url	Parse a canonical URL to extract base URL and version.

Attributes:

Name	Type	Description
local_manifest	Manifest	Manifest of local definitions
fhir_release	str	FHIR release version (e.g., "4.0.1", "4.3.0", "5.0.0").
structure_definitions_by_url	Dict[str, StructureDefinition | StructureDefinition | StructureDefinition]	Mapping of base URL to version to StructureDefinition instance.

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

def __init__(self, fhir_release: str):
    self.fhir_release = fhir_release
    self._internet_access_enabled = False
    self.structure_definitions_by_url = {}
    self._package_client = FHIRPackageRegistryClient()
    self._load_local_definitions_manifest()

local_manifest instance-attribute

local_manifest: Manifest

Manifest of local definitions

fhir_release instance-attribute

fhir_release: str = fhir_release

FHIR release version (e.g., "4.0.1", "4.3.0", "5.0.0").

structure_definitions_by_url instance-attribute

structure_definitions_by_url: Dict[str, StructureDefinition | StructureDefinition | StructureDefinition] = {}

Mapping of base URL to version to StructureDefinition instance.

enable_internet_access

enable_internet_access()

Enable internet access for downloading structure definitions.

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

def enable_internet_access(self):
    """Enable internet access for downloading structure definitions."""
    self._internet_access_enabled = True

disable_internet_access

disable_internet_access()

Disable internet access for downloading structure definitions.

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

def disable_internet_access(self):
    """Disable internet access for downloading structure definitions."""
    self._internet_access_enabled = False

download_url staticmethod

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

Download JSON content from a URL.

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

@staticmethod
def download_url(url: str) -> Dict[str, Any]:
    """Download JSON content from a URL."""
    # Configure proxy if needed
    settings = load_env_variables()
    proxies = (
        {
            k: v
            for k, v in {
                "https": settings.get("PROXY_URL_HTTPS"),
                "http": settings.get("PROXY_URL_HTTP"),
            }.items()
            if v is not None
        }
        if settings.get("PROXY_URL_HTTPS") or settings.get("PROXY_URL_HTTP")
        else None
    )
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json, application/json+fhir, text/json",
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36",
    }
    # Download the StructureDefinition JSON
    response = requests.get(
        url,
        proxies=proxies,
        verify=settings.get("CERTIFICATE_BUNDLE_PATH"),
        headers=headers,
        allow_redirects=True,
    )
    response.raise_for_status()
    return response.json()

download_package

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

Download a package from the registry and add its structure definitions to the registry.

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

def download_package(
    self,
    package_name: str,
    version: str,
    skip_invalid: bool = False,
    include_dependencies: bool = True,
) -> None:
    """Download a package from the registry and add its structure definitions to the registry."""
    for sd in self._package_client.load_resources_from_package(
        "StructureDefinition",
        package_name,
        version,
        install_dependencies=include_dependencies,
    ):
        try:
            structure_definition = self._validate_structure_definition(sd)
            self.add(structure_definition)
        except ValueError as e:
            if not skip_invalid:
                raise e
            else:
                warnings.warn(
                    f"Skipping invalid structure definition {sd.get('url', 'unknown')} in package {package_name} version {version}:\n{e}"
                )

set_registry_base_url

set_registry_base_url(base_url: str) -> None

Change the package registry base URL.

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

def set_registry_base_url(self, base_url: str) -> None:
    """Change the package registry base URL."""
    self._package_client.base_url = base_url

parse_canonical_url staticmethod

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

Parse a canonical URL to extract base URL and version.

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

@staticmethod
def parse_canonical_url(canonical_url: str) -> Tuple[str, Optional[str]]:
    """Parse a canonical URL to extract base URL and version."""
    if "|" in canonical_url:
        base_url, version = canonical_url.split("|", 1)
        return base_url.strip(), version.strip()
    return canonical_url.strip(), None