OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

codelist message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Guidance sought re: changes for annotations


Hi folks,

I started making the changes to the CVA specification according to 
our last teleconference.

I wanted to get some discussion regarding the changes before engaging 
them, because I'm not sure how to proceed.

Version 0.2 allows mixed content in constructs like <ValueList> and 
adding the new <Annotation> with <AppInfo> and <Documentation> there 
makes sense.

But if I add <Annotation> below the document element, does that 
remove the need for <Identification> and <Description>?  My thought 
is that <Annotation> should not have any standardized content at all 
... it should be purely for users to add their own augmentation.

Here is what a sample instance looks like now:

<ValueListConstraints xmlns...
   id="urn:x-illustration"
   name="code-list-rules">

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

   <Identification>
     $Id: order-constraints.cva,v 1.6 2007/11/21 02:23:18 G. Ken Holman Exp $
   </Identification>

   <Description>
     This is an illustrative example of all of the features of specifying the
     context/value constraints that one can express for XML documents.

     The validation requirements for this contrived scenario are as follows:
      - the UN/CEFACT currency code list is restricted to be
        only Canadian and US dollars
      - the seller must be in the US
      - the buyer may be in either Canada or the US
      - the definition for Payment Means is extended to include
        both UBL definitions and additional definitions
   </Description>

Each of the above has the same content model as 
<Annotation><Documentation> would, that is, mixed content with any 
foreign vocabulary (e.g. XHTML).  So, I'm thinking that <Annotation> 
does not belong as a child for any of <Title>, <Identification> or 
<Description>.  For symmetry, though, should I force <Documentation> 
as a child of Title as in:

   <Title>
     <Documentation>
       Illustration of code list constraints - order-constraints.cva
     </Documentation>
   </Title>

   <Identification>
     <Documentation>
       $Id: order-constraints.cva,v 1.6 2007/11/21 02:23:18 G. Ken Holman Exp $
     </Documentation>
   </Identification>

Instead, should the second one be expected to be application info?

   <Title>
     <Documentation>
       Illustration of code list constraints - order-constraints.cva
     </Documentation>
   </Title>

   <Identification>
     <AppInfo>
       $Id: order-constraints.cva,v 1.6 2007/11/21 02:23:18 G. Ken Holman Exp $
     </AppInfo>
   </Identification>

My gut feel is "no", just leave those three as they are currently defined.

The XHTML stylesheet expects to find content in the above 
constructs.  If a user *also* adds <Annotation><Documentation> with 
XHTML at a child of <ValueListConstraints>, then where would that 
documentation "fit" with the other documentation?  Therefore, should 
I only allow <Annotation><AppInfo> for annotating the document 
element?  Should I give up on <Annotation> entirely for the document element?

For the rest of the document model, I think I'm okay just adding 
<Annotation> with both <AppInfo> and <Documentation>.  When producing 
the XHTML rendering of the CVA file I would mix the anticipated XHTML 
of the above <Title>, <Identification> and <Description> elements.

Last question, as I realized I've not been looking closely at the 
genericode specification:  XSD <annotation> has <documentation> and 
<appinfo> children, while genericode's <Annotation> has <Description> 
and <AppInfo> children.  Should I go with <Documentation> or <Description>?

Below is what a CVA file would look like using <Annotation> to add 
documentation to the non-documentary constructs.  Does anything jump 
out at you as incorrect or unexpected?  If I don't hear anything from 
anyone, I'll modify the document model accordingly to support what is below.

Thanks!

. . . . . . . . . . . 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">

   <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>

   <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>

   <!--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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]