BeneficialStrategies.Iso20022.Messages 1.0.1

dotnet add package BeneficialStrategies.Iso20022.Messages --version 1.0.1
                    
NuGet\Install-Package BeneficialStrategies.Iso20022.Messages -Version 1.0.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BeneficialStrategies.Iso20022.Messages" Version="1.0.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="BeneficialStrategies.Iso20022.Messages" Version="1.0.1" />
                    
Directory.Packages.props
<PackageReference Include="BeneficialStrategies.Iso20022.Messages" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add BeneficialStrategies.Iso20022.Messages --version 1.0.1
                    
#r "nuget: BeneficialStrategies.Iso20022.Messages, 1.0.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package BeneficialStrategies.Iso20022.Messages@1.0.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=BeneficialStrategies.Iso20022.Messages&version=1.0.1
                    
Install as a Cake Addin
#tool nuget:?package=BeneficialStrategies.Iso20022.Messages&version=1.0.1
                    
Install as a Cake Tool

Beneficial Strategies

BeneficialStrategies.Iso20022.Messages

An interface for every ISO 20022 message, component and choice, with the verbatim ISO descriptions: the contract that readers, validators and implementations are written against.

Why this package is the nucleus

This is the contract of the family. Almost every other tool is built on the interfaces of the ISO 20022 message shapes, not on any one implementation of them:

  • the validators (Messages.Validation) are written for IValidator<IGroupHeader131>, so they judge anything that implements the interface;
  • the readers (the XML and JSON serializers, Validation.Xml and Validation.Xml.Payloads) read a document into an interface, with objects the Factory makes for it;
  • the Factory writes the classes that implement them, and the Samples build their objects against them;
  • the saga toolkit consumes and publishes messages typed by these interfaces;
  • the ready-made records of BeneficialStrategies.Iso20022 are just one implementation, a convenient one, and nothing above depends on them.

Because the interface is the contract and the implementation is interchangeable, a legacy system can start to take part in an ISO 20022 architecture without being replaced. The Invoice, Payment or Customer class you have had for years can implement one of these interfaces (map its members onto the interface's), and from then on the validators accept it, a consumer typed to the interface takes it, and the rest of the tooling treats it as what it now is. You adopt as much of the standard as you want, one component at a time, and keep your domain objects. Nothing in the rest of the family needs to know yours is not one of ours.

Everything else in this family implements this package or builds on it; it is the nucleus of the implementation of the standard.

How to use

Your own class

An interface is plain C#. Implement one in a class of your own (an entity, a DTO, a type of another message framework), and everything written against the interface works with it:

public sealed class MyIdentification : IGenericIdentification3
{
    public Max35Text Identification => "MINE-1";
    public Max35Text? Issuer => null;
}
static string Describe(IGenericIdentification3 id) => $"{id.Identification} / {id.Issuer?.ToString() ?? "no issuer"}";

Console.WriteLine(Describe(new MyIdentification()));      // MINE-1 / no issuer

Max35Text is a primitive type that holds at most 35 characters, so you cannot build a value that is too long ("MINE-1" converts to it implicitly). A member that is required is not nullable (Identification), one that is optional is (Issuer), and one that may repeat is an IEnumerable<T>.

Try the project yourself.

A choice, and its variants

ISO 20022 has choices: an account is identified either by an IBAN or by some other identification. A choice is an interface (IAccountIdentification4Choice), and each variant is an interface of its own, in a namespace named for the choice, that also derives from it. Test for a variant with a type pattern:

public sealed class MyIban : IIBAN
{
    public IBAN2007Identifier Value => "DE89370400440532013000";
}
static string DescribeAccount(IAccountIdentification4Choice account) => account switch
{
    IIBAN iban => $"IBAN {iban.Value}",
    IOther other => $"account {other.Identification}",
    _ => "an account of another kind",
};

Console.WriteLine(DescribeAccount(new MyIban()));      // IBAN DE89370400440532013000

A choice can hold only one variant, and the type says so: an object is an IIBAN or an IOther, and you ask which.

Try the project yourself.

A message, and what a reader needs to know about it

A message interface (IFIToFICustomerCreditTransferV14, ISO's pacs.008.001.14) is shaped like a component, and also says how the message is read and written: its identifier, the XML element that holds it and the namespace of its document. A reader or writer needs nothing else, so it works with any class that implements the interface:

var message = IsoMessageAttribute.Find(typeof(IFIToFICustomerCreditTransferV14))!;
Console.WriteLine($"{message.IsoIdentifier}  <{message.XmlTag}>  {message.DocumentNamespace}");
// pacs.008.001.14  <FIToFICstmrCdtTrf>  urn:iso:std:iso:20022:tech:xsd:pacs.008.001.14

Console.WriteLine(Iso.KindOf(typeof(IFIToFICustomerCreditTransferV14)));   // Message
Console.WriteLine(Iso.KindOf(typeof(IGenericIdentification3)));            // Component
Console.WriteLine(Iso.KindOf(typeof(IAccountIdentification4Choice)));      // Choice
Console.WriteLine(Iso.KindOf(typeof(IIBAN)));                              // ChoiceVariant

Iso.KindOf(Type) tells the kind of any type of the model, and an interface carries a marker of its kind (IIsoComponent, IIsoChoice, IIsoChoiceVariant, and IOuterRecord for a message).

Try the project yourself.

More

Where the objects come from

The interfaces are only the shape. Something has to implement them, and the packages of the family differ in what:

You want Package
a class of your own this package the examples above
a ready-made class for every message, component and choice BeneficialStrategies.Iso20022 the records implement these interfaces, with XML and JSON serialization
classes made for you, on the fly, as you ask for an interface BeneficialStrategies.Iso20022.Factory no implementation library needed
the rules the types cannot express, checked on anything that implements the interface BeneficialStrategies.Iso20022.Messages.Validation written for these interfaces
valid and invalid objects to use in tests BeneficialStrategies.Iso20022.Samples built through the Factory

How the interfaces are shaped

  • Namespaces are those of the records: IGroupHeader93 is in BeneficialStrategies.Iso20022.Components, a message such as IFIToFICustomerCreditTransferV14 in its business area (BeneficialStrategies.Iso20022.pacs), a choice in BeneficialStrategies.Iso20022.Choices.
  • An interface is flat: it lists every member of its own version and inherits nothing but the marker of its kind.
  • Nullability is the required of the records: a required member is not nullable, an optional one is, and a member that may repeat is an IEnumerable<T>.
  • A choice is an interface and each variant derives from it: Choices.PartyIdentification8Choice.IBICOrBEI derives from IPartyIdentification8Choice.
  • Primitive types (Max35Text, code sets, amounts) are those of BeneficialStrategies.Iso20022.Primitives.

Targets netstandard2.0 (.NET Framework 4.6.1+, Mono, Unity), net8.0 and net10.0.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on BeneficialStrategies.Iso20022.Messages:

Package Downloads
BeneficialStrategies.Iso20022.Messages.Records

The records of every ISO 20022 message, component and choice, written at compile time from the interfaces of iso-20022-messages by a Roslyn source generator: immutable, compared by value, read and written as XML and JSON.

BeneficialStrategies.Iso20022.Messages.Samples

Named, valid ISO 20022 objects for tests, and a generated minimal valid object for any interface of the model, built through the Factory against the interfaces, so a test needs no message records.

BeneficialStrategies.Iso20022.Messages.Validation

FluentValidation validators for the interfaces of the ISO 20022 messages, components and choices: the rules the type system alone cannot express, such as cross-field rules and the check of a code against a registry. Written for the interfaces, so they validate whatever implements them: the records, objects of the Factory, or a class of your own.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.1 242 10/25/2026
1.0.1-alpha 372 10/23/2026
1.0.0-alpha 128 10/23/2026

Added: First stable release: the interfaces of 1.0.1-alpha, depending on the stable Primitives 1.1.1 or later (#14).
Changed: The README links to the packages by the names they have now (#5).