rust_iso20022

A Rust library for ISO 20022 (MX / SWIFT) financial messages, generated from the official iso20022.org XSD schemas. It provides a strongly-typed model for MX messages with XML and JSON parsing/serialization, message identification, a generic message tree for reading any message without the model, and business metadata extraction.

Installation

Add it with cargo (enable only the features you need — see Features):

cargo add rust_iso20022                                  # core: identify, MxNode, catalogue
cargo add rust_iso20022 --features model-pacs            # + the typed pacs model
cargo add rust_iso20022 --features model-pacs,serde,convert

or in Cargo.toml:

[dependencies]
# Core only (identification, generic tree, catalogue) — no model compiled.
rust_iso20022 = "0.1"

# Or pull in one or more typed message families plus JSON and typed scalars:
rust_iso20022 = { version = "0.1", features = ["model-pacs", "serde", "convert"] }

Enabling the umbrella model feature compiles all ~1130 message modules and is slow; prefer the per-area model-<area> features for the families you actually use.

Minimal first program — no features required:

use rust_iso20022::{detect, MxNode};

fn main() {
    let xml = r#"<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
      <FIToFICstmrCdtTrf><GrpHdr><MsgId>ABC-1</MsgId></GrpHdr></FIToFICstmrCdtTrf>
    </Document>"#;

    let id = detect(xml).expect("recognised");
    println!("type = {}", id.message_name());            // pacs.008.001.08

    let doc = MxNode::parse(xml).unwrap();
    println!("MsgId = {:?}", doc.find("MsgId").and_then(|n| n.text())); // Some("ABC-1")
}

What's in the crate

Layer	Module	Always available?
Core	(root)	yes — MxId, BusinessArea, from_xml/to_xml, detect, MxNode, Error
Catalogue	catalogue	yes — every message id + namespace as static phf tables
Model	generated	per area — generated::<area>::<msg>::Document, enable with model-<area>

Coverage: a typed model is generated for 1130 message versions across 32 business areas (acmt, admi, auth, caaa, caad, caam, cafc, cafm, cafr, cain, camt, canm, casp, casr, catm, catp, colr, fxtr, head, pacs, pain, reda, remt, secl, seev, semt, sese, setr, tsin, tsmt, tsrv, trck). This is the current iso20022.org catalogue (latest versions) plus the earlier versions, so older in-circulation messages still parse.

The generated types derive yaserde for XML and (with the serde feature) serde::{Serialize, Deserialize} for JSON.

Capabilities

Capability	API
Typed model, all message versions	generated::<area>::<msg>::Document
XML parse / serialize	from_xml / to_xml
JSON parse / serialize (ISO element names)	from_json / to_json (feature serde)
Per-message identity (namespace, MxId, area, functionality, variant, version)	the MxMessage trait on every Document
Auto-detect & parse	detect, parse_as::<T>(), generated::any::parse_auto → AnyMessage
Business Application Header — read & build	app_hdr::parse_business_header / BusinessHeader::to_app_hdr_xml
Business metadata extraction	metadata::extract
Business message (header + typed document)	Envelope<D> / parse_envelope, read_business_message
Generic tree — read any message without the model	MxNode::parse
Typed scalars (amount → Decimal, dates → chrono)	convert::{to_decimal, to_date, to_datetime} (feature convert)
Message catalogue	catalogue
WebAssembly / JS bindings	src/wasm.rs (build via scripts/build-wasm.sh; see docs/wasm-api.md)

Quick start

Identify a message and read its metadata — no model feature needed:

use rust_iso20022::{detect, BusinessArea, MxNode};

let xml = r#"<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
  <FIToFICstmrCdtTrf><GrpHdr><MsgId>ABC-1</MsgId></GrpHdr>
    <CdtTrfTxInf><IntrBkSttlmAmt Ccy="EUR">1234.56</IntrBkSttlmAmt></CdtTrfTxInf>
  </FIToFICstmrCdtTrf></Document>"#;

let id = detect(xml).unwrap();
assert_eq!(id.message_name(), "pacs.008.001.08");
assert_eq!(id.business_area, BusinessArea::pacs);

// Read fields from the generic tree without the typed model:
let doc = MxNode::parse(xml).unwrap();
assert_eq!(doc.find("MsgId").and_then(|n| n.text()), Some("ABC-1"));
let amt = doc.find("IntrBkSttlmAmt").unwrap();
assert_eq!((amt.text(), amt.attr("Ccy")), (Some("1234.56"), Some("EUR")));

Typed parse / serialize (enable the area's model, e.g. cargo add rust_iso20022 -F model-pacs):

use rust_iso20022::generated::pacs::pacs_008_001_08::Document;

let doc: Document = rust_iso20022::from_xml(&xml)?;
let back: String = rust_iso20022::to_xml(&doc)?;

See the runnable examples:

cargo run --example inspect_message                                   # no features
cargo run --example typed_payment --features model-pacs,serde,convert # typed

Features

Feature	Default	Effect
model-<area>	no	the typed model for one business area, e.g. model-pacs. Enable only what you need — a single area compiles in seconds vs many minutes for all
model	no	all model-<area> at once (~1130 modules; slow to compile)
serde	no	serde + JSON (to_json/from_json) for the core, catalogue and message types
convert	no	typed scalar conversions (to_decimal/to_date/to_datetime) via rust_decimal/chrono
cli	no	the iso20022 command-line catalogue lookup tool
catalogue	no	runtime XSD fetcher (fetch module): pulls in tokio, reqwest, regex

The core (MxId, BusinessArea, MxNode, detect) and the catalogue are always available. The XSD → Rust generator is a separate, unpublished workspace crate (tools/codegen), so the published crate has no git dependencies.

Command-line tool

cargo run --features cli --bin iso20022 -- pacs.008   # all pacs.008 versions
# or after `cargo install rust_iso20022 --features cli`:
iso20022 camt          # every message in the camt business area
iso20022               # the whole catalogue

Regenerating the model

The model and catalogue are produced from the XSD schemas in xsds/ by the codegen tool:

cargo run -p rust_iso20022_codegen -- --input xsds --output src/generated

To (re)download schemas, the catalogue feature provides a Fetcher. The authoritative source is iso20022.org; its static schema path (/sites/default/files/documents/messages/<area>/schemas/<name>.xsd) is the reliable programmatic download path (Fetcher::download_schema).

Design notes

• Scalars are String — lossless (exact text, no float rounding, ideal for money) and keeps XML and JSON in sync. Convert on demand with the convert feature.
• Choices are modelled as a struct of Option<…> fields (the same shape JAXB uses), so an amount inside a <xsd:choice> round-trips with its Ccy attribute and unset choices are simply omitted.
• JSON uses the ISO 20022 element names (MsgId, IBAN, …); to_json / from_json round-trip.
• A value that is not a known member of a coded enumeration parses to an __Unknown__(String) fallback (surfaces only for invalid input).
• XML round-tripping preserves the data model, not byte-for-byte formatting.

License

Apache-2.0.