Code Sets

Abstract

We propose an approach for the modelling and generation of dynamic External Code Sets, also considering several alternative approaches.

Introduction

When we define a message, we want to be able to constrain some elements to have values from a set of codes. Sometimes we want a static Code Set – so that the message must always use a code from this fixed list. Other times we want it to be dynamic – so that the list can change after the design of the message.

Current practice has been

  • conceptual Code Sets are dynamic.
    They are updated without their name changing.
  • derived logical Code Sets to be either
    • static – fully defined in the eRepository as a subset of the conceptual, versioned by appending a number.
    • dynamic – declared in the eRepository as a subset of the conceptual, appended with the number “1”, as empty Code Sets.
      It’s generated as a string type without enumeration restriction.
      They are defined in an External Code Sets Excel spreadsheet.

The ISO 20022 Technical Support Group are considering ways to make these code sets more easily machine readable.

Proposal

Currently, dynamic external code sets:

  • are managed in an Excel Spreadsheet
  • are modelled as empty logical Code Sets
  • are generated into xml schema as strings without enumeration restrictions
  • can be schema validated by redefining the type in a header schema file.

Ideally, dynamic external code sets would:

  • be modelled as both complete conceptual and derived logical Code Sets in an iso20022 repository;
  • with a semantic attribute to distinguish dynamic and static Code Sets, as their codes are updateable and so their generation is different.
    (Perhaps add a zero to their name to indicate they’re unversioned.)

One approach which would keep existing messages xml schema files unchanged, uses the redefine mechanism. Generate redefine schema files containing the latest relevant code lists for each message, which include the message schema. Redefine files are required for each message as their namespaces are distinct.

Another approach is to include seperate schema files for external code sets, either directly into the message schema file; or into a configuration schema file which includes both the external code sets and message schema files.

The compromise is to model Message Elements as referencing conceptual Code Sets, to be generated as unenumurated string data types in message schema, possibly with a pattern facet. Logical code sets types derived from the the conceptual can thus be generated into both code set definition and redefinition schema files. This then allows users to use type substitution or to redefine the schema to use specific logical Code Sets.

The next steps are

  • to model the dynamic External Code Sets in an external iso20022 repository file
  • generate code list schema file for the external code sets.
  • generate redefine schema files for registered messages,
    to make it easier for people to use the registered code sets.
  • generate other relevant documentation formats such as xlsx, csv, html, and others.

Design Implications

Message designers would have a choice of selecting whether to use:

  • a specific version – reference a specific static logical code set
  • the latest version – reference the dynamic logical code set
  • any version – reference the conceptual code set,
    which is substituted by one of the logical code sets.

Logical Code Sets would be derived from the Conceptual Code Set Type, so that type substitution can be used to select a specific version.
In xml with schema this is acheived using xsi:type substitution:

<MyElement xsi:type="MySubType">MyData<MyElement>

XML Schema generation would produce, for references to :

  • a specific version – the message element references an enumerated simpleType in the message schema.
  • the latest version – the message element references an enumerated simpleType in code set schema, included into the message schema.
  • any version – the message element references an unenumerated complexType for the conceptual Code Set in code set schema, whis is included into the message schema. Enumerated complexTypes for the logical Code Sets are based on an unenumerated type for the conceptual Code Set to enable type substitution.

Alternatives

Alternatively, external code sets could be referenced from Message Elements as:

  • Conceptual Code Set (as in practice they are dynamic)
    • External Code Sets modelled as per existing Internal Code Sets
      (unversioned conceptual code set changes over time,
      whereas versioned logical code set unchanging.)
    • Message instances may declare which static code set was used.
    • Message schema reference a CodeSet schema,
      which is edited by users to include only their supported versions.
    • XML Schema generation would produce message schema files as now, plus include a code set schema file (chameleon), which may be edited by users to include only supported the logical code sets.
    • Conceptual Code Sets
      generated as an abstract complex type based on string,
      perhaps with a pattern.
    • Logical Code Sets
      generated as an concrete complex type based on conceptual code set,
      restricted by enumeration.
    • Other Code Sets remain generated as simple types.
  • External Schema
    • External Code Sets in modelled in external iso20022 repository.
    • Generation into xml schema as elements
      in identification scheme namespace
      either null content (code token only),
      or internationalised enumerations (for supported languages).
  • Text
    • Validation is performed programmatically.
    • External Code Sets in modelled in external iso20022 repository.
    • Generation of various file formats such csv, gcl.xml, xsd, json, etc.
  • Identifier Set
    • As for text, and has Identification Scheme property metadata
      which allows automated linking to the relevant code set.

Illustrations

These code snippets provide simplifies illustrations.

Code Set Repository

Code Sets are modelled in the repository containing a complete list of codes with their codeNames, names, definitions, and (more not shown). 

<iso20022:Repository xmlns:iso20022="urn:iso:std:iso:20022:2013:ecore">
  <dataDictionary>
    <topLevelDictionaryEntry 
      xsi:type="iso20022:CodeSet" 
      name="ExternalAccountIdentification1Code" definition="Specifies the external account identification scheme name code in the format of character string with a maximum length of 4 characters." 
      registrationStatus="Registered" minLength="1" maxLength="4" >
      <code codeName="UPIC" name="UPICIdentifier" 
        definition="Universal Payment Identification Code (UPIC)" />
      <code codeName="CUID" name="CHIPSUniversalIdentifier" 
        definition="CHIPS Universal Identification (UID)." />
      <code codeName="BBAN" name="BBANIdentifier" 
        definition="Basic Bank Account Number" />
      <code codeName="AIIN" name="IssuerIdentificationNumber" 
        definition="Issuer Identification Number (IIN)" />
    </topLevelDictionaryEntry>
  </dataDictionary>
</iso20022:Repository>

Code Set Schema

XML Schema generation turns these into simpleTypes based on string, listing all the enumeration values. 

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
	<xs:simpleType name="ExternalAccountIdentification1Code">
		<xs:restriction base="xs:string">
			<xs:enumeration value="AIIN"/>
			<xs:enumeration value="BBAN"/>
			<xs:enumeration value="CUID"/>
			<xs:enumeration value="UPIC"/>
		</xs:restriction>
	</xs:simpleType>
</xs:schema>

When the Code Set has no codes, enumeration values aren’t generated and so aren’t validated. This quirk is currently used to declare an external code set, but leave the values undefined in the message schema.

Redefine Message Schema

To use schema validation to check codes, redefine the types from the message schema.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08" targetNamespace="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08" elementFormDefault="qualified" attributeFormDefault="unqualified" >
 <xs:redefine schemaLocation="pacs.008.001.08.xsd">
  <xs:simpleType name="ExternalAccountIdentification1Code">
   <xs:restriction base="ExternalAccountIdentification1Code">
    <xs:enumeration value="AIIN"/>
    <xs:enumeration value="BBAN"/>
    <xs:enumeration value="CUID"/>
    <xs:enumeration value="UPIC"/>
   </xs:restriction>
  </xs:simpleType>
 </xs:redefine>
</xs:schema>

It would be possible to generate redefine message schema, when their external code sets are updated.

Alternatives

There are several alternative ways to implement dynamic Code Sets
in XML Schema, aside from programmatically validating each code.

SimpleCodeSet.1.xml

This example shows alternatives in a single XML.

  • simple-type – uses enumeration restrictions on a simpleType
  • concrete-complex-type – uses enumeration restrictions on a complexType based on an abstract complexType.
  • abstract-complex-type – as above, requiring declaration of which concrete complex type is used.
  • external-schema – use of simpleType declared in a separate file.
  • external-namespace-schema – codes are represented as elements
    • me:value4 is empty
    • me:value5 has a fixed value
    • me:value6 has a range of allowed values – one for each language,
      showing how presentation strings could be encoded.
<document 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:noNamespaceSchemaLocation="SimpleCodeSet.1.xsd" 
 xmlns:me="my:external:namespace">
 <simple-type>value1</simple-type>
 <concrete-complex-type>value2</concrete-complex-type>
 <abstract-complex-type xsi:type="my-enum-concrete">value2</abstract-complex-type>
 <external-schema>value3</external-schema>
 <external-namespace-schema><me:value4/></external-namespace-schema>
 <external-namespace-schema><me:value5>My Value 5</me:value5></external-namespace-schema>
 <external-namespace-schema><me:value6>我的价值6</me:value6></external-namespace-schema>
</document>

SimpleCodeSet.1.xsd

This files shows how enumerations can be defined locally,
included from a chameleon schema (no namespace),
or imported from a matching namespace schema.
XSD 1.1 is used simply to permit multiple elements to appear in any order.

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"  elementFormDefault="qualified" attributeFormDefault="unqualified" 
 vc:minVersion="1.1" xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" 
 xmlns:me="my:external:namespace">
 <xs:include schemaLocation="SimpleCodeSet1-external.xsd"/>
 <xs:import namespace="my:external:namespace" schemaLocation="SimpleCodeSet1-external-namespace.xsd"/>
 <xs:element name="document">
  <xs:complexType>
   <xs:all>
    <xs:element name="simple-type" type="my-enum-simple"/>
    <xs:element name="abstract-complex-type" type="my-enum-abstract"/>
    <xs:element name="concrete-complex-type" type="my-enum-concrete"/>
    <xs:element name="external-schema" type="my-external-enum-simple"/>
    <xs:element name="external-namespace-schema" type="my-external-namespace-enum" maxOccurs="unbounded"/>
   </xs:all>
  </xs:complexType>
 </xs:element>
 <xs:simpleType name="my-enum-simple">
  <xs:restriction base="xs:string">
   <xs:enumeration value="value1"/>
  </xs:restriction>
 </xs:simpleType>
 <xs:complexType name="my-enum-abstract" abstract="true">
  <xs:simpleContent>
   <xs:extension base="xs:string"/>
  </xs:simpleContent>
 </xs:complexType>
 <xs:complexType name="my-enum-concrete">
  <xs:simpleContent>
   <xs:restriction base="my-enum-abstract">
    <xs:enumeration value="value2"/>
   </xs:restriction>
  </xs:simpleContent>
 </xs:complexType>
 <xs:complexType name="my-external-namespace-enum">
  <xs:sequence>
   <xs:any namespace="my:external:namespace" processContents="strict"/>
  </xs:sequence>
 </xs:complexType>
</xs:schema>

SimpleCodeSet1-external.xsd

A chameleon schema without a target namespace is able to be included in other schema, taking on the target namespace of that schema.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
 <xs:simpleType name="my-external-enum-simple">
  <xs:restriction base="xs:string">
   <xs:enumeration value="value3"/>
  </xs:restriction>
 </xs:simpleType>
</xs:schema>

SimpleCodeSet1-external-namespace.xsd

An external namespace schema, where the target namespace would be the IdentificationScheme URI of the Code Set. This enable Codes to be represented by global elements, which may be empty, contain a fixed string, or presentation values for supported languages.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="my:external:namespace" targetNamespace="my:external:namespace" elementFormDefault="qualified" attributeFormDefault="unqualified">
 <xs:element name="value4" fixed=""/>
 <xs:element name="value5" fixed="My Value 5"/>
 <xs:element name="value6">
  <xs:simpleType>
   <xs:restriction base="xs:string">
    <xs:enumeration value="My Value 6" xml:lang="EN"/>
    <xs:enumeration value="Η αξία μου 6" xml:lang="EL"/>
    <xs:enumeration value="我的价值6" xml:lang="ZH"/>
   </xs:restriction>
  </xs:simpleType>
 </xs:element>
</xs:schema>