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

cbpr_usage_rules-0.1.0.dist-info/METADATA

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: cbpr-usage-rules
+Version: 0.1.0
+Summary: Validate ISO 20022 CBPR+ XML messages against SWIFT usage (business) rules.
+Author: Pete Houghton
+License: MIT License
+        
+        Copyright (c) 2021 Peter Houghton
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/phoughton/iso20022-cbpr-ur
+Project-URL: Repository, https://github.com/phoughton/iso20022-cbpr-ur
+Project-URL: Issues, https://github.com/phoughton/iso20022-cbpr-ur/issues
+Keywords: iso20022,cbpr,swift,payments,validation,pacs,pain,camt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+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.9
+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: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml>=4.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: openpyxl>=3.1; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# cbpr-usage-rules
+
+Validate **ISO 20022 CBPR+** XML messages (the SWIFT cross-border payments
+profile) against the **Usage / Business Rules** that apply on top of the XSD
+schemas. These are the rules that the schema alone cannot express: cross-field
+constraints, cross-schema checks between the Business Application Header (BAH)
+and the message Document, conditional presence, code-list restrictions, and
+field-format algorithms (IBAN, LEI, BIC, country, currency).
+
+Rules are versioned per year (currently **2025** and **2026**) and organised by
+message type (pacs.008, pacs.009 and its COV/ADV variants, pacs.002, pacs.004,
+pain.001, camt.052, camt.054, and the STP variants).
+
+> **This package is AI generated.** The rule logic was derived, with review,
+> from the published CBPR+ usage-guideline spreadsheets. Treat it as an aid, not
+> as a substitute for the official SWIFT specifications. Verify against the
+> source material before relying on results in production.
+
+---
+
+## Installation
+
+```bash
+pip install cbpr-usage-rules
+```
+
+Requires Python 3.9+ and depends only on `lxml`.
+
+---
+
+## Quick start
+
+### As a library
+
+```python
+import cbpr_rules
+
+result = cbpr_rules.validate_file("payment.xml", year=2025)
+
+if result["valid"]:
+    print("Compliant")
+else:
+    for v in result["violations"]:
+        print(f"{v['rule_number']}  line {v['line']}  {v['xpath']}")
+        print(f"    {v['description']}")
+```
+
+`validate_string` is the same but takes XML text:
+
+```python
+result = cbpr_rules.validate_string(xml_text, year=2026)
+```
+
+### From the command line
+
+```bash
+# Human-readable (default). Exit code is non-zero if there are violations.
+cbpr-validate payment.xml --year 2025
+
+# JSON output
+cbpr-validate payment.xml --year 2025 --json
+
+# Read from stdin
+cat payment.xml | cbpr-validate --year 2026
+
+# Also list the advisory (non-enforced) rules in full
+cbpr-validate payment.xml --year 2025 --advisory
+
+# Additionally schema-validate against an XSD (repeatable, results shown separately)
+cbpr-validate payment.xml --year 2025 --xsd pacs.008.001.08.xsd
+```
+
+Each reported violation shows the rule, **why** this instance failed (`Problem:`),
+the **offending XML** from your file (`Found:`), and its line + xpath (`At:`).
+Advisory rules are summarised as a count by default; pass `--advisory` to list them.
+
+---
+
+## The result object
+
+Both `validate_file` and `validate_string` return a dictionary:
+
+```python
+{
+  "valid": False,                     # True only if there are no VIOLATION-severity findings
+  "message_type": "pacs.008",         # the rule set that was applied
+  "detected_message_type": "pacs.008",# auto-detected from the Document namespace
+  "year": 2025,
+  "rules_evaluated": 84,
+  "violations": [
+    {
+      "rule_number": "pacs.008:R41",   # unique within the message type
+      "name": "CBPR_Interbank_Settlement_Currency_FormalRule",
+      "description": "The codes XAU, XAG, XPD and XPT are not allowed ...",
+      "detail": "commodity currency 'XAU' not allowed",  # why this instance was flagged
+      "found": "<IntrBkSttlmAmt Ccy=\"XAU\">1000.00</IntrBkSttlmAmt>",  # the offending XML
+      "xpath": "/RequestPayload/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/IntrBkSttlmAmt",
+      "line": 39,                      # 1-based line in the source XML
+      "severity": "violation"
+    }
+  ],
+  "advisory": [                        # textual guidance that cannot be mechanically enforced
+    {"rule_number": "pacs.008:R4", "name": "...", "description": "..."}
+  ]
+}
+```
+
+Every violation carries the four required pieces of information: the **xpath**,
+the **line number**, a **description**, and a **unique rule number**.
+
+---
+
+## Mid-level usage
+
+### Choosing the year
+
+Pass `year=2025` or `year=2026`. Rule loading is per-year and lazy — only the
+requested year's modules are imported. You can validate against more than one
+year in the same process simply by calling with different `year` values.
+
+### Message type detection and variants
+
+The message type is auto-detected from the `<Document>` namespace, so you
+normally don't pass it. Business variants that share a base namespace — **STP**
+(pacs.008/pacs.009), **COV** and **ADV** (pacs.009) — cannot be told apart from
+the XML alone, so select them explicitly when you want their stricter rule sets:
+
+```python
+cbpr_rules.validate_file("cover.xml", year=2025, msgtype="pacs.009_cov")
+```
+
+```bash
+cbpr-validate cover.xml --year 2025 --type pacs.009_cov
+```
+
+### Wrapper tags
+
+Messages arrive inside different envelopes (`<RequestPayload>`, `<DataPDU>`,
+SWIFT SAA wrappers, and so on). The validator locates the `AppHdr` and
+`Document` elements wherever they sit in the tree and ignores the surrounding
+wrapper, so the same input validates identically regardless of envelope. Element
+matching is by local name, so namespace prefixes never matter.
+
+### Severity
+
+- `violation` — a usage rule is broken; this makes `valid` false.
+- `info` — advisory guidance surfaced for awareness; it never fails validation
+  and appears in the separate `advisory` list (textual rules that cannot be
+  mechanically checked).
+
+---
+
+## In-depth usage
+
+### Discovering the rule set
+
+```python
+cbpr_rules.available(2025)              # -> ['camt.052', 'pacs.008', ...]
+cbpr_rules.list_rules(2025, "pacs.008") # -> [{rule_number, name, description, severity, enforced}, ...]
+```
+
+```bash
+cbpr-validate --year 2025 --list-types
+cbpr-validate --year 2025 --type pacs.008 --list
+```
+
+### Algorithmic field validation
+
+Beyond the published rules, the following formats are validated with their
+standard algorithms wherever the corresponding fields appear:
+
+| Field    | Standard            | Check                                   |
+|----------|---------------------|-----------------------------------------|
+| IBAN     | ISO 13616           | structure + mod-97 check digits         |
+| LEI      | ISO 17442           | structure + ISO 7064 mod-97-10 check    |
+| BIC      | ISO 9362            | 8/11-char structure + valid country     |
+| Country  | ISO 3166-1 alpha-2  | membership                              |
+| Currency | ISO 4217            | membership                              |
+
+The reference code lists are vendored, so validation never makes a network call.
+
+Some of these check-digit algorithms and reference code lists were derived from
+Wikipedia (e.g. [IBAN](https://en.wikipedia.org/wiki/International_Bank_Account_Number),
+[LEI](https://en.wikipedia.org/wiki/Legal_Entity_Identifier), and the
+[ISO 3166 country codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)).
+Verify against the authoritative ISO/registry sources before relying on them in
+production.
+
+### Optional XSD schema validation
+
+You can additionally validate a message against one or more **XSD schemas** as a
+*separate* second result set. XSD files are **not** bundled with the package —
+supply your own path(s):
+
+```python
+result = cbpr_rules.validate_file("payment.xml", year=2025, xsd="pacs.008.001.08.xsd")
+# or several:  xsd=["head.001.001.02.xsd", "pacs.008.001.08.xsd"]
+```
+
+```bash
+cbpr-validate payment.xml --year 2025 --xsd pacs.008.001.08.xsd
+```
+
+Each XSD is auto-matched by its `targetNamespace`: a message schema validates the
+`Document`, a head.001 schema validates the `AppHdr`. When (and only when) an XSD
+is supplied, the result gains a separate top-level `xsd` block, and the CLI prints
+a distinct **XSD SCHEMA VALIDATION** section:
+
+```python
+"xsd": {
+  "checked": True,
+  "schema_valid": False,                 # all supplied schemas passed?
+  "schemas": [
+    {
+      "file": "pacs.008.001.08.xsd",
+      "target_namespace": "urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08",
+      "validated_element": "Document",   # or "AppHdr" / "root"
+      "valid": False,
+      "errors": [{"message": "...", "line": 82, "xpath": "/Document/.../CdtrAgt"}]
+    }
+  ]
+}
+```
+
+Usage-rule results and schema results stay separate: the top-level `valid` reflects
+only the usage rules, while schema validity is `xsd.schema_valid`. The **CLI exit
+code is non-zero if either** the usage rules or the schema fail. With no `--xsd`,
+nothing about XSD appears in the output.
+
+### Handling errors
+
+`validate_file` / `validate_string` raise `cbpr_rules.engine.ValidationError`
+for unparseable XML or when the message type cannot be determined and was not
+supplied. The CLI turns these into a message on stderr and exit code 2.
+
+### CLI exit codes
+
+| Code | Meaning                          |
+|------|----------------------------------|
+| 0    | Valid (no violations)            |
+| 1    | Invalid (one or more violations) |
+| 2    | Usage error / could not validate |
+
+---
+
+## How the rules are organised
+
+Each `(year, message type)` has a hand-authored Python module under
+`cbpr_rules/rules/y<year>/`. Rules are built from a small library of reusable
+combinators (presence, conditional presence, mutual exclusion, value matching,
+length, code lists, address grace-period rules) plus bespoke functions for
+cross-field and cross-schema logic. The XSD files in the source material are
+informational only and are not reimplemented here.
+
+### Enforced vs advisory
+
+Every published rule is registered. A rule is **enforced** (can produce a
+violation) when it can be checked deterministically from the message alone —
+this includes the formal pseudo-code rules and the mechanizable textual rules,
+such as:
+
+- header ↔ message consistency (`MsgDefIdr` matches the Document definition;
+  `BizMsgIdr` carries the GroupHeader `MsgId`);
+- no structured Postal Address value duplicated in an `AddressLine`;
+- `AnyBIC` present ⇒ `Name`/`PostalAddress` not allowed;
+- Structured Remittance ≤ 9,000 characters;
+- charge rules where instructed and settlement amounts share a currency and
+  differ, and amount-total-equals-sum checks.
+
+A rule stays **advisory** (`severity: info`, surfaced as guidance, never failing
+validation) when it cannot be verified from the message in isolation — for
+example anything that refers to a *related or underlying message* not present
+(`Original_*`, related-BAH, COV/ADV UETR/E2E), depends on the SWIFT network or a
+jurisdiction, or expresses a recommendation / bilaterally-agreed practice.
+Checks are deliberately **conservative**: each skips when its inputs are absent
+or ambiguous, so a compliant message is never failed spuriously.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

cbpr_usage_rules-0.1.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+cbpr_rules/__init__.py,sha256=k42ZYh_EMU18nxOPRFJNCmnY71F7iGj7gGxxl_2tTxc,493
+cbpr_rules/cli.py,sha256=okRp2YWvp0HH6O1-5FgHvqwC4c7paJNnjIMejdoPw-s,6510
+cbpr_rules/engine.py,sha256=a_9eVKVg_hUmbyGl9oORv2Bzo1HnjpODRAgLUzAPOf0,3411
+cbpr_rules/helpers.py,sha256=myLyRQU4aHbo777y3waW9vL5APWw52VrrkECwpx4QL0,14958
+cbpr_rules/loader.py,sha256=CVEjcWDdlDS5LAHRVQqRqIpCjl3XsO8ons8_T2oWFN4,2468
+cbpr_rules/message.py,sha256=4Xxn5mp33SrlqAYYG-K9I7Fb3QfMhpW1sJepltcuqjY,6488
+cbpr_rules/models.py,sha256=AMPhncnlHHn1ehBKxnfaGSfzAxD0jmkaC_AhAPKu8Aw,2372
+cbpr_rules/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cbpr_rules/registry.py,sha256=fafVr3gsSiCucp8AqSe2LjC3zaNfvmaK3pH9Vlh_eoA,3660
+cbpr_rules/schema.py,sha256=aCEP7ECSUvVEcVhacl-N78S23SxFdpWGBKCbC0MDjNc,3455
+cbpr_rules/reference/__init__.py,sha256=pqWAN-iWWv-5oNM1mtaWcRvn9hnBIGxkSYm8C6bh7ck,297
+cbpr_rules/reference/countries.py,sha256=U519poQS49Js_ZJBT_e9xC2DyrSPZ74s1Lv0T-h3_O8,1802
+cbpr_rules/reference/currencies.py,sha256=nO6BueDRwc9J1H4dvsZJkFArPzjcO8dfStRgz-7BVh8,1513
+cbpr_rules/rules/__init__.py,sha256=oDId4pgbOQbNRtfEvTY0tZpCPBoXpADWktpwMDNkT1g,82
+cbpr_rules/rules/y2025/__init__.py,sha256=-S2vcoTEWb3HPdtrDUQ7z8W2jt2oCbVgLoQdWlErUQg,32
+cbpr_rules/rules/y2025/camt_052.py,sha256=Tpu0voEq0b_LG_nHWEkYU2NkVL3pRmRff_ZDPd3eVkk,11050
+cbpr_rules/rules/y2025/camt_054.py,sha256=MQv7_7yuCKmLBgTxnMJgwlWGca7-xbz4yzI_yz36Gg0,9312
+cbpr_rules/rules/y2025/pacs_002.py,sha256=IEfbijL5tHagkujR9rj5CzgLaeOxK8Et1Y1R1aCxX-s,10585
+cbpr_rules/rules/y2025/pacs_004.py,sha256=E1fRPKL56N2ybbu1cP3ZUSB6lxyAzSqs4MgyD-Q2w14,59465
+cbpr_rules/rules/y2025/pacs_008.py,sha256=zvfigewkZ2EMlB_CspthcTiF9f18qqGWKW2T_Q-rhsM,18189
+cbpr_rules/rules/y2025/pacs_008_stp.py,sha256=zellRcGmTB_3RiLkagGAppWlt4kzczTbEXJJSLJ5uZk,18457
+cbpr_rules/rules/y2025/pacs_009.py,sha256=lHNX9xqLAP1B-nTEs-C9KH3jMuSib7nYM3zx67jxR80,13387
+cbpr_rules/rules/y2025/pacs_009_adv.py,sha256=swH2pKEdFaDqiC7hcoPFnIucFXeK5Yojj1ca-n0zumg,12114
+cbpr_rules/rules/y2025/pacs_009_cov.py,sha256=9wNtaIz2K6yz32m8QSr1zpbvr6wQpxIj4eT3C1uX_4U,18643
+cbpr_rules/rules/y2025/pain_001.py,sha256=kY0i1vl31pDyjLnS7xftnaejBejNUowVF2wXVfSxNyY,15756
+cbpr_rules/rules/y2026/__init__.py,sha256=l13kGUN2HeD7P4RELOPEzDpLjzdvWESKAXkAUhPSwHw,32
+cbpr_rules/rules/y2026/camt_052.py,sha256=0wp_7eIhFJYJJKGGCKB_hiCqnL4R9A4NWHT5933S9FM,8707
+cbpr_rules/rules/y2026/camt_054.py,sha256=RL0Sq1xYA6OpTF3kkLw11IK5KrVurIobZgNCTd-VYvg,8658
+cbpr_rules/rules/y2026/pacs_002.py,sha256=kabK9vfSYLH6-Mod7Txj3vcqoMzP5IFPTyjPaFNWZu8,9814
+cbpr_rules/rules/y2026/pacs_004.py,sha256=vbwKSEKjTs61UWh25G-w6NFU62BDDBbKvgMGHaw6VDc,25246
+cbpr_rules/rules/y2026/pacs_008.py,sha256=VWnfD1LzsrzIeEfIjmm8b6Sruw0at4iucmj9CNrYy5Q,20963
+cbpr_rules/rules/y2026/pacs_008_stp.py,sha256=CWkmCOgmzU4Avz7qt5is1n5JG3kooK4u_X8YAJZ964k,18514
+cbpr_rules/rules/y2026/pacs_009.py,sha256=1ZeyP9K7Ei2U2mDJ_evutxMhLpeD-QQ9XeqMlsWBd34,11646
+cbpr_rules/rules/y2026/pacs_009_adv.py,sha256=wGMI0oYPxeWQi-CVNTx8ubW9Xuihlkd0zyxRTEYPt5s,11420
+cbpr_rules/rules/y2026/pacs_009_cov.py,sha256=kOu9OGvKj6j1vZYEDIbt63eURrkR4doF7cPmm1G2dwA,16338
+cbpr_rules/rules/y2026/pain_001.py,sha256=-nJDZQJ0N2WZhupfSIqAWBU-IRjbDyDezPhaAp944bE,11919
+cbpr_rules/validators/__init__.py,sha256=8B-QAb7-TaRjYE2C_qxHFcmXKh416mfHBExolo0LWqs,403
+cbpr_rules/validators/bic.py,sha256=RHsZ7rjyT1POFWShCUyzp2UVMBX81Hs67nSlKBSD9QA,656
+cbpr_rules/validators/country.py,sha256=UkGmsKPZjcIIApvMvA_DmyzqNnPVh5BDOuoEyyzLaac,346
+cbpr_rules/validators/currency.py,sha256=i6H4aBtFTz-zqDj6MRkEOgfs6yLlT32s3aBIPlnr-f8,316
+cbpr_rules/validators/iban.py,sha256=ksA4Sr12hPVPqoBWYnYjHr-5YX77NyID8E9p-5lrR7I,900
+cbpr_rules/validators/lei.py,sha256=MBekU14fjMbNO1JRvhjW3og--KBAogfnyulVur7LfJs,545
+cbpr_usage_rules-0.1.0.dist-info/licenses/LICENSE,sha256=VAAd5Xxo-KD8zhuGVJNETiX0fZgHPpwMVjeKIGKcPnA,1071
+cbpr_usage_rules-0.1.0.dist-info/METADATA,sha256=hZ_KIKCSi-bKONbtMcDUNASmo-WkQ5HMMxm93bUP__U,13071
+cbpr_usage_rules-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cbpr_usage_rules-0.1.0.dist-info/entry_points.txt,sha256=BJ7UqvDeLtS8rqpPh7-WLnpxrmpJiSQF-fVYLJdG7m4,54
+cbpr_usage_rules-0.1.0.dist-info/top_level.txt,sha256=tz4sIzzVmkkJjZICUpzjK5XRcz45Y1_IFRH60Jx7YnY,11
+cbpr_usage_rules-0.1.0.dist-info/RECORD,,

cbpr_usage_rules-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cbpr_usage_rules-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cbpr-validate = cbpr_rules.cli:main

cbpr_usage_rules-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Peter Houghton
+
+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.

cbpr_usage_rules-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cbpr_rules