Re: [clr-dev] Additional information about InstanceMetadataSets

[ericdes <eric@vcardprocessor.com>]

Hi Ken, thank you for that superb explanation. But let me tell you I was 
far from understanding one could add an additional attribute (such as 
the metadata attribute "isoyear" in your example) in a document that 
makes use of genericodes (Do CIQ, UBL allow this?) just because a CVA 
contract (that specifies a set of medatada) is there. I was under that 
impression that a CVA file was used to specify codelists and validation 
rules, I would never have thought it could have gone so far as to allow 
injection of attributes (maybe of xml elements too?) into the exchanged 
documents. I'm still not sure what the consequences are (I mean as for 
the applications I'm developing).
Eric.


On 10/7/2010 8:22 PM, G. Ken Holman wrote:
> 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
>