Quality Standards

Quality Standards MUST be comprehensible, implementable, and reusable.

To help standards authors deliver improved quality, we present this guide.

This document outlines practices and provides a checklist for standards.
It is recognised that the standards we produce are widely used to provide international interoperability of financial services. In particular, careful attention is to be paid to internationalisation to ensure that even when translated into local languages the standard can produce the same results.

Terms and Definitions

For Technical Committees whose working language is English,
we recommend spelling using the British dialect,
with reference to the Oxford English Dictionary as principle source.

Standards must define any terms used in a section Terms and Definitions where not already defined in the dictionary, or reference the sources of terms. Terms in section 3 of ISO standards are published via the ISO terminological databases, allowing reuse of the terms by others.

If a Term is defined differently to a term already in the database,
a Note MUST explain the difference. The purpose of this is to build the terminological database, so that it can be reused in relevant contexts.

There are several important reasons to ensure terms are well defined in this section:

  • They are published via terminology databases.
  • Well defined terms help with translation into other languages.
  • They have a universal reference using IETF RFC 5141 ISO URN.
  • They are used to define records for the exchange and storage of information.

In English, term names should be listed as in a dictionary – in sentence case, not title case.
eg. Proper nouns have capital first letter. Abbreviations and acronyms as commonly represented – some are all capitals with interleaved periods, some are lowercase shortened with apostrophes.

As per ISO guidance, the definition of a term should be able to replace the term in it use in a sentence. This aids understand of the reader by being able to put the term in context.

Further explanation of the term appears in Notes sub-sections. Examples may also be provided.

Note

Legislation, regulations and contracts define the terms they use, usually near the start. Although standards are none of these, they are often referenced by these, and so the terms we define may become important and widely used. It is important to be clear about what we mean and don’t mean by the term, including whether we are being purposely ambiguous to allow further interpretation within the users context.

ISO Standards

It is good practice to use the guidance provided by standards bodies.
ISO requires each of it’s standards to comprise at least:

  1. Scope – specifying the topics covered.
  2. Normative References – of documents which specify rules used here.
  3. Terms and Definitions – used here, and referenceable by others.

ISO Directives part 2, chapter 16 Terms and Definitions requires that:
“Terminological entries shall be drafted in accordance with ISO 10241-1.”
This in turn requires:

  1. ISO 639 (all parts), Codes for the representation of names of languages
  2. ISO 704, Terminology work — Principles and methods
  3. ISO 860, Terminology work — Harmonization of concepts and terms
  4. ISO 3166 (all parts), Codes for the representation of names of countries and their subdivisions
  5. ISO 12199, Alphabetical ordering of multilingual terminological and lexicographical data represented in the Latin alphabet
  6. ISO 15924, Information and documentation — Codes for the representation of names of scripts

ISO 704:2009 0.2 says documents must “clarify relations among concepts by representing them formally or graphically.”

Defining Records

Where a standard defines flat and hierarchical records comprising terms, it MUST list a table of the terms showing:

Data Element names a defined term or dictionary word.

Range of values names a defined term or dictionary word,
which is a set of values whose elements cover the possible values of the Data Element.
Data type example is an illustration of how the range may be implemented,
and is informative, not normative.

Group is another term to which this term is related, usually as part of the Group.
If no Group is specified, the term is directly related to the whole record.

Occurrence is the number of times a term may occur within each Group.
Whether something is conditionally mandatory is a constraint, not an occurrence.

Constraints on the record should be listed in individual clauses, which allows them to be referenced. Constraints may be grouped by using subheadings. Constraints may further restrict the value space named in the range.

Where the records are graphs, diagrams may also be used to illustrate both record structure, and instances of record structure. These diagrams MUST be described in clauses to enable translation and for use by the visually impaired.

Example

GroupOccurrence
in Group		Data ElementRange of valuesData type exampleConstraints
 1..*Whole Term   
Whole Term0..2Part TermTextISO106464.1.1 4.1.2
Example table showing how a pair of Part Terms may appear in a Whole Term.
The Part Term is constrained Text, for example ISO10646.

4.1.1 Part Term is printable.

The characters in Part Term must be printable. Permitted white space includes space and line breaks only.

4.1.2 Part Term occurs in pairs.

Whole Term has either a pair of part terms, or none at all.

Implementing the standard

The purpose of this is to ensure that standards can be implemented.

For example, ISO20022, the Universal Financial Industry Message Scheme requires this information to specify Business Components and Message Components. This is turn is used by financial market infrastructure to define interfaces.

Diagrams

There are several instances in some standards where diagrams are not readable, either because too much information is being squeezed into an A4 size diagram, or because the image was too low resolution when scaled up to an A4 size diagram.

Diagrams MUST be SVG or PNG. We prefer PNG with embedded SVG. PNG with another embedded diagramming or modelling language is another good option.

Diagrams MUST be oversized when submitted to ensure reproductive quality.

Diagrams MUST  be readable when printed on A4 paper.

Diagrams MUST also be described in words to aid translation and the visually impaired.

Connecting lines should be thick enough to be viewable on low resolution or smaller displays.

If colour is used, it MUST be distinguishable if converted to greyscale.

Lines and colour blocks should also be distinguished by style, pattern and/or shading.

Visually impaired includes people without any sight, effectively blind and colour blind.

Checklist

  • Diagrams
    • Readable and clear within an A4 page
    • Overscanned – when page enlarged to A3, diagram is not pixellated.
    • Connecting lines and border are thick enough to be easily seen.
    • is understandable in black and white, or at very least grey scale.
    • Different coloured blocked have different shades and patterns.
    • Different coloured lines have different styles and patterns.
    • appear in their own clause with title,
      and/or have a title which is indexed in list of figures.
    • Have descriptive text in an associated clause, to enable referencing of the diagram and text together and/or separately.
  • Terms
    • Any word appearing in the standard is a dictionary word with same meaning,  or is well defined in 3. Terms and Definitions.
    • The definition of a term could replace its use in a sentence in context and make sense.
    • Note and Examples may be provide further explanation.
    • Source of term definition should be referenced, unless it’s the original contribution of the working group. These should appear in references.
  • Terms in English
    • Terms names are in sentence case, not title case.
    • If Acronyms and Abbreviations are listed as terms,
      then their expansion as listed another term.
      This enables translation into other languages which may also use distinctive abbreviations and expanded terms. Eg. USA à ΗΠΑ in Greek.
  • Records
    • A value space and its representation should be distinguished.
      eg. UUID is a 128 bit number, which can be represented as hexadecimal.
    • Data Elements in a record must be defined in clauses in 3. Terms and Definitions, even when they appear to be common dictionary terms.
      This is to enable referencing of the terms that make up the record.
    • Are the records flat, hierarchical, relational or graphs ?
      Have you explained why ?
    • Which data elements are language independent ?
    • Which data elements are language dependent ?
    • Which data elements require grouping by language ?
      Data elements require language grouping,
      only if they are dependent on eachother being in the same language
      (such as name in local language and it’s transliteration);
      otherwise they can be translated independently of eachother.
    • Is the data type for example text set to ISO10646 Unicode,
      to support languages internationally. It is a character set containing all known human scripts, even emoji.
    • Have you constrained text to printable characters and whitespace ?
    • Have you constrained text to natural human languages ?

Further Work

The terms used in this initial draft are to be replaced by the terms and reference from the standards pertaining to data definition and management. If there’s more than one, explain the reason for selection.