The OASIS Code List Representation Technical Committee [CLRTC] has created the Context/value association (CVA) file format [CVA] where partners in information interchange can associate the values found in genericode [genericode] files with information items found in XML documents of any vocabulary. For example, the Universal Business Language [UBL 2.0] defines a vocabulary for business documents and a two-phase validation process in which the structural and lexical validation is achieved using W3C Schema [W3C Schema], and value validation using a methodology based on CVA files using XSLT 1.0 [XSLT 1.0].

Crane Softwrights Ltd. has developed the following three XSLT 1.0 stylesheets used for the rendering of either standalone genericode files or context/value association files that reference genericode files. These stylesheets recognize elements in the XHTML namespace ("http://www.w3.org/1999/xhtml") or HTML 4 namespace ("http://www.w3.org/TR/REC-html40") and produce a report with constructs in the XHTML namespace.

The stylesheet to render a genericode file is named "Crane-gc2html.xsl".

The simplified stylesheet to render a context/value association file is named "Crane-cva2html.xsl" (does not include instance metadata summaries for each referenced list). A more detailed stylesheet to render a context/value association file is named Crane-cva2htmlXSLT.xsl (includes instance metadata summaries for each referenced list) and requires a more detailed process to render the results than that of the simplified stylesheet.

The renderings are simplified presentations of the information found in these files. Where it makes sense there are hyperlinks pointing elsewhere in the document to definitions of the information referenced.

The specification and document constraints for context/association files allow for embedded use of elements from a foreign namespace, in addition to text documentation. The stylesheet in this package assumes that the embedded documentation is wrapped in HTML constructs using the http://www.w3.org/TR/REC-html40 namespace.

The documentation for the value validation methodology includes the file order-constraints.cva. This stylesheet package includes a modified version of that file, named order-constraints-doc.cva, in which the documentation constructs are wrapped in HTML vocabulary:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="Crane-cva2html.xsl"?>
<cva:ContextValueAssociation 
  xmlns:cva=
         "http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/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"
  version=
"$Id: readme-Crane-cva-gc-xsl.xml,v 1.47 2013/04/16 00:40:23 admin Exp $">
  <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>

  <!--list all test expressions-->
  <ValueTests>
    <ValueTest xml:id="length-35" test="string-length(.)&lt;=35">
      <Annotation>
        <Description>
          <x:p>Certain fields are restricted to 35 characters in length.</x:p>
        </Description>
      </Annotation>
    </ValueTest>
  </ValueTests>

  <!--list all of the genericode expressions of agreed-upon code list
      value enumerations-->
  <ValueLists>
    <ValueList xml:id="currency" uri="CAUS_CurrencyCode.gc"
               masqueradeUri="UBL_CurrencyCode-2.0.gc">
      <Annotation>
        <Description>
          <x:p>Restricted to only Canadian and US dollars.</x:p>
        </Description>
      </Annotation>
      <Identification>
        <LongName>ISO Currency List</LongName>
      </Identification>
    </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 instance-level metadata components associated with
      genericode <Identification> components-->
  <InstanceMetadataSets>
    <Annotation>
      <Description>
        <x:p>UN/CEFACT CCTS V2.01 supplementary components to genericode</x:p>
      </Description>
      </Annotation>
    <InstanceMetadataSet xml:id="cctsV2.01-amount">
      <Annotation>
        <Description>
          <x:p>CCTS 2.01 AmountType instance metadata</x:p>
        </Description>
      </Annotation>
      <InstanceMetadata address="../@currencyCodeListVersionID"
                        identification="Version"/>
    </InstanceMetadataSet>
    <InstanceMetadataSet xml:id="cctsV2.01-measure">
      <Annotation>
        <Description>
          <x:p>CCTS 2.01 MeasureType instance metadata</x:p>
        </Description>
      </Annotation>
      <InstanceMetadata address="../@unitCodeListVersionID"
                        identification="Version"/>
    </InstanceMetadataSet>
    <InstanceMetadataSet xml:id="cctsV2.01-quantity">
      <Annotation>
        <Description>
          <x:p>CCTS 2.01 QuantityType instance metadata</x:p>
        </Description>
      </Annotation>
      <InstanceMetadata address="../@unitCodeListID"
                        identification="Version"/>
      <InstanceMetadata address="../@unitCodeListAgencyName"
                        identification="Agency/LongName"/>
      <InstanceMetadata address="../@unitCodeListAgencyID"
                        identification="Agency/Identifier"/>
    </InstanceMetadataSet>
    <InstanceMetadataSet xml:id="cctsV2.01-code">
      <Annotation>
        <Description>
          <x:p>CCTS 2.01 CodeType instance metadata</x:p>
        </Description>
      </Annotation>
      <InstanceMetadata address="@listName"
                        identification="LongName[not(@Identifier='listID')]"/>
      <InstanceMetadata address="@listID"
                        identification="LongName[@Identifier='listID']"/>
      <InstanceMetadata address="@listVersionID"
                        identification="Version"/>
      <InstanceMetadata address="@listSchemeURI"
                        identification="CanonicalUri"/>
      <InstanceMetadata address="@listURI"
                        identification="LocationUri"/>
      <InstanceMetadata address="@listAgencyName"
                        identification="Agency/LongName"/>
      <InstanceMetadata address="@listAgencyID"
                        identification="Agency/Identifier"/>
    </InstanceMetadataSet>
    <InstanceMetadataSet xml:id="cctsV2.01-identifier">
      <Annotation>
        <Description>
          <x:p>CCTS 2.01 IdentifierType instance metadata</x:p>
        </Description>
      </Annotation>
      <InstanceMetadata address="@schemeName"
                        identification="LongName[not(@Identifier='listID')]"/>
      <InstanceMetadata address="@schemeID"
                        identification="LongName[@Identifier='listID']"/>
      <InstanceMetadata address="@schemeVersionID"
                        identification="Version"/>
      <InstanceMetadata address="@schemeURI"
                        identification="CanonicalUri"/>
      <InstanceMetadata address="@schemeDataURI"
                        identification="LocationUri"/>
      <InstanceMetadata address="@schemeAgencyName"
                        identification="Agency/LongName"/>
      <InstanceMetadata address="@schemeAgencyID"
                        identification="Agency/Identifier"/>
    </InstanceMetadataSet>
  </InstanceMetadataSets>

  <!--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 address="@currencyID" values="currency" mark="money"
             metadata="cctsV2.01-amount">
      <Annotation>
        <Description>
      <x:p>All currencies are restricted to only Canadian and US dollars.</x:p>
        </Description>
      </Annotation>
    </Context>
    <Context address="cac:BuyerCustomerParty//cbc:CountrySubentityCode"
             values="provinces states"
             metadata="cctsV2.01-code">
      <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 address="cac:SellerSupplierParty//cbc:CountrySubentityCode"
             values="states"
             metadata="cctsV2.01-code">
      <Annotation>
        <Description>
          <x:p>The seller can only be in the US.</x:p>
        </Description>
      </Annotation>
      <Message>Invalid state '<sch:value-of select="."/>' for seller "<sch:value-of select="ancestor::cac:SellerSupplierParty/cac:Party/cac:PartyName/cbc:Name"/>"</Message>
    </Context>
    <Context address="cac:TaxCategory/cbc:ID"
             values="tax-ids" mark="money"
             metadata="cctsV2.01-identifier">
      <Annotation>
        <Description>
          <x:p>Limit the recognized tax identifiers</x:p>
        </Description>
      </Annotation>
    </Context>
    <Context address="cbc:PaymentMeansCode" mark="money"
             values="payments additional_payments"
             metadata="cctsV2.01-code">
      <Annotation>
        <Description>
      <x:p>The payments can be by either standard or supplemental means.</x:p>
        </Description>
      </Annotation>
    </Context>
    <Context address="cbc:Name" values="length-35">
      <Annotation>
        <Description>
          <x:p>Names are not allowed to be too long.</x:p>
        </Description>
      </Annotation>
    </Context>
    <Context address="cbc:StreetName" values="length-35">
      <Annotation>
        <Description>
          <x:p>Addresses are not allowed to be too long.</x:p>
        </Description>
      </Annotation>
    </Context>
  </Contexts>
</cva:ContextValueAssociation>

Note throughout the embedded documentation the use of a namespace prefix (in this example "x") to reference the HTML vocabulary ("http://www.w3.org/TR/REC-html40").

It is possible to view either a genericode file or a context/value association file directly in a browser by embedding a stylesheet association [Assoc] processing instruction. If the stylesheet is in the same directory as the genericode file, then the following would be added to the genericode file, immediately after the XML declaration at the top of the file (as in the testRender.gc sample file):

  <?xml-stylesheet type="text/xsl" href="Crane-gc2html.xsl"?>

Similarly for a context/value association file, the following processing instruction would be used (as in the order-constraints-doc.cva sample file):

  <?xml-stylesheet type="text/xsl" href="Crane-cva2html.xsl"?>

Of course if the stylesheets are in a different directory than the files using them, the href= attribute needs to point to the correct path to the stylesheet.

When embedding references to stylesheets in a CVA file it is not necessary to also add them to the referenced genericode files as the CVA stylesheet will trigger the genericode stylesheet for each genericode reference it finds.

When creating standalone HTML from the XML of a genericode file, two examples of using Saxon [Saxon] are as follows, the first explicitly referencing the stylesheet and the second looking for the embedded stylesheet association:

  java -jar saxon.jar -o file.html file.gc Crane-gc2html.xsl

and

  java -jar saxon.jar -o file.html -a file.gc

When creating standalone HTML from the XML of a context/value association file with the simplified CVA stylesheet, two examples of using Saxon are as follows, the first explicitly referencing the stylesheet and the second looking for the embedded stylesheet association:

  java -jar saxon.jar -o file.html file.cva Crane-cva2html.xsl

and

  java -jar saxon.jar -o file.html -a file.cva

When creating standalone HTML from the XML of a context/value association file with the more detailed CVA stylesheet Crane-cva2htmlXSLT.xsl, the following two steps must be taken, in order, to produce the result:

  java -jar saxon.jar -o intermediateFileAnywhere.xsl file.cva Crane-cva2htmlXSLT.xsl
  java -jar saxon.jar -o file.html intermediateFileAnywhere.xsl intermediateFileAnywhere.xsl

The stylesheets are structured such that the built-in textual messages can be overridden with a importing stylesheet. The included stylesheet Crane-alternate-cva2html.xsl illustrates how this overriding can be done, and would be invoked in the following manner, the first explicitly referencing the stylesheet and the second looking for the embedded stylesheet association:

  java -jar saxon.jar -o file.html file.cva Crane-alternate-cva2html.xsl

or

  java -jar saxon.jar -o file.html -a file.cva

Both Crane-cva2html.xsl and Crane-gc2html.xsl have all built-in messages written in English and can have these messages overridden using the method illustrated in Crane-alternate-cva2html.xsl. When declaring the overriding variables and template, be sure to use the corresponding namespace qualification on the name of the top-level construct.

To utilize the overriding stylesheet with the more detailed CVA reporting process, copy Crane-cva2htmlXSLT.xsl and modify the copy to import the overriding stylesheet. The two-step process is identical, only using the newly-created stylesheet in the first step.

The stylesheets are structured such that a wrapper stylesheet can define content for the HTML header element that is output. This is particularly handy to add embedded CSS styles in the HTML header.

The two example wrapper stylesheets Crane-head-gc2html.xsl and Crane-head-cva2html.xsl illustrate this technique. These stylesheets colour the background, respectively, green and blue.

Invoking the stylesheet for a genericode file is done along the lines of one of the following:

  java -jar saxon.jar -o file.html file.gc Crane-head-gc2html.xsl

or

  java -jar saxon.jar -o file.html -a file.gc

Invoking the stylesheet for a CVA file is done along the lines of the following:

  java -jar saxon.jar -o file.html file.cva Crane-head-cva2html.xsl

or

  java -jar saxon.jar -o file.html -a file.cva

To utilize the augmenting stylesheet with the more detailed CVA reporting process, copy Crane-cva2htmlXSLT.xsl and modify the copy to import the augmenting stylesheet. The two-step process is identical, only using the newly-created stylesheet in the first step.

The following sample files included in the ZIP package in which this documentation is obtained:

At this time the rendering of a context/value association file that includes other context/value association files will result in the duplicate rendering of a given genericode that is referenced from more than one context/value association file. This does not happen often, and it is not an error, but the end result will have as many renderings of a given genericode file as there are value list declarations for that file in the complete "include set" of context/association files. A future version of these stylesheets could detect the redundant renderings of a given genericode file.