UBL Code List Value Validation Methodology

Schema expressions constraining the values of code list coded values often use xsd:enumeration elements restricting a base data type of either a normalized string or a tokenized value. The UBL declaration for currency coded values imported from UN/CEFACT uses such an approach as illustrated by this incomplete fragment:

  <xsd:simpleType name="CurrencyCodeContentType">
    <xsd:restriction base="xsd:token">
      <xsd:enumeration value="AED">
        <xsd:annotation>
          <xsd:documentation>
            <ccts:CodeName>Dirham</ccts:CodeName>
            <ccts:CodeDescription></ccts:CodeDescription>
          </xsd:documentation>
        </xsd:annotation>
      </xsd:enumeration>
      <xsd:enumeration value="AFN">
        <xsd:annotation>
          <xsd:documentation>
            <ccts:CodeName>Afghani</ccts:CodeName>
            <ccts:CodeDescription></ccts:CodeDescription>
          </xsd:documentation>
        </xsd:annotation>
      </xsd:enumeration>
      <xsd:enumeration value="ALL">
        <xsd:annotation>
          <xsd:documentation>
            <ccts:CodeName>Lek</ccts:CodeName>
            <ccts:CodeDescription></ccts:CodeDescription>
          </xsd:documentation>
        </xsd:annotation>
      </xsd:enumeration>
      <xsd:enumeration value="AMD">
      ...

Trading partners may wish to contractually constrain the set of coded values for these information items to only those values that are allowed in instances being exchanged. This is easily accommodated in the information exchange since any coded value used from a strict subset is, by definition, a coded value in the full enumeration. Instances with one of the limited values can be validated by the unchanged schema for the document model with all of the values.

Note that while techniques are available in some schema expression languages for restricting a data type definition of an enumeration to a subset of values, such a restriction typically has global scope across the instance. Trading partners may wish to constrain the values to different sets in different contexts of the document, which is not possible by way of available restriction techniques in some schema language expression semantics.

Trading partners wishing to extended the set of coded values for these information items are unable to do so when code list constraints in a schema are expressed with an enumeration. Adding a new value to the list changes the definition of the list such that instances with new values cannot be validated by the unchanged schema for the document model.

Some code lists are declared in schemata without an enumeration, as there may be far too many possible coded values to be manageable, the sets of coded values may differ in different contexts of a single document, or the coded values are not predefined in any way. Schema expressions constraining such code list coded values often merely constrain the value to a normalized string or a tokenized value. This satisfies the lexical requirements of the coded value without constraining the particular values that meet the requirements.

A UBL example of a code list with an unmanageable number of enumerations is cbc:CountrySubentityCode as there are so very many provinces, states, regions, prefectures and other administrative or jurisdictional areas in the world that would be included to be complete. UBL does not supply any sets of values to use.

A UBL example of a code list with predefined values that trading partners may wish to extend or restrict is DocumentStatusCodeType where the UBL committee has chosen a set of meaningful values for a certain class of workflow definitions, but trading partners may have a richer set employed in their respective systems. This predefined list, among other predefined lists, is supplied in UBL using an external code list expression conforming to this methodology.

An example of a code list without any predefined values is cac:AccountTypeCode as there may be as many account types as there are trading parties, and none are predefined by UBL. Trading partners wishing to validate information items using coded values from this code list are obliged to agree on and express the set of values they expect to use. UBL does not supply any sets of values to use.

UBL has two generic declarations of code lists for these examples based on whether the coded value is an identifier or a code. These declarations are illustrated by this incomplete fragment:

   <xsd:complexType name="CodeType">
      <xsd:annotation>
         <xsd:documentation xml:lang="en">
            ...
         </xsd:documentation>
      </xsd:annotation>
      <xsd:simpleContent>
         <xsd:extension base="xsd:normalizedString">
            <xsd:attribute name="listID" type="xsd:normalizedString" 
                           use="optional"/>
            <xsd:attribute name="listAgencyID" type="xsd:normalizedString" 
                           use="optional"/>
            <xsd:attribute name="listAgencyName" type="xsd:string" 
                           use="optional"/>
            <xsd:attribute name="listName" type="xsd:string" use="optional"/>
            <xsd:attribute name="listVersionID" type="xsd:normalizedString" 
                           use="optional"/>
            <xsd:attribute name="name" type="xsd:string" use="optional"/>
            <xsd:attribute name="languageID" type="xsd:language" 
                           use="optional"/>
            <xsd:attribute name="listURI" type="xsd:anyURI" use="optional"/>
            <xsd:attribute name="listSchemeURI" type="xsd:anyURI" 
                           use="optional"/>
         </xsd:extension>
      </xsd:simpleContent>
   </xsd:complexType>
   ...
   <xsd:complexType name="IdentifierType">
      <xsd:annotation>
         <xsd:documentation xml:lang="en">
            ...
         </xsd:documentation>
      </xsd:annotation>
   <xsd:simpleContent>
      <xsd:extension base="xsd:normalizedString">
        <xsd:attribute name="schemeID" type="xsd:normalizedString" 
                       use="optional"/>
        <xsd:attribute name="schemeName" type="xsd:string" use="optional"/>
        <xsd:attribute name="schemeAgencyID" type="xsd:normalizedString" 
                       use="optional"/>
        <xsd:attribute name="schemeAgencyName" type="xsd:string" 
                       use="optional"/>
        <xsd:attribute name="schemeVersionID" type="xsd:normalizedString" 
                       use="optional"/>
        <xsd:attribute name="schemeDataURI" type="xsd:anyURI" 
                       use="optional"/>
        <xsd:attribute name="schemeURI" type="xsd:anyURI" use="optional"/>
      </xsd:extension>
   </xsd:simpleContent>
 </xsd:complexType>

Note in the above how the optional metadata attributes do not have fixed attributes, thus allowing the XML instance to indicate not only the coded value but also the metadata related to the code list from which the value is taken. This approach allows XML instances validated with the schema to have any coded value for these information items.

UBL includes both kinds of constraints for coded values in code lists, very few of which are declared with enumerations. The CurrencyCodeContentType data type is an example whose coded values are internationally standardized [currency]. The only other two such code lists in UBL enumerate MIME encoding identifiers and unit code values. All three enumerations are imported from UN/CEFACT-standardized sets of coded values.

All other code lists in UBL are not enumerated in the schema expressions. Such code lists can be very large and would be awkward to accommodate in a schema expression. Some code lists have a set of predefined coded values supplied by UBL that trading partners may wish to extend. Other codes lists can only have coded values provided by the users, as standardization either hasn't happened or shouldn't happen because it isn't appropriate to set out what trading partners are allowed to use.

The UBL 2.0 support package [UBL 2.0 Support] includes genericode files for every code list. All the enumerated code lists have complete sets of coded values distilled from the schema expressions, a limited number of code lists have the sets of coded values predefined by the UBL committee, and all other code lists have an empty set of coded values. Trading partners can modify or replace any of the genericode files to meet their business requirements using the code list value validation methodology in this Working Draft.

Trading partners will need to replace the genericode definitions for those code lists they wish to restrict or, if allowed, extend. Their flexibility in modifying the code list is based on whether the code list is described in the schema with or without an enumeration.

When limiting the coded values from a list described in the schema with an enumeration, the unedited genericode file is initialized to include all enumerated values. Trading partners can then work from the complete list and prune unwanted values in a copy leaving in the values agreed to be used in XML instances.

An example of this is a genericode file based on the UN/CEFACT currency values that would have over 160 entries. A copy of this file named scenario/MyCurrencyLimits.gc is edited where the entire list of coded values has been pruned to only the Canadian dollar and the US dollar. An excerpt from that file reads as:

<gc:CodeList xmlns:gc="http://genericode.org/2006/ns/CodeList/0.4/" ...
   <Identification>
      <ShortName>CurrencyCode</ShortName>
      <LongName>ISO 4217 Alpha</LongName>
      ...
   <SimpleCodeList>
      <Row>
         <Value ColumnRef="code">
            <SimpleValue>CAD</SimpleValue>
         </Value>
         <Value ColumnRef="name">
            <SimpleValue>Canadian Dollar</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value ColumnRef="code">
            <SimpleValue>USD</SimpleValue>
         </Value>
         <Value ColumnRef="name">
            <SimpleValue>US Dollar</SimpleValue>
         </Value>
      </Row>
   </SimpleCodeList>
</gc:CodeList>

When specifying the coded values for a list described in the schema without an enumeration, the unedited genericode file may either have some predefined coded values initialized through system design decisions, or may be void of any coded values whatsoever. Trading partners can modify a copy of the genericode file or synthesize a new file from scratch and include the values agreed to be used.

An excerpt from the scenario/MyCanadianProvinces.gc file created by hand reads as:

<gc:CodeList xmlns:gc="http://genericode.org/2006/ns/CodeList/0.4/" ...
   <Identification>
      <ShortName>provinces</ShortName>
      <LongName>Canadian Provinces</LongName>
      <Version>2</Version>
      ...
   </Identification>
   ...
   <SimpleCodeList>
      <Row>
         <Value ColumnRef="code">
            <SimpleValue>AB</SimpleValue>
         </Value>
         <Value ColumnRef="name">
            <SimpleValue>Alberta</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value ColumnRef="code">
            <SimpleValue>BC</SimpleValue>
         </Value>
         <Value ColumnRef="name">
            <SimpleValue>British Columbia</SimpleValue>
         </Value>
      </Row>
      ...

An excerpt from the scenario/MyUSStates.gc file created by hand reads as:

<gc:CodeList xmlns:gc="http://genericode.org/2006/ns/CodeList/0.4/" ...
   <Identification>
      <ShortName>states</ShortName>
      <LongName>US States</LongName>
      <Version>1</Version>
      ...
   </Identification>
   ...
   <SimpleCodeList>
      <Row>
         <Value ColumnRef="code">
            <SimpleValue>AL</SimpleValue>
         </Value>
         <Value ColumnRef="name">
            <SimpleValue>ALABAMA</SimpleValue>
         </Value>
      </Row>
      <Row>
         <Value ColumnRef="code">
            <SimpleValue>AK</SimpleValue>
         </Value>
         <Value ColumnRef="name">
            <SimpleValue>ALASKA</SimpleValue>
         </Value>
      </Row>
      ...

Of course genericode files need not be created by hand and could be synthesized as the result of a database query or some other process to create the XML expression of the coded values.

To satisfy the normative requirements for references in UBL, the UBL set of deliverables includes a snapshot of the genericode specification.

The UBL support package includes a complete set of genericode files conforming to this snapshot specification, with which trading partners can tailor their needs. Each of the more than 80 code lists in UBL schemata are accommodated by a genericode file structured as one of the following:

The XML Path Language 1.0 [XPath 1.0] is used to address locations in an XML document according to a data model of processed syntax. This XPath data model differs from other data models such as the Document Object Model [DOM] in that the DOM models more aspects of raw syntax used in the document. Given that syntax is irrelevant (in that it is arbitrary to the creator of XML which syntactic choices are made when marking up documents) the XPath data model is sufficient to talk about the elements and attributes found in documents.

Elements are referred to in an XPath expression by their namespace-qualified names, while the "@" character (an abbreviation for the XPath attribute:: axis) prefixes attributes referred to by their namespace-qualified names.

The syntax of an XPath expression separates multiple location steps of a single location path using an oblique "/" character. Each step to the right names the child element or attached attribute of the immediately preceding step to the left which is always an element. Child elements are one level deeper in the XML hierarchical nesting than their parents. Elements are also parents of their attached attributes.

A fully-qualified absolute XPath location path begins with the oblique indicating the path starts from the root node (the parent of the document element) of the XPath data model document tree. A relative XPath location path starts with the name of an information item without the oblique at the beginning.

Examples of absolute XPath location paths possible for an instance of UBL Order are:

/po:Order/cac:TaxTotal/cbc:TaxAmount/@currencyID
/po:Order/cbc:DocumentCurrencyCode
/po:Order/cac:BuyerCustomerParty/cac:Party/cac:Address/cbc:CountrySubentityCode
/po:Order/cac:SellerSupplierParty/cac:Party/cac:Address/cbc:CountrySubentityCode

An example of a relative XPath location that matches all currency coded values in attributes in the entire instance of any UBL document model is as follows, as the information item does not include any ancestral distinction to the left:

@currencyID

An example of a relative XPath location that matches all country sub-entity coded values in elements in the entire instance of any UBL document model is as follows, as the information item does not include any ancestral distinction to the left:

cbc:CountrySubentityCode

The minimum XPath addresses needed to precisely distinguish the country sub-entity code of the party address of each of the buyer and seller are as follows, as the information item includes explicit ancestry to the left:

cac:BuyerCustomerParty/cac:Party/cac:Address/cbc:CountrySubentityCode
cac:SellerSupplierParty/cac:Party/cac:Address/cbc:CountrySubentityCode

Note the use of the "//" operator in XPath allows the matching within an entire sub-tree of the hierarchy; the XPath addresses needed to distinguish all (not just in the party address) country sub-entity codes descendent to the buyer and the seller would be as follows indicating only the required (and possibly distant) ancestor:

cac:BuyerCustomerParty//cbc:CountrySubentityCode
cac:SellerSupplierParty//cbc:CountrySubentityCode

When deciding on code list value validation, trading partners must agree in which contexts particular sets of values need to be constrained.

Some business rules may require the same context to be specified across all document types, such as "All currency values must be Canadian or US dollars."

Other business rules may require indistinct document contexts to be specified, such as "all country sub-entity coded values used in the order and in the invoice shall be valid states according to the United States postal service."

Yet other business rules might require more distinct document contexts to be specified, such as "The country sub-entity codes for the seller can only be states of the United States, while country sub-entity codes for the buyer can be both provinces of Canada and states of the United States."

Furthermore, trading partners can choose to employ an agreed-upon controlled vocabulary for document contexts for which code lists are not defined. This UBL value validation methodology is agnostic to the method by which information items are declared in schemata, thus allowing trading partners to specify acceptable values for information items in any context.

Trading partners must, therefore, take the step to agree on which XPath addresses will specify the contexts at which particular values are constrained. Examining the list of contexts in which code-list-typed information items are found, the partners can identify as much specificity as is required to match those contexts in which the values are constrained.

The UBL support package includes context reports for every document type of the UBL suite. Each context report lists all of the minimally-unique document contexts for information items based on code lists in that document type definition expressed by the schema. These reports are algorithmically derived from the UBL W3C Schema expressions.

The number of code-list-based information items ranges from a low of 14 for the Order Response Simple model, to a high of 77 for the Freight Invoice model.

The number of minimally-unique code-list-based information item document contexts ranges from a low of 311 for the Attached Document model, to a high of 153,335 for the Order Response model.

This model is found in the compressed package associated with this specification in utility/ directory in the UBL-ContextConstraints-0.6.xsd file. This model needs an external declaration of the xml:id= attribute, for which one is supplied named xmlid.xsd (derived from the xml:id Recommendation [xml:id]).

Using this document model, trading partners create an instance of code list context associations. The instance points to genericode files as system resources using URI strings, and names these pointers using XML identifiers unique to the instance. The document context of each information item to be validated using this methodology is then associated with as many pointer identifiers as required to enumerate all of the possible values from all of the possible enumerations.

A pro-forma code list context association instance reads as follows:

<?xml version="1.0" encoding="US-ASCII"?>
<CodeListConstraints 
  ... namespace declarations as required for XPath addresses ...
  xmlns="urn:oasis:names:tc:ubl:schema:CodeList-Constraints-0.6" 
  id="urn:x-optional-unique-identifier-for-external-referencing"
  name="required-unique-name-token-for-internal-referencing">

  <Identification>
    This is the main code list context association file for project X.

    Revision: 27a – 2006-06-17 15:00z
  </Identification>

  <Include uri="other-assoc-file-1.xml"/>
  <Include uri="other-assoc-file-2.xml"/>

  <CodeLists>
    <CodeList xml:id="a1" uri="enumeration1.gc"/>
    <CodeList xml:id="a2" uri="enumeration2.gc"/>
    <CodeList xml:id="a3" uri="enumeration3.gc"/>
  </CodeLists>

  <Contexts>
    <Context item="@item-a" codes="a2" value="token"/>
    <Context item="item-b" context="context-b1" codes="a1 a3"/>
    <Context item="item-b" xpath="context-b2/item-b" codes="a3"/>
  </Contexts>
</CodeListConstraints>

The required name= attribute specifies a name token for internal referencing by downstream processes that take advantage of alternative expressions of this information.

The optional id= attribute specifies a public identifier (typically, but not required to be, a URI) for external referencing, such as in formal trading partner agreements.

The optional <Identification> element is a text-only string that is made available to be copied into any intermediate results for tracking purposes. This gives an indication in a result file as to where portions of its information originated when there are a number of portions included.

The optional and repeatable <Include> element is a directive to incorporate the associations found in other code list context association files into the one generated result. Where two contexts from the suite of association files match the same node, the priority for the single match that is acted upon is highest for the contexts in the invoked association file, then next highest for the last association file included by an <Include> directive (e.g. those in other-assoc-file-2.xml above), then the next-to-last association file included by an <Include> directive (e.g. those in other-assoc-file-1.xml above), and so on with the lowest priority being the first association file included by an <Include> directive. Any included association files having such directives will treat those in priority before other directives of the including file.

Each <CodeList> element declares the unique identifier for the external code list expression and the pointer to the associated system resource itself, in this example a genericode-encoded file.

Each <Context> element points to all of the codes for a given information item in the codes= attribute as a white-space-separated list of <CodeList> identifiers. It also must declare the XPath address of the information item in isolation without context using the item= attribute (the first example above is an attribute, the other two are elements). This is sufficient contextual information when testing the item in a document-wide context, however, when the information item needs to be tested in a given sub-document context or a subset of a multi-document context, one of two mutually-exclusive attributes is required.

The context= attribute specifies some ancestral element of the information item beneath which all information items addressed are to be considered in context. Alternatively, when more nuanced detail is required, the xpath= attribute specifies the precise XPath context of the information item, including in the address the information item itself. These two attributes can be any valid XPath expression, with as much context and as many predicates as is needed to identify the constructs in the instances.

The value= attribute is optional and there is no functional difference in the validation result of instances if this attribute is specified or not. Specifying value="token" will, however, indicate there are no white-space characters expected in any of the coded values specified in instances, thus giving the opportunity for execution-time optimization of the validation functionality.

It is possible that regardless of which combination of attributes is used, two XPath expressions will both match the same node in the source document. The <Context> elements for the code list context associations must, therefore, be ordered with the more important XPath contexts first and the less important XPath contexts following in order to ensure a predictable result. A given information item from the document being validated can match only a single context declaration in this code list context association file.

Trading partners can choose to have separate expressions of code list context associations for instances of each document type, or using the context of the document element, combine the associations in a single file for a subset of a multi-document context. An example of a code list context association file testing information items in both UBL Order and UBL Invoice instances is as follows, where @item-a has the same constraints in both instances, but @item-b has different constraints in both instances:

<?xml version="1.0" encoding="US-ASCII"?>
<CodeListConstraints 
  xmlns:in="urn:oasis:names:specification:ubl:schema:xsd:Invoice-1.0"
  xmlns:po="urn:oasis:names:specification:ubl:schema:xsd:Order-1.0"
  xmlns="urn:oasis:names:tc:ubl:schema:CodeList-Constraints-1.0" 
  id="urn:x-myurn:code-constraints"
  name="code-list-rules">
  <Information>
    This is another example.
  </Information>
  <CodeLists>
    <CodeList xml:id="a1" uri="enumeration1.gc"/>
    <CodeList xml:id="a2" uri="enumeration2.gc"/>
    <CodeList xml:id="a3" uri="enumeration3.gc"/>
  </CodeLists>
  <Contexts>
    <Context item="@item-a" codes="a2" value="token"/>
    <Context item="@item-b" context="/po:Order//context-b1" 
             codes="a1 a3"/>
    <Context item="@item-b" xpath="/in:Invoice//context-b1/@item-b"
             codes="a3"/>
  </Contexts>
</CodeListConstraints>

In the absence of metadata properties for coded values in the instance being validated, only the coded values of the associated external code list expressions can be used. There being no qualification of the values, all values are in play as valid codes for validation.

However, if the instance being validated does have metadata properties specified for a given coded value, then that coded value is asserted to be a value from a particular version or identified code list. Therefore, when the external XML representation of a set of coded values is qualified by metadata properties indicating information about the set of values, the validation process can accurately correlate the instance's value with a set's values.

In the absence of metadata properties for coded values in the external code list expression, all coded values of the associated external code list expression are used. There being no qualification of the values, all values are in play as valid codes for validation.

In the presence of metadata in the external code list expression, the validation can only check an information item's coded value as being correct when the information item's metadata, when present, matches as well.

The ISO assertion-based schema language Schematron [Schematron] works by validating the information items in an instance against a set of assertions. A Schematron validating process tests each information item against the highest-priority assertion (earliest in the list of assertions) to which its XPath address matches.

The compressed package that is part of this methodology includes the schematron-ISO-assembly.xsl and schematron-ISO-incomplete-text.xsl XSLT 1.0 stylesheets (in the utility/ subdirectory) that are used in tandem to transform a compound set of Schematron sets of assertions into a single XSLT 1.0 stylesheet that, when applied against a document to be validated, reports any failed assertions that are detected. All validation failures are sent to the operating system standard error port, and a non-zero exit is returned from the XSLT processor. A zero exit returned from the XSLT processor indicates successful validation.

This methodology implements coded value validation by expressing the assertions that the information items in the instance being validated, with any related metadata, are valid values from the external code list expressions that are associated to the information items through the code list context association files. This is accomplished in a modular fashion so as to mesh with other business rules that trading partners may need to express regarding their agreed-upon electronic documents.

The compressed package that is part of this methodology includes an XSLT 1.0 stylesheet (complete with imported fragments) that transforms a code list context association file for a UBL document model and genericode external code list expressions into a corresponding Schematron set of assertions in a single named Schematron pattern.

These stylesheets are modular in a fashion that allows new stylesheets to take advantage of existing modules to support the methodology with other document models and other external code list expressions.

When adapting this methodology to document models and external code list expressions, the basic stylesheet filename patterns follow these conventions:

Following this convention, then, the demonstrative example included with this methodology invokes the following stylesheet and fragments:

Using the methodology stylesheet for the target document models and external code list expressions, each code list context association file <Context> element becomes a Schematron assertion (thus requiring the document order of <Context> elements to be the required priority order).

The Constraints2Schematron-0.6.xsl stylesheet creates a named Schematron pattern, named using the name= attribute in the context association file, in the standalone output file. . This end result can then be incorporated into complete Schematron schemata by reference using the <sch:include> directive that is resolved in a strict assembly stage that takes place in advance of semantic interpretation of the other Schematron constructs

The demonstrative example implementation of this methodology has two distinct phases, one for the preparation of the validation process and one for the validation activity itself, as shown in Figure 1, “Methodology data flow”. The information expressed in the code list context association file is thus manipulated, but only when the inputs change, into a form with which the actual validation of the document instances is accomplished as many times as required.

Figure 1. Methodology data flow

There is no obligation that an implementation of this methodology follow this particular data flow, only that the end result include the same reported validation violations of contextual use of coded values in the document instances to be validated.

Not illustrated in the data flow diagram are three necessary preconditions for the data flow to produce bona fide validation reports. The three inputs to the data flow must each be validated against their respective document models in advance to provide properly structured information to the internal processes. None of the XSLT processes illustrated perform any validation of the inputs.

The code list context associations file must have been validated against the UBL-ContextConstraints-0.6.xsd constraints.

The external code list expressions must have been validated against their respective model, in this example the genericode-code-list-0.4.xsd constraints.

The documents being validated with this methodology must have been validated against their respective structural schema model, which is not included in this example. This is a critically important precondition because the schema constraints will confirm the information items are correctly positioned in the XML instance document hierarchy. This ensures the XPath instructions in the code list context association will be properly applied. Without having confirmed the structural integrity of the XML instance, the assertion validation report is meaningless.

In both the Linux shell environment and the Windows command-line environment, two shell scripts or batch files are invoked in the test scenario and must be available on the path. The following illustrates how each of these are invoked, the first line for a Windows environment and the second line for a Linux environment:

In this scenario two trading partners are going to interchange UBL documents between buyer and seller parties. At a technical level, they are using unmodified UBL W3C Schema expressions publicly available for the structural integrity of their XML instances.

At a business level, the trading partners have agreed that all currencies used in an instance can be only Canadian or US dollars. The MyCurrencyLimits.gc file documented in Section 4.1, “Trading partner genericode definitions” expresses this limited number of coded values.

As well, the partners have agreed that the buyer's country sub-entity codes may be either a US state or a Canadian province, but that the seller's country sub-entity codes may only be a US state. The two genericode files MyUSStates.gc and MyCanadianProvinces.gc, also documented in Section 4.1, “Trading partner genericode definitions”, express these limitations.

The following code list context association file order-constraints.xml points each of the UBL instance contexts to the required genericode files in order to satisfy the trading partner agreement:

<?xml version="1.0" encoding="US-ASCII"?>
<!--
Example constraints on UBL instances exchanged between trading partners.
-->
<CodeListConstraints 
  xmlns="urn:oasis:names:tc:ubl:schema:CodeList-Constraints-0.5" 
xmlns:cbc="urn:oasis:names:draft:ubl:schema:xsd:CommonBasicComponents-2"
xmlns:cac="urn:oasis:names:draft:ubl:schema:xsd:CommonAggregateComponents-2"
  id="urn:x-illustration"
  name="code-list-rules">

  <Identification>
    Illustration of code list constraints.
  </Identification>

  <!--list all of the genericode expressions of agreed-upon code list
      value enumerations-->
  <CodeLists>
    <CodeList xml:id="currency" uri="MyCurrencyLimits.gc"/>
    <CodeList xml:id="states" uri="MyUSStates.gc"/>
    <CodeList xml:id="provinces" uri="MyCanadianProvinces.gc"/>
  </CodeLists>
  <!--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>
    <!--all currencies are restricted-->
    <Context item="@currencyID" codes="currency" value="token"/>
    <!--buyer can be in Canada or US-->
    <Context item="cbc:CountrySubentityCode"
             context="cac:BuyerCustomerParty"
             codes="provinces states" value="token"/>
    <!--seller can be only in the US-->
    <Context item="cbc:CountrySubentityCode"
             xpath="cac:SellerSupplierParty//cbc:CountrySubentityCode"
             codes="states" value="token"/>
  </Contexts>
</CodeListConstraints>

These genericode files and code list context association file together form a formal and unambiguous expression of the contextual coded value constraints that go beyond the constraints of the standardized UBL schema expressions. The package of these files can, therefore, be included in a contractual agreement between the trading partners.

The artefact in this scenario produced by the stylesheet is the file order-constraints.sch which includes only a single named Schematron pattern, suitable for inclusion in any ISO Schematron schema. The following Schematron schema codes-only-constraints.sch is a minimum expression suitable for including the generated named pattern, as it is acceptable that an assembled Schematron schema contain only a single pattern:

<schema xmlns="http://purl.oclc.org/dsdl/schematron">
  <title>Code list value assertions</title>
  <ns prefix="cbc"
      uri="urn:oasis:names:draft:ubl:schema:xsd:CommonBasicComponents-2"/>
  <ns prefix="cac"
      uri="urn:oasis:names:draft:ubl:schema:xsd:CommonAggregateComponents-2"/>
  <include href="order-constraints.sch"/>
</schema>

Moreover, trading partners may have additional business rules that apply to instances. Consider there might also be a Schematron expression limiting the total amount of the invoice to less than $10,000. This business rule would be in its own pattern, thus the Schematron file including the order-constraints.sch schema would have two patterns. This could be simply expressed merely as two patterns in the schema without any phases, thus implying that all patterns are in play at all times. Alternatively, for more validation flexibility if desired, this can be expressed in Schematron semantics as a single phase that would indicate both patterns as active in the validation process as in the example total-constraints.sch schema:

<?xml version="1.0" encoding="US-ASCII"?>
<schema xmlns="http://purl.oclc.org/dsdl/schematron"
        defaultPhase="only-phase">
  <title>Business rules for maximum total value</title>
  <ns prefix="cbc" 
      uri="urn:oasis:names:draft:ubl:schema:xsd:CommonBasicComponents-2"/>
  <ns prefix="cac"
      uri="urn:oasis:names:draft:ubl:schema:xsd:CommonAggregateComponents-2"/>
  <phase id="only-phase">
    <active pattern="code-list-rules"/>
    <active pattern="business-rules"/>
  </phase>
  <pattern id="business-rules">
    <rule context="cbc:ToBePaidAmount">
      <assert test=". &lt; 10000">Total amount '<value-of select="."/>' cannot be $10,000 or more.</assert>
    </rule>
  </pattern>
  <include href="order-constraints.sch"/>
</schema>

Such business rules could also form part of the contract between trading partners, and for one of the tests in the scenario the generated Schematron rules augment authored Schematron rules to make a single assertion validation expression for use against the instances.

A number of test instances are included to demonstrate the code list value validation methodology in this test scenario:

First the scenario establishes the preconditions by validating the code list context association expression of constraints in order-constraints.xml and each of the genericode code list expressions (the necessary W3C Schema validation of the test input files is not included in the demonstration).

Next, the code list rules expressed in the code list context association file are translated into a Schematron pattern in order-constraints.sch. This can now be reused wherever code list constraints need to be checked. Note that the comments created in this pattern file include the markup for namespace declarations that are necessary in the including Schematron schemas. It is the user's responsibility to ensure that all of the namespaces required by all of the included Schematron pattern files are appropriately declared in the including schema.

The first test scenario, named "Test 1", translates these inputs without business rules into Schematron expression in codes-only-constraints.sch without any supplemental business rules, and then translates that first into a complete Schematron instance order-codes-only.sch and from there into an XSLT 1.0 expression in order-codes-only.xsl.

Preparation is complete for the first test and now the validation stage runs this resulting XSLT against all the test files, producing no errors and a zero return code when there are no problems, and producing a list of errors and a non-zero return code when there are problems. The error report is output to the standard error port, and the return code is testable by the script running the process.

The second test scenario, named "Test 2", augments the Schematron expression of business rules in total-constraints.sch with the code list rules into order-codes-total.sch and then translates that into an XSLT 1.0 expression in order-codes-total.xsl.

Preparation is complete for the second test and the validation stage runs the resulting XSLT against the order-test-bad3.xml file with the corrupted total amount, indicating the violation of both the code list and business constraints.

Note again how the constraints need only be prepared once, translating the requirements into the XSLT in the preparation phase to the artefact which is then reused during the validation phase as often as required. In a production environment the XSLT used for validation need only be recreated whenever the trading partner agreement changes to include a new formal expression of the coded value constraints in either the code list context association file or a code list expression file.

Run "sh test-all.sh" in a Linux environment or "test-all.bat" in a Windows command-line environment to get the following results of running the test scenario:

Precondition validation...

Validating partner-agreed constraints...
  w3cschema UBL-ContextConstraints-0.6.xsd order-constraints.xml
Attempting validating, namespace-aware parse
Parse succeeded (0.230) with no errors and no warnings.

Validating code lists...
  w3cschema genericode-code-list-0.4.xsd MyCanadianProvinces.xml
Attempting validating, namespace-aware parse
Parse succeeded (0.291) with no errors and no warnings.
  w3cschema genericode-code-list-0.4.xsd MyUSStates.xml
Attempting validating, namespace-aware parse
Parse succeeded (0.311) with no errors and no warnings.
  w3cschema genericode-code-list-0.4.xsd MyCurrency.xml
Attempting validating, namespace-aware parse
Parse succeeded (0.281) with no errors and no warnings.

Preparing code list rules...

Translating partner-agreed constraints into Schematron rules...
  xslt order-constraints.xml ../utility/UBL-genericode2Schematron-0.6.xsl
                                                     order-constraints.sch

Test 1 - standalone code list rules

Assembling rules into a Schematron schema...
  xslt codes-only-constraints.sch ../utility/schematron-ISO-assembly.xsl 
                                                     order-codes-only.sch

Translating Schematron into validation stylesheet...
  xslt order-codes-only.sch ../utility/schematron-ISO-incomplete-text.xsl 
                                                     order-codes-only.xsl

Document validation...

Testing order-test-good1.xml...
  xslt order-test-good1.xml order-codes-only.xsl nul "2>test-constraints.txt"
Result: 0


Testing order-test-good2.xml...
  xslt order-test-good2.xml order-codes-only.xsl nul "2>test-constraints.txt"
Result: 0


Testing order-test-bad1.xml...
  xslt order-test-bad1.xml order-codes-only.xsl nul "2>test-constraints.txt"
Result: 1

Value supplied ' UYU ' is unacceptable for codes identified by 'currency' 
in the context: @currencyID
Processing terminated by xsl:message at line 18


Testing order-test-bad2.xml...
  xslt order-test-bad2.xml order-codes-only.xsl nul "2>test-constraints.txt"
Result: 1

Value supplied ' ON ' is unacceptable for codes identified by 'provinces 
states' in the context: cac:BuyerCustomerParty//cbc:CountrySubentityCode
Processing terminated by xsl:message at line 18


Testing order-test-bad3.xml...
  xslt order-test-bad3.xml order-codes-only.xsl nul "2>test-constraints.txt"
Result: 1

Value supplied ' ON ' is unacceptable for codes identified by 'states' in 
the context: cac:SellerSupplierParty//cbc:CountrySubentityCode
Processing terminated by xsl:message at line 18


Test 2 - with business rules

Assembling rules into a Schematron schema...
  xslt total-constraints.sch ../utility/schematron-ISO-assembly.xsl 
                                                     order-codes-total.xsl

Translating Schematron into validation stylesheet...
  xslt order-codes-total.sch ../utility/schematron-ISO-incomplete-text.xsl 
                                                     order-codes-total.xsl

Document validation...

Testing order-test-bad3.xml...
  xslt order-test-bad3.xml order-codes-total.xsl nul "2>test-constraints.txt"
Result: 1

Total amount ' 11500 ' cannot be $10,000 or more.
Value supplied ' ON ' is unacceptable for codes identified by 'states' in 
the context: cac:SellerSupplierParty//cbc:CountrySubentityCode
Processing terminated by xsl:message at line 19


Done.