cbpr-usage-rules 0.1.0__py3-none-any.whl

cbpr_rules/models.py

@@ -0,0 +1,83 @@
+"""Core data models: Severity, Violation, Rule."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:  # avoid import cycle at runtime
+    from .message import ParsedMessage
+
+
+class Severity(str, Enum):
+    """How serious a finding is.
+
+    VIOLATION - a usage rule is broken; the message is not compliant.
+    INFO      - advisory guidance surfaced for awareness, not a hard breach.
+    """
+
+    VIOLATION = "violation"
+    INFO = "info"
+
+
+@dataclass(frozen=True)
+class Violation:
+    """A single rule finding against a message."""
+
+    rule_number: str
+    name: str
+    description: str
+    xpath: str = ""
+    line: Optional[int] = None
+    severity: Severity = Severity.VIOLATION
+    # Why it was flagged (rule-specific) and the offending XML at that location.
+    detail: str = ""
+    found: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "rule_number": self.rule_number,
+            "name": self.name,
+            "description": self.description,
+            "detail": self.detail,
+            "found": self.found,
+            "xpath": self.xpath,
+            "line": self.line,
+            "severity": self.severity.value,
+        }
+
+
+# A rule check receives the parsed message and a ``report`` callback and emits
+# findings by calling ``report(element, detail=None)``.
+CheckFn = Callable[["ParsedMessage", Callable], None]
+
+
+@dataclass
+class Rule:
+    """A single usage rule for one (year, message type)."""
+
+    rule_number: str
+    name: str
+    description: str
+    severity: Severity = Severity.VIOLATION
+    # When None the rule is advisory/catalog-only: it cannot be mechanically
+    # checked, so it is surfaced as guidance rather than evaluated.
+    check: Optional[Callable[["ParsedMessage"], List[Violation]]] = None
+
+    @property
+    def enforced(self) -> bool:
+        return self.check is not None
+
+    def run(self, msg: "ParsedMessage") -> List[Violation]:
+        if self.check is None:
+            return []
+        return self.check(msg)
+
+    def to_dict(self) -> dict:
+        return {
+            "rule_number": self.rule_number,
+            "name": self.name,
+            "description": self.description,
+            "severity": self.severity.value,
+            "enforced": self.enforced,
+        }

cbpr_rules/reference/__init__.py

@@ -0,0 +1,9 @@
+"""Vendored ISO reference data (country and currency code lists).
+
+Shipped as package data so validation never requires a network call. Sourced
+from ISO 3166-1 alpha-2 and ISO 4217.
+"""
+from .countries import ISO3166_ALPHA2
+from .currencies import ISO4217
+
+__all__ = ["ISO3166_ALPHA2", "ISO4217"]

cbpr_rules/reference/countries.py

@@ -0,0 +1,28 @@
+"""ISO 3166-1 alpha-2 country codes (officially assigned)."""
+from __future__ import annotations
+
+ISO3166_ALPHA2 = frozenset(
+    {
+        "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT",
+        "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI",
+        "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY",
+        "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN",
+        "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM",
+        "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK",
+        "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL",
+        "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM",
+        "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR",
+        "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN",
+        "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS",
+        "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK",
+        "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW",
+        "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP",
+        "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM",
+        "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW",
+        "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM",
+        "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF",
+        "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW",
+        "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI",
+        "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW",
+    }
+)

cbpr_rules/reference/currencies.py

@@ -0,0 +1,25 @@
+"""ISO 4217 active currency codes."""
+from __future__ import annotations
+
+ISO4217 = frozenset(
+    {
+        "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN",
+        "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV",
+        "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHE", "CHF",
+        "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUC", "CUP", "CVE",
+        "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD",
+        "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD",
+        "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD",
+        "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD",
+        "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA",
+        "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MXV",
+        "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB",
+        "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB",
+        "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS",
+        "SRD", "SSP", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND",
+        "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "UYI",
+        "UYU", "UYW", "UZS", "VED", "VES", "VND", "VUV", "WST", "XAF", "XAG",
+        "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XOF", "XPD", "XPF",
+        "XPT", "XSU", "XTS", "XUA", "XXX", "YER", "ZAR", "ZMW", "ZWG", "ZWL",
+    }
+)

cbpr_rules/registry.py

@@ -0,0 +1,107 @@
+"""Rule registry and the ``@rule`` / ``advisory`` authoring helpers.
+
+Rule modules live under ``cbpr_rules.rules.y<year>.<msgtype>`` and register their
+rules at import time via the decorators below. ``load_rules`` imports the right
+module on demand and returns the rules for a (year, message type).
+"""
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import Callable, Dict, List, Tuple
+
+from .models import Rule, Severity, Violation
+
+# (year, message_type) -> list[Rule]
+_REGISTRY: Dict[Tuple[int, str], List[Rule]] = {}
+_LOADED: set = set()
+# module name -> import error message, for modules that failed to load
+IMPORT_ERRORS: Dict[str, str] = {}
+
+
+def _key(year: int, msgtype: str) -> Tuple[int, str]:
+    return (int(year), msgtype)
+
+
+def register(year: int, msgtype: str, rule: Rule) -> None:
+    _REGISTRY.setdefault(_key(year, msgtype), []).append(rule)
+
+
+def rule(
+    msgtype: str,
+    year: int,
+    number: str,
+    name: str,
+    description: str,
+    severity: Severity = Severity.VIOLATION,
+) -> Callable:
+    """Decorate a ``fn(msg, report)`` checker and register it.
+
+    The wrapped function receives the ParsedMessage and a ``report`` callback.
+    Call ``report(element, detail=None)`` for each finding; the element supplies
+    the xpath and line number, and the rule supplies number/name/description.
+    """
+    rule_id = f"{msgtype}:{number}"
+
+    def decorator(fn: Callable) -> Callable:
+        def check(msg) -> List[Violation]:
+            findings: List[Violation] = []
+
+            def report(element=None, detail=None, severity_override=None):
+                findings.append(
+                    Violation(
+                        rule_number=rule_id,
+                        name=name,
+                        description=description,
+                        detail=detail or "",
+                        found=msg.snippet_of(element) if element is not None else "",
+                        xpath=msg.xpath_of(element) if element is not None else "",
+                        line=msg.line_of(element) if element is not None else None,
+                        severity=severity_override or severity,
+                    )
+                )
+
+            fn(msg, report)
+            return findings
+
+        register(year, msgtype, Rule(rule_id, name, description, severity, check))
+        return fn
+
+    return decorator
+
+
+def advisory(msgtype: str, year: int, number: str, name: str, description: str) -> None:
+    """Register an advisory (non-mechanizable) rule, surfaced as guidance only."""
+    rule_id = f"{msgtype}:{number}"
+    register(year, msgtype, Rule(rule_id, name, description, Severity.INFO, check=None))
+
+
+def _discover(year: int) -> None:
+    """Import every rule module for a year so its rules register."""
+    if year in _LOADED:
+        return
+    pkg_name = f"{__package__}.rules.y{year}"
+    try:
+        pkg = importlib.import_module(pkg_name)
+    except ModuleNotFoundError:
+        _LOADED.add(year)
+        return
+    for mod in pkgutil.iter_modules(pkg.__path__):
+        if mod.name.startswith("_"):
+            continue
+        full = f"{pkg_name}.{mod.name}"
+        try:
+            importlib.import_module(full)
+        except Exception as exc:  # a broken rule module must not break the rest
+            IMPORT_ERRORS[full] = f"{type(exc).__name__}: {exc}"
+    _LOADED.add(year)
+
+
+def load_rules(year: int, msgtype: str) -> List[Rule]:
+    _discover(int(year))
+    return list(_REGISTRY.get(_key(year, msgtype), []))
+
+
+def available_message_types(year: int) -> List[str]:
+    _discover(int(year))
+    return sorted({mt for (yr, mt) in _REGISTRY if yr == int(year)})

cbpr_rules/rules/__init__.py

@@ -0,0 +1 @@
+"""Hand-authored usage rules, organised as ``y<year>.<message_type>`` modules."""

cbpr_rules/rules/y2025/__init__.py

@@ -0,0 +1 @@
+"""CBPR+ SR2025 usage rules."""

cbpr_rules/rules/y2025/camt_052.py

@@ -0,0 +1,224 @@
+"""CBPR+ SR2025 usage rules for camt.052.001.08 (BankToCustomerAccountReport).
+
+Rule numbers, names and descriptions are taken from the published usage
+guideline's Rules sheet; XML paths are the short ISO 20022 tags from its
+Full_View / XML Path column. Formal rules are implemented with shared
+combinators from ``helpers`` (or bespoke ``fn(msg, report)`` where the shape is
+cross-schema); mechanizable textual rules are enforced; the remaining textual
+rules are surfaced as advisory guidance. Algorithmic field validations
+(VAL-*) are added for the data types that occur in this message.
+"""
+from __future__ import annotations
+
+from ...registry import advisory, rule
+from ...validators import is_valid_bic, is_valid_country, is_valid_currency, is_valid_lei
+from ...helpers import (
+    amount_equals_sum,
+    business_msg_id_carries_group_id,
+    each_value_valid,
+    header_msg_def_id_matches,
+    not_matching_pattern,
+    requires_if_present,
+    same_value,
+)
+
+MT = "camt.052"
+YEAR = 2025
+ROOT = "/Document/BkToCstmrAcctRpt"
+RPT = ROOT + "/Rpt"
+
+
+def reg(number: str, name: str, description: str, check) -> None:
+    """Register a combinator-built check as a rule."""
+    rule(MT, YEAR, number, name, description)(check)
+
+
+# ---------------------------------------------------------------------------
+# Formal rules
+# ---------------------------------------------------------------------------
+
+reg("R1", "CBPR_Copy_Duplicate_FormalRule",
+    "If Copy Duplicate indicator is used in the Business Application Header, it "
+    "must be identical to the Copy Duplicate indicator in the business document "
+    "(if the latter is present).",
+    same_value("/AppHdr/CpyDplct", RPT + "/CpyDplctInd"))
+
+reg("R12", "CBPR_Party_Name_Postal_Address_FormalRule",
+    "If Postal Address is present then Name is mandatory.",
+    requires_if_present(RPT + "/Acct/Ownr", "PstlAdr", "Nm"))
+
+reg("R17", "CBPR_Original_Instruction_Identification_FormalRule",
+    "This field must not start or end with a slash '/' and must not contain two "
+    "consecutive slashes '//'.",
+    not_matching_pattern(RPT + "/Ntry/NtryDtls/TxDtls/Refs/InstrId",
+                         r"(/.*)|(.*/)|(.*//.*)"))
+
+
+# ---------------------------------------------------------------------------
+# Mechanizable textual rule (enforced)
+# ---------------------------------------------------------------------------
+
+reg("R6", "CBPR_Business_Service_Usage_TextualRule",
+    'The value "swift.cbprplus.03" must be used.',
+    lambda msg, report: [
+        report(node, detail=f"BizSvc must be 'swift.cbprplus.03', found '{val}'")
+        for node in msg.find("/AppHdr/BizSvc")
+        for val in [msg.text_of(node)]
+        if val and val != "swift.cbprplus.03"
+    ])
+
+# Header consistency between the Business Application Header and the Document.
+reg("R3", "CBPR_Business_Message_Identifier_TextualRule",
+    "The Business Message Identifier is the unique identifier of the Business Message "
+    "instance that is being transported with this header, as defined by the sending "
+    "application or system.",
+    business_msg_id_carries_group_id())
+
+reg("R4", "CBPR_Message_Definition_Identifier_TextualRule",
+    "The Message Definition Identifier of the Business Message instance must be formatted "
+    "exactly as it appears in the namespace of the Business Message instance.",
+    header_msg_def_id_matches())
+
+# Interest: total must equal the sum of the per-record amounts (Entry level).
+_INTRST_TTL = RPT + "/Ntry/Intrst/TtlIntrstAndTaxAmt"
+_INTRST_RCRD = RPT + "/Ntry/Intrst/Rcrd/Amt"
+
+reg("R16", "CBPR_Interest_TextualRule",
+    "Total Charges And Tax Amount must equal the sum of the individual record amounts.",
+    amount_equals_sum(_INTRST_TTL, _INTRST_RCRD))
+
+reg("R20", "CBPR_Interest_TextualRule",
+    "Total Charges And Tax Amount must equal the sum of the individual record amounts.",
+    amount_equals_sum(_INTRST_TTL, _INTRST_RCRD))
+
+
+# ---------------------------------------------------------------------------
+# Algorithmic field validation (VAL-*), only for data types present here.
+# ---------------------------------------------------------------------------
+
+# Every FinInstnId/BICFI anywhere in the report (Account Servicer + related agents)
+_BIC_PATHS = (
+    RPT + "/Acct/Svcr/FinInstnId/BICFI",
+    RPT + "/Ntry/Chrgs/Rcrd/Agt/FinInstnId/BICFI",
+    RPT + "/Ntry/NtryDtls/TxDtls/Chrgs/Rcrd/Agt/FinInstnId/BICFI",
+)
+
+
+def _val_bic(msg, report):
+    for p in _BIC_PATHS:
+        for node in msg.find(p):
+            val = msg.text_of(node)
+            if val and not is_valid_bic(val):
+                report(node, detail=f"invalid BIC: '{val}'")
+
+
+reg("VAL-BIC", "CBPR_Valid_Agent_BIC",
+    "Every FinInstitution BICFI must be a structurally valid ISO 9362 BIC.",
+    _val_bic)
+
+
+reg("VAL-LEI", "CBPR_Valid_LEI",
+    "Account Owner / Account Servicer LEI must be a structurally valid ISO 17442 LEI.",
+    each_value_valid(RPT + "/Acct/Svcr/FinInstnId/LEI", is_valid_lei, "LEI"))
+
+
+def _val_ctry(msg, report):
+    for node in msg.find(RPT + "/Acct/Svcr/FinInstnId/PstlAdr/Ctry"):
+        val = msg.text_of(node)
+        if val and not is_valid_country(val):
+            report(node, detail=f"invalid country '{val}'")
+    for node in msg.find(RPT + "/Acct/Ownr/PstlAdr/Ctry"):
+        val = msg.text_of(node)
+        if val and not is_valid_country(val):
+            report(node, detail=f"invalid country '{val}'")
+
+
+reg("VAL-CTRY", "CBPR_Valid_Country",
+    "Every PostalAddress Country must be a valid ISO 3166 alpha-2 code.",
+    _val_ctry)
+
+
+def _val_ccy(msg, report):
+    for p in (RPT + "/Bal/Amt", RPT + "/Ntry/Amt"):
+        for el, ccy in msg.attr_nodes(p, "Ccy"):
+            if ccy and not is_valid_currency(ccy):
+                report(el, detail=f"invalid currency '{ccy}'")
+
+
+reg("VAL-CCY", "CBPR_Valid_Amount_Currency",
+    "Balance and Entry amount currency must be a valid ISO 4217 code.",
+    _val_ccy)
+
+
+# ---------------------------------------------------------------------------
+# Advisory textual rules (not mechanically enforceable - surfaced as guidance)
+# ---------------------------------------------------------------------------
+_ADVISORY = {
+    "R2": ("CBPR_Character_Set_Usage_TextualRule",
+           "For further description on the usage of the field, pls refer to the CBPR Plus UHB."),
+    "R5": ("CBPR_Business_Service_TextualRule",
+           "This field may be used by SWIFT to support differentiated processing on "
+           "SWIFT-administered services such as FINplus."),
+    "R7": ("CBPR_Market_Practice_TextualRule",
+           "This field may be used by SWIFT on SWIFT-administered services. A user-specific value "
+           "may be used, but please contact your Service Administrator."),
+    "R8": ("CBPR_Related_Business_Application_Header_TextualRule",
+           "If used, the Related BAH must transport the exact same information as in the BAH of "
+           "the related message."),
+    "R9": ("CBPR_Related_BAH_Business_Service_TextualRule",
+           "If related BAH is present, it should transport the element Business Service."),
+    "R10": ("CBPR_Electronic_Sequence_Number_TextualRule",
+            "For intra-day report: sequential number of the report, assigned by the account "
+            "servicer, increased incrementally by 1 for each report sent electronically."),
+    "R11": ("CBPR_Copy_Duplicate_Indicator_TextualRule",
+            "If applicable, for Copy or Duplicate, the electronic sequence and legal sequence "
+            "must be the same as the original report."),
+    "R13": ("CBPR_Intraday_Balance_Recommendation_TextualRule",
+            "Every camt.052 message which includes Entry items should include Intraday Booked "
+            "(ITBD) and Intraday Available (ITAV) balances."),
+    "R14": ("CBPR_Domain_Proprietary_Recommendation_TextualRule",
+            "BankTransactionCode/Domain/Code is the preferred option and should be used when "
+            "possible."),
+    "R15": ("CBPR_Charges_TextualRule",
+            "Total Charges And Tax Amount must equal the sum of the individual record amounts."),
+    "R18": ("CBPR_UETR_TextualRule",
+            "If the underlying transaction contains/owns a UETR then it should be reported in the "
+            "camt.052 message."),
+    "R19": ("CBPR_Charges_TextualRule",
+            "Total Charges And Tax Amount must equal the sum of the individual record amounts."),
+    "R21": ("CBPR_Initiating_Party_TextualRule",
+            "Party initiating the payment to an agent. In the payment context this can be the "
+            "debtor, the creditor, or a party that initiates the payment on their behalf."),
+    "R22": ("CBPR_Debtor_TextualRule",
+            "For outward payments, report if different from account owner. For inward payments, "
+            "report where available. When ReversalIndicator is TRUE, the Creditor and Debtor must "
+            "be the same as the Creditor and Debtor of the original entry."),
+    "R23": ("CBPR_Debtor_Account_TextualRule",
+            "For inward payment, report where available. Conditional on the country regulatory "
+            "requirement. If IBAN is available populate the IBAN tag, else populate Other."),
+    "R24": ("CBPR_Ultimate_Debtor_TextualRule",
+            "When ReversalIndicator is TRUE, the Ultimate Creditor and Ultimate Debtor must be the "
+            "same as the Ultimate Creditor and Ultimate Debtor of the original entry."),
+    "R25": ("CBPR_Creditor_TextualRule",
+            "For outward payment, report where available. When ReversalIndicator is TRUE, the "
+            "Creditor and Debtor must be the same as the Creditor and Debtor of the original entry."),
+    "R26": ("CBPR_Creditor_Account_TextualRule",
+            "For outward payment, report where available. If IBAN is available populate the IBAN "
+            "tag, else populate Other."),
+    "R27": ("CBPR_Ultimate_Creditor_TextualRule",
+            "Ultimate party to which an amount of money is due. When ReversalIndicator is TRUE, "
+            "the Ultimate Creditor and Ultimate Debtor must be the same as in the original entry."),
+    "R28": ("CBPR_Debtor_Agent_TextualRule",
+            "One of the following must be provided - BIC or Clearing System Member or Name. When "
+            "ReversalIndicator is TRUE, the Creditor Agent and Debtor Agent must be the same as "
+            "the Creditor Agent and Debtor Agent of the original entry."),
+    "R29": ("CBPR_Creditor_Agent_TextualRule",
+            "When ReversalIndicator is TRUE, the Creditor Agent and Debtor Agent must be the same "
+            "as the Creditor Agent and Debtor Agent of the original entry."),
+    "R30": ("CBPR_Remittance_Rules_TextualRule",
+            "Use of Structured Remittance must be bilaterally or multilaterally agreed. Structured "
+            "Remittance can be repeated, however the total business data for all occurrences "
+            "(excluding tags) must not exceed 9,000 characters."),
+}
+for _num, (_name, _desc) in _ADVISORY.items():
+    advisory(MT, YEAR, _num, _name, _desc)