sdmxlib 0.8.0__py3-none-any.whl

sdmxlib/formats/sdmx_json/reader.py

@@ -0,0 +1,897 @@
+"""SDMX-JSON 2.0 reader: JSON → domain model.
+
+Parses SDMX-JSON 2.0 Structure messages into the sdmxlib domain model.
+All references within the message are auto-resolved where possible.
+"""
+
+import json
+from datetime import datetime
+from typing import Any
+
+from sdmxlib.model.annotations import Annotation, Annotations
+from sdmxlib.model.category import Categorisation, Category, CategoryScheme
+from sdmxlib.model.codelist import Code, Codelist
+from sdmxlib.model.collections import ArtefactList, ItemList
+from sdmxlib.model.concept import Concept, ConceptScheme
+from sdmxlib.model.constraint import (
+    ConstraintAttachment,
+    ContentConstraint,
+    CubeRegion,
+    KeyValue,
+    ReferencePeriod,
+    ReleaseCalendar,
+)
+from sdmxlib.model.dataflow import Dataflow
+from sdmxlib.model.datastructure import (
+    AttachmentLevel,
+    Attribute,
+    DataStructure,
+    Dimension,
+    Group,
+    Measure,
+    TimeDimension,
+)
+from sdmxlib.model.hierarchy import HierarchicalCode, Hierarchy
+from sdmxlib.model.istring import InternationalString
+from sdmxlib.model.mapping import (
+    CategoryMap,
+    CategorySchemeMap,
+    CodelistMap,
+    CodeMap,
+    ComponentMap,
+    ConceptMap,
+    ConceptSchemeMap,
+    DataflowMap,
+    DataStructureMap,
+    StructureSet,
+)
+from sdmxlib.model.message import StructureMessage
+from sdmxlib.model.organisation import Agency, AgencyScheme, Contact, DataProvider, DataProviderScheme
+from sdmxlib.model.provision import ProvisionAgreement
+from sdmxlib.model.ref import AnyRef, Ref
+from sdmxlib.model.registry import Registry
+from sdmxlib.model.representation import Facet
+from sdmxlib.model.urn import SdmxUrn
+
+# ── Common helpers ────────────────────────────────────────────────────────────
+
+
+def _istring(obj: dict[str, Any], key: str) -> InternationalString:
+    """Extract a multilingual string field from a JSON object.
+
+    Tries ``key`` first, then ``key + "s"`` (e.g. ``"name"`` → ``"names"``),
+    because the SDMX Global Registry sends ``"names": {"en": "..."}`` while
+    locally-authored fixtures may use ``"name": {"en": "..."}``.
+    """
+    val = obj.get(key)
+    if not isinstance(val, dict) or not val:
+        val = obj.get(key + "s")
+    if not isinstance(val, dict) or not val:
+        return InternationalString()
+    return InternationalString.of({k: v for k, v in val.items() if isinstance(v, str)})
+
+
+def _read_datetime_str(obj: dict[str, Any], key: str) -> datetime | None:
+    """Parse an optional datetime string field."""
+    val = obj.get(key)
+    if not isinstance(val, str) or not val:
+        return None
+    return datetime.fromisoformat(val)
+
+
+def _read_annotations(obj: dict[str, Any]) -> Annotations:
+    """Parse the optional ``annotations`` array on any artefact."""
+    raw = obj.get("annotations")
+    if not raw:
+        return Annotations()
+    items: list[Annotation] = []
+    for ann in raw:
+        text_raw = ann.get("text")
+        text = InternationalString.of(text_raw) if isinstance(text_raw, dict) else InternationalString()
+        items.append(
+            Annotation(
+                id=ann.get("id"),
+                title=ann.get("title"),
+                type=ann.get("type"),
+                url=ann.get("url"),
+                text=text,
+            )
+        )
+    return Annotations(items)
+
+
+# ── Ref / URN helpers ─────────────────────────────────────────────────────────
+
+
+def _resolve_urn(urn_val: Any, index: dict[str, Any]) -> AnyRef | None:
+    """Parse a URN string and resolve it against the artefact index."""
+    if not isinstance(urn_val, str) or not urn_val.startswith("urn:"):
+        return None
+    try:
+        urn = SdmxUrn.parse(urn_val)
+    except (ValueError, TypeError):
+        return None
+    obj = index.get(str(urn))
+    if obj is not None:
+        return Ref.of(urn, obj)
+    return Ref.unresolved(urn)
+
+
+# ── Index helpers ─────────────────────────────────────────────────────────────
+
+
+def _index_artefact(index: dict[str, Any], obj: Any, artefact_type: type[Any]) -> None:
+    """Add a maintainable artefact to the resolution index."""
+    package = artefact_type.sdmx_package
+    cls = artefact_type.sdmx_class
+    urn = SdmxUrn.make(
+        artefact_type,
+        package=package,
+        artefact_class=cls,
+        agency=obj.agency_id,
+        id=obj.id,
+        version=obj.version,
+    )
+    index[str(urn)] = obj
+    urn_latest = SdmxUrn.make(artefact_type, package=package, artefact_class=cls, agency=obj.agency_id, id=obj.id)
+    index[str(urn_latest)] = obj
+
+
+def _index_item(index: dict[str, Any], item: Any, parent: Any, package: str, cls: str) -> None:
+    """Add an item (e.g. Concept) to the index under its item URN."""
+    urn = SdmxUrn.make(
+        object,
+        package=package,
+        artefact_class=cls,
+        agency=parent.agency_id,
+        id=parent.id,
+        version=parent.version,
+        item_id=item.id,
+    )
+    index[str(urn)] = item
+    urn_latest = SdmxUrn.make(
+        object,
+        package=package,
+        artefact_class=cls,
+        agency=parent.agency_id,
+        id=parent.id,
+        item_id=item.id,
+    )
+    index[str(urn_latest)] = item
+
+
+# ── Representation ────────────────────────────────────────────────────────────
+
+
+def _read_representation(rep: dict[str, Any] | None, index: dict[str, Any]) -> AnyRef | Facet | None:
+    """Parse a ``localRepresentation`` object → Ref[Codelist] | Facet | None."""
+    if not rep:
+        return None
+
+    enum_val = rep.get("enumeration")
+    if enum_val is not None:
+        return _resolve_urn(enum_val, index)
+
+    tf_raw = rep.get("textFormat")
+    if isinstance(tf_raw, dict):
+        return Facet(
+            type=tf_raw.get("textType"),
+            max_length=tf_raw.get("maxLength"),
+            min_length=tf_raw.get("minLength"),
+            max_value=tf_raw.get("maxValue"),
+            min_value=tf_raw.get("minValue"),
+            decimals=tf_raw.get("decimals"),
+            pattern=tf_raw.get("pattern"),
+            start_value=tf_raw.get("startValue"),
+            end_value=tf_raw.get("endValue"),
+            is_sequence=tf_raw.get("isSequence"),
+            is_multi_lingual=tf_raw.get("isMultiLingual"),
+        )
+
+    return None
+
+
+def _resolve_agency(agency_id: str, agencies: dict[str, Agency]) -> Agency:
+    """Return the rich Agency if parsed from an AgencyScheme, else a minimal one."""
+    return agencies.get(agency_id, Agency(id=agency_id))
+
+
+# ── OrganisationSchemes ───────────────────────────────────────────────────────
+
+
+def _read_contact(obj: dict[str, Any]) -> Contact:
+    return Contact(
+        name=_istring(obj, "name"),
+        department=_istring(obj, "department"),
+        role=_istring(obj, "role"),
+        phones=tuple(obj.get("phones") or []),
+        faxes=tuple(obj.get("faxes") or []),
+        uris=tuple(obj.get("uris") or []),
+        emails=tuple(obj.get("emails") or []),
+    )
+
+
+def _read_organisation_schemes(
+    data: dict[str, Any],
+) -> tuple[list[AgencyScheme], list[DataProviderScheme]]:
+    agency_schemes: list[AgencyScheme] = []
+    provider_schemes: list[DataProviderScheme] = []
+
+    for as_obj in data.get("agencySchemes") or []:
+        agencies = [
+            Agency(
+                id=item["id"],
+                name=_istring(item, "name"),
+                description=_istring(item, "description"),
+                contacts=tuple(_read_contact(c) for c in (item.get("contacts") or [])),
+                annotations=_read_annotations(item),
+            )
+            for item in (as_obj.get("items") or [])
+        ]
+        agency_schemes.append(
+            AgencyScheme(
+                id=as_obj["id"],
+                maintainer=as_obj.get("agencyID", ""),
+                version=as_obj.get("version", "1.0"),
+                name=_istring(as_obj, "name"),
+                description=_istring(as_obj, "description"),
+                is_final=bool(as_obj.get("isFinal", False)),
+                agencies=ItemList(agencies),
+                annotations=_read_annotations(as_obj),
+                valid_from=_read_datetime_str(as_obj, "validFrom"),
+                valid_to=_read_datetime_str(as_obj, "validTo"),
+            )
+        )
+
+    for ps_obj in data.get("dataProviderSchemes") or []:
+        providers = [
+            DataProvider(
+                id=item["id"],
+                name=_istring(item, "name"),
+                description=_istring(item, "description"),
+                contacts=tuple(_read_contact(c) for c in (item.get("contacts") or [])),
+                annotations=_read_annotations(item),
+            )
+            for item in (ps_obj.get("items") or [])
+        ]
+        provider_schemes.append(
+            DataProviderScheme(
+                id=ps_obj["id"],
+                maintainer=ps_obj.get("agencyID", ""),
+                version=ps_obj.get("version", "1.0"),
+                name=_istring(ps_obj, "name"),
+                description=_istring(ps_obj, "description"),
+                is_final=bool(ps_obj.get("isFinal", False)),
+                providers=ItemList(providers),
+                annotations=_read_annotations(ps_obj),
+                valid_from=_read_datetime_str(ps_obj, "validFrom"),
+                valid_to=_read_datetime_str(ps_obj, "validTo"),
+            )
+        )
+
+    return agency_schemes, provider_schemes
+
+
+# ── Codelists ─────────────────────────────────────────────────────────────────
+
+
+def _read_codelists(data: dict[str, Any], agencies: dict[str, Agency]) -> list[Codelist]:
+    result: list[Codelist] = []
+    for cl in data.get("codelists") or []:
+        codes = [
+            Code(
+                id=item["id"],
+                name=_istring(item, "name"),
+                description=_istring(item, "description"),
+                parent_id=item.get("parent"),
+                annotations=_read_annotations(item),
+            )
+            for item in (cl.get("codes") or cl.get("items") or [])
+        ]
+        result.append(
+            Codelist(
+                id=cl["id"],
+                maintainer=_resolve_agency(cl.get("agencyID", ""), agencies),
+                version=cl.get("version", "1.0"),
+                name=_istring(cl, "name"),
+                description=_istring(cl, "description"),
+                is_final=bool(cl.get("isFinal", False)),
+                codes=ItemList(codes),
+                annotations=_read_annotations(cl),
+                valid_from=_read_datetime_str(cl, "validFrom"),
+                valid_to=_read_datetime_str(cl, "validTo"),
+            )
+        )
+    return result
+
+
+# ── ConceptSchemes ────────────────────────────────────────────────────────────
+
+
+def _read_concept_schemes(data: dict[str, Any], agencies: dict[str, Agency]) -> list[ConceptScheme]:
+    result: list[ConceptScheme] = []
+    for cs in data.get("conceptSchemes") or []:
+        concepts = [
+            Concept(
+                id=item["id"],
+                name=_istring(item, "name"),
+                description=_istring(item, "description"),
+                annotations=_read_annotations(item),
+            )
+            for item in cs.get("items") or []
+        ]
+        result.append(
+            ConceptScheme(
+                id=cs["id"],
+                maintainer=_resolve_agency(cs.get("agencyID", ""), agencies),
+                version=cs.get("version", "1.0"),
+                name=_istring(cs, "name"),
+                description=_istring(cs, "description"),
+                concepts=ItemList(concepts),
+                annotations=_read_annotations(cs),
+                valid_from=_read_datetime_str(cs, "validFrom"),
+                valid_to=_read_datetime_str(cs, "validTo"),
+            )
+        )
+    return result
+
+
+# ── CategorySchemes ───────────────────────────────────────────────────────────
+
+
+def _read_categories(items: list[dict[str, Any]]) -> list[Category]:
+    """Recursively build Category objects from a JSON items array."""
+    return [
+        Category(
+            id=item["id"],
+            name=_istring(item, "name"),
+            description=_istring(item, "description"),
+            categories=ItemList(_read_categories(item.get("items") or [])),
+            annotations=_read_annotations(item),
+        )
+        for item in items
+    ]
+
+
+def _read_category_schemes(data: dict[str, Any], agencies: dict[str, Agency]) -> list[CategoryScheme]:
+    return [
+        CategoryScheme(
+            id=cs["id"],
+            maintainer=_resolve_agency(cs.get("agencyID", ""), agencies),
+            version=cs.get("version", "1.0"),
+            name=_istring(cs, "name"),
+            description=_istring(cs, "description"),
+            categories=ItemList(_read_categories(cs.get("items") or [])),
+            annotations=_read_annotations(cs),
+            valid_from=_read_datetime_str(cs, "validFrom"),
+            valid_to=_read_datetime_str(cs, "validTo"),
+        )
+        for cs in data.get("categorySchemes") or []
+    ]
+
+
+# ── DataStructures ────────────────────────────────────────────────────────────
+
+
+def _read_attachment(ar: dict[str, Any]) -> tuple[AttachmentLevel | None, list[str] | None, str | None]:
+    """Parse ``attributeRelationship`` → (level, related_dimensions, related_measure)."""
+    if "observation" in ar or "primaryMeasure" in ar:
+        return AttachmentLevel.OBSERVATION, None, "OBS_VALUE"
+    if "dataSet" in ar or "none" in ar:
+        return AttachmentLevel.DATASET, None, None
+    dims = ar.get("dimensions")
+    if dims:
+        related = [d if isinstance(d, str) else (d.get("componentId") or d.get("id", "")) for d in dims]
+        return AttachmentLevel.SERIES, related or None, None
+    if "group" in ar:
+        return AttachmentLevel.GROUP, None, None
+    return AttachmentLevel.DATASET, None, None
+
+
+def _read_dimension(dim: dict[str, Any], index: dict[str, Any]) -> Dimension:
+    concept_ref = _resolve_urn(dim.get("conceptIdentity"), index)
+    return Dimension(
+        id=dim["id"],
+        concept=concept_ref,
+        representation=_read_representation(dim.get("localRepresentation"), index),
+        annotations=_read_annotations(dim),
+    )
+
+
+def _read_time_dimension(td: dict[str, Any], index: dict[str, Any]) -> TimeDimension:
+    rep = _read_representation(td.get("localRepresentation"), index)
+    concept_ref = _resolve_urn(td.get("conceptIdentity"), index)
+    return TimeDimension(
+        id=td.get("id", "TIME_PERIOD"),
+        concept=concept_ref,
+        representation=rep if isinstance(rep, Facet) else None,
+        annotations=_read_annotations(td),
+    )
+
+
+def _read_attribute(attr: dict[str, Any], index: dict[str, Any]) -> Attribute:
+    concept_ref = _resolve_urn(attr.get("conceptIdentity"), index)
+    attachment: AttachmentLevel | None = None
+    related_dims: list[str] | None = None
+    related_measure: str | None = None
+    ar = attr.get("attributeRelationship")
+    if isinstance(ar, dict):
+        attachment, related_dims, related_measure = _read_attachment(ar)
+    return Attribute(
+        id=attr["id"],
+        usage=attr.get("usage") or attr.get("assignmentStatus"),
+        attachment=attachment,
+        related_dimensions=related_dims,
+        related_measure=related_measure,
+        concept=concept_ref,
+        representation=_read_representation(attr.get("localRepresentation"), index),
+        annotations=_read_annotations(attr),
+    )
+
+
+def _read_measure(meas: dict[str, Any], index: dict[str, Any]) -> Measure:
+    concept_ref = _resolve_urn(meas.get("conceptIdentity"), index)
+    return Measure(
+        id=meas.get("id", "OBS_VALUE"),
+        concept=concept_ref,
+        representation=_read_representation(meas.get("localRepresentation"), index),
+        annotations=_read_annotations(meas),
+    )
+
+
+def _read_groups(components: dict[str, Any]) -> list[Group]:
+    result: list[Group] = []
+    for grp in components.get("groups") or []:
+        dim_ids = [gd.get("componentId") or gd.get("id", "") for gd in grp.get("groupDimensions") or []]
+        result.append(Group(id=grp["id"], dimension_ids=dim_ids))
+    return result
+
+
+def _read_data_structures(
+    data: dict[str, Any],
+    index: dict[str, Any],
+    agencies: dict[str, Agency],
+) -> list[DataStructure]:
+    result: list[DataStructure] = []
+    for dsd in data.get("dataStructures") or []:
+        components = dsd.get("dataStructureComponents") or {}
+
+        dim_list = components.get("dimensionList") or {}
+        dimensions = [_read_dimension(d, index) for d in dim_list.get("dimensions") or []]
+
+        td_raw = dim_list.get("timeDimension")
+        time_dimension = _read_time_dimension(td_raw, index) if td_raw else None
+
+        attr_list = components.get("attributeList") or {}
+        attributes = [_read_attribute(a, index) for a in attr_list.get("attributes") or []]
+
+        measure_list = components.get("measureList") or {}
+        # SDMX 3.0 style: measures array; SDMX 2.1 fallback: primaryMeasure object
+        raw_measures = measure_list.get("measures") or []
+        if not raw_measures and (pm := measure_list.get("primaryMeasure")):
+            raw_measures = [pm]
+        measures = [_read_measure(m, index) for m in raw_measures]
+
+        groups = _read_groups(components)
+
+        result.append(
+            DataStructure(
+                id=dsd["id"],
+                maintainer=_resolve_agency(dsd.get("agencyID", ""), agencies),
+                version=dsd.get("version", "1.0"),
+                name=_istring(dsd, "name"),
+                description=_istring(dsd, "description"),
+                is_final=bool(dsd.get("isFinal", False)),
+                dimensions=ItemList(dimensions),
+                time_dimension=time_dimension,
+                attributes=ItemList(attributes),
+                measures=ItemList(measures),
+                groups=ItemList(groups) if groups else None,
+                annotations=_read_annotations(dsd),
+                valid_from=_read_datetime_str(dsd, "validFrom"),
+                valid_to=_read_datetime_str(dsd, "validTo"),
+            )
+        )
+    return result
+
+
+# ── Dataflows ─────────────────────────────────────────────────────────────────
+
+
+def _read_dataflows(
+    data: dict[str, Any],
+    index: dict[str, Any],
+    agencies: dict[str, Agency],
+) -> list[Dataflow]:
+    result: list[Dataflow] = []
+    for df in data.get("dataflows") or []:
+        structure_ref = _resolve_urn(df.get("structure"), index)
+        result.append(
+            Dataflow(
+                id=df["id"],
+                maintainer=_resolve_agency(df.get("agencyID", ""), agencies),
+                version=df.get("version", "1.0"),
+                name=_istring(df, "name"),
+                description=_istring(df, "description"),
+                annotations=_read_annotations(df),
+                structure=structure_ref,
+                valid_from=_read_datetime_str(df, "validFrom"),
+                valid_to=_read_datetime_str(df, "validTo"),
+            )
+        )
+    return result
+
+
+# ── Categorisations ───────────────────────────────────────────────────────────
+
+
+def _read_categorisations(
+    data: dict[str, Any],
+    index: dict[str, Any],
+    agencies: dict[str, Agency],
+) -> list[Categorisation]:
+    return [
+        Categorisation(
+            id=cat["id"],
+            maintainer=_resolve_agency(cat.get("agencyID", ""), agencies),
+            version=cat.get("version", "1.0"),
+            name=_istring(cat, "name"),
+            description=_istring(cat, "description"),
+            annotations=_read_annotations(cat),
+            source=_resolve_urn(cat.get("source"), index),
+            target=_resolve_urn(cat.get("target"), index),
+            valid_from=_read_datetime_str(cat, "validFrom"),
+            valid_to=_read_datetime_str(cat, "validTo"),
+        )
+        for cat in data.get("categorisations") or []
+    ]
+
+
+# ── ProvisionAgreements ───────────────────────────────────────────────────────
+
+
+def _read_provision_agreements(
+    data: dict[str, Any],
+    index: dict[str, Any],
+    agencies: dict[str, Agency],
+) -> list[ProvisionAgreement]:
+    return [
+        ProvisionAgreement(
+            id=pa["id"],
+            maintainer=_resolve_agency(pa.get("agencyID", ""), agencies),
+            version=pa.get("version", "1.0"),
+            name=_istring(pa, "name"),
+            description=_istring(pa, "description"),
+            annotations=_read_annotations(pa),
+            dataflow=_resolve_urn(pa.get("structureUsage") or pa.get("dataflow"), index),
+            data_provider=_resolve_urn(pa.get("dataProvider"), index),
+            valid_from=_read_datetime_str(pa, "validFrom"),
+            valid_to=_read_datetime_str(pa, "validTo"),
+        )
+        for pa in data.get("provisionAgreements") or []
+    ]
+
+
+def _read_constraints(
+    data: dict[str, Any],
+    index: dict[str, Any],
+    agencies: dict[str, Agency],
+) -> list[ContentConstraint]:
+    """Parse dataConstraints (SDMX-JSON key) into ContentConstraint objects."""
+    result: list[ContentConstraint] = []
+    for cc in data.get("dataConstraints") or []:
+        # ConstraintAttachment
+        attach = ConstraintAttachment()
+        ca = cc.get("constraintAttachment")
+        if ca:
+            if dataflow_urn := ca.get("dataflow"):
+                ref = _resolve_urn(dataflow_urn, index)
+                attach = ConstraintAttachment(dataflow=ref)
+            elif ds_urn := ca.get("dataStructure"):
+                ref = _resolve_urn(ds_urn, index)
+                attach = ConstraintAttachment(data_structure=ref)
+            elif pa_urn := ca.get("provisionAgreement"):
+                ref = _resolve_urn(pa_urn, index)
+                attach = ConstraintAttachment(provision_agreement=ref)
+
+        regions: list[CubeRegion] = []
+        for region in cc.get("cubeRegions") or []:
+            include = region.get("include", True)
+            keys: list[KeyValue] = []
+            for kv in region.get("keyValues") or []:
+                dim_id = kv.get("id", "")
+                values = frozenset(str(v) for v in kv.get("values") or [])
+                keys.append(KeyValue(dimension_id=dim_id, values=values))
+            regions.append(CubeRegion(include=include, keys=tuple(keys)))
+
+        reference_period: ReferencePeriod | None = None
+        rp_raw = cc.get("referencePeriod")
+        if isinstance(rp_raw, dict):
+            reference_period = ReferencePeriod(
+                start_period=datetime.fromisoformat(rp_raw["startPeriod"]),
+                end_period=datetime.fromisoformat(rp_raw["endPeriod"]),
+            )
+
+        release_calendar: ReleaseCalendar | None = None
+        rc_raw = cc.get("releaseCalendar")
+        if isinstance(rc_raw, dict):
+            release_calendar = ReleaseCalendar(
+                periodicity=rc_raw["periodicity"],
+                offset=rc_raw["offset"],
+                tolerance=rc_raw["tolerance"],
+            )
+
+        result.append(
+            ContentConstraint(
+                id=cc.get("id", ""),
+                maintainer=_resolve_agency(cc.get("agencyID", ""), agencies),
+                version=cc.get("version", "1.0"),
+                name=_istring(cc, "name"),
+                description=_istring(cc, "description"),
+                is_final=cc.get("isFinal", False),
+                constraint_type=cc.get("type", "Allowed"),
+                attachment=attach,
+                regions=tuple(regions),
+                reference_period=reference_period,
+                release_calendar=release_calendar,
+                annotations=_read_annotations(cc),
+                valid_from=_read_datetime_str(cc, "validFrom"),
+                valid_to=_read_datetime_str(cc, "validTo"),
+            )
+        )
+    return result
+
+
+def _read_structure_sets(
+    data: dict[str, Any],
+    index: dict[str, Any],
+    agencies: dict[str, Agency],
+) -> list[StructureSet]:
+    """Parse structureSets (SDMX-JSON key) into StructureSet objects."""
+    result: list[StructureSet] = []
+    for ss in data.get("structureSets") or []:
+        maps: list[CodelistMap] = []
+        for cm in ss.get("codelistMaps") or []:
+            source_ref = _resolve_urn(cm.get("source"), index)
+            target_ref = _resolve_urn(cm.get("target"), index)
+            code_maps = [
+                CodeMap(source_id=m["source"], target_id=m["target"])
+                for m in cm.get("codeMaps") or []
+                if "source" in m and "target" in m
+            ]
+            maps.append(
+                CodelistMap(
+                    id=cm.get("id", ""),
+                    name=_istring(cm, "name"),
+                    description=_istring(cm, "description"),
+                    source=source_ref,
+                    target=target_ref,
+                    maps=tuple(code_maps),
+                )
+            )
+
+        concept_scheme_maps: list[ConceptSchemeMap] = []
+        for csm in ss.get("conceptSchemeMaps") or []:
+            source_ref = _resolve_urn(csm.get("source"), index)
+            target_ref = _resolve_urn(csm.get("target"), index)
+            concept_maps = [
+                ConceptMap(source_id=m["sourceId"], target_id=m["targetId"])
+                for m in csm.get("conceptMaps") or []
+                if "sourceId" in m and "targetId" in m
+            ]
+            concept_scheme_maps.append(
+                ConceptSchemeMap(
+                    id=csm.get("id", ""),
+                    name=_istring(csm, "name"),
+                    description=_istring(csm, "description"),
+                    source=source_ref,
+                    target=target_ref,
+                    maps=tuple(concept_maps),
+                )
+            )
+
+        category_scheme_maps: list[CategorySchemeMap] = []
+        for catm in ss.get("categorySchemeMaps") or []:
+            source_ref = _resolve_urn(catm.get("source"), index)
+            target_ref = _resolve_urn(catm.get("target"), index)
+            cat_maps = [
+                CategoryMap(source_id=m["sourceId"], target_id=m["targetId"])
+                for m in catm.get("categoryMaps") or []
+                if "sourceId" in m and "targetId" in m
+            ]
+            category_scheme_maps.append(
+                CategorySchemeMap(
+                    id=catm.get("id", ""),
+                    name=_istring(catm, "name"),
+                    description=_istring(catm, "description"),
+                    source=source_ref,
+                    target=target_ref,
+                    maps=tuple(cat_maps),
+                )
+            )
+
+        data_structure_maps: list[DataStructureMap] = []
+        for dsm in ss.get("dataStructureMaps") or []:
+            source_ref = _resolve_urn(dsm.get("source"), index)
+            target_ref = _resolve_urn(dsm.get("target"), index)
+            comp_maps = [
+                ComponentMap(source_id=m["sourceId"], target_id=m["targetId"])
+                for m in dsm.get("componentMaps") or []
+                if "sourceId" in m and "targetId" in m
+            ]
+            data_structure_maps.append(
+                DataStructureMap(
+                    id=dsm.get("id", ""),
+                    name=_istring(dsm, "name"),
+                    description=_istring(dsm, "description"),
+                    source=source_ref,
+                    target=target_ref,
+                    maps=tuple(comp_maps),
+                )
+            )
+
+        dataflow_maps: list[DataflowMap] = []
+        for dfm in ss.get("dataflowMaps") or []:
+            source_ref = _resolve_urn(dfm.get("source"), index)
+            target_ref = _resolve_urn(dfm.get("target"), index)
+            dataflow_maps.append(
+                DataflowMap(
+                    id=dfm.get("id", ""),
+                    name=_istring(dfm, "name"),
+                    description=_istring(dfm, "description"),
+                    source=source_ref,
+                    target=target_ref,
+                )
+            )
+
+        result.append(
+            StructureSet(
+                id=ss.get("id", ""),
+                maintainer=_resolve_agency(ss.get("agencyID", ""), agencies),
+                version=ss.get("version", "1.0"),
+                name=_istring(ss, "name"),
+                description=_istring(ss, "description"),
+                is_final=ss.get("isFinal", False),
+                codelist_maps=tuple(maps),
+                concept_scheme_maps=tuple(concept_scheme_maps),
+                category_scheme_maps=tuple(category_scheme_maps),
+                data_structure_maps=tuple(data_structure_maps),
+                dataflow_maps=tuple(dataflow_maps),
+                annotations=_read_annotations(ss),
+                valid_from=_read_datetime_str(ss, "validFrom"),
+                valid_to=_read_datetime_str(ss, "validTo"),
+            )
+        )
+    return result
+
+
+# ── Hierarchies ──────────────────────────────────────────────────────────────
+
+
+def _read_hierarchical_code(obj: dict[str, Any]) -> HierarchicalCode:
+    """Recursively parse a hierarchicalCode JSON object."""
+    code_ref: Ref[Code] | None = None
+    code_urn = obj.get("code")
+    if isinstance(code_urn, str) and code_urn.startswith("urn:"):
+        try:
+            urn = SdmxUrn.parse(code_urn)
+            code_ref = Ref[Code].unresolved(urn)
+        except (ValueError, TypeError):
+            pass
+
+    children = [_read_hierarchical_code(child) for child in obj.get("hierarchicalCodes") or []]
+
+    return HierarchicalCode(
+        id=obj["id"],
+        code=code_ref,
+        name=_istring(obj, "name"),
+        description=_istring(obj, "description"),
+        children=children,
+        annotations=_read_annotations(obj),
+    )
+
+
+def _read_hierarchies(
+    data: dict[str, Any],
+    agencies: dict[str, Agency],
+) -> list[Hierarchy]:
+    """Parse hierarchies array into Hierarchy objects."""
+    result: list[Hierarchy] = []
+    for h in data.get("hierarchies") or []:
+        tree = [_read_hierarchical_code(hc) for hc in h.get("hierarchicalCodes") or []]
+        result.append(
+            Hierarchy(
+                id=h["id"],
+                maintainer=_resolve_agency(h.get("agencyID", ""), agencies),
+                version=h.get("version", "1.0"),
+                name=_istring(h, "name"),
+                description=_istring(h, "description"),
+                is_final=bool(h.get("isFinal", False)),
+                tree=tree,
+                annotations=_read_annotations(h),
+                valid_from=_read_datetime_str(h, "validFrom"),
+                valid_to=_read_datetime_str(h, "validTo"),
+            )
+        )
+    return result
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+
+def read(data: bytes, *, registry: Registry | None = None) -> StructureMessage:
+    """Parse SDMX-JSON 2.0 bytes into a StructureMessage.
+
+    References within the message are auto-resolved where URNs match
+    artefacts present in the same message.
+
+    If *registry* is provided all parsed artefacts are added to it via
+    ``registry.add_all()``, interning their Refs for cross-message resolution.
+
+    Args:
+        data: Raw JSON bytes of an SDMX-JSON 2.0 Structure message.
+        registry: Optional Registry to intern artefacts into after parsing.
+
+    Returns:
+        A fully constructed StructureMessage with resolved cross-references.
+    """
+    doc = json.loads(data)
+    payload: dict[str, Any] = doc.get("data") or {}
+
+    # ── Phase 1: parse leaf artefacts (no refs to other artefacts) ──────────
+    agency_schemes, data_provider_schemes = _read_organisation_schemes(payload)
+
+    # Build agency lookup for opportunistic resolution in subsequent phases
+    agencies: dict[str, Agency] = {a.id: a for s in agency_schemes for a in s.agencies}
+
+    codelists = _read_codelists(payload, agencies)
+    concept_schemes = _read_concept_schemes(payload, agencies)
+    category_schemes = _read_category_schemes(payload, agencies)
+
+    # ── Phase 2: build resolution index ─────────────────────────────────────
+    index: dict[str, Any] = {}
+
+    for cl in codelists:
+        _index_artefact(index, cl, Codelist)
+
+    for cs in concept_schemes:
+        _index_artefact(index, cs, ConceptScheme)
+        for concept in cs.concepts:
+            _index_item(index, concept, cs, ConceptScheme.sdmx_package, "Concept")
+
+    for cat_s in category_schemes:
+        _index_artefact(index, cat_s, CategoryScheme)
+
+    # ── Phase 3: parse artefacts that reference codelists / concepts ─────────
+    data_structures = _read_data_structures(payload, index, agencies)
+    for dsd in data_structures:
+        _index_artefact(index, dsd, DataStructure)
+
+    dataflows = _read_dataflows(payload, index, agencies)
+    for df in dataflows:
+        _index_artefact(index, df, Dataflow)
+
+    # ── Phase 4: parse artefacts that reference DSDs / dataflows ────────────
+    categorisations = _read_categorisations(payload, index, agencies)
+    provision_agreements = _read_provision_agreements(payload, index, agencies)
+    constraints = _read_constraints(payload, index, agencies)
+    structure_sets = _read_structure_sets(payload, index, agencies)
+    hierarchies = _read_hierarchies(payload, agencies)
+
+    msg = StructureMessage(
+        codelists=ArtefactList(codelists),
+        concept_schemes=ArtefactList(concept_schemes),
+        data_structures=ArtefactList(data_structures),
+        dataflows=ArtefactList(dataflows),
+        category_schemes=ArtefactList(category_schemes),
+        categorisations=ArtefactList(categorisations),
+        provision_agreements=ArtefactList(provision_agreements),
+        agency_schemes=ArtefactList(agency_schemes),
+        data_provider_schemes=ArtefactList(data_provider_schemes),
+        constraints=ArtefactList(constraints),
+        structure_sets=ArtefactList(structure_sets),
+        hierarchies=ArtefactList(hierarchies),
+    )
+    if registry is not None:
+        registry.add_all(msg.all_artefacts())
+    return msg