The C# ISO 20022 library, rebuilt around interfaces

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 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.