ISO 20022 and JSON, balancing standardisation and flexibility in APIs

The rising adoption of ISO 20022 and the increased demand for APIs has led to much innovation in the Financial Industry. However, ISO 20022's rich data standards can clash with the simplicity and minimalism that JSON, the de facto data format used in APIs, encourages. This issue has the potential to hinder the industry in realising the benefits that ISO 20022 can provide.

In this article, we explore the issues facing developers and the industry when trying to reconcile JSON’s flexibility and simplicity with ISO 20022s data richness. We’ll also take a look at the ongoing efforts attempting to address this important issue.

What is ISO 20022?

ISO 20022 is a global standard for exchanging data between financial institutions and covers the domains of payments, foreign exchange, cards, trade finance and securities. The standard is rich, structured, and flexible making it a big leap forward from previous global standards, ISO 15022 (SWIFT’s MT Format) and ISO 8583 (used for card payments and account-to-account payments).

There has been a concerted effort across the industry to drive the adoption of ISO 20022 as the benefits are most obvious when everybody is using it. The pace of this change has accelerated as more initiatives have made the switch – with many Automated Clearing Houses (ACH) across the world now using the new format for high and low value payments as well as SWIFT’s Cross Border Payments system. Its usage is not yet ubiquitous, with some systems supporting legacy formats especially for bulk payments, however, for local real-time payments systems usage of ISO 20022 is widespread.

ISO 20022’s scope focuses on the exchange of information, but the key benefit comes from institutions using the Data Dictionary to support their internal data models, in essence, adopting a common language. This means, for example, that the attributes that make up a Party (Name, Address, Date and Place of Birth, etc.) are consistent when the Party is a Debtor in a cross-border transaction or an Account Owner in an Account Switching Request.

ISO 20022, as a standard, is format agnostic but specific message schemas are only officially published as XSDs (XML Schema Definitions) and are available from the catalogue of messages, this has led to XML being the most widely used format to exchange ISO 20022 messages.

APIs, JSON, and ISO 20022

As the usage of ISO 20022 increases so too does the demand for new use cases and new ways of exchanging data, with a prominent example being APIs which are used by financial institutions for numerous applications such as allowing access to account information, initiation of payments, Open Banking, or internal systems integrations.

API developers, especially when designing REST APIs1, often take a minimalist approach, prioritising efficiency and only transmitting the essential data required for a specific request and response. Information exchanged via API is usually sent in JSON (JavaScript Object Notation), which is like XML but has some slight incompatibilities.

Since ISO 20022 does not publish JSON Schemas and there are currently no commonly followed rules for how to represent it in this format2 this can present challenges to API developers hoping to use the standard.

ISO 20022 supports financial messaging use cases globally, meaning that each message will include many elements. Whilst the key elements necessary to execute a specific business message exchange, for example a credit transfer, remain quite consistent (Debtor Name, Creditor Name, Amount, Currency etc.), there is variation in the way these elements are used. For example, in local clearing houses a Debtor Agent (Bank of the Debtor) in Germany is defined using a BIC (Business Identifier Code) or a Bankleitzahl (BLZ – derived from the IBAN), but in Australia it is identified using a BSB Number (Bank State Branch).

To accommodate for this, ISO 20022 messages are structured in a way that allows you to provide either one or the other, but this flexibility leads to larger messages than would be strictly necessary for any given use case.

When developers design APIs, with an emphasis on minimalism, they will often only include the elements specific to their use case, for example, if they are in the United Kingdom there is little reason to include the BSB Number, since all Agents will be identified with a Sort Code. Similarly, if an Agent can only be identified with a Sort Code, then why include some of the structure of an ISO 20022 message when the element name can be changed, the following example highlights this:

This is how a UK Sort Code and Account Number would appear in an XML-based ISO 20022 instance:

    
    <CdtrAgt> 
        <FinInstnId> 
            <ClrSysMmbId> 
                <ClrSysId> 
                    <Cd>GBDSC</Cd> 
                </ClrSysId> 
                <MmbId>080800</MmbId> 
            </ClrSysMmbId> 
        </FinInstnId> 
    </CdtrAgt> 
    <CdtrAcct> 
        <Id> 
            <Othr> 
                <Id>21325698</Id> 
            </Othr> 
        </Id> 
    </CdtrAcct> 

The code “GBDSC” defines that the Member ID is a “UK Domestic Sort Code” the Id/Other/Id contains the Account Number.

Comparatively, the following is how the same data would be transmitted via UK Open Banking APIs, which were ‘designed using the ISO 20022 message elements and components where available’3, note the smaller size but also the change of element names, codes, and structure:

    "CreditorAccount": { 
        "SchemeName": "UK.OBIE.SortCodeAccountNumber", 
        "Identification": "08080021325698" 
} 

This issue is not specific to UK Open Banking and is occurring across the industry, with ISO 20022-based APIs being implemented without clear guidelines on best practices or official JSON Schemas being published. The risk of fragmentation of approach is high, leading to incompatibility between implementations and not realising some of the benefits that standardisation was intending to achieve. The industry has identified this risk and ISO 20022 has taken some steps to mitigate it:

• The API SEG (Standards Evaluation Group) was established to register, develop, and maintain API resources.
• ISO/TC 68/WG4 (Technical Committee 68/Working Group 4), the group responsible for managing/updating the ISO 20022 standard, have been investigating how to change the standard to formalise the introduction of JSON-based ISO 20022 resources as well as introducing a template to aide modellers looking to register different formats for the standard to be published in (i.e. JSON Schema).
• The ISO 20022 Technical Support Group (TSG) is looking to update and revise their JSON best practices Whitepaper (referenced in the footer) to provide further guidance on modelling JSON.

As the financial industry continues to evolve, continued standardisation and interoperability is crucial. The adoption of JSON-based messaging is a key enabler for innovation, but it does also pose potential pitfalls that the industry needs to be aware of. Otherwise, it faces the risk of undoing a lot of the challenging work that has gone before.

Mastercard is actively involved in these initiatives and will continue to collaborate with the industry to drive towards a framework that allows for the adoption of new formats whilst preserving the standardisation and interoperability that is essential for future innovation.