sdmxlib 0.8.0__py3-none-any.whl

sdmxlib/model/validation.py

@@ -0,0 +1,338 @@
+"""Validate domain objects against SDMX structural rules.
+
+Validation is explicit and non-blocking — objects can be constructed in any
+state, and validation is called when ready. This allows iterative building,
+format readers to accept non-compliant data, and tests to construct invalid
+objects deliberately.
+
+Example:
+    import sdmxlib as sl
+
+    issues = sl.validate(dsd)
+    for issue in issues:
+        print(f"  {issue.severity}: {issue.path} — {issue.message}")
+
+    ref_issues = sl.validate_references(msg)
+    for issue in ref_issues:
+        print(f"  BROKEN: {issue.source} → {issue.target_urn}")
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+import attrs
+from attrs import frozen
+
+from sdmxlib.model.base import MaintainableArtefact
+from sdmxlib.model.codelist import Codelist
+from sdmxlib.model.concept import ConceptScheme
+from sdmxlib.model.datastructure import DataStructure
+from sdmxlib.model.hierarchy import Hierarchy
+from sdmxlib.model.ref import AnyRef, Ref
+from sdmxlib.model.urn import SdmxUrn
+
+if TYPE_CHECKING:
+    from sdmxlib.model.message import StructureMessage
+
+# SDMX 2.1 / 3.0 formal type patterns from SDMXCommonReferences.xsd
+# IDType:       [A-Za-z0-9_@$-]+
+# NestedIDType: [A-Za-z0-9_@$-]+(\.[A-Za-z0-9_@$-]+)*   (dots for agency hierarchy)
+# VersionType:  [0-9]+(\.[0-9]+)*
+_ID_RE = re.compile(r"^[A-Za-z0-9_@$-]+$")
+_AGENCY_RE = re.compile(r"^[A-Za-z0-9_@$-]+(\.[A-Za-z0-9_@$-]+)*$")
+_VERSION_RE = re.compile(r"^\d+(\.\d+)*$")
+
+
+@frozen
+class ValidationIssue:
+    """A single validation problem found on an artefact.
+
+    Attributes:
+        path: Dotted path to the offending field (e.g. ``"dimensions[FREQ].id"``).
+        message: Human-readable description of the problem.
+        severity: ``"error"`` or ``"warning"``.
+    """
+
+    path: str
+    message: str
+    severity: str = "error"
+
+    def __str__(self) -> str:
+        return f"{self.severity}: {self.path} — {self.message}"
+
+
+@frozen
+class ReferenceIssue:
+    """A broken cross-artefact reference within a StructureMessage.
+
+    Attributes:
+        source: Path of the artefact/field that holds the Ref.
+        target_urn: The URN the Ref points to.
+        message: Human-readable description.
+    """
+
+    source: str
+    target_urn: str
+    message: str = "referenced artefact not found in message"
+
+    def __str__(self) -> str:
+        return f"BROKEN: {self.source} → {self.target_urn}"
+
+
+# ── Per-artefact validation ────────────────────────────────────────────────────
+
+
+class _ValidationError(Exception):
+    """Internal: raised in strict mode on the first issue."""
+
+    def __init__(self, issue: ValidationIssue) -> None:
+        self.issue = issue
+
+
+def _issue(
+    issues: list[ValidationIssue],
+    path: str,
+    message: str,
+    severity: str = "error",
+    *,
+    strict: bool,
+) -> None:
+    issue = ValidationIssue(path=path, message=message, severity=severity)
+    issues.append(issue)
+    if strict:
+        raise _ValidationError(issue)
+
+
+def _check_id(val: str, path: str, issues: list[ValidationIssue], *, strict: bool) -> None:
+    if not val:
+        _issue(issues, path, "id must not be empty", strict=strict)
+    elif not _ID_RE.match(val):
+        _issue(issues, path, f"id {val!r} contains invalid characters (allowed: A-Za-z0-9_@$-)", strict=strict)
+
+
+def _check_agency_id(val: str, path: str, issues: list[ValidationIssue], *, strict: bool) -> None:
+    if not val:
+        _issue(issues, path, "agency_id must not be empty", strict=strict)
+    elif not _AGENCY_RE.match(val):
+        _issue(
+            issues,
+            path,
+            f"agency_id {val!r} is not valid (allowed: A-Za-z0-9_@$- segments separated by dots)",
+            strict=strict,
+        )
+
+
+def _check_version(val: str, path: str, issues: list[ValidationIssue], *, strict: bool) -> None:
+    if not _VERSION_RE.match(val):
+        _issue(issues, path, f"version {val!r} is not valid (expected digits separated by dots)", strict=strict)
+
+
+def _check_ref_urn(ref: AnyRef, path: str, issues: list[ValidationIssue], *, strict: bool) -> None:
+    try:
+        _ = str(ref.urn)
+    except (ValueError, TypeError, AttributeError):
+        _issue(issues, path, "Ref has an invalid or missing URN", strict=strict)
+
+
+def _validate_maintainable(
+    artefact: MaintainableArtefact,
+    prefix: str,
+    issues: list[ValidationIssue],
+    *,
+    strict: bool,
+) -> None:
+    _check_id(artefact.id, f"{prefix}.id", issues, strict=strict)  # type: ignore[union-attr]
+    _check_agency_id(artefact.agency_id, f"{prefix}.agency_id", issues, strict=strict)  # type: ignore[union-attr]
+    _check_version(artefact.version, f"{prefix}.version", issues, strict=strict)  # type: ignore[union-attr]
+
+
+def _validate_codelist(cl: Codelist, prefix: str, issues: list[ValidationIssue], *, strict: bool) -> None:
+    _validate_maintainable(cl, prefix, issues, strict=strict)
+    seen: set[str] = set()
+    for code in cl.codes:
+        _check_id(code.id, f"{prefix}.codes[{code.id}].id", issues, strict=strict)
+        if code.id in seen:
+            _issue(issues, f"{prefix}.codes[{code.id}]", f"duplicate code id {code.id!r}", strict=strict)
+        seen.add(code.id)
+
+
+def _validate_dsd(dsd: DataStructure, prefix: str, issues: list[ValidationIssue], *, strict: bool) -> None:
+    _validate_maintainable(dsd, prefix, issues, strict=strict)
+
+    for dim in dsd.dimensions:
+        _check_id(dim.id, f"{prefix}.dimensions[{dim.id}].id", issues, strict=strict)
+        if isinstance(dim.representation, Ref):
+            _check_ref_urn(dim.representation, f"{prefix}.dimensions[{dim.id}].representation", issues, strict=strict)
+        if isinstance(dim.concept, Ref):
+            _check_ref_urn(dim.concept, f"{prefix}.dimensions[{dim.id}].concept", issues, strict=strict)
+
+    for attr in dsd.attributes:
+        _check_id(attr.id, f"{prefix}.attributes[{attr.id}].id", issues, strict=strict)
+        if isinstance(attr.representation, Ref):
+            _check_ref_urn(attr.representation, f"{prefix}.attributes[{attr.id}].representation", issues, strict=strict)
+
+    for meas in dsd.measures:
+        _check_id(meas.id, f"{prefix}.measures[{meas.id}].id", issues, strict=strict)
+
+
+def _validate_hierarchy(hierarchy: Hierarchy, prefix: str, issues: list[ValidationIssue], *, strict: bool) -> None:
+    _validate_maintainable(hierarchy, prefix, issues, strict=strict)
+    seen: set[str] = set()
+    for node in hierarchy.codes:
+        _check_id(node.id, f"{prefix}.codes[{node.id}].id", issues, strict=strict)
+        if node.id in seen:
+            _issue(issues, f"{prefix}.codes[{node.id}]", f"duplicate node id {node.id!r}", strict=strict)
+        seen.add(node.id)
+        if isinstance(node.code, Ref):
+            _check_ref_urn(node.code, f"{prefix}.codes[{node.id}].code", issues, strict=strict)
+
+
+def validate(artefact: Any, *, strict: bool = False) -> list[ValidationIssue]:
+    """Validate an artefact against SDMX structural rules.
+
+    Checks:
+    - ``id`` format (``[A-Za-z0-9_-]+``)
+    - ``agency_id`` format (``[A-Za-z0-9._-]+``)
+    - ``version`` format (digits separated by dots)
+    - Required fields present (id, agency_id for maintainables)
+    - Code id uniqueness within codelists
+    - Dimension position continuity (1, 2, 3, ...)
+    - Ref URN format validity
+
+    Args:
+        artefact: Any domain model object.
+        strict: If ``True``, raises ``ValueError`` on the first issue found
+            instead of collecting all issues.
+
+    Returns:
+        List of ``ValidationIssue``. Empty list means the artefact is valid.
+
+    Raises:
+        ValueError: If ``strict=True`` and an issue is found.
+
+    Example:
+        issues = validate(dsd)
+        for issue in issues:
+            print(f"{issue.path}: {issue.message}")
+    """
+    issues: list[ValidationIssue] = []
+    cls_name = type(artefact).__name__
+    try:
+        if isinstance(artefact, DataStructure):
+            _validate_dsd(artefact, cls_name, issues, strict=strict)
+        elif isinstance(artefact, Codelist):
+            _validate_codelist(artefact, cls_name, issues, strict=strict)
+        elif isinstance(artefact, Hierarchy):
+            _validate_hierarchy(artefact, cls_name, issues, strict=strict)
+        elif isinstance(artefact, MaintainableArtefact):
+            _validate_maintainable(artefact, cls_name, issues, strict=strict)
+    except _ValidationError as exc:
+        if strict:
+            raise ValueError(str(exc.issue)) from exc
+    return issues
+
+
+# ── Cross-artefact reference validation ──────────────────────────────────────
+
+
+def _collect_known_urns(msg: StructureMessage) -> set[str]:
+    """Build the set of all artefact URN strings present in the message.
+
+    Includes both scheme-level URNs and item-level URNs for concept schemes
+    (so that concept refs used in DSD components resolve correctly).
+    """
+    known: set[str] = set()
+    for artefact in msg.all_artefacts():
+        if isinstance(artefact, MaintainableArtefact):
+            try:
+                urn: SdmxUrn[Any] = SdmxUrn.make(
+                    type(artefact),
+                    package=artefact.sdmx_package,  # type: ignore[union-attr]
+                    artefact_class=artefact.sdmx_class,  # type: ignore[union-attr]
+                    agency=artefact.agency_id,  # type: ignore[union-attr]
+                    id=artefact.id,  # type: ignore[union-attr]
+                    version=artefact.version,  # type: ignore[union-attr]
+                )
+                known.add(str(urn))
+            except (ValueError, TypeError, AttributeError):
+                pass
+
+            # Also add item-level URNs for concept schemes so DSD concept
+            # refs (which carry item_id) can be resolved.
+            if isinstance(artefact, ConceptScheme):
+                for concept in artefact.concepts:
+                    try:
+                        item_urn: SdmxUrn[Any] = SdmxUrn.make(
+                            type(concept),
+                            package="conceptscheme",
+                            artefact_class="Concept",
+                            agency=artefact.agency_id,
+                            id=artefact.id,
+                            version=artefact.version,
+                            item_id=concept.id,
+                        )
+                        known.add(str(item_urn))
+                    except (ValueError, TypeError, AttributeError):
+                        pass
+    return known
+
+
+def _collect_refs(artefact: Any, prefix: str) -> list[tuple[str, AnyRef]]:
+    """Collect (path, ref) pairs for all Ref fields in an artefact.
+
+    Uses dataclass field introspection so new Ref fields are automatically
+    picked up without maintaining a hardcoded list.
+    """
+    results: list[tuple[str, AnyRef]] = []
+    if attrs.has(type(artefact)) and not isinstance(artefact, type):
+        for field in attrs.fields(type(artefact)):
+            val = getattr(artefact, field.name, None)
+            if isinstance(val, Ref):
+                results.append((f"{prefix}.{field.name}", val))
+
+    # Recurse into components for DataStructure
+    if isinstance(artefact, DataStructure):
+        for dim in artefact.dimensions:
+            results.extend(_collect_refs(dim, f"{prefix}.dimensions[{dim.id}]"))
+        for attr in artefact.attributes:
+            results.extend(_collect_refs(attr, f"{prefix}.attributes[{attr.id}]"))
+        for meas in artefact.measures:
+            results.extend(_collect_refs(meas, f"{prefix}.measures[{meas.id}]"))
+    if isinstance(artefact, Hierarchy):
+        for node in artefact.codes:
+            results.extend(_collect_refs(node, f"{prefix}.codes[{node.id}]"))
+    return results
+
+
+def validate_references(msg: StructureMessage) -> list[ReferenceIssue]:
+    """Check that all Refs within a message resolve to artefacts in that message.
+
+    For each unresolved Ref whose URN does not correspond to any artefact in
+    the message, a ``ReferenceIssue`` is reported.
+
+    Args:
+        msg: The ``StructureMessage`` to check.
+
+    Returns:
+        List of ``ReferenceIssue``. Empty list means all references are satisfied.
+
+    Example:
+        issues = validate_references(msg)
+        for issue in issues:
+            print(f"  BROKEN: {issue.source} → {issue.target_urn}")
+    """
+    known = _collect_known_urns(msg)
+    issues: list[ReferenceIssue] = []
+
+    for artefact in msg.all_artefacts():
+        cls_name = type(artefact).__name__
+        artefact_id = getattr(artefact, "id", "?")
+        prefix = f"{cls_name}:{artefact_id}"
+        for path, ref in _collect_refs(artefact, prefix):
+            urn_str = str(ref.urn)
+            if urn_str not in known:
+                issues.append(ReferenceIssue(source=path, target_urn=urn_str))
+
+    return issues