sdmxlib 0.8.0__py3-none-any.whl

sdmxlib/model/istring.py

@@ -0,0 +1,81 @@
+"""InternationalString — dict-like multilingual string."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+class InternationalString:
+    """A multilingual string where language access is always explicit.
+
+    Stores key-value pairs of language code → text. Immutable after
+    construction (no ``__setitem__``).
+
+    Example:
+        s = InternationalString(en="Annual", fr="Annuel")
+        s["en"]  # "Annual"
+        s.get("de", "en")  # "Annual" (fallback)
+        "fr" in s  # True
+        s.langs  # ["en", "fr"]
+    """
+
+    __slots__ = ("_data",)
+
+    def __init__(self, **kwargs: str) -> None:
+        self._data: dict[str, str] = dict(kwargs)
+
+    # ── Construction helpers ───────────────────────────────────────────────
+
+    @classmethod
+    def of(cls, pairs: dict[str, str]) -> InternationalString:
+        """Build from an existing dict."""
+        obj = cls.__new__(cls)
+        obj._data = dict(pairs)  # noqa: SLF001
+        return obj
+
+    # ── Access ────────────────────────────────────────────────────────────
+
+    def __getitem__(self, lang: str) -> str:
+        """Return the string for *lang*, raising KeyError if absent."""
+        return self._data[lang]
+
+    def get(self, *langs: str) -> str | None:
+        """Return the first available language in priority order, or None."""
+        for lang in langs:
+            if lang in self._data:
+                return self._data[lang]
+        return None
+
+    def __contains__(self, lang: object) -> bool:
+        return lang in self._data
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __bool__(self) -> bool:
+        return bool(self._data)
+
+    @property
+    def langs(self) -> list[str]:
+        """List of available language codes."""
+        return list(self._data)
+
+    # ── Equality & repr ───────────────────────────────────────────────────
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, InternationalString):
+            return self._data == other._data
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(tuple(sorted(self._data.items())))
+
+    def __repr__(self) -> str:
+        pairs = ", ".join(f"{k}={v!r}" for k, v in self._data.items())
+        return f"InternationalString({pairs})"

sdmxlib/model/mapping.py

@@ -0,0 +1,134 @@
+"""StructureSet, CodelistMap, and CodeMap — SDMX structural mapping types."""
+
+from datetime import datetime
+from typing import ClassVar
+
+from attrs import define, field
+
+from sdmxlib.model.annotations import Annotations
+from sdmxlib.model.base import MaintainableArtefact
+from sdmxlib.model.istring import InternationalString
+from sdmxlib.model.organisation import Agency, _to_agency, _to_annotations, _to_istring
+from sdmxlib.model.ref import AnyRef
+
+
+@define
+class CodeMap:
+    """Single code-level mapping: source code id → target code id."""
+
+    source_id: str
+    target_id: str
+
+
+@define
+class CodelistMap:
+    """Maps one codelist onto another, code by code."""
+
+    id: str
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    source: AnyRef | None = None
+    target: AnyRef | None = None
+    maps: tuple[CodeMap, ...] = ()
+
+    def translate(self, source_code: str) -> str | None:
+        """Return the target code id for a source code id, or None if unmapped."""
+        for m in self.maps:
+            if m.source_id == source_code:
+                return m.target_id
+        return None
+
+
+@define
+class ConceptMap:
+    """Single concept-level mapping: source concept id → target concept id."""
+
+    source_id: str
+    target_id: str
+
+
+@define
+class ConceptSchemeMap:
+    """Maps one concept scheme onto another, concept by concept."""
+
+    id: str
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    source: AnyRef | None = None
+    target: AnyRef | None = None
+    maps: tuple[ConceptMap, ...] = ()
+
+
+@define
+class CategoryMap:
+    """Single category-level mapping: source category id → target category id."""
+
+    source_id: str
+    target_id: str
+
+
+@define
+class CategorySchemeMap:
+    """Maps one category scheme onto another, category by category."""
+
+    id: str
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    source: AnyRef | None = None
+    target: AnyRef | None = None
+    maps: tuple[CategoryMap, ...] = ()
+
+
+@define
+class ComponentMap:
+    """Single component-level mapping: source component id → target component id."""
+
+    source_id: str
+    target_id: str
+
+
+@define
+class DataStructureMap:
+    """Maps one DSD onto another, component by component."""
+
+    id: str
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    source: AnyRef | None = None
+    target: AnyRef | None = None
+    maps: tuple[ComponentMap, ...] = ()
+
+
+@define
+class DataflowMap:
+    """Maps one dataflow onto another (artefact-level only, no item maps)."""
+
+    id: str
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    source: AnyRef | None = None
+    target: AnyRef | None = None
+
+
+@define
+class StructureSet(MaintainableArtefact):
+    """Maintainable container for structural mappings between artefacts."""
+
+    sdmx_package: ClassVar[str] = "mapping"
+    sdmx_class: ClassVar[str] = "StructureSet"
+    msg_field: ClassVar[str] = "structure_sets"
+
+    id: str = ""
+    maintainer: Agency = field(factory=lambda: Agency(id=""), converter=_to_agency)
+    version: str = "1.0"
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    is_final: bool = False
+    codelist_maps: tuple[CodelistMap, ...] = ()
+    concept_scheme_maps: tuple[ConceptSchemeMap, ...] = ()
+    category_scheme_maps: tuple[CategorySchemeMap, ...] = ()
+    data_structure_maps: tuple[DataStructureMap, ...] = ()
+    dataflow_maps: tuple[DataflowMap, ...] = ()
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+    valid_from: datetime | None = None
+    valid_to: datetime | None = None

sdmxlib/model/message.py

@@ -0,0 +1,70 @@
+"""StructureMessage — version-neutral envelope for SDMX structural artefacts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from attrs import field, frozen
+
+from sdmxlib.model.collections import ArtefactList
+
+if TYPE_CHECKING:
+    from sdmxlib.model.category import Categorisation, CategoryScheme
+    from sdmxlib.model.codelist import Codelist
+    from sdmxlib.model.concept import ConceptScheme
+    from sdmxlib.model.constraint import ContentConstraint
+    from sdmxlib.model.dataflow import Dataflow
+    from sdmxlib.model.datastructure import DataStructure
+    from sdmxlib.model.hierarchy import Hierarchy
+    from sdmxlib.model.mapping import StructureSet
+    from sdmxlib.model.organisation import AgencyScheme, DataProviderScheme
+    from sdmxlib.model.provision import ProvisionAgreement
+
+
+def _to_artefact_list(v: Any) -> ArtefactList:  # type: ignore[type-arg]
+    return v if isinstance(v, ArtefactList) else ArtefactList(v)
+
+
+@frozen
+class StructureMessage:
+    """Version-neutral envelope returned by the format layer.
+
+    The format reader populates whichever collections are present in the
+    parsed message. Cross-references within the message are auto-resolved
+    by the reader.
+
+    Example:
+        msg = parse(xml_bytes)
+        dsd = msg.data_structures[0]
+        cl = msg.codelists["SDMX:CL_FREQ(1.0)"]
+    """
+
+    codelists: ArtefactList[Codelist] = field(factory=ArtefactList, converter=_to_artefact_list)
+    concept_schemes: ArtefactList[ConceptScheme] = field(factory=ArtefactList, converter=_to_artefact_list)
+    data_structures: ArtefactList[DataStructure] = field(factory=ArtefactList, converter=_to_artefact_list)
+    dataflows: ArtefactList[Dataflow] = field(factory=ArtefactList, converter=_to_artefact_list)
+    category_schemes: ArtefactList[CategoryScheme] = field(factory=ArtefactList, converter=_to_artefact_list)
+    categorisations: ArtefactList[Categorisation] = field(factory=ArtefactList, converter=_to_artefact_list)
+    provision_agreements: ArtefactList[ProvisionAgreement] = field(factory=ArtefactList, converter=_to_artefact_list)
+    agency_schemes: ArtefactList[AgencyScheme] = field(factory=ArtefactList, converter=_to_artefact_list)
+    data_provider_schemes: ArtefactList[DataProviderScheme] = field(factory=ArtefactList, converter=_to_artefact_list)
+    constraints: ArtefactList[ContentConstraint] = field(factory=ArtefactList, converter=_to_artefact_list)
+    structure_sets: ArtefactList[StructureSet] = field(factory=ArtefactList, converter=_to_artefact_list)
+    hierarchies: ArtefactList[Hierarchy] = field(factory=ArtefactList, converter=_to_artefact_list)
+
+    def all_artefacts(self) -> list[Any]:
+        """Flat list of every artefact in the message."""
+        return [
+            *self.codelists,
+            *self.concept_schemes,
+            *self.data_structures,
+            *self.dataflows,
+            *self.category_schemes,
+            *self.categorisations,
+            *self.provision_agreements,
+            *self.agency_schemes,
+            *self.data_provider_schemes,
+            *self.constraints,
+            *self.structure_sets,
+            *self.hierarchies,
+        ]

sdmxlib/model/organisation.py

@@ -0,0 +1,149 @@
+"""Organisation types — Agency, DataProvider, AgencyScheme, DataProviderScheme."""
+
+from datetime import datetime
+from typing import ClassVar
+
+from attrs import define, evolve, field
+
+from sdmxlib.model.annotations import Annotation, Annotations
+from sdmxlib.model.base import MaintainableArtefact
+from sdmxlib.model.collections import ItemList
+from sdmxlib.model.istring import InternationalString
+
+
+def _to_istring(v: InternationalString | dict[str, str]) -> InternationalString:
+    return InternationalString.of(v) if isinstance(v, dict) else v
+
+
+def _to_annotations(v: Annotations | list[Annotation]) -> Annotations:
+    return Annotations(v) if isinstance(v, list) else v
+
+
+@define
+class Contact:
+    """Contact information for an agency or data provider."""
+
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    department: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    role: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    phones: tuple[str, ...] = ()
+    faxes: tuple[str, ...] = ()
+    uris: tuple[str, ...] = ()
+    emails: tuple[str, ...] = ()
+
+
+@define
+class Agency:
+    """An organisation that maintains SDMX artefacts."""
+
+    id: str
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    contacts: tuple[Contact, ...] = ()
+    parent: "Agency | None" = None
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+
+
+def _to_agency(v: "Agency | str") -> "Agency":
+    return Agency(id=v) if isinstance(v, str) else v
+
+
+def _to_item_list_agency(v: "ItemList[Agency] | list[Agency]") -> "ItemList[Agency]":
+    return v if isinstance(v, ItemList) else ItemList(v)
+
+
+def _to_item_list_provider(v: "ItemList[DataProvider] | list[DataProvider]") -> "ItemList[DataProvider]":
+    return v if isinstance(v, ItemList) else ItemList(v)
+
+
+@define
+class DataProvider:
+    """An organisation that provides data under a ProvisionAgreement."""
+
+    id: str
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    contacts: tuple[Contact, ...] = ()
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+
+
+@define
+class AgencyScheme(MaintainableArtefact):
+    """Maintainable container for Agency items."""
+
+    sdmx_package: ClassVar[str] = "base"
+    sdmx_class: ClassVar[str] = "AgencyScheme"
+    msg_field: ClassVar[str] = "agency_schemes"
+
+    id: str
+    maintainer: Agency = field(converter=_to_agency)
+    version: str = "1.0"
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    is_final: bool = False
+    agencies: ItemList[Agency] = field(factory=ItemList, converter=_to_item_list_agency)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+    valid_from: datetime | None = None
+    valid_to: datetime | None = None
+
+    def add(self, agencies: "Agency | list[Agency]") -> "AgencyScheme":
+        """Return a new AgencyScheme with *agencies* added.
+
+        Accepts a single Agency or a list of Agencies.
+        """
+        new = [agencies] if isinstance(agencies, Agency) else list(agencies)
+        return evolve(self, agencies=[*self.agencies, *new])
+
+    def drop(self, agency_ids: str | list[str]) -> "AgencyScheme":
+        """Return a new AgencyScheme with the given agency(ies) removed.
+
+        Accepts a single id string or a list of id strings.
+        Raises KeyError if any id is not present.
+        """
+        ids = [agency_ids] if isinstance(agency_ids, str) else list(agency_ids)
+        missing = [i for i in ids if i not in self.agencies]
+        if missing:
+            raise KeyError(missing[0] if len(missing) == 1 else missing)
+        id_set = set(ids)
+        return evolve(self, agencies=[a for a in self.agencies if a.id not in id_set])
+
+
+@define
+class DataProviderScheme(MaintainableArtefact):
+    """Maintainable container for DataProvider items."""
+
+    sdmx_package: ClassVar[str] = "base"
+    sdmx_class: ClassVar[str] = "DataProviderScheme"
+    msg_field: ClassVar[str] = "data_provider_schemes"
+
+    id: str
+    maintainer: Agency = field(converter=_to_agency)
+    version: str = "1.0"
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    is_final: bool = False
+    providers: ItemList[DataProvider] = field(factory=ItemList, converter=_to_item_list_provider)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+    valid_from: datetime | None = None
+    valid_to: datetime | None = None
+
+    def add(self, providers: "DataProvider | list[DataProvider]") -> "DataProviderScheme":
+        """Return a new DataProviderScheme with *providers* added.
+
+        Accepts a single DataProvider or a list of DataProviders.
+        """
+        new = [providers] if isinstance(providers, DataProvider) else list(providers)
+        return evolve(self, providers=[*self.providers, *new])
+
+    def drop(self, provider_ids: str | list[str]) -> "DataProviderScheme":
+        """Return a new DataProviderScheme with the given provider(s) removed.
+
+        Accepts a single id string or a list of id strings.
+        Raises KeyError if any id is not present.
+        """
+        ids = [provider_ids] if isinstance(provider_ids, str) else list(provider_ids)
+        missing = [i for i in ids if i not in self.providers]
+        if missing:
+            raise KeyError(missing[0] if len(missing) == 1 else missing)
+        id_set = set(ids)
+        return evolve(self, providers=[p for p in self.providers if p.id not in id_set])

sdmxlib/model/provision.py

@@ -0,0 +1,45 @@
+"""ProvisionAgreement — binds a data provider to a dataflow."""
+
+from datetime import datetime
+from typing import ClassVar
+
+from attrs import define, field
+
+from sdmxlib.model.annotations import Annotations
+from sdmxlib.model.base import MaintainableArtefact
+from sdmxlib.model.dataflow import Dataflow
+from sdmxlib.model.istring import InternationalString
+from sdmxlib.model.organisation import Agency, _to_agency, _to_annotations, _to_istring
+from sdmxlib.model.ref import AnyRef, Ref
+
+
+def _to_dataflow_ref(v: "Ref[Dataflow] | Dataflow | None") -> "Ref[Dataflow] | None":
+    if isinstance(v, Dataflow):
+        return Ref.to(v)
+    return v
+
+
+@define
+class ProvisionAgreement(MaintainableArtefact):
+    """Binds a data provider to a dataflow.
+
+    Example:
+        pa.dataflow()  # Dataflow (if resolved)
+        pa.dataflow().structure()  # DataStructure
+        pa.dataflow().structure.dimensions  # ItemList[Dimension]
+    """
+
+    sdmx_package: ClassVar[str] = "registry"
+    sdmx_class: ClassVar[str] = "ProvisionAgreement"
+    msg_field: ClassVar[str] = "provision_agreements"
+
+    id: str
+    maintainer: Agency = field(converter=_to_agency)
+    version: str = "1.0"
+    name: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    description: InternationalString = field(factory=InternationalString, converter=_to_istring)
+    annotations: Annotations = field(factory=Annotations, converter=_to_annotations)
+    valid_from: datetime | None = None
+    valid_to: datetime | None = None
+    dataflow: Ref[Dataflow] | None = field(default=None, converter=_to_dataflow_ref)
+    data_provider: AnyRef | None = None

sdmxlib/model/ref.py

@@ -0,0 +1,195 @@
+"""Ref[T], HasUrn, UnresolvedRef, SdmxRef — SDMX reference abstraction."""
+
+from typing import Any, ClassVar, Protocol, runtime_checkable
+
+from attrs import define, field, frozen
+
+from sdmxlib.model.urn import SdmxUrn
+
+
+@runtime_checkable
+class HasUrn(Protocol):
+    """Protocol for SDMX artefacts that can be referenced by URN.
+
+    Any MaintainableArtefact satisfies this protocol. Accepts anywhere
+    a Ref target is needed — allows ``Ref(cl_freq)`` instead of
+    ``Ref.unresolved(cl_freq.urn)``.
+    """
+
+    sdmx_package: ClassVar[str]
+    sdmx_class: ClassVar[str]
+    agency_id: str
+    id: str
+    version: str
+
+
+@define
+class Ref[T]:
+    """A reference to an SDMX artefact.
+
+    Always carries the URN. May also carry the resolved object once
+    the artefact has been added to a Registry.
+
+    ``None`` on a parent field means "no reference exists."
+    ``Ref[T]`` means "a reference exists, resolved or not."
+
+    Access tiers:
+
+    - ``ref.urn``, ``ref.id``, ``ref.agency`` — URN metadata, always available
+    - ``ref.resolved`` — bool check
+    - ``ref.codes``, ``ref.name`` etc — proxy to resolved object, raises
+      ``UnresolvedRef`` if not yet resolved
+
+    Construction:
+
+        Ref(cl_freq)                      # from domain object — resolved
+        Ref(cl_freq.urn)                  # from SdmxUrn — unresolved
+        Ref.unresolved(urn)               # explicit unresolved factory
+        Ref.of(urn, obj)                  # explicit resolved factory
+
+    Example:
+        ref = Ref(cl_freq_urn)
+        ref.id       # "CL_FREQ"
+        ref.resolved  # False
+        ref.codes    # raises UnresolvedRef
+
+        reg.add(cl_freq)
+        ref.resolved  # True (if interned through registry)
+        ref.codes    # ItemList[Code]
+    """
+
+    urn: SdmxUrn[T]
+    _resolved: T | None = field(default=None, repr=False, alias="_resolved")
+
+    def __attrs_post_init__(self) -> None:
+        # Allow passing a HasUrn (MaintainableArtefact) directly
+        if not isinstance(self.urn, SdmxUrn):
+            obj = self.urn  # type: ignore[assignment]
+            self.urn = SdmxUrn.make(  # type: ignore[assignment]
+                type(obj),
+                package=obj.sdmx_package,  # type: ignore[union-attr]
+                artefact_class=obj.sdmx_class,  # type: ignore[union-attr]
+                agency=obj.agency_id,  # type: ignore[union-attr]
+                id=obj.id,  # type: ignore[union-attr]
+                version=obj.version,  # type: ignore[union-attr]
+            )
+            if self._resolved is None:
+                self._resolved = obj  # type: ignore[assignment]
+
+    # ── Resolution ────────────────────────────────────────────────────────
+
+    @property
+    def resolved(self) -> bool:
+        """True if the referenced object has been resolved."""
+        return self._resolved is not None
+
+    def __call__(self) -> T:
+        """Unwrap to the resolved object. Raises UnresolvedRef if not resolved."""
+        if self._resolved is None:
+            raise UnresolvedRef(self.urn)
+        return self._resolved
+
+    def __getattr__(self, name: str) -> Any:
+        """Proxy attribute access to the resolved object.
+
+        Allows ``ref.codes`` instead of unwrapping manually.
+        Raises ``UnresolvedRef`` if the ref has not been resolved.
+        """
+        try:
+            resolved = self._resolved
+        except AttributeError:
+            raise AttributeError(name) from None
+        if resolved is None:
+            raise UnresolvedRef(self.urn)
+        return getattr(resolved, name)
+
+    # ── URN metadata ──────────────────────────────────────────────────────
+
+    @property
+    def id(self) -> str:
+        """Artefact id from the URN."""
+        return self.urn.id
+
+    @property
+    def agency(self) -> str:
+        """Agency id from the URN."""
+        return self.urn.agency
+
+    @property
+    def version(self) -> str:
+        """Version from the URN."""
+        return self.urn.version
+
+    @property
+    def item_id(self) -> str | None:
+        """Item id from the URN (e.g. the concept id within a ConceptScheme)."""
+        return self.urn.item_id
+
+    # ── Factories ─────────────────────────────────────────────────────────
+
+    @classmethod
+    def unresolved(cls, urn: SdmxUrn[T]) -> "Ref[T]":
+        """Create an unresolved Ref carrying the URN only."""
+        return cls(urn=urn)
+
+    @classmethod
+    def of(cls, urn: SdmxUrn[T], obj: T) -> "Ref[T]":
+        """Create a resolved Ref. Useful in tests and format readers."""
+        return cls(urn=urn, _resolved=obj)
+
+    @classmethod
+    def to(cls, obj: T) -> "Ref[T]":
+        """Create a resolved Ref from a MaintainableArtefact instance.
+
+        The object must satisfy HasUrn — it needs ``agency_id``, ``id``,
+        ``version``, ``sdmx_package``, and ``sdmx_class`` attributes.
+
+        Example:
+            cl = Codelist(id="CL_FREQ", maintainer="SDMX", version="1.0", ...)
+            ref = Ref.to(cl)
+            ref.resolved   # True
+        """
+        return cls(urn=obj)  # type: ignore[arg-type]  # delegates to __post_init__
+
+    # ── Boolean ───────────────────────────────────────────────────────────
+
+    def __bool__(self) -> bool:
+        """Always True — the Ref exists (use .resolved to check resolution)."""
+        return True
+
+    # ── Repr ──────────────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        if self._resolved is not None:
+            return f"Ref({self.urn.id} → resolved)"
+        return f"Ref({self.urn.id} [unresolved])"
+
+
+class UnresolvedRef(Exception):  # noqa: N818
+    """Raised when accessing an unresolved Ref."""
+
+    def __init__(self, urn: SdmxUrn[Any]) -> None:
+        self.urn = urn
+        super().__init__(f"{urn} has not been resolved — add the artefact to a Registry first.")
+
+
+@frozen
+class SdmxRef:
+    """Partial artefact identity for filtering and lookup.
+
+    All fields optional. ``None`` means "match any."
+    Used as ``ArtefactList`` key and in ``Query``.
+
+    Example:
+        SdmxRef(agency="SDMX", id="CL_FREQ")
+        SdmxRef(id="CL_FREQ", version="1.0")
+    """
+
+    agency: str | None = None
+    id: str | None = None
+    version: str | None = None
+
+
+# Type alias for Ref[Any] — used in format layers and internal code where the
+# specific artefact type is not yet known or not relevant.
+AnyRef = Ref[Any]