UBL 2.0 Code Lists and Two-phase Validation

Introduction

Code lists — the sets of codes such as “FR” and “USD” that are used to specify countries, currencies, and so on — play an important role in UBL, just as they do in all electronic business messaging schemes. By default, UBL uses several lists of standard codes published by agencies such as ISO and UN/CEFACT, as well as various codes that are specific to UBL.

To give users maximum flexibility in configuring and updating UBL code lists without changing the standard UBL schemas, UBL 2.0 assumes a two-phase validation model. In the first validation phase, the UBL instance is checked for structure and vocabulary against a standard UBL 2.0 XSD schema. In the second validation phase, new in UBL 2.0, code list values in the instance are checked against values obtained from external code list configuration files using an XSLT 1.0 processor driven by an XSLT 1.0 stylesheet. The default values assumed by the UBL 2.0 specification are incorporated into a file named defaultCodeList.xsl located in the val directory.

The separation of structural and vocabulary checking from code value checking allows trading partners to easily and precisely specify code list subsets and extensions and to apply them not just to individual UBL document types but also to particular elements and subtrees within UBL document instances. Another way to say this is that the the UBL code list methodology allows different versions of the same code list to be used in different document contexts. Thus, for example, a business in Canada might agree with a business in the United States to use a set of code list configuration files that allow the Buyer to be associated with either a U.S. state or a Canadian province but restrict the Seller to just U.S. states — that is, to apply a code list subset containing state and province codes in one place in a document instance and a different code list subset containing just state codes in another place in the instance.

The process for creating custom XSLT code list files to enable this context-specific functionality is described in a separate specification called the UBL Code List Value Validation Methodology, a copy of which can be obtained from the UBL TC web site at OASIS. A set of support files to aid implementers in creating custom XSLT code list files will be included in the UBL 2.0 Support Package from the same site.

It should be clear from the foregoing that the second phase of the default validation process can safely be omitted if it is considered unnecessary to check code list values. However, the reverse is not true. The second phase depends for correct operation on a prior check for structural validity, and therefore it will not give reliable results if run in the absence of the first (schema) validation phase.

Code List Documentation

While the defaultCodeList.xsl file is what actually drives the second validation phase where the code list values get checked, it doesn’t function well as documentation of those values. For listings of the default codes, it’s better to consult the separate code list files from which defaultCodeList.xsl was compiled.

These files, which can be found in the cl/gc directory, use an XML format called genericode that is specially designed to represent code lists. The version of genericode adopted for this release is an early draft that is now being worked on by another OASIS technical committee. While still unfinished, this version provides all of the functionality needed for UBL and is the one intended for use in the UBL 2.0 Code List Support Package.

See Also

Dycode.SimpleUBL | Dycode.SimpleUBL.Common

---