PathBridge 0.1.0__tar.gz

pathbridge-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+*.pyo
+*.pyc
+*.swp
+.DS_Store
+*~
+build/
+dist/
+forgery-py.sublime-project
+forgery-py.sublime-workspace
+docs/_build/
+.idea/
+tmp/
+.coverage
+TODO.rst
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+htmlcov/
+__pycache__/
+_version.py

pathbridge-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Vitaly Samigullin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pathbridge-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: PathBridge
+Version: 0.1.0
+Summary: Translate validator error locations back to your application's schema paths and emit structured errors
+Project-URL: Homepage, https://github.com/pilosus/pathbridge
+Project-URL: Repository, https://github.com/pilosus/pathbridge
+Project-URL: Issues, https://github.com/pilosus/pathbridge/issues
+Author-email: Vitaly Samigullin <vrs@pilosus.org>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PathBridge
+
+> Bridge validator locations (XPath/JSONPath/JSON Pointer) back to your application model paths, and emit structured errors (Marshmallow-ready).
+
+[![PyPI version](https://img.shields.io/pypi/v/pathbridge.svg)](https://pypi.org/project/pathbridge/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/pathbridge.svg)](https://pypi.org/project/pathbridge/)
+
+## Why
+
+Validators (XSD/Schematron, JSON Schema) report failures at **document locations** (XPath/JSONPath).  
+Your users need errors on **your model** (Pydantic/Marshmallow/dataclasses). PathBridge converts between the two.
+
+- Prefix & case tolerant (e.g., `hd:`, `MTR:`).
+- Fixes 1-based indices to Python 0-based.
+- Works with plain mappings or an optional tracer (add-on) that learns rules from your converter.
+
+## Install
+
+```bash
+pip install pathbridge
+```
+
+## Quick start
+
+```python
+from pathbridge import compile_rules, translate_location, to_marshmallow
+
+# 1. Provide or load rules: destination path -> facade (your app models) path 
+rules = {
+    "Return[1]/Contact[1]/Phone[1]": "person/phones[0]",
+    "Return[1]/Contact[1]/Phone[2]": "person/phones[1]",
+}
+
+compiled = compile_rules(rules)
+
+# 2. Translate validator location (e.g. from Schematron SVRL)
+loc = "/Return[1]/Contact[1]/Phone[2]"
+print(translate_location(loc, compiled))
+# "person/phones[1]"
+
+# 3. Transform error location into a Marshmallow-style error dict
+errors = to_marshmallow([(loc, "Invalid phone")], compiled)
+# {'person': {'phones': {1: ['Invalid phone']}}}
+```

pathbridge-0.1.0/README.md

@@ -0,0 +1,45 @@
+# PathBridge
+
+> Bridge validator locations (XPath/JSONPath/JSON Pointer) back to your application model paths, and emit structured errors (Marshmallow-ready).
+
+[![PyPI version](https://img.shields.io/pypi/v/pathbridge.svg)](https://pypi.org/project/pathbridge/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/pathbridge.svg)](https://pypi.org/project/pathbridge/)
+
+## Why
+
+Validators (XSD/Schematron, JSON Schema) report failures at **document locations** (XPath/JSONPath).  
+Your users need errors on **your model** (Pydantic/Marshmallow/dataclasses). PathBridge converts between the two.
+
+- Prefix & case tolerant (e.g., `hd:`, `MTR:`).
+- Fixes 1-based indices to Python 0-based.
+- Works with plain mappings or an optional tracer (add-on) that learns rules from your converter.
+
+## Install
+
+```bash
+pip install pathbridge
+```
+
+## Quick start
+
+```python
+from pathbridge import compile_rules, translate_location, to_marshmallow
+
+# 1. Provide or load rules: destination path -> facade (your app models) path 
+rules = {
+    "Return[1]/Contact[1]/Phone[1]": "person/phones[0]",
+    "Return[1]/Contact[1]/Phone[2]": "person/phones[1]",
+}
+
+compiled = compile_rules(rules)
+
+# 2. Translate validator location (e.g. from Schematron SVRL)
+loc = "/Return[1]/Contact[1]/Phone[2]"
+print(translate_location(loc, compiled))
+# "person/phones[1]"
+
+# 3. Transform error location into a Marshmallow-style error dict
+errors = to_marshmallow([(loc, "Invalid phone")], compiled)
+# {'person': {'phones': {1: ['Invalid phone']}}}
+```

pathbridge-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "PathBridge"
+version = "0.1.0"
+description = "Translate validator error locations back to your application's schema paths and emit structured errors"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Vitaly Samigullin", email = "vrs@pilosus.org" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+keywords = []
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/pilosus/pathbridge"
+Repository = "https://github.com/pilosus/pathbridge"
+Issues = "https://github.com/pilosus/pathbridge/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pathbridge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/pathbridge"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]  # doctrings length

pathbridge-0.1.0/src/pathbridge/__init__.py

@@ -0,0 +1,16 @@
+import sys
+from importlib.metadata import version as _get_version
+
+from .adapter import to_marshmallow
+from .compiler import compile_rules, insert_error, translate_location
+
+__version__ = _get_version("pathbridge")
+
+version = f"{__version__}, Python {sys.version}"
+
+__all__ = [
+    "compile_rules",
+    "translate_location",
+    "insert_error",
+    "to_marshmallow",
+]

pathbridge-0.1.0/src/pathbridge/adapter.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from .compiler import insert_error, translate_location
+from .types import (
+    CompiledRulesT,
+    ErrorInputT,
+    ErrorItemT,
+    LocationT,
+    MarshmallowValidationErrorT,
+)
+
+#
+# Public API
+#
+
+
+def to_marshmallow(
+    items: ErrorInputT,
+    compiled_rules: CompiledRulesT,
+    *,
+    default_message: str = "Invalid",
+    include_meta: bool = False,
+) -> dict[str | int, Any]:
+    """
+    Translate validator locations to facade paths and fold into a Marshmallow-style nested dict.
+
+    include_meta adds a `_meta` key-val with translation stats and misses.
+
+    Returns
+    -------
+    dict
+        Nested structure compatible with Marshmallow errors, e.g.:
+        {
+          'mtr': {
+            'sa103s': {
+              6: {'net_profit_or_loss': ['The amount must equal ...']}
+            }
+          },
+          '_meta': { ... }  # only when include_meta=True
+        }
+    """
+    errors: MarshmallowValidationErrorT = {}
+    total = 0
+    matched = 0
+    misses: list[tuple[LocationT, str]] = []
+
+    for loc, msg in _iter_error_pairs(items, default_message):
+        total += 1
+        facade = translate_location(loc, compiled_rules)
+        if facade is None:
+            misses.append((loc, msg))
+            continue
+        insert_error(errors, facade, msg)
+        matched += 1
+
+    # shallow copy for meta injection
+    result: dict[str | int, Any] = dict(errors)
+    if include_meta:
+        result["_meta"] = {
+            "total": total,
+            "matched": matched,
+            "missed": len(misses),
+            "misses": [{"location": loc, "message": msg} for (loc, msg) in misses],
+        }
+    return result
+
+
+#
+# Helpers
+#
+
+
+def _iter_error_pairs(items: ErrorInputT, default_message: str) -> Iterator[ErrorItemT]:
+    """
+    Normalize different error input shapes into (location, message) pairs.
+
+    Supports:
+      - Iterable[tuple[str, str]]
+      - Iterable[dict] with 'location' (str|list[str]) and optional 'message' or 'text'
+      - Iterable[objects] with .location (Sequence[str]) and .text (Sequence[str])
+    """
+    for item in items:
+        # Case 1: already a (location, message) pair
+        if (
+            isinstance(item, tuple)
+            and len(item) == 2
+            and all(isinstance(x, str) for x in item)
+        ):
+            yield item
+            continue
+
+        # Case 2: dict-like (JSON-derived)
+        if isinstance(item, dict) and "location" in item:
+            locs = _as_list(item.get("location"))
+            msgs = _as_list(item.get("message", item.get("text")))
+            for idx, loc in enumerate(locs):
+                if not isinstance(loc, str):
+                    continue
+                msg = (
+                    msgs[idx]
+                    if idx < len(msgs) and isinstance(msgs[idx], str)
+                    else default_message
+                )
+                yield (loc, msg)
+            continue
+
+        # Case 3: Dataclasses with .location / .text
+        locs = _as_list(getattr(item, "location", None))
+        if locs is not None:
+            msgs = _as_list(getattr(item, "text", None))
+            loc_list = list(
+                locs
+                if isinstance(locs, Sequence) and not isinstance(locs, str)
+                else [locs]
+            )
+            msg_list = (
+                list(msgs)
+                if isinstance(msgs, Sequence) and not isinstance(msgs, str)
+                else ([] if msgs is None else [str(msgs)])
+            )
+            for idx, loc in enumerate(loc_list):
+                if not isinstance(loc, str):
+                    continue
+                msg = msg_list[idx] if idx < len(msg_list) else default_message
+                yield (loc, msg)
+            continue
+
+        # Fallback: ignore unknown shapes
+
+
+def _as_list(x: Any) -> list[Any]:
+    if x is None:
+        return []
+    if isinstance(x, list):
+        return x
+    if isinstance(x, tuple):
+        return list(x)
+    return [x]
+
+
+__all__ = [
+    "to_marshmallow",
+]

pathbridge-0.1.0/src/pathbridge/compiler.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+import re
+
+from .types import (
+    CompiledRulesT,
+    CompiledRuleT,
+    FacadePathT,
+    FacadePathTemplateT,
+    LocationT,
+    MarshmallowValidationErrorT,
+    RawRulesMapT,
+)
+
+#
+# Public API
+#
+
+
+def compile_rules(rules: RawRulesMapT) -> CompiledRulesT:
+    """
+    Compile mappings of {destination_path -> facade_path} into case-insensitive
+    regex matchers and facade templates with capture placeholders like '{i0-1}'.
+
+    - Destination path is typically XPath-like with one-based indices and optional prefixes
+    - Each step tolerates an optional namespace prefix and case-insensitive names
+    - Any arbitrary leading prefixes are skipped (e.g., '/hd:GovTalkMessage[1]/.../IRenvelope[1]/')
+    - Every captured index is available as a named group 'iK'; facade templates use '{iK-1}'
+    """
+    compiled: list[CompiledRuleT] = []
+    for dest, facade in rules.items():
+        pattern_str, _, name_to_caps = _dest_segments_with_captures(dest)
+        template = _build_facade_template(facade, name_to_caps)
+        pat = re.compile(pattern_str, re.IGNORECASE | re.UNICODE)
+        compiled.append((pat, template))
+    return compiled
+
+
+def translate_location(
+    location: LocationT, compiled_rules: CompiledRulesT
+) -> FacadePathT | None:
+    """
+    Return a first matching facade path (e.g., 'mtr/sa103s[6]/foo/bar') if any rule matches the given location.
+    If no matches found return None.
+    """
+    for pat, template in compiled_rules:
+        match = pat.match(location)
+        if match:
+            return _render_template(template, match)
+    return None
+
+
+def insert_error(
+    root: MarshmallowValidationErrorT, facade_path: FacadePathT | None, message: str
+) -> None:
+    """
+    Insert `message` into a nested dict at `facade_path`.
+
+    Example result shape:
+      {'mtr': {'sa103s': {6: {'net_profit_or_loss': ['...']}}}}
+    """
+    if not facade_path:
+        return
+
+    parts = _split_path(facade_path)
+    node: MarshmallowValidationErrorT = root  # current nesting
+
+    for idx, part in enumerate(parts):
+        match = _FACADE_STEP_REGEX.match(part)
+        if not match:
+            # Fallback: treat the entire token as a plain key
+            key = part
+            is_last = idx == len(parts) - 1
+            if is_last:
+                leaf = node.setdefault(key, [])
+                if isinstance(leaf, list):
+                    leaf.append(message)
+                else:
+                    node[key] = [message]
+            else:
+                node = node.setdefault(key, {})  # type: ignore[assignment]
+            continue
+
+        name = match.group("name")
+        idx_str = match.group("idx")
+        is_last = idx == len(parts) - 1
+
+        if idx_str is None:
+            # plain object step
+            if is_last:
+                leaf = node.setdefault(name, [])
+                if isinstance(leaf, list):
+                    leaf.append(message)
+                else:
+                    node[name] = [message]
+            else:
+                next_node = node.get(name)
+                if not isinstance(next_node, dict):
+                    next_node = {}
+                    node[name] = next_node
+                node = next_node
+        else:
+            # indexed collection step
+            idx = int(idx_str)
+            bucket = node.get(name)
+            if not isinstance(bucket, dict):
+                bucket = {}
+                node[name] = bucket
+            next_node = bucket.get(idx)
+            if is_last:
+                if isinstance(next_node, list):
+                    next_node.append(message)
+                else:
+                    bucket[idx] = [message]
+            else:
+                if not isinstance(next_node, dict):
+                    next_node = {}
+                    bucket[idx] = next_node
+                node = next_node
+
+
+#
+# Const
+#
+
+# Placeholder like {i0-1} or {i3} (we support both; -1 means convert 1-based -> 0-based)
+_PLACEHOLDER_REGEX = re.compile(r"\{i(?P<n>\d+)(?P<delta>-1)?\}")
+
+# Token parser for facade paths like 'mtr/sa103s[6]/foo/bar'
+_FACADE_STEP_REGEX = re.compile(r"^(?P<name>[^/\[\]]+)(?:\[(?P<idx>\d+)\])?$")
+
+# Matches one step of an XPath-like path, with an optional namespace prefix and optional [index]
+# Examples it should match:
+#   MTR:Sa103S[7]
+#   Sa103S[1]
+#   hd:Body[1]
+#   NetBusinessLossForTax[2]
+#   SelfEmployment[*]  (wildcard)
+#   Key[@Type='UTR']   (predicate)
+_STEP_REGEX = re.compile(
+    r"""
+    ^                                    # start of segment
+    (?:(?P<prefix>[A-Za-z][\w.-]*)\:)?   # optional ns prefix (e.g. 'MTR:')
+    (?P<name>[A-Za-z_][\w.-]*)           # local name
+    (?:\[(?P<idx>\d+|\*|@[^\]]+)\])?     # optional [index], [*] wildcard, or [@predicate]
+    $                                    # end of segment
+    """,
+    re.VERBOSE,
+)
+
+# Allow arbitrary leading prefixes like /hd:GovTalkMessage[1]/.../
+# before the destination root. Anchor at start, optionally skip any prefix.
+_PREFIX_SKIP = r"^.*?"
+
+# Optional namespace prefix on each step
+_NS_OPT = r"(?:[A-Za-z][\w.-]*:)?"
+
+#
+# Helpers: path parsing, normalization, etc.
+#
+
+
+def _render_template(
+    template: FacadePathTemplateT, match: re.Match[str]
+) -> FacadePathT:
+    def sub_one(mm: re.Match[str]) -> str:
+        n = int(mm.group("n"))
+        group_name = f"i{n}"
+        raw = match.group(group_name)
+        if raw is None:
+            # If a referenced capture was not present, keep as-is
+            return mm.group(0)
+        val = int(raw)
+        if mm.group("delta"):
+            val -= 1
+        return str(val)
+
+    return _PLACEHOLDER_REGEX.sub(sub_one, template)
+
+
+def _split_path(path: str) -> list[str]:
+    """
+    Split a path like 'MTR:MTR[1]/MTR:Sa103S[7]/MTR:Foo[1]' into segments
+    """
+    p = path.strip("/")
+    return [s for s in p.split("/") if s]
+
+
+def _normalize_name(s: str) -> str:
+    """
+    Normalize a step name for comparison (case-insensitive)
+    """
+    return re.sub(r"[^A-Za-z0-9]+", "", s).lower()
+
+
+def _dest_segments_with_captures(
+    dest: str,
+) -> tuple[str, list[tuple[str, str | None]], dict[str, list[int]]]:
+    """
+    Build a tolerant regex for the destination path and produce a mapping from
+    normalized local-names to the capture indices we assign.
+
+    Returns:
+      pattern_str, segments, name_to_capture_indices
+
+    Where:
+      segments = list of (local_name, idx_str_or_None)
+      name_to_capture_indices maps normalized local-name -> [capture_ordinals]
+    """
+    segments = _split_path(dest)
+    regex_parts: list[str] = []
+    name_to_caps: dict[str, list[int]] = {}
+    cap_counter = 0
+
+    for raw_segment in segments:
+        match = _STEP_REGEX.match(raw_segment)
+        if not match:
+            # Be conservative: treat as literal name without index
+            name, idx_val = raw_segment, None
+        else:
+            name = match.group("name")
+            idx_val = match.group("idx")  # could be digit, '*', or '@...'
+
+        norm = _normalize_name(name)
+        if idx_val == "*":
+            # Wildcard: capture any numeric index
+            cap_name = f"i{cap_counter}"
+            cap_counter += 1
+            name_to_caps.setdefault(norm, []).append(int(cap_name[1:]))
+            regex_parts.append(rf"/{_NS_OPT}{re.escape(name)}\[(?P<{cap_name}>\d+)\]")
+        elif idx_val is not None and idx_val.isdigit():
+            # Explicit numeric index: capture it
+            cap_name = f"i{cap_counter}"
+            cap_counter += 1
+            name_to_caps.setdefault(norm, []).append(int(cap_name[1:]))
+            regex_parts.append(rf"/{_NS_OPT}{re.escape(name)}\[(?P<{cap_name}>\d+)\]")
+        elif idx_val is not None and idx_val.startswith("@"):
+            # XPath predicate like [@Type='UTR']: match it literally (escaped)
+            regex_parts.append(rf"/{_NS_OPT}{re.escape(name)}\[{re.escape(idx_val)}\]")
+        else:
+            # No index or unrecognized: tolerate presence/absence of [n]
+            regex_parts.append(rf"/{_NS_OPT}{re.escape(name)}(?:\[\d+\])?")
+
+    # Anchor, permit any leading prefix, and force end-of-string
+    pattern = _PREFIX_SKIP + "".join(regex_parts) + r"$"
+    # Also return segments parsed into (local_name, idx_str_or_None)
+    parsed_segments: list[tuple[str, str | None]] = []
+    for raw_segment in segments:
+        match = _STEP_REGEX.match(raw_segment)
+        if match:
+            parsed_segments.append((match.group("name"), match.group("idx")))
+        else:
+            parsed_segments.append((raw_segment, None))
+    return pattern, parsed_segments, name_to_caps
+
+
+#
+# Facade template construction
+#
+
+_FACADE_INDEX_REGEX = re.compile(r"(?P<name>[^/\[\]]+)\[(?P<idx>\d+)\]")
+
+
+def _build_facade_template(
+    facade: FacadePathT,
+    name_to_caps: dict[str, list[int]],
+) -> FacadePathTemplateT:
+    """
+    Replace numeric indices in the facade path with placeholders that reference
+    the right destination capture groups by normalized element name.
+
+    Example:
+      facade: 'mtr/sa103s[0]/profits_losses_nics_and_cis/net_business_loss_for_tax'
+      name_to_caps: {'mtr': [0], 'sa103s': [1], 'profitslossesnicsandcis': [2], ...}
+
+      -> 'mtr/sa103s[{i1-1}]/profits_losses_nics_and_cis/net_business_loss_for_tax'
+    """
+    used_per_name: dict[str, int] = {}
+
+    def repl(m: re.Match[str]) -> str:
+        local = m.group("name")
+        norm = _normalize_name(local)
+        indices = name_to_caps.get(norm)
+        if indices:
+            # Use the next available capture index for this element name
+            used = used_per_name.get(norm, 0)
+            # Guard in case of more facade indices than captures of same name
+            idx_ord = indices[used] if used < len(indices) else indices[-1]
+            used_per_name[norm] = min(used + 1, len(indices))
+            return f"{local}" + f"[{{i{idx_ord}-1}}]"
+        # If we cannot bind by name, leave the original numeric index as-is
+        return m.group(0)
+
+    return _FACADE_INDEX_REGEX.sub(repl, facade)

pathbridge-0.1.0/src/pathbridge/types.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping, MutableMapping, Sequence
+from typing import (
+    Protocol,
+    TypeAlias,
+    TypedDict,
+    Union,
+)
+
+#
+# Aliases
+#
+
+LocationT = str  # validator-reported path (e.g., XPath/JSONPath/Pointer)
+ErrorMessageT = str  # error message text
+DestinationPathT = str  # key in raw rules (validator/document path)
+FacadePathT = str  # your app/model path (facades destination)
+FacadePathTemplateT = (
+    str  # your app/model path with capture placeholders, e.g 'mtr/sa103s[{i1-1}]'
+)
+
+#
+# Rules
+#
+
+# Raw rules
+RawRulesMapT = Mapping[DestinationPathT, FacadePathT]
+
+# Compiled rule used at runtime
+CompiledRuleT = tuple[re.Pattern[str], FacadePathTemplateT]
+CompiledRulesT = Sequence[CompiledRuleT]
+
+#
+# Errors
+#
+
+ErrorItemT = tuple[LocationT, ErrorMessageT]
+
+
+# Think of GovTalk-style error items
+class ErrorItemClassT(Protocol):
+    location: Sequence[LocationT]  # list of validator locations
+    text: Sequence[str]  # list of messages
+
+
+class ErrorItemDictT(TypedDict):
+    location: LocationT
+    text: str
+
+
+# Union accepted by adapters
+ErrorInputT = (
+    Iterable[ErrorItemT] | Iterable[ErrorItemClassT] | Iterable[ErrorItemDictT]
+)
+
+#
+# Adapter related types
+#
+
+# A recursive mapping of str/int -> (subtree | list[str] messages)
+# This keeps type-checkers happy when building nested error dicts
+MarshmallowValidationErrorT: TypeAlias = MutableMapping[
+    str | int,
+    Union["MarshmallowValidationErrorT", list[str]],
+]
+
+#
+# Public API
+#
+
+__all__ = [
+    "LocationT",
+    "DestinationPathT",
+    "FacadePathT",
+    "FacadePathTemplateT",
+    "RawRulesMapT",
+    "CompiledRuleT",
+    "CompiledRulesT",
+    "ErrorItemT",
+    "ErrorItemClassT",
+    "ErrorItemDictT",
+    "ErrorInputT",
+    "MarshmallowValidationErrorT",
+]