Standards
Usage Guideline Editor
For MyStandards
Best Practices
This document provides best practice recommendations for users of the MyStandards Usage Guideline Editor
defining their message usage guidelines.
20 June 2012
Usage Guideline Editor for MyStandards
Table of Contents
Table of Contents ...............................................................................................................................2
Preface .................................................................................................................................................3
1
Introduction ...............................................................................................................................4
2
Naming Conventions................................................................................................................5
2.1
2.2
2.3
3
Introduction .............................................................................................................................5
Collection Name ......................................................................................................................5
2.2.1 Examples ............................................................................................................................ 5
Usage Guidelines ....................................................................................................................6
2.3.1 Examples ............................................................................................................................ 6
Usage Guideline Editor Conventions .....................................................................................8
3.1
3.2
3.3
3.4
3.5
3.6
Introduction .............................................................................................................................8
Must not Be Used (Remove) ...................................................................................................8
Make Mandatory .....................................................................................................................9
Reduce Multiplicity ..................................................................................................................9
Ignore ....................................................................................................................................10
Rules (and Guidelines)..........................................................................................................10
3.6.1 Text Rule or Guideline ...................................................................................................... 11
3.6.2 Conditional Rule ............................................................................................................... 11
3.7 Fixed Value ...........................................................................................................................14
3.8 Comment ...............................................................................................................................15
3.9 Annotation .............................................................................................................................16
3.9.1 Example 1......................................................................................................................... 17
3.9.2 Example 2......................................................................................................................... 18
3.9.3 Example 3......................................................................................................................... 18
3.10 Change Datatype ..................................................................................................................19
3.10.1 Redefine a Text or Narrative Field as a Code List............................................................ 19
3.10.2 Redefine a Narrative Field as Structured Lines of Text (MT) ........................................... 20
3.11 Create Extension (MX Only) .................................................................................................21
3.11.1 Scenario 1: Fixed Value ................................................................................................... 21
3.11.2 Scenario 2: Fixed Value and Code List ............................................................................ 24
3.12 Synonyms .............................................................................................................................27
4
Collections and Usage Guidelines .......................................................................................28
Legal Notices ....................................................................................................................................29
2
Best Practices
Preface
Preface
Purpose of the document
This document provides best practice recommendations for users of the MyStandards Usage
Guideline Editor defining their message usage guidelines.
Audience
This document is for the following audience:
·
Users of the MyStandards Usage Guideline Editor
Significant changes
The following tables list all significant changes to the content of the MyStandards Best Practices
since the 27 April 2012 edition. These tables do not include editorial changes that SWIFT makes
to improve the usability and comprehension of the document.
New information
Location
New section on collections and usage
guidelines
4 Collections and Usage Guidelines
Updated information
Location
Changes to naming conventions for collections
and usage guidelines
2.2 Collection Name
2.3 Usage Guidelines
Related documentation
20 June 2012
·
MyStandards Service Description
·
MyStandards Best Practices
3
Usage Guideline Editor for MyStandards
1
Introduction
This document describes naming conventions and recommended approaches when specifying
restrictions on message fields.
It is important to have a convention when naming collections and guideline definitions so that
there is a level of consistency with names and to support the easy searching of guideline
definitions.
The driving principle behind having best practices is to push users to formalise as much as
possible. The more formal a usage guideline definition is, then the more semantic value it has
and so the more meaningful any automated or manual analysis can be.
This document is intended for those users that already have a good knowledge of the
MyStandards Usage Guideline Editor. It is not a user manual.
In most cases, the best practice principals used are the same or similar for both MT and MX.
Where illustrations are used, MX (XML) messages has been used.
4
Best Practices
Naming Conventions
2
Naming Conventions
2.1
Introduction
The naming conventions described below for collections and usage guidelines functionality are
valid, although practically, there may be variants.
2.2
Collection Name
A collection is a container of logical set of guideline definitions which the user must analyse and
manage.
The table below gives an overview of how to build up the collection name.
Parameter
Description
Example
1
Organisational Entity -
SMPG, NMPG, RMPG, CGI, PMPG
2
[Locale or initiative -]
Global, IT, GB, FR, Almus
3
Business area -
CA, TIC, SR, IF, Payments, FX, Derivatives, Commodities
Business process -
Events, Order & Confirmation, Block Trade, Order Status
& Confirmation, Transfers, Price Reporting, High Value
Payments
5
Version -
V1, V2, V3
6
Status_
DRAFT, FINAL, WIP
4
CA = Corporate Actions
TIC = Trade Initiation & Confirmation
SR = Settlement & Reconciliation
IF = Investment Funds
WIP = Work in progress
CGI = Common Global Implementation
Warning Optional parameters are indicated by square brackets [].
Versioning
MyStandards has its own convention for versioning and will apply Version 1 to the first time a
collection is uploaded, and increment the version number of subsequent uploads. This is a
technical version number and is distinct from the "true" version number of a collection. For
example, V1 of the IF-Orders, Status and Confirmations collection may have been updated
several times as several iterations of a "work-in-progress" version are posted. Thus Version 1 of
the IF Orders and Confirmations collection may have, for example, an internal MyStandards
version number of 5. Therefore, there is a need for a "business version number".
2.2.1
Examples
The spaces in the following example collection names are present for readability, they do not
have to be present in the actual collection name, it is up to the user.
SMPG
#
Collection Name
1
SMPG - Global - TIC - Order & Confirmation - V1 – FINAL_
2
SMPG - Global - SR Block Trades - V1 – FINAL_
3
SMPG - Global - CA - Events - V2 – DRAFT_
4
SMPG - Global - IF - Order Status & Confirmations - V1 – DRAFT_
NMPG
#
20 June 2012
Collection Name
5
Usage Guideline Editor for MyStandards
1
NMPG - FR - IF - Order & Confirmation - V1 – FINAL_
2
NMPG - DE - IF - Price Reporting - V1 – FINAL_
3
NMPG - DE - IF - Statements - V3 – DRAFT_
4
NMPG - US – TIC - Trade Initiation & Confirmation - V1 – DRAFT_
RMPG
#
Collection Name
1
RMPG – ALMUS - IF - Order & Confirmation - V1 – FINAL_
2
RMPG - AFAC - IF - Order & Confirmation - V1 – FINAL_
3
RMPG - FINDEL - IF - Order & Confirmation - V2 – FINAL_
4
RMPG - FINDEL - IF - Transfer - V1 – DRAFT_
5
RMPG - SHARP - IF - Order & Confirmation - V1 – FINAL_
#
Collection Name
1
CGI - Global - Payments -Corporate to Bank - V1 – FINAL_
CGI
PMPG
2.3
#
Collection Name
1
PMPG - Global - Payments -PACS High Value Payments - V1 – FINAL_
Usage Guidelines
A usage guideline represents a message definition which has been restricted by the user.
The table below gives an overview of how to build up the usage guideline name for the MX or
ISO 20022 XML messages:
Parameter
Description
Example
1
Message Name &
Identifier
Subscription Order_ setr.010.001.03
2
[ Additional optional
parameter - ]
Subscription Leg, Redemption Leg
The table below gives an overview of how to build up the usage guideline name for the MT:
Parameter
Description
Example
1
Message Identifier &
Message Name -
541_ Receive Against Payment
2
[For MT: SR year - ]
SR2011, SR2012
3
[ Additional optional
parameter - ]
Bonus Issue
Warning Optional parameters are indicated by square brackets [].
2.3.1
Examples
The spaces in the following examples of collection and usage guideline names are present for
readability, they do not have to be present in the actual collection name, it is up to the user.
6
Best Practices
Naming Conventions
SMPG
#
Usage Guideline Name
1
541_Receive Against Payment
2
502_Order To Buy Or Sell - SR2011 - Subscription Leg
3
Subscription Order_setr.010.001.03 - Institutional
4
Subscription Order_setr.010.001.03
#
Usage Guideline Name
1
Customer Credit Transfer Initiation_pain.001.001.03 - ACH Domestic & International
2
Customer Credit Transfer Initiation_pain.001.001.03 - Wires Domestic & International
3
Customer Credit Transfer Initiation _pain.001.001.03 - Cheques / Drafts
CGI
PMPG
#
Usage Guideline Name
1
FI To FI Customer Credit Transfer_pacs.008.001.02 - IG
2
Financial Institution Credit Transfer_pacs.008.001.02 - IG General
3
Financial Institution Credit Transfer_pacs.008.001.02 - IG Cover
Other, for example, commodities
#
Usage Guideline Name
1
600_Commodity Trade Confirmation
Note
20 June 2012
When a message is added to a collection, the name of the collection is automatically
appended in front of the message name. The collection name should be deleted from
the message name.
7
Usage Guideline Editor for MyStandards
3
Usage Guideline Editor Conventions
3.1
Introduction
The Usage Guideline Editor makes it very easy for a user to accurately and unambiguously
describe their specific usage of a message. It allows a user to easily apply additional restrictions
on top of the base message definition.
Note
A "restriction" is an additional limitation defined by the user on the base message
definition which an implementer would need to follow in order to be compliant with the
guideline. In some contexts the term "rule" would be used instead of "restriction".
The list below describes the different restriction types that may be applied:
#
Restriction Type
Description
1
Must not be used
(Remove)
An optional field or element must not be populated.
2
Make Mandatory
An optional field or element must be populated.
3
Reduce Multiplicity
A repeating field or element must repeat fewer times.
4
Ignore
A field or element could be populated but is ignored by the
receiver.
5
Text Rule
A mandatory, unstructured, rule.
6
Conditional Rule
A mandatory, if-then-else, rule.
7
Fixed Value
A field or element must contain a given value.
8
Comment
Information which cannot be expressed in a more
structured way.
9
Annotation
A user-defined structure if a built in restriction is
insufficient.
10
Change Datatype
A user-defined datatype replaces an existing simple
datatype.
11
Create Extension
A user-defined extension - MX specific.
12
Synonym
A field or element has another name.
The first four basic restriction types are very easy to set up in the message usage editor in an
unambiguous way.
The other more advanced restriction types, such as rules, comments and annotations require
more thought before their use. It’s possible to confuse their distinct functionality and the next
sections attempts to define when it is appropriate to use each kind of functionality.
3.2
Must not Be Used (Remove)
Indicating a field must not be used (removed), means that in order to be compliant with the userdefined guideline, a particular field must not be populated.
If the sender of a message does populate the "removed" field, then the message will not be
viewed as being compliant to the usage guideline. As a result, the receiver of the message may
stop any processing and end the business transaction.
Care must be taken when using this functionality since its implementation may be costly to the
sender, if the sender has already implemented the message. An alternative solution that
minimises the impact on a message already implemented by the sender is "Ignore" – in other
words, a field or element may be populated by the sender but it is ignored by the receiver.
8
Best Practices
Usage Guideline Editor Conventions
3.3
Make Mandatory
Making an optional field mandatory, means that in order to be compliant with the user-defined
guideline, a particular field must be populated.
If the sender of a message does not populate the "mandatory" field, then the message will not be
viewed as being compliant to the usage guideline. As a result, the receiver of the message may
stop any processing and end the business transaction.
3.4
Reduce Multiplicity
Some fields are defined in the base message as being repeatable. The user-defined guideline
could contain a restriction which reduces the amount of times a field can be repeated.
If the sender of a message repeats a field more times than is allowed in the usage guideline,
then the message will not be viewed as being compliant. As a result, the receiver of the message
may stop any processing and end the business transaction.
It is not possible to increase the multiplicity of a field or element.
20 June 2012
9
Usage Guideline Editor for MyStandards
3.5
Ignore
Indicating a field must be ignored, means that in order to be compliant with the user-defined
guideline, a particular field may or may not be populated.
If the sender of a message does populate the "ignored" field, then the message is still viewed as
being compliant to the usage guideline. However, the receiver of the message will not use the
data in any way. In other words, the data in the field will not influence either the processing or the
business transaction.
3.6
Rules (and Guidelines)
Over and above restrictions such as "must not use" (remove), "must be used", "use only once"
and "ignore", additional rules may be added to a field, which means that in order to be compliant
with the user-defined guideline, the rule must be followed.
If the sender of a message does not follow the additional rule on a field, then the message will
not be viewed as being compliant to the usage guideline. As a result, the receiver of the
message may stop any processing and end the business transaction.
10
1.
A rule should contain a single constraint. If more than one rule constraint is necessary on a
single field, these should be added in additional, separate rules.
2.
The rule should be given a meaningful name. It is sensible to differentiate message usage
rules or guidelines from the rules and guidelines actually present in the message standard.
Prefixing the rule name with something like "ITNMPG" will help with this differentiation. Each
rule should end in the word "Rule".
3.
If a text rule (see below) is to be considered a guideline rather than a rule, then the rule
name should end in the word "guideline".
4.
Where possible, it is recommended to use the "Conditional Rule" format, over the "Text
Rule" format as it increases interpretation clarity.
5.
A rule should not be added if it is already part of, or conflicts with, the base message
standard definition.
Best Practices
Usage Guideline Editor Conventions
6.
Do not use punctuation, spaces or underscore types of characters. Follow the camel case
convention. These restrictions are to allow for potential future functionality.
7.
The cross element rule checkbox should be used as necessary.
Differentiation between a Rule and a Guideline.
3.6.1
Type
Description
Guideline
Compliance is recommended and
so often contains the word "may".
Rule
Compliance is mandatory and so
contain the word "must".
Example
·
·
"The use of an ISIN is recommended."
"The field may be used to quote the
reference of the account opening
instruction."
·
"The field must contain the reference
of the account opening instruction."
Text Rule or Guideline
This is a simple usage rule which is described in a plain text paragraph. It will require the user to
interpret the rule carefully. So, it is recommended that the rule is concise and precise language is
used.
Example 1 – text rule
Example 2 – guideline
3.6.2
20 June 2012
Conditional Rule
1.
The rule is added to the first element (as referenced in <element>) of the conditional rule.
2.
It is recommended that the rule definition is empty. In most cases the "if-then-else" text
fields should be sufficient to describe the rule.
11
Usage Guideline Editor for MyStandards
3.
When referring to other fields in the rule, then the XML tag or field name must be used. In
some cases, it may be necessary to include some "path" information (see example below).
Path information may also be needed in those cases where the same element name is used
in different parts of the message.
4.
Recommended structures of the "if", "then" and "else" text boxes is: <element> <logic> [
<value> ]
-
<element> represents the element or field being referenced.
-
<logic> represents the operator
-
<value> optional value to which relates to the content in <element>
Example usage would be:
12
<element>
<logic>
<value>
If
Currency
is
equal
to
EUR
If
OrdrTp/ST
AF
is
presen
t
<element> <logic> <value>
Then
Amount must not contain
decimals
Then
StafClntBrkdwn/OrdrBrkdwnTp/
NSPN must be present
<element>
<logic>
<value>
Else
Amount
may
contain
decimals
Best Practices
Usage Guideline Editor Conventions
Example 1
20 June 2012
13
Usage Guideline Editor for MyStandards
Example 2
3.7
Fixed Value
Setting a fixed value for a field, means that in order to be compliant with the user-defined
guideline, a particular field, when present, must be populated with the specified fixed value.
If the sender of a message does not populate the field with the fixed value, then the message will
not be viewed as being compliant to the usage guideline. As a result, the receiver of the
message may stop any processing and end the business transaction.
A fixed value may only be used on fields containing simple types, for example, Max35Text or
Extended350Code. Examples of fixed field values are a user-defined code word, or a specific
currency code.
14
Best Practices
Usage Guideline Editor Conventions
The fixed value is entered in the "Fixed value" text field. If the fixed value is a code, then the
definition of the code should be specified in the associated comment box. Note that a separate
definition box for fixed value has been requested.
3.8
Comment
A comment can only be used to contain information which cannot be expressed using more
structured restriction types, like "make mandatory" or "must not be used". So, it should only be
populated if a more restrictive restriction type cannot be used. It is "for information only".
Don’t use a comment for the following:
20 June 2012
·
To redefine the semantic of a field.
·
To create a local language definition.
·
To redefine the base message standard definition.
·
To state the field is "recommended". If a field is recommended, this is better expressed as a
guideline, using the "Add rule" functionality.
·
To specify a fixed value. This is to be expressed using the Fixed Value box. However, the
comment box is used to give the definition of the fixed value when it is a code word, until the
Fixed Value has its own definition box.
15
Usage Guideline Editor for MyStandards
Example
3.9
Annotation
The built-in restriction types may not cover all the scenarios which a user may need to apply in
their usage guideline. The annotation mechanism allows the user to create a re-usable restriction
type to cover its particular requirement.
So, annotations should only be used when it is not possible to express the message usage
information through one of the "normal" mechanisms. For example, do not use an annotation to
define a rule or to or to express a fixed value.
Note
16
The MyStandards platform has no knowledge of the semantics of annotations – there
is no impact on the generated schema. An annotation appears in the generated
spreadsheet in the Annotation column.
Best Practices
Usage Guideline Editor Conventions
Annotations should be given meaningful names and definitions:
3.9.1
Example 1
The IT NMPG, for example, has the need to attach change request information to a field. An
annotation function can be defined for such usage:
20 June 2012
17
Usage Guideline Editor for MyStandards
3.9.2
Example 2
The IT NMPG, for example, has the need to redefine the semantic of an element for local use.
An annotation function can be defined for such usage:
3.9.3
Example 3
The IT NMPG, for example, has the need to include definitions in Italian:
18
Best Practices
Usage Guideline Editor Conventions
3.10
Change Datatype
Some fields are defined in the base message as being "simple data types", such as text, a
number, a date. The user may choose to redefine a field's simple datatype to a more restrictive
existing datatype, which is already available in the repository, or to use a newly created datatype.
It is recommended to re-use existing datatypes.
3.10.1
Redefine a Text or Narrative Field as a Code List
A user may redefine a text field as a code list, to enable a more formal way of specifying that, for
example, "this field may contain the values SPEC and XPEC".
This involves two steps, first, the setting up of the new code list and, secondly, redefining the
type of the relevant field to use the new code list.
When setting up the new code list, care must be taken to give the code list datatype a meaningful
name:
A definition at this level is probably not necessary.
20 June 2012
19
Usage Guideline Editor for MyStandards
The individual codes must be entered, and each code must be given a code word and a
definition:
3.10.2
Redefine a Narrative Field as Structured Lines of Text (MT)
A user may redefine a narrative field, for example, 6 * 35x, so that it is more structured.
This involves two or three steps, depending on the requirements. First, the new complex type is
set up. And second, the relevant field is typed by the new complex type. When setting up the
new complex datatype, care must be taken to make sure it and all its subfields have relevant
names and, if necessary, meaningful definitions. And for the subfields, multiplicity must be set to
override the default multiplicity proposed by the usage guideline editor. In turn, each of the
subfields can each have their own datatype.
Example
In this scenario, in a usage guideline for the MT 502, field 70E (10*35X) TPRO in sequence B
ORDRDET, is re-defined in the following way:
Original definition in MT
New definition
Data Type
10 * 35x
20
Line 1
Subfield 1
Code list with values
NEAM and GRAM and
GRPE
Line 2
Subfield 2
3!a – currency code
Line 3
Subfield 3
15d
Best Practices
Usage Guideline Editor Conventions
3.11
Create Extension (MX Only)
Because the investment funds order messages have not been maintained for some considerable
time, many markets have defined the use of the Extension sequence for additional functionality,
pending the maintenance.
Extension sequence
3.11.1
Scenario 1: Fixed Value
There is a requirement to be able to optionally specify an SLA Reference in the Charge Details
sequence of a message. The NMPG has agreed that this should be specified in an Extension
sequence.
An iteration of an Extension sequence is inserted in the Charge Details sequence. Following the
addition of a new Extension sequence, give it a meaningful name and definition:
20 June 2012
21
Usage Guideline Editor for MyStandards
For each of the elements of the Extension sequence, you need to define the contents (1):
22
Best Practices
Usage Guideline Editor Conventions
For each of the elements of the Extension sequence, you need to define the contents (2):
20 June 2012
23
Usage Guideline Editor for MyStandards
3.11.2
Scenario 2: Fixed Value and Code List
There is a requirement to be able to optionally specify information about "order sequencing" in
the message. The order sequencing can be either FIST (first) or FIILW (additional order).
The NMPG has agreed that this should be specified in an Extension sequence.
An iteration of an Extension sequence is inserted in the Individual Order Details sequence.
Following the addition of a new Extension sequence, give it a meaningful name and definition:
24
Best Practices
Usage Guideline Editor Conventions
For each of the elements of the Extension sequence, you need to define the contents (1):
20 June 2012
25
Usage Guideline Editor for MyStandards
The first element will be defined with "Fixed value" and this will be the XML path. A comment for
the fixed value is entered.
For each of the elements of the Extension sequence, you need to define the contents (2):
26
Best Practices
Usage Guideline Editor Conventions
In this example, the second element (Text: Max350Text) can be one of two codes and therefore
a code list has been created and the element Text has been typed by it (See Redefine a Text or
Narrative Field as a Code List).
3.12
Synonyms
Every field in a base message has a specific name with associated meaning. A user-defined
guideline may link another name, from a different context, to the given field.
Examples:
20 June 2012
·
A back-office system may use another, proprietary, format. This proprietary format also has
fields which match fields in the base message. A synonym can then be used to link the base
message field to the proprietary format field.
·
A non-English speaking country may want to use the base message, however the fact that
all base messages are in English means adoption is hampered. A synonym can then be
used to link the base message field to the translation of that field which should ease
adoption.
27
Usage Guideline Editor for MyStandards
4
Collections and Usage Guidelines
A collection is a container of logical set of guideline definitions which the user must analyse and
manage.
Typically, a "collection" will be for a specific business process and contain usage guidelines for
messages that support the business process.
Example
There will be cases where a collection contains a single message. Publishers of usage
guidelines, market practices, implementation guidelines, etc., on MyStandards should try to
organise their work so that it’s published as a logical collection.
28
Best Practices
Legal Notices
Legal Notices
Copyright
SWIFT © 2012. All rights reserved.
You may copy this publication within your organisation. Any such copy must include these legal notices.
Confidentiality
This publication contains SWIFT or third-party confidential information. Do not disclose this publication outside your
organisation without the prior written consent of SWIFT.
Disclaimer
The information in this publication may change from time to time. You must always refer to the latest available
version on www.swift.com.
SWIFT Standards Intellectual Property Rights (IPR) Policy - End-User License Agreement
SWIFT Standards are licensed subject to the terms and conditions of the SWIFT Standards IPR Policy - End-User
License Agreement, available at www.swift.com > About SWIFT > Legal > SWIFT Standards IPR Policy.
Translations
The English version of SWIFT documentation is the only official and binding 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, the Standards Forum logo, 3SKey, Innotribe, 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.
20 June 2012
29