Codelist usability issues - ease and performance design

["David RR Webber \(XML\)" <david@drrw.info>]

Developing a universal mechanism is definately a holy grail that many
have sought. 
  
With this comes some significant responsibilities however! 
  
I'd like to share some of my own thoughts on all this - and experience
from working on XML and codelists in the past.  
  
These are just touch points that I feel strongly about / success metrics
that I would look for. 
  
Hope this is helpful as you embark on this important work, 
  
Thanks, DW 
==================================================== 
  
1) The mechanism should not be a burden on the community of users to
create, support and maintain 
  
2) It should be optimized to provide high performance metrics since
codelists are scanned and 
    processed repeatedly. 
  
3) Minimal XML knowledge / tools needed to comprehend / process codelist
mechanisms. 
  
Here are some guidelines I suggest to further this. 
  
a) Avoid use of namespaces or other extended markup features whereever
possible - simple well-formed XML is preferred. 
  
b) Avoid excessive angle bracket / element nesting - instead attributes
provide faster access to content (this may only be milliseconds - but
they add up when you are doing this 1,000's of times each day / hour in
your systems. 
  
c) Human readability - this is actually helped by b) 
  
d) Have separate optional sections for logical parts of the content - so
the processing codes themselves are not mixed up with human readable
descriptions, documentation and such.  Provide means to make these
externally referenced to encourage use of registry services instead of
a single "kitchen sink" XML approach. 
  
e) Make extensible types, attributes and such so as to avoid necessity
to "police" codelist implementations / create an Uber-codelist
authority - fosters rapid broad adoption and direct ownership by
communities of practice. 
  
Example: 
  
Good -  
         <codelist version="1.20" date="06/06/06T00:00:00"
refID="123456" 
          name="Example CodeList - Currency"> 
          <code value="1" short="dollars" symbol="$"/> 
          <code value="2" short="euros" symbol="E"/> 
          <documentation> 
              <item refvalue="1">Here is a good example</item> 
              <item refvalue="2" url="http://wikipedia.org#euro";>See
wikipedia for details on euros</item> 
          </documentation> 
        </codelist> 
  
Bad -   
        <code:codelist
xmlns:code="http://oasis-open.org/committee/foobar/schemas/more/lists.url";

          version="1.20" 
          date="06/06/06T00:00:00" 
          refID="123456"> 
          <code:Hdr> 
              <code:title> 
                 <code:text>Example Codelist - Currency</text> 
              </code:title> 
          </code:Hdr> 
          <ent:code
xmlns:ent="http://oasis-open.org/committee/foobar/schemas/more/reference.url";>

            <annotation> 
               <documentation>Here is a bad example</documentation> 
           </annotation> 
            <typing> 
              <type>string</type> 
            </typing> 
            <usage> 
               <use>all</use> 
            </usage> 
            <values> 
              <item> 
               <value>1</value> 
               <shortdescription>dollars</shortdescription> 
               <symbol>$</symbol> 
              </item> 
            </values> 
         </ent:code> 
<ent:code
xmlns:ent="http://oasis-open.org/committee/foobar/schemas/more/reference.url";>

            <annotation> 
               <documentation>You can look this up at
Wikipedia</documentation> 
               <xsi:xlink type="read"
xmlns:xsi="http://www.w3c.org/foobar/xlink/more/reference.url";>http://wikipedia.org#euro</xlink>

           </annotation> 
            <typing> 
              <type>string</type> 
            </typing> 
            <usage> 
               <use>all</use> 
            </usage> 
            <values> 
              <item> 
               <value>2</value> 
               <shortdescription>euros</shortdescription> 
               <symbol>E</symbol> 
              </item> 
            </values> 
         </ent:code> 
      </code:codelist>