RE: [clr-dev] Additional information about InstanceMetadataSets

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

Hi Eric!  I see from Juerg's post that you posted today but for some 
reason a copy never made it to my inbox.  I'm pleased to take a 
moment to explain instance metadata sets.  I believe you understand 
the basics, but please allow me to explain the whole situation for 
readers of the archive who have not progressed to the point where you are.

While some code lists can live in isolation (thus not needing 
instance metadata for disambiguation; say directions of latitude and 
directions of longitude for two examples), I think it is wise to 
model metadata for *all* code lists in an XML vocabulary.

Consider a country code from the most current UN/CEFACT list of ISO 
3166 country codes:

   http://www.unece.org/cefact/recommendations/country.htm

... in particular key 189 SERBIA & MONTENEGRO has the country code "CS".

Before 1993, the ISO country code "CS" represented 
Czechoslovakia.  In 2006 there was no "CS" code in the ISO country 
list (I chose that year because I use that list in another project).

So, if you see a document with the following:

    <country>CS</country>

... is it ambiguous?  Do you rely on the date of the document?  Not 
if it is a document documenting historical information.

To disambiguate the ISO country code, thus indicating exactly the 
semantics represented by the coded value, one could add, say, a 
metadata attribute of the year in which the list was published.  Thus 
this would be the coded value for Czechoslovakia in your XML data instance:

    <country isoyear="1990">CS</country>

... whereas this would be the coded value for Serbia and Montenegro:

    <country isoyear="2010">CS</country>

... and this would be in error because *no* country had that code in 2006:

    <country isoyear="2006">CS</country>

Without the metadata you don't know which country you are referencing 
unless you have prior agreement with your trading partner that, say, 
all codes are post 2010.  But who knows if ISO will five years from 
now retires another code and reassigns it?  So it is safest to code 
it with the metadata to indicate which code list is being used.

Assuming you have a genericode file for each year:

    iso3166-1990.gc   - with <Version>1990</Version> in <Identification>
    iso3166-2006.gc   - with <Version>2006</Version> in <Identification>
    iso3166-2010.gc   - with <Version>2010</Version> in <Identification>

... and a declaration in the CVA file for each:

   <ValueList xml:id="country1990" uri="iso3166-1990.gc"/>
   <ValueList xml:id="country2006" uri="iso3166-2006.gc"/>
   <ValueList xml:id="country2010" uri="iso3166-2010.gc"/>

... and you have a document context in the CVA file describing your 
country element that points to the item in your XML using address="":

   <Context address="country" values="country1990 country2006 country2010" ...

... you have to describe in the CVA file where the genericode 
<Version> element information is found relative to the <country> 
element in your XML.  It is found in the isoyear="" attribute.  So in 
your context you point to a metadata set:

   <Context address="country" values="country1990 country2006 country2010"
            metadata="iso3166metadata"/>

... and in the metadata set in the CVA file you associate the address 
of the isoyear="" attribute of your XML (relative to the context 
item) with the address of the <Version> element of your genericode 
(relative to <Identification>):

   <InstanceMetadataSet xml:id="iso3166metadata">
     <InstanceMetadata address="attribute::isoyear"
                       identification="child::Version"/>
   </InstanceMetadataSet>

... or more succinctly as:

   <InstanceMetadataSet xml:id="iso3166metadata">
     <InstanceMetadata address="@isoyear" identification="Version"/>
   </InstanceMetadataSet>

Now the validation will use only the 1990 genericode file when 
isoyear="1990", only the 2006 genericode file when isoyear="2006" and 
only the 2010 genericode file when isoyear="2010".  It will use all 
three files in the absence of the isoyear="" attribute.  It will use 
none of the files if the isoyear="" attribute is a value other than 
"1990", "2006" or "2010".

If one uses the free CVA to XSLT conversion package found here:

    http://www.CraneSoftwrights.com/resources/ubl/index.htm#codelist

... and creates the XSLT for validating the above three lists, then 
this will validate (because it is ambiguous):

    <country>CS</country>

... these two will validate (because the codes exist in the respective lists):

    <country isoyear="1990">CS</country>
    <country isoyear="2010">CS</country>

... and this will be flagged in error (because the code does not 
exist in the respective list):

    <country isoyear="2006">CS</country>

To summarize, the instance metadata is used to associate metadata 
attributes of your XML with metadata values in the identification 
section of genericode files.

With the above explanation, can you suggest where to improve the documentation?

I hope this example helps.

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

At 2010-10-08 13:06 +1300, DMS Lists wrote:
>Eric,
>The CVA documentation supplied at
>http://www.oasis-open.org/apps/group_public/download.php/37909/cs01-ContextV
>alueAssociation-1.0-20100521-2130z.zip
>containing the file 'context-value-association.pdf' should hopefully provide
>what you require.
>
>Juerg Tschumperlin
>Data Management Solutions
>Wellington, New Zealand
>www.d-m-s.co.nz
>
>
> >-----Original Message-----
> >From: ericdes [mailto:eric@vcardprocessor.com]
> >Sent: Friday, 8 October 2010 11:47 a.m.
> >To: clr-dev@lists.oasis-open.org
> >Subject: [clr-dev] Additional information about InstanceMetadataSets
> >
> >I must tell you I'm seriously confused about how to understand and use
> >the section InstanceMetadataSets in CVA files. I understand it's
> >optional and meant to disambiguate between multiple versions of code
> >lists but, really, I don't have to clue how to make use of it. Is there
> >any additional documentation?
> >
> >Sincerely,
> >Eric Desgranges


--
XSLT/XQuery training:   after http://XMLPrague.cz 2011-03-28/04-01
Vote for your XML training:   http://www.CraneSoftwrights.com/c/i/
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/c/
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/c/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal