Re: [ubl-lcsc] [code lists] drafct of section to put in documentation - for comment

["CRAWFORD, Mark" <MCRAWFORD@lmi.org>]

Tim,

An excellent first cut. I think you need to clarify hat all codes will be handled by scheMa modules, regardless of their source so that the necessary enumerations and their subsequent maintenance will not impact the root schema. I think you should also add that as external code ist owners do make their code lists available in the form of importable schema modules, the corresponding import statements for those code list modules will be changed accordingly.
Mark Crawford
Research Fellow - LMI XML Lead
W3C Advisory Committee, OASIS, RosettaNet Representative
Vice Chair - OASIS UBL TC & Chair Naming and Design Rules Subcommittee
Chair - UN/CEFACT XML Syntax Working Group
Editor - UN/CEFACT Core Components
______
Logistics Management Institute
2000 Corporate Ridge, McLean, VA 22102-7805
(703) 917-7177   Fax (703) 917-7481 
Wireless (703) 655-4810
mcrawford@lmi.org
http://www.lmi.org
"Opportunity is what you make of it"


-----Original Message-----
From: Tim McGrath <tmcgrath@portcomm.com.au>
To: ubl-lcsc@lists.oasis-open.org <ubl-lcsc@lists.oasis-open.org>
Sent: Sat Oct 25 01:59:26 2003
Subject: [ubl-lcsc] [code lists] drafct of section to put in documentation - for comment

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