Amendment

This page proposes an initial draft amendment to the second edition of the international standard ISO 20022:2013, in order to:

  • clarify and correct accumulated errata;
  • support modelling and generation of External CodeSets;
  • support generation of other syntax message schemes.

Introduction

ISO 20022 has become widely adopted for defining message schemes for payments, cards, and securities.
This amendment aims to ensure that the standard is clear and consistent.

  • Clarifications and Errata
    • Part 1: Metamodel
      = clarify diagrams, amount and errata
    • Part 2: UML profile 
      = realization diagrams and separate MessageTransportMode.
    • Part 3: Modelling
      = clarify diagrams, encourage Message Choreography.
    • Part 4: XML Schema generation = support for external code sets.
    • Part 5: Reverse engineering = review by FIX and SWIFT.
    • Part 6: Message transport characteristics  = Web Service mode.
    • Part 7: Registration
      = replace TC68 with user community to conform with Annex SN.
  • Deprecation
    • Part 8: ASN.1 generation 
      = was incompletely specified, untested and unused.
  • Addition
    • Part 9: Scheme generation 
      = example model and template for specifying generation.

1       Scope

Clarifications and disposition of errata in ISO20022:2013. Modelling and generation of External CodeSets. Generation of other syntax message schemes.

2       Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

ISO 20022:2013, Financial services — Universal financial industry message scheme

3       Terms and definitions

For the purposes of this document, the terms and definitions given in ISO 20022:2013 and the following apply.

ISO and IEC maintain terminological databases for use in standardization at the following addresses:

—    ISO Online browsing platform: available at https://www.iso.org/obp

—    IEC Electropedia: available at http://www.electropedia.org/

3.1 External CodeSet

a CodeSet whose Codes are generated outside of a SyntaxMessageScheme

Note The intent is to allow users to configure which version of the External CodeSets to use for validation. This enables use of an version of the CodeSet update after the SyntaxMessageScheme was generated.

The numbering of the following headings relates to the part being amended.

Part 1: Metamodel 

Clarify Diagrams

All diagrams should be made clear and legible.

Table 1 – Metamodel levels.

Move Message Choreographies from Conceptual to Logical as B.2.8.8 Metaclass MessageChoreography.

Replace undefined BusinessActivities with defined Participant, MessageTransmission and Component.

Level name Focus
Scope Achieving a thorough understanding of the business objectives of the considered BusinessArea and its relevant Business Processes.
Conceptual Formalizing the semantics and discovering the communication and interaction requirements related to these Business Processes by defining the BusinessTransactions, Participants, MessageTransmissions and their Components.
Logical Creating a precise description of the MessageChoreography comprising messages and systems, without regard to technology.
Physical Creating a precise description of the messages and systems in a technology that can be used for implementation.

2 Normative References

The ISO 20022 metamodel specifies in B.2.1.11 that Metaclass RepositoryConcept may have an objectIdentifier defined as:
“An ITU-T X.660 | ISO/IEC 9834 series OID (Object Identifier).”

The reference, should be included in this clause, as it is normative.

3 Terms and definitions

3.69 SyntaxMessageScheme

To clarify the definition, replace strikethough with bold text and add note:

syntax processable notation specification in a syntax used to define the structure of a MessageInstance in a particular syntax possible encoding


NOTE 1 In case of XML, the representation might, for instance, be an XML DTD or an XML Schema and can then be used as a validation tool for XML MessageInstances.

NOTE 2 Syntax message representations are stored in the BusinessProcessCatalogue

NOTE 3. ASN.1 and RDF messages can each be encoded several ways.
An ASN.1 SyntaxMessageScheme can specify the structure of messages encoded as XML, JSON, and binary formats.
An RDF SyntaxMessageScheme can use SHACL syntax to define the shape of a graph encoded as RDF/XML, JSON-LD, TTL, and others.

Define the following terms, which are used in the text but not specified clearly.
The examples copy and extend those in the corresponding metaclasses.

Syntax

interface definition language
NOTE A syntax is the specification language of a Syntax Message Scheme.
EXAMPLE 1 W3C XML Schema 1.0
EXAMPLE 2 ISO ASN.1
EXAMPLE 3 OpenAPI Specification
EXAMPLE 4 RDF SHACL

Encoding

wire format of message instances
NOTE An encoding specifies the format of message instances that are structured according to a Syntax Message Scheme.
EXAMPLE 1 ASN.1 PER
EXAMPLE 2 ASN.1 XER
EXAMPLE 3 XSD XML
EXAMPLE 4 JSON (IETF RFC 8259)
EXAMPLE 5 RDF TTL

6.1.1 Overview

Replace the list under “The main relationships between Dictionary Items and Catalogue Items are as follows.” with

  • Within the DataDictionary: Each MessageConcept derives from a BusinessConcept.
  • Within the BusinessProcessCatalogue: Each MessageChoreography derives from a BusinessTransaction, which derives from a BusinessProcess. Each MessageDefinition traces from a MessageTransmission.
  • Between the BusinessProcessCatalogue and the DataDictionary: Each MessageDefinition comprises MessageBuildingBlocks which are either a simple Data Type or a MessageConcept.

6.3.2 List of BusinessProcessCatalogue Items

In “MessageSet with its MessageDefinitions” insert “and MessageBuildingBlocks” before “(Diagram);”.

A.2.3.12 Datatype ENTITIES
A.2.3.23 Datatype IDREFS
A.2.3.32 Datatype NMTOKENS

These currently specify their singular form as a superclass, whereas XML schema says they are derived by list. Instead, their super class should be normalizedString, with a constraint that its space separated tokens match the relevant singular datatype.

B.2.1.15 Datatype Cardinality

Define minimumOccurrence and maximumOccurrence properties, which are referenced by B.2.6.2 Metaclass BusinessElementTrace.

B.2.1.10 Metaclass Repository

Add or change constraints so that names of top level entries are unique across the Repository, so that these can be referenced directly, instead of via Data Dictionary and Business Process Catalogue.

B.2.3.1 Metaclass BusinessTransaction

Remove the UniqueName constraint, because

  • it wrongly specifies oclIsKindOf(SyntaxMessageScheme)
  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.3 Metaclass BusinessProcessCatalogue.

B.2.4 Package ISO20022::Metamodel::ConceptualLevel::MessageTransport

Add a diagram showing the metaclasses and their relations. For example:

For decision: Although modelled, there is nothing in the repository that contains instances of the metaclasses defined in this section. To enable the repository to hold instances, we could consider:

  • for MessageTransportSystem, Address, BroadcastList, Conversation:
    • Adding a new repository feature to comprise these features
      eg. “Scenario”.
    • Add these features to the catalogue by making each a kind of TopLevelCatalogueEntry.
  • A Conversation could comprise a sequence of MessageInstances.
  • Each MessageInstance could comprise its transportMessages.
    (This appears to model IP fragmentation.)

B.2.5.1 Metaclass BusinessAssociation

Remove the UniqueName constraint, because

  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.7 Metaclass DataDictionary.

B.2.5.4 Metaclass BusinessComponent

Remove the UniqueName constraint, because

  • it wrongly specifies oclIsKindOf(SyntaxMessageScheme)
  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.7 Metaclass DataDictionary.

B.2.7.1 Metaclass Amount

For Properties currencyIdentifierSet Description:
In “Specifies the” insert “set of” before “allowed currencies that can be used to qualify this amount.”

Add “Absence of a specified set allows any currency.”, as all Amounts are intended to have an explicit currency. Fields specifying a monetary amount with an implied currency should use a decimal type.
Note that ISO20022-4:2013 disallows any currency in contradiction,
and so should be amended to allow any currency.

B.2.7.15 Metaclass String

Change the Type of minLength
from: ISO20022::TypeLibrary::XMLSchema::string
to: ISO20022::TypeLibrary::XMLSchema::nonNegativeInteger

B.2.8.1 Metaclass BusinessArea

Set Multiplicity of code to 1. (It was not set.)
Remove the UniqueName constraint, because

  • it wrongly specifies oclIsKindOf(SyntaxMessageScheme)
  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.3 Metaclass BusinessProcessCatalogue.

Add a constraint “UniqueMessageDefinitionIdentifiers”, to ensure that within a BusinessArea, the combination of messageFunctionality, flavour and version is unique. Note that its businessArea is already constrained to be the same as the BusinessArea it is within, which is distinct.

B.2.8.4 Metaclass ExternalSchema

Set Multiplicity of processContent to 1. (It was not set.)

B.2.8.5 Metaclass MessageAssociationEnd

Change the Type of isComposite
from: ISO20022::TypeLibrary::XMLSchema::string
to: ISO20022::TypeLibrary::XMLSchema::boolean

B.2.8.8 Metaclass MessageChoreography

Remove the UniqueName constraint, because

  • it wrongly specifies oclIsKindOf(SyntaxMessageScheme)
  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.3 Metaclass BusinessProcessCatalogue.

B.2.8.10 Metaclass MessageComponentType

Remove the UniqueName constraint, because

  • it wrongly specifies oclIsKindOf(SyntaxMessageScheme)
  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.7 Metaclass DataDictionary.

B.2.8.14 Metaclass MessageSet

Remove the UniqueName constraint, because

  • it wrongly specifies oclIsKindOf(SyntaxMessageScheme)
  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.3 Metaclass BusinessProcessCatalogue.

B.2.11.1 Metaclass MessageInstance

For decision: Although modelled, there is nothing in the repository that contains MessageInstance. To enable the repository to hold instances, they could be made a subclass of TopLevelCatalogueEntry, or set SyntaxMessageScheme’s aggregation to composite.

Add property “encoding”, because any syntax may support multiple valid encodings.

B.2.11.2 Metaclass SyntaxMessageScheme

Note: This is the correct case for oclIsKindOf(SyntaxMessageScheme).
Update definition to match proposed change in 3.69.

Remove the UniqueName constraint, because

  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.7 Metaclass DataDictionary.

Add property “syntax”, because this is not inferable when a MessageDefinition is included across MessageSets with more than one generated syntax.

B.2.12.1 Metaclass BusinessProcess

Remove the UniqueName constraint, because

  • it wrongly specifies oclIsKindOf(SyntaxMessageScheme)
  • it is covered by the EntriesHaveUniqueName constraint of B.2.1.3 Metaclass BusinessProcessCatalogue.

Part 2: UML profile 

Add realization Diagrams

Add diagrams to illustrate each UML realization.

Split BusinessTransaction from MessageTransportMode

There are only a few MessageTransportMode with high levels of reuse. It’s better to make it a stereotype to characterise the requirements of the BusinessTransaction.

1.2.1       Figure A.2 — Example of ISO20022 Level Stereotypes

Move TopLevelDictionaryEntry down so it is clear the both CodeSet and IndentifierSet generalise to it.

1.2.2       Figure A.3 — Example of conceptual Dynamic Stereotypes

Add “MessageTransportMode” generalize to “TopLevelCatalogueEntry”

Move properties from “BusinessTransaction” to “MessageTransportMode”.

Add an association from “BusinessTransaction” to each of “MessageTransportMode”, “MessageTransmission” and “Participant”.

A.2.8.2 Stereotype BusinessArea

The Multiplicity of the “code” tag should be 1.

Part 3: Modelling

Figure 1 — High level workflow activity diagram

Text on diagram is too small. The diagram should be redrawn for clarity. Instead of drawing lines to the datastores, the items themselves can be labelled, leaving the remaining line to indicate process flow.

7 Logical level

Encourage the creation of Message Choreography.

7.1.1 Purpose

Replace BusinessTransactions with its corresponding logical level concept: Message Choreography.

7.1.3 Main activities

Add main activity “defining the Message Choreography”.

7.1.4 Deliverables

Add deliverable “a Message Choreography with constraints.”

7.2.2.2 Create a MessageDefinition

Add “Note: The MessageFunctionality is intended to be an incremental numeric assignment by the RA upon full registration; where as the flavour is intended to be alphanumeric to allow mnemonic codes by countries or organisations.”

Add “Note: The metamodel does not enforce these suggestions, merely that they are valid token strings.”

Annex A (normative) Applied UML diagrams

In “To model BusinessTransactions and the associated Participants and MessageTransmissions, use” replace “Sequence Diagrams” with “Information Flow Diagrams”.

In “To model BusinessRoleTraces,” replace “bind <<BusinessRole>>-stereotyped Actors to LifeLines in Sequence Diagrams.” with “add a <<trace>> dependency from each <<Participant>> Actor to its <<BusinessRole>> Actor.”

Add ” To model Message Choreography, define constraints on its MessageDefinition.” NOTE: ISO20022.plus defines a Logical Level concept Interface traced to a Participant, represented as a Lifeline in SequenceDiagrams for the Choreography.

Part 4: XML Schema generation

External CodeSets have been modelled and generated slightly differently to the standard. These amendments bring them into line.

An “External” CodeSet is intended to be a CodeSet that is external to generated messages schema, so that the CodeSet can be updated  a separate pace to the messages. These have been modelled as empty CodeSets which by a quirk specific to the XML Schema generation, generates a simpleType based on xsd:string without any restriction allowing any string value.

These External CodeSets are now managed on the repository, and generated into several formats.
In order to be able to regenerate messages that use External CodeSets this amendment adds a sub section  to:

5.7.3.3.4 DataType CodeSet

In order to correctly specifiy the generation of codes as enumerations:

From: << for each CodeSetLiteral, an XSD Enumeration using namespace prefix “xs:”. >>

CodeSetLiteral is a UML concept. It should use the ISO 20022 concept:

To: << for each Code, an XSD Enumeration using namespace prefix “xs:”,
with the attribute “value” whose value is the Code’s codeName. >>

5.7.3.3.4.1 DataType CodeSet is external

If a CodeSet has Semantic Markup with the TupleTypeName = ExternalCodeSetAttribute and a TupleElement  with TupleElementName = IsExternalCodeSet and TupleElementValue = true, then:

DataType CodeSet is transformed into XML Element “xs:simpleType”. It contains:

  • XML Attribute “name” with value DataType CodeSet Name;
  • XML Element “xs:restriction”, which contains
    • XML Attribute “base”, which has value “xs:string”,
    • the Properties as defined in Table 2, which are transformed into XSD Constraining Facets with the same name and preceded by “xs:”, and the value of the Property is copied into the attribute “value” of the XSD Constraining Facet (properties are only transformed if their value is not empty),
    • no transformation for Property IdentificationScheme,
    • no transformation for Codes. The simpleType is not restricted by enumeration.

EXAMPLE

<xs:simpleType name="ExternalMandateStatusCode">
	<xs:restriction base="xsd:string">
		<xs:minLength value="1"/>
		<xs:maxLength value="4"/>
	</xs:restriction>
</xs:simpleType>

Part 5: Reverse engineering

N/A for post implementation review by FIX and SWIFT.

Part 6: Message transport characteristics 

We could add an Example MessageTransportMode for interactive Web Service.

Part 7: Registration

Some small changes to comply with Annex SN of ISO/IEC directives 2020 :

Committees (either directly or through the RMG) shall not participate or get involved in providing the Registration Services except in the supervisory roles specified in this subclause.

1 Scope

Change from “the RA is monitored and assisted by ISO/TC 68.” to “the RA is supervised by ISO/TC 68/SC 9”.

4.1.2 Responsibilities to Submitting Organizations

Change from “The approval of Business Justifications and Maintenance Change Requests shall be performed with the help of ISO/TC 68 as described on www.iso20022.org.” to “The RA must consult the user community on Business Justifications and Maintenance Change Requests.”

Change from “The approval of Repository outputs shall be performed with the help of ISO/TC 68 as described on www.iso20022.org.” to The RA must consult the user community on Repository outputs.

Part 8: ASN.1 generation 

Deprecate this part.

  • much of the generation is left unspecified,
  • so rely on examples for what is intended;
  • some examples do not conform to strict ASN.1 syntax;
  • further notation is required to enable compilation;
  • an XSD module is not defined, nor referenced.

Part 9: Syntax generation

Add new part describing a Template for specification of syntax generation, and an example Model for comprehensive testing of syntax generation.

The example Model should include

  • choices of optional elements,
  • Amounts with and without currencyIdentifierSets.
  • MessageAssociationEnds – composite and not composite
  • CodeSets and External CodeSets

We’d also like to add support to the standard for modelling APIs,
which would require further updates to parts 1, 2, 3.