Building an ISO 20022 End-to-End Demo with ngx-iso-form and ISO20022 Libraries

ISO 20022 has emerged as the global standard for financial messaging, offering a structured, extensible framework for payments, securities, and trade communications. However, working with its XML-based messages and XSD schemas can be daunting due to their complexity. In this article, we’ll walk through an end-to-end demo that simplifies ISO 20022 message creation and processing. We’ll use ngx-iso-form, an Angular library, to dynamically generate user-friendly forms, and leverage either the ISO20022.Suite library to convert XSD to JSON and transform form output into validated ISO 20022 messages. Let’s dive in!

Overview of the Tools

• ngx-iso-form: An Angular library that generates reactive forms from XSD schemas, ideal for creating ISO 20022 messages dynamically. It outputs JSON, making it a bridge between user input and downstream processing.
• ISO20022.Suite: A .NET library that parses XSDs, converts them to JSON, and validates/generates ISO 20022 messages.

For this demo, we’ll use ISO20022.Suite a .NET library capable of both XSD-to-JSON conversion and JSON-to-XML transformation with validation.

LIVE End-To-End DEMO

Step 1: Setting Up the Environment

Frontend (Angular with ngx-iso-form)
First, install Angular and ngx-iso-form:

ng new iso20022-demo
cd iso20022-demo
ng add @angular/material
npm install ngx-iso-form

Import Module & SCSS

import { NgxIsoFormModule } from 'ngx-iso-form';
import { HttpClient, provideHttpClient } from '@angular/common/http';

@NgModule({
  ...
  imports: [
    ...
    NgxIsoFormModule
  ],
  provider:[provideHttpClient()]
  TranslateModule.forRoot({
      defaultLanguage: 'en',
      loader: {
        provide: TranslateLoader,
        useFactory: HttpLoaderFactory,
        deps: [HttpClient]
      }
    })
    ...
})

export function HttpLoaderFactory(http: HttpClient) {
  return new TranslateHttpLoader(http, '/i18n/', '.json');
}

Add style file to angular.json file

styles:[
     "node_modules/ngx-iso-form/lib/styles/index.scss"
]

Add component to view

 <div class="iso-form">
  <ngx-iso-form [schema]="schema" [form]="form"></ngx-iso-form>
  <button mat-button matStepperNext (click)="onSubmit($event)">Next</button>
 </div>

Component

export class AppComponent implements OnInit {
    @ViewChild('isoForm') isoForm: NgxIsoFormComponent;

    form: IsoForm;
    schema: SchemaElement;

    // exclude the MsgId field from loading.
    excludes:string[] = ['Document_BkToCstmrStmt_GrpHdr_MsgId'];
    ngOnInit() {

        this.httpClient.get('http://localhost:5000/api/iso20022/generate-schema').subscribe((data) => {
        this.schema = data as SchemaElement
       });
    }

    //To get the form object
    get model(): string {
        const data = this.isoForm.model;
        this.formData = JSON.stringify(data)
    }

    //To get the form validation status
    get invalid(): boolean {
        return this.isoForm.invalid;
    }

  onSubmit($event: any) {

    // Send to backend for processing
    this.submitToBackend(this.form.getFormModel());
  }

  submitToBackend(data: any) {
      const formData = JSON.stringify(jsonModel);
      const url = `http://localhost:5000/api/iso20022/create-message`;
      this.httpClient
      .post(url, formData , { responseType: 'text' })
       .subscribe({next: (data) => {
          $event.target.click();
        },error: (errorData)=>{
          const error = JSON.parse(errorData.error);
          console.log(error);
          $event.target.click();
        }});
  }
}

Backend (.NET with ISO20022.Suite)
Set up a .NET Core API project:

dotnet new webapi -n Iso20022Api
cd Iso20022Api
dotnet add package ISO20022.Suite

Note: Ensure you have an ISO 20022 XSD file (e.g., pacs.008.001.12.xsd) downloaded from iso20022.org or your provider.

Step 2: Designing the ISO 20022 Form

Using ngx-iso-form, we’ll generate a form based on an XSD like pacs.008.001.12 (FI-to-FI Customer Credit Transfer). First, convert the XSD to a JSON schema compatible with ngx-iso-form using ISO20022.Suite

Convert ISO 20022 XSD to JSON

// In your .NET API (e.g., Iso20022Controller.cs)
using ISO20022.Suite;

public class Iso20022Controller : ControllerBase
{
    [HttpGet("generate-schema")]
    public IActionResult GenerateSchema()
    {
        string xsdPath = "path/to/pacs.008.001.10.xsd";
        XsdToJson xsdLib = new(xsdPath);
        xsdLib.Convert();
        return Ok(xsdLib.SchemaJson);
    }
}

Step 3: Converting JSON to ISO 20022 Message

On the backend, use ISO20022.Suite to transform the JSON into an ISO 20022 XML message and validate it against the XSD:

[HttpPost("create-message")]
public IActionResult CreateMessage([FromBody] string jsonData)
{
    try
    {
        string targetNamespace = "urn:iso:std:iso:20022:tech:xsd:pacs.008.001.12";
        string xsdContent = File.ReadAllText("path/to/pacs.008.001.12.xsd");

        // Generate ISO 20022 XML from JSON
        XElement xml = MxMessage.Create(jsonData, targetNamespace);

        // Validate against XSD
        bool isValid = MxMessage.                    MxMessage.ValidateMXMessage(xsdContent, xmlMessage, out string validationMessage);
(xml, xsdPath);
        if (!isValid) return BadRequest("Validation failed");

        return Ok(xml.ToString());
    }
    catch (Exception ex)
    {
        return StatusCode(500, $"Error: {ex.Message}");
    }
}

Here, MxMessage.Create constructs the XML, and ValidateMXMessage ensures it adheres to the schema, catching errors like missing mandatory fields or invalid data types.

Step 4: Running the Demo

1. Start the Backend: Run the .NET API (dotnet run in the Iso20022Api directory).
2. Launch the Frontend: Serve the Angular app (ng serve).
3. Interact with the Form: Open http://localhost:4200, fill out the form (e.g., a payment instruction), and submit.
4. View the Output: Check the console for the JSON form data and the resulting ISO 20022 XML message, validated against the XSD.

Benefits and Considerations

• Ease of Use: ngx-iso-form abstracts XSD complexity into a user-friendly UI, while ISO20022.Suite handles backend validation and transformation.

• Validation: Ensures compliance with ISO 20022 standards, critical for financial interoperability.

• Scalability: Extend this setup for other message types (e.g., camt.053, pain.001) by swapping XSDs.

Conclusion

This end-to-end demo showcases how ngx-iso-form and ISO20022.Suite (or raw XSDs) can streamline ISO 20022 workflows. From form creation to validated XML output, it’s a practical solution for fintech developers aiming to adopt this standard efficiently. Try it out,a nd let us know how it transforms your financial messaging projects!