rust_iso20022 0.1.2

ISO 20022 financial message parser and generated Rust types for SWIFT MX XML/JSON.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

# Command-line interface

The `iso20022` binary is a thin adapter over the `rust_iso20022` core SDK. It
does not maintain its own message catalogue, XML/JSON parser, or validation
rules. Generated message types remain the canonical ISO 20022 data model.

Build the standalone CLI with the capabilities needed by the command. For the
currently verified validation and serialization slice:

```console
cargo build -p rust_iso20022_cli --features json,model-pacs,profiles
```

Every command that reads a document accepts a file path or `-` for standard
input. Input is bounded before processing. The CLI never writes source message
content to logs or error messages.

## Detection and inspection

Detect a message from its namespace and root element:

```console
iso20022 detect payment.xml
iso20022 detect --json - < payment.xml
```

Inspect its generated-code descriptor:

```console
iso20022 inspect --json payment.xml
```

The JSON response is a versioned envelope. Its top-level fields are
`schema_version`, `command`, `status`, and either `data` or `error`.

## Serialization

Convert XML into the generated model's JSON representation, or deserialize
JSON into an explicitly selected generated message type and serialize it as
XML:

```console
iso20022 to-json --json payment.xml
iso20022 to-xml pacs.008.001.08 --json payment.json
```

These operations require the `json` feature and the applicable `model-*`
feature. A missing compile-time capability returns exit 5 instead of silently
using a different representation.

## Validation

Run the implemented ISO 20022 semantic rules (L2):

```console
iso20022 validate --layer l2 payment.xml
iso20022 validate --json --layer l2 - < payment.xml
```

The JSON result contains the detected `message_id`, the executed layer, and a
`ValidationReport` with `valid`, `complete`, `errors`, `warnings`, and
`unavailable_layers`. Invalid documents return the same report with exit 4, so
scripts do not need to parse human-readable output.

L1 offline XSD validation is not implemented yet and returns exit 5. Profile
(L3) validation never selects a release implicitly. `--profile` accepts only a
complete immutable release key:

```text
scheme|scheme_release|guideline_edition|effective_from|effective_until|sha256[,sha256]
```

For example, a syntactically complete but uninstalled release returns exit 5:

```console
iso20022 validate --json \
  --profile 'test-network|2025.1|ig-2025.1|2025-01-01|2025-12-31|aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  payment.xml
```

Short aliases such as `cbpr-plus:2026` are rejected with exit 2 because they do
not identify a reproducible rule release. See [profiles.md](profiles.md) and
[validation.md](validation.md) for the release and report contracts.

## Catalogue and versions

Catalogue queries are direct views of code-generated core metadata:

```console
iso20022 catalog pacs.008.001
iso20022 catalog --json pacs.008.001
iso20022 versions --json pacs.008.001
```

No message list is copied into the CLI. An empty result is represented by an
empty array and exit 0.

## Explain a validation rule

`explain` returns the same immutable descriptor used by core rule execution:

```console
iso20022 explain ISO20022-L2-IBAN-CHECKSUM
iso20022 explain --json ISO20022-L2-IBAN-CHECKSUM
```

The descriptor includes its rule ID, validation layer, title, reason,
source/reference, profile and exact profile version when applicable, affected
message IDs, and logical field paths. The CLI does not copy these fields into a
separate explanation database.

Profile explanations become available only from an installed exact-release
rule set. The generic adapter preserves L3 `profile`, `profile_version`,
`source`, `affected_messages`, and `field_paths`; this release does not claim
that gated CBPR+ or SEPA rule packs are installed. An unknown or unavailable
rule returns exit 5 and the stable JSON code `rule_not_found` without echoing
the requested value.

## Compare message versions

`compare` returns the core schema-metadata diff for two exact versions of the
same message family:

```console
iso20022 compare pacs.008.001.08 pacs.008.001.10
iso20022 compare --json pacs.008.001.08 pacs.008.001.10
```

The response pins both source schema hashes and lists deterministically ordered
field additions/removals, type changes, cardinality changes, and enum value
changes. It does not compare XML text or infer renames. See
[version-comparison.md](version-comparison.md) for the complete contract.

## Stable exit codes

| Code | Meaning |
|---:|---|
| 0 | Command succeeded; validation, when requested, is valid |
| 2 | Invalid command-line usage or unresolved profile selector |
| 3 | Input/read/detection/parse/serialization failure |
| 4 | Validation completed and reported errors |
| 5 | Requested layer, profile release, generated model, feature, or rule is unavailable |
| 10 | Internal adapter failure |

When `--json` is present, operational errors also use the versioned envelope
and a stable `error.code`. Diagnostics are deliberately generic and must not
contain account numbers, names, addresses, transaction references, or the
original financial message.

## Compliance boundary

A successful result means the message passed the rules implemented and selected
by this SDK. It does not guarantee acceptance by a bank or network, regulatory
certification, onboarding approval, or legal compliance.