Standards
Standards Developer Kit 1.0
User Guide
This document describes the components of the SWIFT Standards Developer Kit, and illustrates how they can be
used to solve common standards implementation problems.
25 September 2009
Standards Developer Kit 1.0
Table of Contents
Preface ............................................................................................................................................. 3 1 MT Resources ........................................................................................................................ 4 1.1 MT/XML Schema Library ........................................................................................................4 2 MX Resources ...................................................................................................................... 12 2.1 MX Repository.......................................................................................................................12 2.2 MX Enriched Schemas .........................................................................................................20 2.3 MX Spreadsheets..................................................................................................................22 A.1 Sample Implementation of ISchemaDocResolver (Java) ................................................. 24 A.2 MT Message Generation Using Apache XML Beans (fragment) ...................................... 25 A.3 Generating an MT Message Using a Commodity Mapping Tool ...................................... 25 B.1 Message Definition Query (XQuery) ................................................................................... 26 B.2 Extract Code Data Types and Details of Code Values for Messages in a Given Business
Area ....................................................................................................................................... 27 C.1 Acknowledgements ............................................................................................................. 28 C.2 References and Resources ................................................................................................. 28 Legal Notices ................................................................................................................................. 29 2
User Guide
Preface
Preface
Purpose of this document
The SWIFT Standards Developer Kit (SDK) is a coherent set of machine consumable standards
definitions aimed at supporting many phases of standards implementation, from analysis through
to design, build, document and test. The purpose of this document is to describe the components
of the kit, and illustrate how they can be used to solve common standards implementation
problems.
It is important to understand the philosophy that underpins the SDK. The SDK is not an
application or a development tool in its own right; it is a collection of resources that can be used
in conjunction with other tools – tools that you may already have, or that can be easily obtained
on the market – to build standards implementations. To ensure that they can be used with the
widest possible range of tools, SDK resources are delivered in technical formats that adhere to
mainstream, open industry standards, such as XML, XML Schema, and Comma Separated
Value (CSV). Some working samples that use easily obtainable tools are included with the SDK
to illustrate the use of the resources, but these should be treated purely as examples; no
endorsement of any particular tool, programming language or approach is implied, nor should the
omission of a technology be taken as a sign of its unsuitability for use with the SDK.
Intended audience
The SDK includes components aimed at helping implementers of MT (traditional FIN messages)
and MX (ISO 20022 XML) messages. Some components are suitable for technical IT
developers; others are also accessible to less technical users, such as business analysts. The
technical profile of the expected user of the component is indicated in the section of this
document that describes it.
This document assumes some knowledge of SWIFT and ISO standards, and SWIFT messaging
services. More information can be found in the SWIFT User Handbook Online and at
www.iso20022.org.
Document conventions
This document uses the following typographical conventions:
Bold
Names of files, parameters, API calls, user logon, and logon groups
References to a directory or a menu
GUI elements and command names
Italics
Important information and document names
Courier
User input, directory paths, parameter values, place holders, and system
output examples
Significant changes
This is the first publication of this document.
25 September 2009
3
Standards Developer Kit 1.0
1
MT Resources
1.1
MT/XML Schema Library
Naming
Audience/Skills: Technical IT / XML
The MT/XML Schema Library consists of around 250 XML schemas, one for each MT message
supported by the SWIFT FIN service, plus several extras for Message User Group (MUG) –
specific message variants. There is also one schema which includes definitions for the header
and trailer blocks that are common to all MT messages.
MT message definitions are maintained annually, but only a subset of messages are changed in
any given Standards Release (SR). New schemas are only issued for messages that have
changed in a given SR. The message type and standards release to which a schema relates is
given in its namespace declaration. Therefore, each MT schema is updated to reflect the proper
namespace relative to that Standards Release. For example, the following declaration is taken
from the 2008 MT103 schema:
Schema filenames are in the form:
fin.nnn.yyyy.xsd
where nnn is the message type and yyyy is the standards release, for example: fin.103.2008.xsd.
For MUG-specific variants a qualifier is added to the name. For example the MT103+, which is a
subset of the MT103 intended to enable Straight Through Processing (STP), has file name:
fin.103.STP.2008.xsd, and the namespace declaration is similarly modified:
4
User Guide
MT Rresources
Structure
A SWIFT MT user-to-user message in its native format conforms to the following structure:
The message is divided into 5 blocks, labelled 1 to 5. Each block is declared:
{n: <block content>}
where, n is the block number. Blocks 1 and 2 are mandatory headers, which include the sender
and destination address of the message, and certain other details relevant to all messages; block
3 is an optional user header; block 4 (the text block) contains the business content of the
message and block 5 is a trailer that contains technical details related to communications.
The message-type specific XML schemas in the MT/XML Schema Library define just the content
of block 4.
Definitions for the common elements that are included in the header and trailer blocks are found
in one schema, file name mtmsg.2008.xsd, and namespace:
This schema defines block 4 using the XML Schema xs:any construct.
A full message instance should declare the namespace for the header/trailer and block 4
business content. For example:
25 September 2009
5
Standards Developer Kit 1.0
Identifiers, delimiters and separators
A feature of the schemas in the MT/XML schema library is that definitions of the ‘scaffolding’
required by the MT syntax, such as block identifiers and subfield separators, are provided in
schema annotations, to be applied automatically by formatting and parsing software. The user of
the schema is not required to populate these syntax-specific elements. For example, the ‘ {1:’
block identifier that begins the declaration of the Basic Header does not need to be specified by
the user of the schema, nor does the closing ‘ }’; the user is only required to specify the variable
content of the header elements.
Header and trailer blocks
The content of the SWIFT header and trailer blocks is defined in the SWIFT User Handbook >
FIN Operations Guide > Part D.
Each header element is modelled by an XML element in the mtmsg.yyyy.xsd schema. For
example, the basic header definition (see Basic header definition) is modelled in the schema
(see Schema).
Basic header definition
Block identifier Must be the first character within the block. The block identifier for the Basic Header is 1. Application Identifier Must designate the application that has established the association used to convey the message. Service Identifier 6
Identifies the type of message. The identifier used must belong to the set of identifiers defined for the application. User Guide
MT Rresources
Logical Terminal address The system must know the logical terminal address, and the logical terminal address must be active. Session Number When present, must be numeric. Must also equal the current application session number of the application entity that receives the input message. Sequence Number •
•
•
•
For all General Purpose Application messages or General Purpose Application service messages that have Service Identifiers 01, 03, or 06, the sequence number must be equal to the next expected number. For all General Purpose Application messages that have Service Identifiers 21, 23, 26, or 43, the sequence number must be equal to that of the acknowledged service message. For all FIN messages or FIN service messages that have Service Identifiers 01 or 05, the sequence number must be equal to the next expected number. For all FIN messages that have Service Identifiers 21 or 25, the sequence number must be equal to that of the acknowledged service message. Schema:
Note
25 September 2009
No element is defined for Block Identifier, which is populated automatically, as
explained in the previous section.
7
Standards Developer Kit 1.0
Block 4
The business content of MT messages – block 4 – is defined in the SWIFT User Handbook in
terms of field tags, names, format options and syntax. See the following example
Tag 20 MT 103 Single Customer Credit Transfer Field Name Content/Options Sender's Reference 16x 13C Time Indication /8c/4!n1!x4!n 2 23B Bank Operation Code 4!c 3 23E Instruction Code 4!c[/30x] 4 26T 32A Transaction Type Code Value Date/Currency/Interbank Settled Amount Currency/Instructed Amount Exchange Rate Ordering Customer 3!c 6!n3!a15d 5 6 3!a15d 7 12d A, F, or K 8 9 Status M ‐‐‐‐‐> O ‐‐‐‐‐| M ‐‐‐‐‐> O ‐‐‐‐‐| O M O 33B O M Etc… 36 50a No. 1 Status indicates whether a field is Mandatory (M), or optional (O). Tag is a 2 or 3 character
identifier that appears in the MT native syntax to identify the data that follows. Content identifies
the syntax of the field data using a syntax notation similar to a regular expression. In some
instances a data item can be represented in one of several different ways. In these cases the tag
is shown with a lower-case ‘a’, and Options indicates the letters that can replace the ‘a’ in the
message instance. For each letter/option, a different Content (syntax) is specified in the more
detailed notes referred to in the No. column. The ‘–---|’ and ‘----->’ notation indicates repetition of
fields or sequences.
8
User Guide
MT Rresources
In schema terms, the same message elements are represented:
Note:
•
Field tags are indicated in element names (for example, Tag 20 is represented by element
F20).
•
All fields are modelled as a choice of format options, even if there is a choice of only one
(see F20a, F20, for example).
•
Fields are defined to the subfield level, for example field 13C, which contains 4 subfields:
Code, Time Indication, Sign and Time Offset.
•
In the UHB, field 13C’s syntax is defined /8c/4!n1!x4!n. Schema users need only populate
the business content of this field, as set out in 13C’s schema definition. The ‘/’ characters
used to delimit Code are not required: they are included automatically by the formatting
software, according to instructions given in annotations of the type definition:
25 September 2009
9
Standards Developer Kit 1.0
•
Schema minOccurs and maxOccurs indicators are used to distinguish between optional and
mandatory fields, and to indicate repeated fields or sequences. For example, the repetition
of field 13C is reflected in the 0..∞ (unbounded) multiplicity of element F13a.
•
Restrictions are used to provide detailed field level validation, for example, the following
definition is used to ensure that a BIC or BEI code is correctly formed:
ISO 15022 generic fields
ISO 15022 generic field definitions extend the field tag identifier with 4 character qualifiers, which
refine the definition of the field. For example, in an MT502 sequence B1, the definition of field
90a must be extended by one of three specified qualifiers (DEAL, STOP, LIMI), to create an
identifier for the data that follows. The full identifier includes the field format option (the letter after
the tag number) and the qualifier, for example ’:90B::DEAL’. In schemas, the order of field
format option and allowed qualifiers is reversed, in order to keep the semantic components of the
definition (what the field means) separate from the format of the data representation:
MT to XML conversion reference software
Audience/Skills: Technical IT / XML / Java
The MT/XML Schema Library is supplied with working Java software that illustrates how to
convert from an MT in its native format to an XML instance and from an XML instance back to
native MT.
10
User Guide
MT Rresources
The software is supplied as commented source code, and includes comprehensive Javadoc
documentation.
The software is able to convert complete MT messages, including all 5 blocks, or just block 4.
When converting a complete MT message, the software first uses the mtmsg.yyyy.xsd schema to
parse the headers, including block 2, which includes the 3 digit MT message type. It uses this
message type identifier to determine the namespace of the schema required to parse block 4.
The task of locating the schema document to use given the namespace is delegated to a class
which must be provided by the user. This class must implement the ISchemaDocResolver
interface. A sample implementation, which obtains schemas from the local file system, is
provided in Appendix A1.
For detailed information about the Conversion Reference Software, programmers should consult
the Javadoc included in the package.
Uses for the MT/XML Schema Library
Audience/Skills: Technical IT / XML / Java
The MT/XML Schema Library allows XML technology to be used to process MT messages,
effectively MT-enabling users’ existing technical platforms, generic middleware and XML tools.
In Java, JAXP can be used to process message instances. Schema validation can be used to
verify that messages conform structurally to the standard. Because schemas include detailed
field level validation in the form of facets, schema validation also catches many common field
format errors.
XML binding technology such as JAXB and Apache XML Beans can be used to generate Java
classes based on schemas. Messages can then be populated and processed as Java objects.
The code fragment in Appendix A2 shows Java logic being used to populate an instance of an
MT515 class which was generated from a schema using XML Beans.
A wide variety of commercial and open source XML tools are available, which can be used in
conjunction with the MT/XML Schema Library to build MT implementations. Appendix A3
illustrates the use of one such tool to create an MT101 payment initiation message from payment
details captured in an Excel spreadsheet. A similar approach can be used to create outgoing
messages from other data sources, such as proprietary XML or database tables. Equally, such
tools can be used to automate the processing of incoming MT messages, for example to create a
comma-separated value (CSV) file suitable for processing in a back-office system from a
received MT.
25 September 2009
11
Standards Developer Kit 1.0
2
MX Resources
2.1
MX Repository
Introduction
Audience/Skills: Technical / IT / Architecture / XPath / XQuery
ISO 20022 message definitions and documentation are derived from a rich conceptual and
logical model which is maintained in a UML repository. The repository has great potential value
for implementers: it can be used to generate custom documentation and a range of other
artefacts from data models to GUI definitions. The MX Repository is an extract of the UML
repository in the form of an XML file which presents the content in a form meaningful to those
familiar with ISO 20022, and accessible to the wide range of XML tools and APIs available in
today’s technical platforms. Definitions in the repository include all the structural information that
can be found in MX schemas, and the semantic information that is normally found in the MX
documentation.
Background: ISO 20022
ISO 20022 recognises that defining the meaning of the information conveyed in messages is
critical to enabling interoperability between often disparate communities of users. The standard
requires definitions to be captured at two levels– the conceptual (or business) level, and the
logical (or message) level. A third (technical) level is required for the technical realisation of
messages defined at the logical level, but the processes of transforming a logical definition into
its technical equivalent – such as an XML schema – is purely mechanical. Definitions at the
conceptual level are of the concepts and relationships that are found in the business area under
consideration, for example: Payment Transaction, Settlement Instruction, Financial Institution,
Individual, Cash Account, Account Owner, Account Servicer. Each concept definition includes
text in English that describes the item in business terms. Definitions at the logical level are
restricted to the information that needs to be exchanged in messages in order to process a
transaction, but they refer to definitions in the conceptual layer, from which they gain their
meaning. The ISO 20022 repository includes definitions from both layers, and the links between
logical and conceptual that allow the meaning of a logical message definition to be understood.
The reusable elements in the logical and physical layers are maintained in a data dictionary.
Elements in the dictionary include Business Components (conceptual definitions), Message
Components (logical definitions) and Data Types (shared by both levels). Message definitions,
which are not reusable, are maintained outside the dictionary, but refer to the dictionary for
definitions of message components which in turn refer to data types.
More detailed information about ISO 20022 can be found at www.iso20022.org. The full
documentation set can be purchased from www.iso.org (search for ISO 20022).
The MX Repository
The MX Repository includes Message Definitions and the Data Dictionary in a single XML
instance described by a schema, as shown below.
12
User Guide
MX Rresources
The SSFD (SWIFT Standards Financial Dictionary) element contains the Data Dictionary. The
Message element contains Message Definitions.
Data types
Data type definitions are shared by the logical and conceptual layers of the ISO 20022
repository, and include basic date, currency-amount and text types, and code lists. Data type
definitions include the following information:
Data Type ID Technical identifier Name ISO 20022 name (e.g. Max35Text, ISODateTime, MarketType1Code) EnhancedDefinition The ISO 20022 description of the Data Type AdministrativeData Details of ISO 20022 registration status Synonym Equivalent term in the vocabulary of another syntax (e.g. ISO 15022), DateTime, Rate Representation One of: Code (for an enumeration), Identifier (for an externally defined code like IBAN), Text, DateTime, Rate, Indicator (a boolean), Amount (of money), Quantity (of non‐monetary units) or User Defined. XMLType The XML type used to represent the value 25 September 2009
13
Standards Developer Kit 1.0
Code Code representation only: enumeration of codes names, definitions and message values Property Several uses. For Identifiers, the identification scheme; for Indicators, the meaning implied by the indicator being true or false. XMLFacet The XML facets to be used to constrain the value of the data type when it appears in XML schema representation, for example, minLength, maxLength, Pattern (regular expression). Rule Reference to a rule that may further constrain the content. XMLAttribute XML attribute used to qualify the value, for example Currency (used to qualify Amounts) Simple XPath statements can be used to extract Data Type information. For example:
//DataType[Name='TaxRecordPeriod1Code']/Code
Exploring the Logical Layer
The diagram illustrates the relationship between XML definitions in the logical (message) layer:
•
A Message Definition is defined as a series of Message Building Blocks.
•
Each message building block is typed by a Message Component (or Choice Component).
•
Each message component is composed of a series (or choice, if it’s a choice component) of
Message Elements.
•
Each message element is typed by a message component or a Data Type.
•
Message components reference other message components recursively, until finally each
message element resolves to a data type.
A specific message definition can be traced by following the references between message
elements, message components and data types, as shown below:
14
User Guide
MX Rresources
References between definitions are defined in the repository using TypeIDRef and ID attributes,
as illustrated below:
XPath can be used to navigate references. The example below shows the Message Building
Blocks defined for SubscriptionOrderConfirmationCancellationInstructionV01:
25 September 2009
15
Standards Developer Kit 1.0
The TypeIDRef attribute can be used to locate the definition of the message component to which
the Message Identification message element refers:
//MessageComponent[@ID='_45FA4A81017741F7C55600AD']
Message building blocks are always typed by message components (which may be standard or
‘choice’ components). Message elements may be typed by either message components, or by
data types.
The TypeOfType element in a message element definition indicates what sort of dictionary item
the element refers to: it contains one of the following constants: MESSAGE_COMPONENT,
CHOICE_COMPONENT or DATATYPE.
Where a data type is indicated, its definition can be found in the DataType element of the
dictionary, for example:
//DataType[@ID='_45FA4A8101773B36F6D20334']
From here, it is easy to find the Message Components referred to by the Message Elements in a
containing Message Component:
//MessageComponent[@ID=//MessageComponent[Name='<ContainingComponent>']/
Messa
geElement[TypeOfType != 'DATATYPE']/@TypeIDRef]
Simple recursive logic can be used to traverse a complete message definition. See Appendix B
for a sample XQuery that produces an HTML report of a message definition.
Content of Logical Layer Definitions
Message
Message
Building Block
16
ID
Technical identifier
Name
ISO 20022 name (e.g. PaymentReturnV01)
EnhancedDefinition
The ISO 20022 description of the message
AdministrativeData
Details of ISO 20022 registration status
MessageID
The ISO 20022 ID (e.g. pacs.004.001.01)
Rule
Any usage rules that apply to the message, including
each rule’s name and textual definition.
XMLTag
The XML tag that represents the message structure in the
ISO 20022 XML schema.
TargetNamespace
The namespace declaration that appears in the ISO
20022 XML schema.
TypeIDRef
Reference to the Message Component that types this
Message Building Block.
ID
Technical identifier
User Guide
MX Rresources
Message
Component
Message
Element
25 September 2009
Name
ISO 20022 name (e.g. GroupHeader) of the element in
the context of the message
EnhancedDefinition
The ISO 20022 description of the Message Building Block
AdministrativeData
Details of ISO 20022 registration status
Multiplicity
The minimum and maximum number of times that this
element may appear in the message (minOccurs = 0
implies that this element is optional)
TypeOfType
The type of ISO 20022 element referred to by TypeIDRef:
MESSGAGE_COMPONENT or CHOICE_COMPONENT.
XMLTag
The XML tag that represents the message building block
in the ISO 20022 XML schema.
ImpactedByRule
Details of any usage or other rules that apply, including
XOR rules (which imply a choice).
IsBasedOnIDRef
Reference to the Business Component on which this
Message Component is based and from which it derives
its meaning.
ID
Technical identifier
Name
ISO 20022 name (e.g.PartyIdentification1)
EnhancedDefinition
The ISO 20022 description of the Message Component. A
blank value implies that the definition should be taken
directly from the Business Component referenced by
IsBasedOnIDRef. Non-blank values refine (rather than
replace) the definition in the business layer.
AdministrativeData
Details of ISO 20022 registration status
Rule
Any usage rules that apply to the message, including
each rule’s name and textual definition.
ChoiceIndicator
True if the message elements of the component are
mutually exclusive (and will appear in an xs:choice
structure in the associated schema)
IsAlternativeFor
A reference to a message component that this one
supersedes in some messages. May include a description
of the change and a reference to the change request.
TypeIDRef
Reference to the Message Component or Data Type that
types this Business Element.
ID
Technical identifier
IsBasedOnIDRef
Reference to the Business Element on which this
Message Element is based and from which it derives its
meaning (if blank, implies that this is a technical definition;
it is required for some technical-messaging related
purpose and there is no corresponding Business
Element).
Name
ISO 20022 name of the element in the context of the
message
EnhancedDefinition
The ISO 20022 description of the Message Element
AdministrativeData
Details of ISO 20022 registration status
Multiplicity
The minimum and maximum number of times that this
element may appear in the containing Message
Component (minOccurs = 0 implies that this element is
optional)
TypeOfType
The type of ISO 20022 element referred to by TypeIDRef:
DATAYPE, MESSGAGE_COMPONENT or
17
Standards Developer Kit 1.0
CHOICE_COMPONENT.
IsTechnical
True for technical definitions (see IsBasedOnIDRef).
XMLTag
The XML tag that represents the message element in the
ISO 20022 XML schema.
Rule
Details of any usage or other rules that apply, including
XOR rules (which imply a choice).
Exploring the Conceptual Layer
The diagram illustrates the relationship between XML definitions in the conceptual (business)
layer:
Business Components contain Business Elements which can refer to other Business
Components or to Data Types. Business Components can also refer to each other directly using
Business Associations (indicated by the blue line on the diagram). The difference between the
two types of business component relationship is that BC-BE-BC relationships are ones of strong
dependency / containment; the referenced component has no independent existence outside the
context of the referring component, whereas business associations are between 2 free-standing
concepts.
Business Elements refer to either Business Components or Data Types. As in the Logical Layer,
references between definitions are defined in the repository using TypeIDRef and ID attributes:
18
User Guide
MX Rresources
Note:
•
Business Concepts are all maintained in the Financial Dictionary.
•
Business Components may be organised in inheritance hierarchies (unlike Message
Components).
•
Business Elements are weakly typed; it is not possible to determine whether an element
refers to a Business Component or a Data Type except by performing a lookup. Key values
are unique across Business Component and Data Type, so only one or the other will be
found.
Business Associations are navigated in a similar way, using the TargetComponentIDRef attribute
of the association.
Content of Conceptual Layer Definitions
Business
Component
Business
Element
25 September 2009
ID
Technical identifier
Name
ISO 20022 name (e.g.PartyIdentification1)
EnhancedDefinition
The ISO 20022 description of the Business Component.
AdministrativeData
Details of ISO 20022 registration status
Synonym
Synonyms for equivalent concepts in other standards /
syntaxes, such as ISO 15022.
Abstract
True if this is an abstract definition (must have at least
one subclass).
ExtendedBy
References to subclasses.
Extends
Reference to superclasses.
TypeIDRef
Reference to the Business Component or Data Type that
types this Business Element.
ID
Technical identifier
Name
ISO 20022 name of the Business Element.
EnhancedDefinition
The ISO 20022 description of the Business Element
19
Standards Developer Kit 1.0
Business
Association
AdministrativeData
Details of ISO 20022 registration status
Multiplicity
The minimum and maximum number of times that this
element may appear in the containing Business
Component (minOccurs = 0 implies that this element is
optional)
BusinessRule
Details of any business rules that apply.
TargetComponentIDRef
Reference to the Business Component that this
component is associated with.
ID
Technical identifier
Name
ISO 20022 name of the Business Association.
EnhancedDefinition
The ISO 20022 description of the Business Association
AdministrativeData
Details of ISO 20022 registration status
Multiplicity
The minimum and maximum number of times that this
association may appear in the Business Component.
Linking the Conceptual and Logical Layers
As explained in the Background section, items in the logical layer are linked to items in the
conceptual layer, from which they derive their meaning.
Definitions in the logical layer that are not technical (that is, concerned only with messaging
requirements, such as page numbers), are linked to business definitions in the conceptual layer.
Message Components are linked to Business Components and Message Elements are linked to
Business Elements.
Links are made using the IsBasedOnIDRef attribute of items in the logical layer, which
references the ID of the corresponding item in the conceptual layer. For example, the following
XPath identifies the Business Component (SettlementInstruction) on which Message Component
SettlementInformation1 is based:
//BusinessComponent[@ID=//MessageComponent[Name='SettlementInformation1'
]/@IsBasedOnIDRef]
In some cases, no textual definition of a Message Component is included in the logical layer; in
these instances the definition should be taken from the referenced Business Component. Where
a definition does exist, it should be understood to be a semantic refinement of the information in
the business layer and interpreted accordingly; it does not override or replace the business
definition.
Uses for the MX Repository
The MX Repository contains complete information for ISO 20022 logical message definitions and
the ISO 20022 business model in a processable form. It can be used in a number of standards
implementation scenarios, for example:
2.2
•
Source for generated or customised documentation
•
Source for generated GUI definitions
•
For ad hoc reports – for example, extract all Code Data Types (with details) for messages
from a given business area (see Appendix B2)
MX Enriched Schemas
Introduction
Audience/Skills: XML, XML Schema
Standard ISO 20022 XML schemas are designed to define and validate messages at a syntactic
level; they contain little of the semantic information that allows a message to be understood.
However, many modern schema-aware development tools include schema visualisation features
20
User Guide
MX Rresources
that make schemas a natural vehicle for simultaneously conveying structural, syntactic and
semantic definitions. MX Enriched Schemas add semantic definitions sourced directly from the
ISO 20022 repository to standards schemas to create a useful, processable reference for ISO
20022 messages.
The illustration shows part of the enriched MX enriched schemas for message
FItoFICustomerCrdeitTransferV02 (pacs.008.001.02), including the additional semantic
information that is included for element MsgId.
The semantic information is contained in XML Schema annotations, as shown in the schema
fragment below:
Annotation source ‘Name’ contains the full ISO 20022 name of the element, and ‘Definition’
contains the enhanced definition. Annotations are also included to describe code values defined
in simple types (ISO 20022 Data Types), for example, data type
RemittanceLocationMethod2Code:
25 September 2009
21
Standards Developer Kit 1.0
Note
Identical information is provided in a different form in the MX Repository.
Uses for MX Enriched Schemas
MX Enriched Schemas can be used in conjunction with suitable tools to visualise and explore MX
message definitions. Also, because schemas are themselves processable XML documents, MX
enriched schemas can be used as the basis for generating useful artefacts such as GUI
definitions and user documentation.
2.3
MX Spreadsheets
Introduction
Audience/Skills: Business Analysis/Office automation products/Microsoft Excel
MX Spreadsheets are Comma Separated Values (CSV) files, which are compatible with MS
Excel and other office automation applications. Each file contains a fully expanded
representation of an MX message. The containment hierarchy of the message is indicated by
indented element names in the left-most columns of the file. For each element, additional
columns list: the XML tag name for easy cross-reference with the XML schema; the multiplicity;
the type; any rules that apply to the use of the element; its full definition from the ISO 20022
repository; details of changes from previous releases; and a full XML path reference which can
be used to extract data from a message instance. For data types that define code values, each
code is listed with its name and a full definition.
Example
The illustration below shows a fragment of the MX spreadsheet for message
FItoFICustomerCrditTransferV02 (pacs.008.001.02) viewed in Microsoft Excel 2007:
22
User Guide
MX Rresources
Uses for MX spreadsheets
Users are free to hide or delete elements or columns and add columns or annotations of their
own to create working analysis documents for their projects. It is also possible to import CSV
files, with or without user amendments, into a technical environment for the generation of useful
artefacts: meta-data definitions, documentation, and so on.
25 September 2009
23
Standards Developer Kit 1.0
Appendix A: MT/XML Schema Library samples
A.1
Sample Implementation of ISchemaDocResolver
(Java)
Note:
24
•
The constructer argument is the path to a directory of MT/XML schemas.
•
The name of the schema files in the directory should correspond to the namespace, plus the
‘.xsd’ file extension (this is the naming convention used in the library as supplied)
User Guide
Appendix A
A.2
MT Message Generation Using Apache XML
Beans (fragment)
Note
A.3
Apache XML Beans technology can be downloaded from
http://xmlbeans.apache.org/.
Generating an MT Message Using a Commodity
Mapping Tool
Note
25 September 2009
The tool shown in this example is Altova MapForce, which can read a Microsoft Excel
spreadsheet and populate an XML instance based on an XSD.
25
Standards Developer Kit 1.0
Appendix B: MX Repository Samples
B.1
Message Definition Query (XQuery)
Note:
26
•
Produces HTML output (could easily be modified to produce XML)
•
Function local:getElements()is called recursively to traverse the complete message
structure.
•
$msg should be set to the name of the message to be extracted (PaymentReturnV01 in the
example).
•
HTML output can be opened in Excel and saved as a spreadsheet (‘.XLS’ or ‘.XLSX’) file.
User Guide
Appendix B
B.2
Extract Code Data Types and Details of Code
Values for Messages in a Given Business Area
Note:
•
Produces HTML output (could easily be modified to produce XML)
•
Can be modified to report on all messages in the MX Repository by removing the following
from the main section:
25 September 2009
27
Standards Developer Kit 1.0
Appendix C: Acknowledgements, References and
Resources
C.1
Acknowledgements
Screenshots of schema visualisations created using XML Spy. Screenshot of mapping tool in
Appendix A3 shows MapForce. Both from Altova www.altova.com.
Screenshot illustration for MX Spreadsheets created using Microsoft Excel 2007.
www.microsoft.com.
Java is a registered trademark of Sun Microsystems www.sun.com.
C.2
References and Resources
ISO 20022; see www.iso20022.org
Extensible Markup Language (XML); see http://www.w3.org/XML/
XML Schema; see http://www.w3.org/XML/Schema
XQuery; see http://www.w3.org/XML/Query/ (for a good tutorial see
http://www.stylusstudio.com/xquery_flwor.html)
Java Architecture for XML Binding (JAXB); see
http://java.sun.com/developer/technicalArticles/WebServices/jaxb/
Java API for XML Processing (JAXP); see http://java.sun.com/
XML Beans; see http://xmlbeans.apache.org/
28
User Guide
Legal Notices
Legal Notices
Copyright
SWIFT © 2009. All rights reserved.
You may copy this publication within your organisation. Any such copy must include these legal notices.
Confidentiality
This publication may contain SWIFT or third-party confidential information. Do not disclose this publication outside
your organisation without the prior written consent of SWIFT.
Disclaimer
SWIFT supplies this publication for information purposes only. The information in this publication may change from
time to time. You must always refer to the latest available version on www.swift.com.
Translations
The English version of SWIFT documentation is the only official version.
Trademarks
SWIFT is the trade name of S.W.I.F.T. SCRL. The following are registered trademarks of SWIFT: SWIFT, the SWIFT
logo, Sibos, SWIFTNet, SWIFTReady, and Accord. Other product, service, or company names in this publication are
trade names, trademarks, or registered trademarks of their respective owners.
25 September 2009
29