Re: [ubl-lcsc] Code Lists Redux

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

At 2003-07-31 07:31 +0100, Anthony B. Coates wrote:
>I want to
>float the idea of adding unique identifiers to each UBL <appinfo> element.
>This would make it possible for external definitions to be keyed to the UBL
>Schemas, which would allow local communities to keep the FPSC-style 
>information
>that they need as relevant and up-to-date as required
>
>Now, if people agree that such identifiers would be useful, the obvious
>question would be whether all FPSC definitions should be external and keyed to
>these unique identifiers, since it would provide a good example to all and
>sundry of how to make it work.
>
>How does that sound as an idea?

Very worthy of consideration, and I will bring this up to the joint meeting 
this morning.  If accepted, it would modify the text (attached below) that 
I sent to Lisa earlier this week.

One hesitation that comes to mind is that up until now we have only 
identified the mandatory and requested information items abstractly, 
without dictating any mechanism by which either of these information items 
are expressed.  We would ask the maintenance authority to meet the abstract 
requirements and document for us the concrete implementation of those 
requirements.

Without changing anything until accepted by all, perhaps the way to fit 
Tony's suggestion is with either an abstract or concrete requirement:

(1) - every enumerated item include a unique identifier and the maintenance 
authority tells us where the unique identifier is

(2) - a required attribute from a UBL namespace is dictated to be added to 
<xs:annotation> (since foreign namespace attributes are allowed).

But ... while writing this ... I ask myself "isn't there already a unique 
identifier in the enumerated value itself?".  I'm now thinking that we 
don't have to add anything at all, because the enumerated values themselves 
satisfy the uniqueness requirement you were looking for.

I think what remains is the question of policy and procedure in UBL 
regarding code lists from outside authorities: where an authority has 
published a code list schema fragment meeting the UBL requirements but 
missing information required by a UBL subcommittee, the subcommittee is 
allowed to create a supplemental information file, keyed by the unique 
enumerated values, in which the missing information can be found.

Such a policy would allow UBL to "add" information to an existing code list 
without physically modifying the code list schema fragment obtained from 
the outside authority.

Being within the UBL purview, we could even come up with a standardized 
vocabulary for such code list adjuncts and ask our committees to always use 
the UBL code list adjunct vocabulary when creating supplemental information 
that an outside authority chooses not to maintain.  Each adjunct would be 
keyed to the enumeration through the uniqueness of the enumerated value.

Hmmmmmm ... what happens, though, when "old" enumerations get reused (as 
was mentioned earlier this week ... apparently one of the old country codes 
(for Czechoslovakia?) is now being reused for a new country)?

I'm curious what you and others think of how we can accommodate your 
suggestion, Tony.

Thanks!

........................ Ken


==============8<-----------------

UBL code list guidelines - 20030729-1010

Code lists express in enumerated lists a selection of codes and their 
associated canonical names.  For XML validation purposes, these enumerated 
lists are expressed in W3C Schema syntax as a set of values restricting all 
possible token values allowed in a simple type as follows:

<xs:simpleType name="NameOfTypeHere">
   <xs:restriction base="xs:token">
     <xs:enumeration value="VAL1"/>
     <xs:enumeration value="VAL2"/>
     <xs:enumeration value="VAL3"/>
     . . .
   </xs:restriction>
</xs:simpleType>

Nothing more need be added from a W3C Schema validation perspective and 
instances of UBL documents can be validated when using the above expression 
of all the permitted values.

In XML syntax the parallel facility would be an enumerated attribute list:

   <!ATTLIST elementName attributeName ( VAL1 | VAL2 | VAL3 ) #IMPLIED>

The W3C Schema expression vocabulary 
http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/ provides for the 
annotation of any construct with two kinds of information:  user 
information targeted for a human reader (an xml:lang= attribute is modeled 
in order to identify the language in which this human-targeted information 
is captured) in <xs:documentation> (optionally with an xml:lang attribute 
indicating the language of the user information), and application 
information targeted for a processor of some kind in 
<xs:appinfo>.  According to 3.13.1: "Annotations do not participate in 
validation as such. Provided an annotation itself satisfies all relevant 
Schema Component Constraints it cannot affect the validation of element 
information items."

In the interest of good maintenance practices, the centralizing of all 
related information in a single area promotes ease of locating and 
upkeep.  Given the only way W3C Schema syntax can be used for enumerated 
value validation is through enumeration declaration in restrictions, this 
would lead to associated information being maintained as annotations of the 
individual enumerated value element declarations.

The document model for both the <xsl:documentation> and <xs:appinfo> allows 
any elements whatsoever, and common practice typically in a namespace and 
structure governed by the owners or maintainers of the schema 
fragment.  These guidelines address the nature of the information to be 
captured in annotations, without attempting to dictate the vocabulary with 
which this is accomplished.

Enumerated codes in UBL code lists shall have a canonical name for the code 
expressed in <xs:appinfo>.  This is sometimes considered a short 
description for the code.  The canonical name must be distinguished from 
any possible variants that might also be captured for use by applications 
and processes.  Without an explicit distinction, the first name in the 
collection of names shall be assumed to be the canonical name.  Note that 
while variants may be language based, they need not be, such as the image 
of a country's flag or a numeric or mnemonic value.

Enumerated codes in UBL code lists should have a definition for the code 
expressed in one or more <xs:documentation> elements.  This is sometimes 
considered a long description for the code.  The canonical definition must 
be distinguished from any possible variant definitions that might also be 
captured for use by human readers.  Without an explicit distinction, the 
first <xs:documentation> element shall be assumed to be the canonical name.

Creators and maintainers of code lists to be used in UBL instances must 
document the structure and identification of definitions and names and 
their variants, including in particular, the distinction of the canonical 
value.



--
Upcoming hands-on courses: in-house corporate training available;
North America public:                     XSLT/XPath Aug 12, 2003

G. Ken Holman                mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.         http://www.CraneSoftwrights.com/o/
Box 266, Kars, Ontario CANADA K0A-2E0   +1(613)489-0999 (F:-0995)
ISBN 0-13-065196-6                      Definitive XSLT and XPath
ISBN 0-13-140374-5                              Definitive XSL-FO
ISBN 1-894049-08-X  Practical Transformation Using XSLT and XPath
ISBN 1-894049-11-X              Practical Formatting Using XSL-FO
Member of the XML Guild of Practitioners:    http://XMLGuild.info
Male Breast Cancer Awareness http://www.CraneSoftwrights.com/o/bc