Re: [codelist] Guidance sought re: changes for annotations

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

Thanks, Tony, for this feedback.

At 2007-12-27 17:51 +0000, Anthony B. Coates (Miley Watts) wrote:
>What genericode does is that the "Annotation/Documentation" elements are
>used for documentation/description information.

I note in the genericode XSD that the element name is "Description", 
not "Documentation".

>There are no other
>genericode elements used for this kind of information.  However,
>"Annotation/AppInfo" elements are purely for the use of end-users, they
>are not used for anything that the genericode specification depends on.
>
>If you were to follow the same reasoning for CVA, you would keep the
>"Identification" element as is, but replace the "Description" element with
>"Annotation/Documentation".
>
>Note also that in genericode, wherever "Annotation" occurs, it is always
>the first (optional) child element.

Okay ... then following those guidelines, the instance below is what 
I would have ... where the documentation detail is first and the 
title and identification pieces of information follow.

Thanks, Tony!

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

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="Crane-assoc2html.xsl"?>
<ValueListConstraints
  xmlns="http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/cd-1.0/";
   xmlns:cbc="urn:oasis:names:draft:ubl:schema:xsd:CommonBasicComponents-2"
   xmlns:cac="urn:oasis:names:draft:ubl:schema:xsd:CommonAggregateComponents-2"
   xmlns:x="http://www.w3.org/TR/REC-html40";
   xmlns:sch="http://purl.oclc.org/dsdl/schematron";
   id="urn:x-illustration"
   name="code-list-rules">
   <Annotation>
     <Description>
       <x:p>
         This is an illustrative example of all of the features of specifying
         the context/value constraints that one can express for XML documents.
       </x:p>
       <x:p>
         The validation requirements for this contrived scenario are 
as follows:
         <x:ul>
           <x:li>the UN/CEFACT currency code list is restricted to be
           only Canadian and US dollars:</x:li>
           <x:li>the seller must be in the US</x:li>
           <x:li>the buyer may be in either Canada or the US</x:li>
           <x:li>the definition for Payment Means is extended to include
           both UBL definitions and additional definitions</x:li>
         </x:ul>
       </x:p>
     </Description>
   </Annotation>

   <Title>
     Illustration of code list constraints -
     <x:samp>order-constraints.cva</x:samp>
   </Title>

   <Identification>
     <x:pre>
    $Id: order-constraints-doc.cva,v 1.7 2007/12/26 23:29:53 G. Ken 
Holman Exp $
     </x:pre>
   </Identification>

   <!--list all of the genericode expressions of agreed-upon code list
       value enumerations-->
   <ValueLists>
     <ValueList xml:id="currency" uri="CAUS_CurrencyCode.gc">
       <Annotation>
         <Description>
           <x:p>Restricted to only Canadian and US dollars.</x:p>
         </Description>
       </Annotation>
       <MetaData>
         <ShortName>CurrencyCode</ShortName>
         <LongName>Currency</LongName>
         <LongName Identifier='listID'>ISO 4217 Alpha</LongName>
         <Version>2001</Version>
         <CanonicalUri>urn:un:unece:uncefact:codelist:specification:54217</CanonicalUri>
         <CanonicalVersionUri>urn:un:unece:uncefact:codelist:specification:54217:2001</CanonicalVersionUri>
         <Agency>
           <LongName>United Nations Economic Commission for Europe</LongName>
           <Identifier>6</Identifier>
         </Agency>
       </MetaData>
     </ValueList>
     <ValueList xml:id="states" uri="US_CountrySubentityCode.gc">
       <Annotation>
         <Description>
           <x:p>List of US states.</x:p>
         </Description>
       </Annotation>
     </ValueList>
     <ValueList xml:id="provinces" uri="CA_CountrySubentityCode.gc">
       <Annotation>
         <Description>
           <x:p>List of Canadian provinces</x:p>
         </Description>
       </Annotation>
     </ValueList>
     <ValueList xml:id="tax-ids" uri="TaxIdentifier.gc" key="codeKey">
       <Annotation>
         <Description>
           <x:p>List of tax type identifiers</x:p>
         </Description>
       </Annotation>
     </ValueList>
     <ValueList xml:id="payments" uri="UBL_PaymentMeansCode-2.0.gc">
       <Annotation>
         <Description>
           <x:p>
             Copied from the UBL 2.0 suite:
             <x:a href="http://docs.oasis-open.org/ubl/cs-UBL-2.0/";>
               <x:samp>http://docs.oasis-open.org/ubl/cs-UBL-2.0/</x:samp>
             </x:a>
           </x:p>
         </Description>
       </Annotation>
     </ValueList>
     <ValueList xml:id="additional_payments"
                uri="Additional_PaymentMeansCode.gc">
       <Annotation>
         <Description>
           <x:p>An extra set of possible payment means.</x:p>
         </Description>
       </Annotation>
     </ValueList>
   </ValueLists>
   <!--list all of the contexts in which the value enumerations are used;
       where two or more contexts might match a given node in the input,
       list them here in order of most-important to least important match-->
   <Contexts>
     <Context item="@currencyID" values="currency">
       <Annotation>
         <Description>
       <x:p>All currencies are restricted to only Canadian and US 
dollars.</x:p>
         </Description>
       </Annotation>
     </Context>
     <Context item="cbc:CountrySubentityCode"
              context="cac:BuyerCustomerParty"
              values="provinces states">
       <Annotation>
         <Description>
           <x:p>The buyer can be in either Canada or the US.</x:p>
         </Description>
       </Annotation>
       <Message>Invalid province or state '<sch:value-of 
select="."/>' for buyer "<sch:value-of 
select="ancestor::cac:BuyerCustomerParty/cac:Party/cac:PartyName/cbc:Name"/>"</Message>
     </Context>
     <Context item="cbc:CountrySubentityCode"
              context="cac:SellerSupplierParty"
              values="states">
       <Annotation>
         <Description>
           <x:p>The seller can only be in the US.</x:p>
         </Description>
       </Annotation>
     </Context>
     <Context item="cbc:ID" xpath="cac:TaxCategory/cbc:ID" values="tax-ids">
       <Annotation>
         <Description>
           <x:p>Limit the recognized tax identifiers</x:p>
         </Description>
       </Annotation>
     </Context>
     <Context item="cbc:PaymentMeansCode"
              values="payments additional_payments">
       <Annotation>
         <Description>
       <x:p>The payments can be by either standard or supplemental means.</x:p>
         </Description>
       </Annotation>
     </Context>
   </Contexts>
</ValueListConstraints>

--
Comprehensive in-depth XSLT2/XSL-FO1.1 classes: Austin TX,Jan-2008
World-wide corporate, govt. & user group XML, XSL and UBL training
RSS feeds:     publicly-available developer resources and training
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)
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/o/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal