didx.iso20022.sdk 1.0.5

💼 ISO 20022 SDK

A modern C# SDK that provides strongly-typed ISO 20022 message models, full schema validation, and rich conversion utilities.

✅ Built on .NET 9

📦 Install

🔗 Package on NuGet

🌐 Package source

nuget.org (https://api.nuget.org/v3/index.json)

📥 Install package

Install-Package didx.iso20022.sdk

🔗 Source

All message definitions are sourced directly from the official ISO 20022 registry:
🔗 https://www.iso20022.org/iso-20022-message-definitions

✅ Features

• 🧩 Strongly-typed C# models for ISO 20022 messages
• 📄 Auto-validated against official XSD schemas
• 🧪 FluentValidation-based semantic rule checking
• 🔁 Convert to/from XML and JSON using extensions
• 🛠️ Tooling to download, parse, and generate message models
• 🧠 Intuitive structure – each message lives in its own namespace

🧱 Structure

📂 Didx.Iso20022.Sdk

The core SDK containing:

• Generated message classes in Contracts/*
• Embedded schema resources (Schema.xsd)
• Validators (Validator.cs)
• Conversion extensions
• Schema validation logic

Each ISO 20022 message is structured in a dedicated namespace:

Contracts/{Area}/{Message}/Model.cs  
Contracts/{Area}/{Message}/Schema.xsd  
Validation/{Area}/{Message}/Validator.cs

Each message has a root object named Document.

🔧 Didx.Iso20022.Sdk.Tools

Handles code generation:

• Downloads ZIPs per area/message from ISO 20022
• Extracts schemas
• Generates Model.cs, Schema.xsd, and Validator.cs files
• Preserves existing files (no overwrites)

Run generation:

dotnet run --project ./Didx.Iso20022.Sdk.Tools -- --generate

⚙️ Configuration – appsettings.json

This configuration determines which ISO 20022 schemas are downloaded and which message contracts and validators are generated.

You can configure multiple message areas (e.g. Pain, Acmt, Head) under MessageDefinitions.Areas. Each area includes:

• NamespaceSuffix: Used as the namespace and folder name under Contracts/
• XsdDownloadUrl: URL pointing to the official ISO 20022 ZIP file for the business area
• RootElementNameInSchema (optional): Overrides the expected root element in the XSD. Defaults to Document. Use AppHdr for head messages.
• Messages (optional): List of specific messages to process. Each item includes:
  • Id: The full ISO 20022 message ID
  • GenerateValidator: Whether a FluentValidation class should be generated (true by default)

If Messages is omitted, all .xsd files in the ZIP will be processed, and validators will be generated for all.

✅ Example: Specific Messages with Validator Control

{
  "MessageDefinitions": {
    "Areas": [
      {
        "NamespaceSuffix": "Pain",
        "XsdDownloadUrl": "https://www.iso20022.org/business-area/81/download",
        "Messages": [
          { "Id": "pain.001.001.12", "GenerateValidator": true },
          { "Id": "pain.002.001.14", "GenerateValidator": false }
        ]
      },
      {
        "NamespaceSuffix": "Head",
        "XsdDownloadUrl": "https://www.iso20022.org/business-area/136/download",
        "RootElementNameInSchema": "AppHdr",
        "Messages": [
          { "Id": "head.001.001.02", "GenerateValidator": true },
          { "Id": "head.001.001.04", "GenerateValidator": false }
        ]
      }
    ]
  }
}

• GenerateValidator: true → A Validator.cs class will be generated for the message
• GenerateValidator: false → Only the Model.cs and embedded schema will be included

✅ Example: Process All Messages in Area (No Messages Specified)

{
  "MessageDefinitions": {
    "Areas": [
      {
        "NamespaceSuffix": "Pain",
        "XsdDownloadUrl": "https://www.iso20022.org/business-area/81/download"
      },
      {
        "NamespaceSuffix": "Acmt",
        "XsdDownloadUrl": "https://www.iso20022.org/business-area/26/download"
      }
    ]
  }
}

📦 Output per Message

For every processed message, the following files are generated under the Contracts/{NamespaceSuffix}/ folder:

• Model.cs – Strongly-typed C# class for the message
• Schema.xsd – Embedded ISO 20022 schema
• Validator.cs – FluentValidation stub (optional, based on GenerateValidator)

🧪 Didx.Iso20022.Sdk.Tests

Unit tests ensure:

• Schema validation works for known-good samples
• Fluent validators pass
• XML/JSON round-trips serialize/deserialize correctly

Example:

using Didx.Iso20022.Sdk.Extensions;
using FluentAssertions;
using Document = Didx.Iso20022.Sdk.Contracts.Pain.Creditor.Payment.Activation.Request.Status.Report.V11.Document;
using Validator = Didx.Iso20022.Sdk.Validation.Pain.Creditor.Payment.Activation.Request.Status.Report.V11.Validator;

public class Tests : MessageTestBase<Document>
{
    protected override string SampleFileName => "Sample.xml";

    [Fact]
    public void FromXml_ShouldDeserializeSuccessfully()
    {
        var xml = Sample.ToXml();
        var result = xml.FromXml<Document>();
        result.Should().NotBeNull();
        result.CdtrPmtActvtnReqStsRpt.Should().NotBeNull();
    }

    [Fact]
    public void ToXml_ShouldSerializeSuccessfully()
    {
        var xml = Sample.ToXml();
        xml.Should().Contain("Document").And.Contain("CdtrPmtActvtnReqStsRpt");
    }

    [Fact]
    public void ToJson_ShouldSerializeSuccessfully()
    {
        var json = Sample.ToJson();
        json.Should().Contain("cdtrPmtActvtnReqStsRpt");
    }

    [Fact]
    public void FromJson_ShouldDeserializeSuccessfully()
    {
        var json = Sample.ToJson();
        var result = json.FromJson<Document>();
        result.Should().NotBeNull();
    }

    [Fact]
    public void Validate_ShouldPassSchemaValidation()
    {
        Sample.ValidateSchema();
    }

    [Fact]
    public void Validate_ShouldPassFluentValidation()
    {
        var validator = new Validator();
        var result = validator.Validate(Sample);

        Assert.True(result.IsValid, $"Validation failed: {string.Join("; ", result.Errors.Select(e => e.ErrorMessage))}");
    }
}

🏷️ [MessageMetadata] Attribute

Each generated Document class includes a [MessageMetadata] attribute, exposing key ISO 20022 metadata at runtime:

[MessageMetadata(
    Id = "pain.001.001.12",
    Name = "CustomerCreditTransferInitiationV12",
    BusinessArea = "Pain",
    Version = "001.12")]
public class Document
{
    // ...
}

This metadata helps with introspection, routing, logging, and analysis.

🔍 Accessing Metadata at Runtime

Use the MessageMetadataResolver to easily retrieve metadata for any message type:

var metadata = MessageMetadataResolver.Get<Document>();
Console.WriteLine(metadata?.Id);           // "pain.001.001.12"
Console.WriteLine(metadata?.Name);         // "CustomerCreditTransferInitiationV12"
Console.WriteLine(metadata?.BusinessArea); // "Pain"
Console.WriteLine(metadata?.Version);      // "001.12"

Or with a Type instance:

var metadata = MessageMetadataResolver.Get(typeof(Document));

This enables tools, validators, and consumers to programmatically identify ISO 20022 messages.

🔁 Conversion & Validation Extensions

These helper methods simplify working with ISO 20022 documents:

var xml = message.ToXml();
var json = message.ToJson();

var messageFromXml = xml.FromXml<Document>();
var messageFromJson = json.FromJson<Document>();

message.ValidateSchema(); // Validate against XSD

Extensions live under Didx.Iso20022.Sdk.Extensions.

🧩 Validation Flow

Validation runs in two layers:

1. XSD Schema Validation

Document.ValidateSchema();

This invokes:

Didx.Iso20022.Sdk.Validation.MessageSchemaValidator.Validate(Document);

Throws a FluentValidation.ValidationException if the payload is not schema-compliant.

2. FluentValidation

var validator = new Validator();
var result = validator.Validate(Document);

Each Validator.cs is found under its message-specific namespace. Only base validation rules are generated automatically — customize as needed.

💡 Notes

• Schema.xsd is embedded per message and used for validation.
• Generated files (Model.cs, Schema.xsd, Validator.cs) are additive and organized by namespace.
• File generation is non-destructive — existing files are never overwritten.