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.