BeneficialStrategies.Iso20022.Primitives
1.1.1
dotnet add package BeneficialStrategies.Iso20022.Primitives --version 1.1.1
NuGet\Install-Package BeneficialStrategies.Iso20022.Primitives -Version 1.1.1
<PackageReference Include="BeneficialStrategies.Iso20022.Primitives" Version="1.1.1" />
<PackageVersion Include="BeneficialStrategies.Iso20022.Primitives" Version="1.1.1" />
<PackageReference Include="BeneficialStrategies.Iso20022.Primitives" />
paket add BeneficialStrategies.Iso20022.Primitives --version 1.1.1
#r "nuget: BeneficialStrategies.Iso20022.Primitives, 1.1.1"
#:package BeneficialStrategies.Iso20022.Primitives@1.1.1
#addin nuget:?package=BeneficialStrategies.Iso20022.Primitives&version=1.1.1
#tool nuget:?package=BeneficialStrategies.Iso20022.Primitives&version=1.1.1

BeneficialStrategies.Iso20022.Primitives
The ISO 20022 primitive data types, code sets and external codes, with their format validation and JSON converters, without the message records.
Why these are types, and not strings
The best way to deal with dirty data is to stop it at the front door.
We could have made every field in ISO 20022 a string and moved on, as most libraries do. We chose the opposite, on purpose: a type designed to fit the standard exactly for every primitive in it. An amount is not text that probably holds a number; it is an ActiveCurrencyAndAmount, with a currency and a decimal, within the digits ISO allows. A country is a CountryCode, two upper-case letters. A name is a Max35Text. If a field is supposed to fit a pattern, then the pattern is burned into the type, and you cannot construct a value that does not fit.
Three things follow, and they are the reason this is the backbone of everything else:
- Bad data has nowhere to go. The value is checked once, at the edge, when it is built or read, and it is refused there with a message that names the type, the value and the rule. Everything behind that door, your business rules, your database, the next system, is holding data that is already right. You do not find a
"$140Yen"where a number should be, or a date that is not a date, two weeks after it was persisted, in the back end, where the only thing left to do is guess what was meant. - It travels the way the standard says, and only that way. These types do not know any other wire format. They are written and read as ISO 20022 defines them, in XML and in JSON, so what you send and what you store is compatible with the published standard and with every other system that follows it, by construction.
- In memory it is a first-class value. Once it is across the door, the amount is a
decimal, the date aDateOnly, the code an enumeration you canswitchon, the identifier a token that compares by value. You do your business logic on real numbers, dates and enumerations, not on text you have to convert again, and again, before you can use it. A method that takes(ActiveCurrencyAndAmount, ChargeBearerType1Code)cannot be called with the arguments swapped, which a method that takes two strings can.
They are assignable from strings and from the natural .NET types (a string to a Max35Text, a DateOnly to an ISODate), so using them costs you nothing at the call site. What they will not do is hold a value the standard does not allow, or travel any way but the standard's. That is what makes them structs of their own, not an alias for something looser: the type is the specification, in the compiler and at run time, so your infrastructure can rely on the data being compatible with the international standard and ready for the rules of your business.
Install
dotnet add package BeneficialStrategies.Iso20022.Primitives --prerelease
The package is in alpha, so the command asks for a prerelease version. Three examples follow, each a step further, and each using nothing but this package.
How to use
Values that refuse what ISO does not allow
A primitive type is an immutable struct that can only hold a value of its ISO format, so an invalid value cannot exist: it is refused when you build it.
using BeneficialStrategies.Iso20022;
using BeneficialStrategies.Iso20022.Amounts;
using BeneficialStrategies.Iso20022.Codesets;
using BeneficialStrategies.Iso20022.SimpleTypes;
Max35Text name = "Acme Corp"; // converts implicitly from a string; 1 to 35 characters
Console.WriteLine(name); // Acme Corp
try { _ = new Max35Text(new string('x', 36)); }
catch (Iso20022FormatException ex) { Console.WriteLine($"{ex.TargetType.Name}: {ex.Violation} - {ex.Message}"); }
// Max35Text: TooLong - 'Max35Text' allows at most 35 character(s) but received 36: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'.
Console.WriteLine(Max35Text.TryCreate("", out _)); // False: no exception, when you would rather ask
- Simple types (
Max35Text, dates, identifiers, numbers): structs that refuse a value outside the ISO format by throwingIso20022FormatException, which says which type, which value and which constraint (ex.Violation,ex.Constraint).TryCreateis the form that does not throw. - Code sets are enums (
ChargeBearerType1Code.SharedisSHARon the wire), and external codes are structs (ActiveCurrencyCode,CountryCode) that check the format of a code whose accepted values live outside the standard:
try { _ = new ActiveCurrencyCode("eur"); }
catch (Iso20022FormatException ex) { Console.WriteLine(ex.Message); }
// 'eur' is not a valid ActiveCurrencyCode. ISO 20022 pattern constraint: ^[A-Z]{3}\z
- Amounts are the currency-and-amount data types. Each refuses a value outside the limits of its ISO type: not negative, and at most so many digits in all and after the decimal point (18 and 5 for
ActiveCurrencyAndAmount; trailing zeros do not count):
try { _ = new ActiveCurrencyAndAmount { Currency = "EUR", Amount = -1m }; }
catch (Iso20022FormatException ex) { Console.WriteLine(ex.Message); }
// '-1' is not a valid ActiveCurrencyAndAmount. ISO 20022 pattern constraint: not negative
Try the project yourself.
Your own class, read from and written to XML
The same types make the members of a class of your own, and the reader fills it from XML, telling you every problem it finds. A message is an IOuterRecord that carries four constants: its ISO identifier, the XML element that holds it and the namespace and root element of its document.
public class MyCustomMessage : IOuterRecord
{
public const string IsoIdentifier = "xmpl.001.001.01";
public const string XmlTag = "Party";
public const string DocumentNamespace = "urn:example:xmpl.001.001.01";
public const string DocumentElementName = "Document";
[IsoXmlTag("Name")]
public required Max35Text Name { get; init; } // at most 35 characters
[IsoXmlTag("ChargeBearer")]
public required ChargeBearerType1Code ChargeBearer { get; init; } // DEBT, CRED, SHAR or SLEV
}
[IsoXmlTag] says which element a member is read from, and required makes a missing element an error. Read some XML:
var xml = "<Document xmlns=\"urn:example:xmpl.001.001.01\"><Party><Name>Acme Corp</Name><ChargeBearer>SHAR</ChargeBearer></Party></Document>";
DeserializationResult<MyCustomMessage> read = Iso20022XmlSerializer.TryRead<MyCustomMessage>(xml);
if (read.Succeeded)
Console.WriteLine($"read: {read.Message!.Name} pays {read.Message.ChargeBearer}"); // read: Acme Corp pays Shared
else
foreach (var issue in read.Issues)
Console.WriteLine($"{issue.Code} {issue.Path}: {issue.Reason}");
Nothing is thrown: the result is the message or the list of problems, each with the path of the element, its kind (MalformedXml, WrongRoot, RequiredMissing, BadValue, FacetViolation, UnexpectedElement, ...) and, for malformed XML, the line and position. With a name of 61 characters and a charge bearer that is not a code, the problems are:
FacetViolation Document/Party/Name: 'Max35Text' allows at most 35 character(s) but received 61: 'A name that is a good deal longer than thirty-f...'.
BadValue Document/Party/ChargeBearer: 'FREE' is not a value of ChargeBearerType1Code. Expected one of: DEBT, CRED, SHAR, SLEV.
Iso20022XmlSerializer also has TryRead for a XDocument and Read for an XElement (any part of a document, with a ReadContext when it is a fragment), Deserialize and TryDeserialize if you prefer exceptions or a bool, and writes a message back:
var mine = new MyCustomMessage { Name = "Acme Corp", ChargeBearer = ChargeBearerType1Code.Shared };
Console.WriteLine(Iso20022XmlSerializer.SerializeToString(mine));
<Document xmlns="urn:example:xmpl.001.001.01">
<Party>
<Name>Acme Corp</Name>
<ChargeBearer>SHAR</ChargeBearer>
</Party>
</Document>
To turn those problems into FluentValidation failures instead, see BeneficialStrategies.Iso20022.Validation.Xml.
Try the project yourself.
The same class as JSON
The same class has a JSON form, with the ISO naming (snake_case property names, the wire codes of the code sets):
var mine = new MyJsonMessage { Name = "Acme Corp", ChargeBearer = ChargeBearerType1Code.Shared };
var json = Iso20022JsonSerializer.SerializeToString(mine);
Console.WriteLine(json); // {"name":"Acme Corp","charge_bearer":"SHAR"}
var ok = Iso20022JsonSerializer.TryDeserialize<MyJsonMessage>(json, out var back, out var error);
Console.WriteLine($"read back: {ok}, {back!.Name}"); // read back: True, Acme Corp
Iso20022JsonSerializer.TryDeserialize<MyJsonMessage>("{\"name\":\"Acme Corp\",\"charge_bearer\":\"FREE\"}", out _, out error);
Console.WriteLine(error!.Message); // Unknown ChargeBearerType1Code value: 'FREE'
TryDeserialize never throws for bad input: a value that breaks its type is a JsonException, with the JSON path in its Path. For a class that is not a message, Iso20022PrimitiveJsonOptions.Default carries the converters of the primitive types, for use with System.Text.Json directly.
Try the project yourself.
More
- Documentation, release notes and issues: https://github.com/Beneficial-Strategies/iso-20022-primitives
- License: MIT. Status: alpha.
What else is in this package
It has no message definitions and depends on no other package; every other package of the family is built on it. Besides the types and the readers, it holds the small contracts the rest of the family agrees on:
- The kinds of ISO type and how to tell them apart:
IIsoComponent,IIsoChoice,IIsoChoiceVariant,IOuterRecordand the attributes ([IsoId],[IsoXmlTag],[IsoMessage],[IsoAmount]);Iso.KindOf(Type)answers for any type of the model. IIsoDataFactory, the abstraction that makes an object for an interface, which is how a reader fills an interface instead of a class (the Messages package has the interfaces, and Factory makes the objects).- The collection types (
ValueList<T>,SimpleValueList<T>), and theIso20022MessageTypeRegistry, which finds a message type from a namespace or an ISO identifier.
Where to go from here
| You want | Package |
|---|---|
| the shape of every ISO 20022 message, component and choice, so a class of yours can stand in for one | BeneficialStrategies.Iso20022.Messages |
| a ready-made class for every message | BeneficialStrategies.Iso20022 (depends on this package; same namespaces) |
| the rules the types cannot express, as FluentValidation validators | BeneficialStrategies.Iso20022.Messages.Validation |
Frameworks
net8.0, net10.0 and netstandard2.0, so the primitives can be used from .NET Framework 4.6.1 and later, Mono 5.4 and later, Xamarin and Unity (the records package is net8.0 and net10.0 only). The netstandard2.0 build depends on System.Text.Json, Portable.System.DateTimeOnly (the DateOnly and TimeOnly types that ISODate and ISOTime use) and Microsoft.Bcl.HashCode.
| Product | Versions 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. |
-
.NETStandard 2.0
- Microsoft.Bcl.HashCode (>= 1.1.1)
- Portable.System.DateTimeOnly (>= 8.0.2)
- System.Text.Json (>= 8.0.6)
-
net10.0
- No dependencies.
-
net8.0
- No dependencies.
NuGet packages (7)
Showing the top 5 NuGet packages that depend on BeneficialStrategies.Iso20022.Primitives:
| Package | Downloads |
|---|---|
|
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. |
|
|
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.Factory
Objects for the ISO 20022 interfaces, made at run time: ask for an interface and the Factory builds a class that implements it, fills it from XML or JSON, and gives it value equality. |
|
|
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.Validation.Xml
Validate ISO 20022 XML straight from text, a document or an element: every problem in the XML is reported with its path, then the FluentValidation rules run on what was read. Needs only the Primitives package, not the message definitions. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.1.1 | 411 | 10/25/2026 |
| 1.1.0-alpha | 151 | 10/25/2026 |
| 1.0.1-alpha | 390 | 10/23/2026 |
| 1.0.0-alpha | 428 | 10/23/2026 |
Added: Three more ISO 20022 types: Max65Text, Percentage14Rate and ISOMonth (#51).
Known issue: NPIIdentifier checks the shape of the identifier but not its two check digits (ISO 24366); the algorithm is not yet confirmed (#26).
Known issue: The check character of the DTI types follows a rule reconstructed from public implementations; the DTI Foundation has not yet confirmed it or the list of exceptions (#27).
Known issue: WertpapierIdentifier accepts digits only, while German securities codes (WKN) can contain letters (#28).
Known issue: BelgianIdentifier and DutchIdentifier accept any text; the national formats are not checked (#29).
Known issue: The IBAN types check the check digits but not the length and structure of each country (#30).
Known issue: The CFI types check the category letter but not the attribute letters (#31).
Known issue: ISOCountrySubDivisionCode refuses numeric ISO 3166-2 codes such as FR-75, because the ISO 20022 pattern allows letters only (#33).
Known issue: ISODate refuses the optional timezone that xs:date allows (#40).