[code lists] drafct of section to put in documentation - for comment

[Tim McGrath <tmcgrath@portcomm.com.au>]

The following is a draft for a new section to be icnluded in our documentation.
 It follows from comments at Friday's LC meeting where concern was expressed
that many of the issues essential to understanding the origins and use of
UBL codes lists were not defined in one place.  This draft is the starting
point for this consilidation.  Feel free to comment/amend/add/question as
you see fit.

"The primary objective of populating codes lists within the UBL Library is
to promote interoperability.  That is, by having known sets of values in
enumerated lists we allow information to be exchanged unambiguously.  We
recognise that other information may be useful for presenting or describing
these codes, but the most effective means of conveying this additional information
is yet to be established.   In UBL 1.0 we have concentrated solely on enabling
interoperability by populating enumerated lists.  

Strictly speaking a code is an abbreviation of  a value.  We recognize that
in some cases the values in our lists are not codes but a controlled vocabulary
of terms.   However, the same mechanisms can be used to support both.  This
mechanism is what we refer to as the UBL code list architecture.

UBL has identified and detailed four validation perspectives, termed "code
list definitions", for the values found in instance content of the type of
a given code list, summarized as:

• Standard:  These are mandatory codes that MUST be used to be UBL compliant.  The reason a code is defined as standard may be that it required for correct use of business transactions (e.g. status codes), promotes a single, internationally recognised code set (e.g. currency code) or enforces a restricted set of possible values (e.g. latitude code).
  UBL will supply codes that should be sufficient to all users of UBL.  The values used in instances should be validated against the supplied codes and   validating processors should correctly throw errors when invalid values are used.
  The implementation of standard codes is as a "stock" code without a "placebo" (see below).

• Placebo: These are code lists whose values SHOULD be agreed upon between trading partners. UBL SHALL NOT enforce any validation of the coded values in these code lists. These are implemented by using  the generic "normalized string" data type for these elements in which these coded values belong.  Applications working with the instances have the responsibility of validating any content found for these codes.

• Stock: These are UBL-supplied sets of candidate codes available to be used in place of "placebo" code lists.  Trading partners who agree to utilize the values supplied by  UBL MAY choose to replace the "placebo" lists with these "stock" lists.

• Private-Use: Trading partners SHOULD always have the ability to create and then utilize sets of codes of their own choosing. "Private-use" code lists MAY replace either "standard" code lists or "placebo" code lists. Trading partners MAY choose to implement validation of private code lists either in the schema expression or in their applications but MUST do so without impacting on any other code list used.
  

There are two sources of codes for UBL code list definitions.  The first is when the code list is created by an outside agency or organization (e.g. the UNCL TRED codes) and is available without fees or incumberances. The second is when no royalty-free external code list is available and UBL has created its own codes (e.g. OrderRejectionReasonCode).  We envisage and encourage external code agencies to establish and maintain their own code schemas for use with UBL.  However, in the first instance we accept that we will need to use localised UBL snapshots of the original codes, maintained by UBL.

Within the UBL schemas, an "in-use" directory is used to define each code list to be used during the validation process. Only values for standard definitions of code lists are validated for their content when UBL is run out-of-the-box. All other code lists are validated using the placebo definition merely as having a tokenized value, and this value is not checked against any further constraints.  Customised implementations can chose to adopt either stock or private-use code list definitions, and after any such engagement can revert to the out-of-the-box configuration by engaging the original standard or placebo code list definition.

UBL provides a catalogue of the code lists in the UBL Library.  This catalogue also describes other meta-data that may be of significance to users of the codes. "

-- 
regards
tim mcgrath
phone: +618 93352228  
postal: po box 1289   fremantle    western australia 6160