We have released the C# part of our ISO 20022 library, and we rebuilt it to do it. The single large package that held everything is now a family of small, focused NuGet packages, and the design under all of them is different: they are interface-centric, not implementation-centric.
This post explains what that means, how the packages fit together, and what you can use now.
Two kinds of building block
Think of an ISO 20022 message as a structure built from two things.
The primitives are the atoms. An IBAN, a BIC, a currency and amount, a date, a country code, a
code from one of ISO’s code sets: the smallest pieces of every message. In
BeneficialStrategies.Iso20022.Primitives
each of these is a type designed to fit the standard exactly, and not a string that probably holds
the right thing. A value is checked once, when it is built or read, and refused there with a
message that names the type, the value and the rule. Bad data has nowhere to go. These types are
written and read the way ISO 20022 defines them, in XML and in JSON, and in no other way.
The messages are the shapes. BeneficialStrategies.Iso20022.Messages
holds an interface for every ISO 20022 message, component and choice, with ISO’s own descriptions
word for word. A shape says what a message is made of, and says nothing about how you store it.
Interface-centric, not implementation-centric
Most libraries ship classes and ask you to build around them. We ship the contract, and put the tools on the contract:
- The validators are written for interfaces (
IValidator<IGroupHeader131>), so they judge anything that implements the interface: a class of your own, our records, or an object made at run time. - The readers read XML or JSON into an interface.
- The Factory builds, at run time, a small class that implements any interface you ask for, fills it from XML or JSON, and gives it value equality. You never write the implementation.
- The records are the ready-made C# classes for every message: 3,339 messages and every component and choice they are made of, as immutable records. A source generator writes them while the package is compiled, from the interfaces. They are one implementation of the shapes, a convenient one, and nothing above them depends on them.
The practical result is freedom. Use our records, or your own domain classes, or neither, and the same validators and readers still work.
How the packages fit together
graph TD P["Primitives"] M["Messages"] F["Factory"] R["Messages.Records"] S["Messages.Samples"] V["Messages.Validation"] X["Validation.Xml"] PL["Validation.Xml.Payloads"] M --> P F --> P X --> P R --> M S --> M S --> F V --> M PL --> X
An arrow means “depends on”. Every package also references Primitives directly, which is why it sits at the bottom. Notice what is not on the diagram: nothing depends on the records. That is the interface-centric design at work.
What is in each package
| Package | What it does | Status |
|---|---|---|
Primitives |
ISO 20022 primitive types, code sets and external codes, with format validation and JSON and XML conversion | released |
Messages |
An interface for every message, component and choice | released |
Factory |
Builds an object for any of the interfaces at run time | released |
Messages.Records |
Immutable records for every message, written by a source generator | released |
Messages.Samples |
Named valid objects for tests | released |
Validation.Xml |
Read ISO 20022 XML into an object and validate it in one call | released |
Validation.Xml.Payloads |
Validate raw XML or JSON payloads as they arrive from a queue or an HTTP body | released |
Messages.Validation |
The cross-field rules and registry checks the type system cannot express | alpha: 44 message definitions in three business areas so far |
Even where a message has no validator yet, the primitives still refuse a wrong IBAN, a malformed date or a text that is too long, as soon as the object is made. What is missing is the cross-field rules.
Works with older .NET too
Seven of the eight packages (everything except the records) target .NET Standard 2.0 as well as the current .NET versions, so they work in modern .NET and also in applications that are still on the .NET Framework. The records package targets .NET 8 and .NET 10, because a source generator is part of how it is built. If you have a legacy application, you can adopt the primitives, the interfaces and the validation without moving the application first.
Try it
dotnet add package BeneficialStrategies.Iso20022.Messages.Records
That gives you the records, the interfaces and the primitives. From there, each package’s page on
NuGet has a short example, and the source for every package is public on
GitHub, including runnable examples. If you want the
alpha validators, add --prerelease to the install command of
BeneficialStrategies.Iso20022.Messages.Validation.
The records package replaces the single package this family grew out of,
BeneficialStrategies.Iso20022, which is now deprecated.
Tell us what you think
This is the first release of a new design, and the shape of it is where we most want your opinion. If something is awkward, missing, or wrong, let us know.