Context/value association using genericode 1.0

This Committee Specification 01 specifies an XML vocabulary used to express the relationship between information items found in a structured hierarchy (such as the XML instance of a business document) and two kinds of constraints imposed on those items. One kind constraint is that the value is a member of a set of controlled vocabularies of enumerated values (such as code lists or identifiers). Another kind of constraint is an arbitrary evaluation of a boolean query expression (such as a non-enumerable code list value check (say, the checksum calculation of an ISBN number), a business rule or a superimposed lexical constraint such as a maximum string value length).

The W3C XML Path Language [XPath 1.0][XPath 2.0] is an example of an addressing and query language used to specify document contexts and to express evaluations using a built-in function library.

The OASIS genericode standard [genericode] for code list representation is used to specify sets of enumerated values, be they codes or identifiers or any other set of values. Genericode provides for list-level metadata to be expressed for the list as a whole, as well as value-level metadata for each member of the list.

An OASIS context/value association (CVA) file specifies the relationship of information items in document contexts to both external enumerations of values allowed for each item and to arbitrary evaluations processed for each item. The diagram Figure 1, “Context/value association” shows the associations in the CVA file, each with the document context pointing into the document instance and one or more file locations pointing to the enumerations. The specification of related instance-level metadata for information items identifies which external code list or value test correlates with the information item's value. The CVA vocabulary allows one to masquerade the list-level metadata found in the external expression with specified overriding metadata.

Figure 1. Context/value association

There are no mandated technologies with which one is required to implement the functionality of a context/value association file. Runtime artefacts can use any technology desired.

XML documents are hierarchical arrangements of elements and attributes where some of these information items are constrained to one of a set of enumerated values and/or to a number of arbitrary evaluations. The document may also provide for such an information item some instance-level metadata in related elements and attributes. This metadata correlates the information item to the list-level metadata of the list of values that governs the value of the item.

Instance-level metadata can be defined differently for different XML vocabularies. Elements and/or attributes can be put aside to contain qualifying values that identify in the instance the list-level metadata associated with a given code or tested value. Typically, however, attributes are used for instance-level metadata for information items, attached to an element whose value is from a list, or a sibling of an attribute whose value is from a list. A simple example of such metadata is a version identifier. Consider that an element in an XML document has a value from one of two different value lists based on version 1 of the value list or version 2 of the value list, where that version number is expressed in the list's list-level metadata. The version instance-level metadata could be specified in an attribute, say ver= for an example. The user can then qualify the element's value by indicating ver="2" to indicate the qualifying values are from the second version of the value list corresponding to the list's genericode list-level metadata. A value found in one version of the list may not be available in another version of the list, thus the user's specification in instance-level metadata of the version of the list in play for the value is significant. Absent instance-level metadata, all of the lists' values are in play.

Information items may share a broad definition across the entire document, or possibly be more narrowly defined in sub-document contexts. An example of a broadly defined information item is a currency attribute with a document context that spans across an invoice: all references to currency across the document need to be associated with a single set of currency coded values. Examples of two narrowly defined information items with unique document contexts are a product identifier element named "ID" as a child of an element named "Product", and a document identifier similarly named "ID" but as a child of the document element: the former might be constrained by a list of identifiers derived from an inventory status query, while the latter might not be constrained at all. A broad specification of the element's value is inappropriate when other elements of the same name are used for different purposes in different document contexts.

Figure 2, “The use of context/value association files in document creation” illustrates how a context/value association file can help in a data entry scenario. It is common in data entry scenarios to limit values for information items to only those allowed by using a user interface control such as a drop-down list. By not making the data entry free-form, the value after creation is guaranteed to be one from the list. Hardwiring the list of allowed values in the application is inflexible if the enumeration changes based on the use of the document, say, for particular trading partners.

Externalizing the list in a genericode file expresses the enumeration as a resource available to the application for data entry. However, the choice of genericode file may vary on a per-information item basis due to the item's document context, or perhaps vary again for particular trading partners. Expressing the appropriate mappings in a colloquial fashion inhibits interoperability and the sharing of resources and program code.

A context/value association file specifies the relationship from information items found in different document contexts to one or more external genericode files for each item. With these relationships a directed authoring environment can precisely direct the editing of individual information items. Different context/value association files can then be used to create instances for different purposes that have different constraints on the enumerations used therein.

The data flow illustrates the CVA file pointing to the genericode files. A one-time preparation step distills the information from the genericode files in the contexts described by the CVA file and prepares a run-time artefact incorporating all the aggregated information. At run-time this artefact informs the directed authoring facility that is governing the data entry, without needing to access the CVA or genericode files. The output of the directed authoring is the XML instance having been populated with appropriate values for the given document contexts as regulated by the CVA associations.

Figure 2. The use of context/value association files in document creation

Figure 3, “The use of context/value association files in document validation” illustrates how a context/value association file can help in a validation scenario. Validation is important to confirm that the values used in an incoming XML instance are the ones allowed for each information item in each document context.

The historical use of W3C Schema enumerations for code lists and identifiers includes the value constraints along with the structural and lexical constraints. Conflating value validation with structural validation requires the structural constraint expression (i.e. the schema) to be changed to accommodate specific value validation requirements between partners in a document interchange. But often, schemas are distributed as read-only artefacts that should not be modified to accommodate trading partner nuances. By using associations a community of users can standardize on the expression of the structural constraints governing document interchange using XSD. Meanwhile, individuals in the community can tailor the value constraints on a per trading partner or scenario profile basis using context/value association files.

In document validation the value validation is irrelevant if the information items being tested are not in the expected document contexts. This suggests a first-pass structural validation to confirm the integrity of the information item locations. Only when structural validation is successful can value validation reflect the true fitness of the values used in the expected document contexts.

The data flow illustrates the CVA file pointing to the genericode files. A one-time preparation step distills the information from the genericode files in the contexts described by the CVA file and prepares a run-time artefact. The data flow shows the incoming XML instance first being checked using W3C Schema for structural integrity. When successful the information items are all correctly found and correctly formed. The incoming instance can then be checked for value validation using the run-time artefact created by the CVA associations (not the CVA or genericode files). When CVA validation is successful the application can then act on the incoming instance.

Figure 3. The use of context/value association files in document validation

Publicly-available enumerations of coded values are published and maintained by registration authorities regarded as the custodians of the code list of defined values and their associated definitions. A schema may constrain a document value to be one of the entire set of published code list values so as to ensure the document value used represents the published definition. A common example of a publicly-maintained code list is that which enumerates currency value indications [currency] and some projects have created genericode expressions of currency code lists containing all known values.

An important feature of CVA files is the ability to masquerade a genericode file in use as being another genericode file that is not being used. The typical uses of currency values illustrates this well. Should two trading partners agree to use only a limited number of currency values, say Canadian dollars and US dollars, a custom genericode file can be created taking only those two values from the publicly available genericode file for all currency codes. The smaller genericode file with only two currency codes necessarily uses custom list-level metadata that is different than the published list-level metadata of the complete genericode file for all currency codes.

When using these two currency codes in an instance, however, the instance-level metadata needs to reflect the published list-level metadata of the complete genericode file, as that would be the international identification of the semantics behind the values being used for the currency information items. A CVA file pointing simply to the reduced trading-partner list and its list-level metadata would prohibit the association of currency values with instance-level metadata of the complete list. Therefore, a CVA file is allowed to masquerade the genericode list-level metadata being pointed at by trading partners with any genericode list-level metadata the community of all trading partners agrees to use.

Thus, a community can standardize on the use of an international list of currency coded values, while individuals can utilize their own subsets of those values without conflict.

This Committee Specification 01 describes the document model for a context/value association file in which associations are made between document contexts of information items and either query language expression evaluations or external resources containing the values allowed for those items.

All elements in this document model are in the namespace identified at the beginning of this specification. The formal expression of this document model is found through links in the namespace documentation found at the URL of the namespace URI.

Using this document model, two partners in document interchange can exchange an instance of agreed-upon context/value associations, accompanied by instances of agreed-upon genericode expressions in support of the enumeration associations.

In summary, the association file describes the query language evaluations and points to the genericode files as system resources using URI strings, and names these pointers using XML identifiers unique to the association instance. The document context of each information item to be governed by an association is then associated with as many pointer identifiers as required to enumerate all of the possible values from all of the possible enumerations.

<?xml version="1.0" encoding="UTF-8"?>
<cva:ContextValueAssociation xmlns:cva=
"http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/1.0/"

  ... namespace declarations as required for context addresses ...
  queryBinding="xslt"
  id="urn:x-optional-unique-identifier-for-external-referencing"
  name="required-unique-name-token-for-internal-referencing"
  version="Revision: 27b - 2006-11-23 15:00z">
  <Annotation>
    <Description>
      This is included for illustrative purposes.
    </Description>
    <AppInfo>
      This is included for illustrative purposes.
    </AppInfo>
  </Annotation>

  <Title>
    This is the main context/value association file for project X.
  </Title>

  <Include uri="other-assoc-file-1.cva">
    <Annotation>
      <Description>
        Incorporating information from another file.
      </Description>
    </Annotation>
  </Include>
  <Include uri="other-assoc-file-2.cva">
    <Annotation>
      <Description>
        Incorporating information from yet another file.
      </Description>
    </Annotation>
  </Include>

  <ValueTests>
    <Annotation>
      <Description>
        All the tests available to be used.
      </Description>
    </Annotation>
    <ValueTest xml:id="a1" test="this > that">
      <Annotation>
        <Description>
          An example expression comparing child values.
        </Description>
      </Annotation>
    </ValueTest>
    <ValueTest xml:id="a2" test="string-length(.)&lt;=35">
      <Annotation>
        <Description>
          An example expression checking the length of data.
        </Description>
      </Annotation>
    </ValueTest>
  </ValueTests>

  <ValueLists>
    <Annotation>
      <Description>
        All the lists available to be used.
      </Description>
    </Annotation>
    <ValueList xml:id="a3" uri="enumeration1.gc">
      <Annotation>
        <Description>
          A set of external values with no masquerading meta data.
        </Description>
      </Annotation>
    </ValueList>
    <ValueList xml:id="a4" uri="enumeration2.gc">
      <Annotation>
        <Description>
          A set of external values with masquerading version meta data.
        </Description>
      </Annotation>
      <Identification>
        <Version>1.4</Version>
      </Identification>
    </ValueList>
    <ValueList xml:id="a5" uri="enumeration3.gc">
    <Annotation>
      <Description>
        Another set of external values with no masquerading meta data.
      </Description>
    </Annotation>
    </ValueList>
  </ValueLists>

  <InstanceMetadataSets>
    <Annotation>
      <Description>
        All the kinds of instance-level meta data available.
      </Description>
    </Annotation>
    <InstanceMetadataSet xml:id="i1">
      <InstanceMetadata address="../@version"
                        identification="Version">
        <Annotation>
          <Description>
            The version in this example is an attribute for an attribute.
          </Description>
        </Annotation>
      </InstanceMetadata>
    </InstanceMetadataSet>
    <InstanceMetadataSet xml:id="i2">
      <InstanceMetadata address="@version"
                        identification="Version">
        <Annotation>
          <Description>
            The version in this example is an attribute for an element.
          </Description>
        </Annotation>
      </InstanceMetadata>
    </InstanceMetadataSet>
  </InstanceMetadataSets>

  <Contexts>
    <Annotation>
      <Description>
        All the contexts using lists.
      </Description>
    </Annotation>
    <Context address="@item-a" values="a4" metadata="i1">
      <Annotation>
        <Description>
          Associating a set of values with all item-a= attributes.
        </Description>
      </Annotation>
    </Context>
    <Context address="context-b1//item-b" values="a3 a5"
             metadata="i2">
      <Annotation>
        <Description>
          Associating two sets of values with all item-b descendants
          of the context-b1 element.
        </Description>
      </Annotation>
    </Context>
    <Context address="context-b2/item-b" 
             values="a5" mark="characteristic-1" metadata="i2">
      <Annotation>
        <Description>
          Associating a set of values with item-b children of the
          context-b2 element.
        </Description>
      </Annotation>
    </Context>
    <Context address="item-c" values="a1 a2">
      <Annotation>
        <Description>
          Associating a pair of expressions with all item-c elements.
        </Description>
      </Annotation>
    </Context>
  </Contexts>
</cva:ContextValueAssociation>

The document element <ContextValueAssociation> specified by this vocabulary is in the "http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/1.0/" namespace while all other elements specified by this vocabulary are in no namespace. Elements of other namespaces are allowed only in reserved locations where specified in this document and schema.

The required name= attribute of the document element specifies a name token for internal referencing by downstream processes that take advantage of run-time or alternative expressions of the information found in the context/association file.

The optional queryBinding= attribute of the document element specifies a name token representing the syntax of item and context addresses. Absent this attribute, the default value can be whatever the processing system assumes, thus leaving it to the processing system to interpret the syntax as it wishes.

The optional id= attribute of the document element specifies a public identifier (typically, but not required to be, a URI) for externally referencing the context/value association file, such as in business process specifications and formal trading partner agreements.

The optional version= attribute of the document element is for reporting purposes suitable for identifying the version of the context/value association file. Its value can be copied to downstream synthesized files distinguishing the particular version of the information from previous versions of the same file.

The optional xml:base= attribute of the document element sets the base URI for any relative URI references in descendent URI-typed attributes.

The <Annotation> element is available everywhere where either application-specific or documentary constructs are contextually added to the content. This element is always added as the first child element of the construct being annotated. When at the top level, that is the first child of the document element, this annotates the entire context/value association file as a whole. There are two optional child elements for <Annotation>: <Description> is used to express information targeted for a human reader, and <AppInfo> is used to express information targeted for an application of some kind to process. In both cases these elements can contain text and/or elements using namespaces other than the context/value association namespace.

Most context/value association constructs allow for such annotations, and in the descriptions of elements that follow only those elements not supporting the <Annotation> first child element are so noted.

The optional <Title> element is for reporting purposes and is typically a single line of text suitable for the titling of any report generated from the documentary content. This element does not allow for an <Annotation> child element. Its string value (stripping markup) can be copied to text-only files to indicate which context/value association file has contributed a portion of its information when there are a number of portions included. This element can have any content for documentation purposes, provided any elements in that content are in a foreign namespace and not in the context/value association file namespace.

The optional and repeatable <Include> element is a directive to incorporate the associations found in other context/value association files into the one generated result. The uri= attribute points to the file being included. The optional xml:base= attribute overrides any ancestrally-specified base URI for a relative URI reference in the uri= attribute. Where two contexts from the suite of association files match the same information item in XML documents, the priority for the single match that is acted upon is highest for the contexts in the including association file, then next highest for the last association file included by an <Include> directive, then the next-to-last association file included by an <Include> directive, 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 optional <ValueTest> element child of the optional <ValueTests> element uses the required xml:id= attribute to declare an identifier suitable for internally referencing an internal expression evaluation. This identifier must be unique within the context/value association file in which it is declared, but is not required to be unique across included context/value association files as well. The required test= attribute contains an evaluation expression written using the query binding language in play.

Each optional <ValueList> element child of the optional <ValueLists> element uses the required xml:id= attribute to declare an identifier suitable for internally referencing the external expression of values. This identifier must be unique within the context/value association file in which it is declared, but is not required to be unique across included context/value association files as well. The required uri= attribute points to the associated genericode-encoded file. A relative URI value is resolved relative to the base URI of this element. The optional xml:base= attribute overrides any ancestrally-specified base URI for a relative URI reference in the uri= attribute. The key= attribute is optional when the referenced list has only a single key. The attribute is required when the referenced list has multiple keys, in order to indicate which single key is to be used for value lookup for the singleton coded value. This element is allowed to have a masqueradeUri= attribute and/or a single <Identification> element whose element children represent masquerading metadata for the external genericode file.

An <Identification> element is allowed to have the same element children as a genericode file's list-level metadata element children of the <Identification> element. These being any or all of <ShortName>, <LongName>, <Version>, <CanonicalUri>, <CanonicalVersionUri>, <LocationUri>, <AlternateFormatLocationUri> and <Agency>, where <Agency> is allowed to have the children <ShortName>, <LongName> and <Identifier>. The semantics of these elements are defined by genericode and are irrelevant in meaning to the association. While the <Identification> element is allowed to have an <Annotation> first child, the other children of <Identification> are not allowed to have an <Annotation> child at all.

An application supporting context/value association, when analyzing instance-level metadata, must treat masquerading list-level metadata in the following order. First, any masquerading list-level element content in the <Identification> declaration has highest precedence. Next, any masquerading list-level metadata in the genericode file referenced by masqueradeUri= has next highest precedence. Finally, over any list-level metadata found in the genericode file of values has the lowest precedence. Empty masquerading metadata replaces lower precedence metadata with no definition. See Section 3.1, “Instance-level metadata” for more details.

Each optional <InstanceMetadataSet> element child of the optional <InstanceMetadataSets> element contains a number of <InstanceMetadata> elements each describing two addresses in the query binding syntax. The address= attribute is an address pointing to a metadata information item assuming the current node is a context information item. The identification= attribute is an address pointing to an identification information item descending from an <Identification> element found either in an external value list's list-level metadata, or a masquerading <Identification> element found as a child of <ValueList>. See Section 3.1, “Instance-level metadata” for more details.

Each optional <Context> element child of the optional <Contexts> element points to all of the value constraints (either value expressions or lists of values) for a given information item using the values= attribute. The attribute string is a white-space-separated list of one or more xml:id= attributes used as <ValueTest> and <ValueList> identifiers in the same context/value association file.

For each specified <Context> all of the cited <ValueTest> tests must be true and the value must be present in any of the cited <ValueList> lists that are applicable given the presence of instance-level metadata and not empty of values, otherwise the constraints on the context are considered violated. The applicability of instance-level metadata is measured by the values at the respective addresses of the two attributes of each <InstanceMetadata> element that is a child of the element pointed to by the metadata= attribute.

The <Context> element must declare the address of the information items being associated with tests or lists by using the address= attribute expressed in the bound query language syntax.

    <Context address="@currencyID" values="currency" mark="money"
             metadata="cctsV2.01-amount">
    ...
    <Context address="cac:BuyerCustomerParty//cbc:CountrySubentityCode"
             values="provinces states"
             metadata="cctsV2.01-code">
    ...
    <Context address="cac:TaxCategory/cbc:ID"
             values="tax-ids" mark="money"
             metadata="cctsV2.01-identifier">
    ...

<cac:TaxSubTotal>
  <cbc:TaxableAmount currencyID="USD">100.00</cbc:TaxableAmount>
  <cbc:TaxAmount currencyID="USD">15.00</cbc:TaxAmount>
  <cac:TaxCategory>
    <cbc:ID>Z</cbc:ID>
    <cbc:Percent>15</cbc:Percent>
    <cac:TaxScheme>
      <cbc:ID>Provincial Tax</cbc:ID>
    </cac:TaxScheme>
  </cac:TaxCategory>
</cac:TaxSubTotal>

Two or more contexts' address expressions may all be valid for a single node in the source document, but only one will get engaged in the validation process. The order of <Context> elements for the context/value associations is interpreted such that the more important document contexts are found first and the less important document contexts follow. Thus, a given information item from the document can be associated with only a single document context declaration (the most important, that is the first one matched) in this context/value association file.

Each <Context> element may have any number of optional <Message> children that contain any content in a foreign namespace. Each message may have a useUri= attribute to characterize where an implementation would use the recognized message in the processing of value violations. At this time the specification has not reserved any such URI strings representing particular violation processing semantics but does reserve any URI string in an OASIS domain for future standardization. An application that does not recognize any of the supplied message characterizations shall use the first supplied message for reporting all violations. When a <Message> element is present with element or non-white-space text content, that content is meant to be used in place of any automatically-generated message an application might use when reporting a violation of the context/value constraint. An otherwise absent or empty <Message> element will signal to the application the permitted use of any automatically-generated message text.

<?xml version="1.0" encoding="UTF-8"?>
<cva:ContextValueAssociation xmlns:cva=
"http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/1.0/"
  xmlns:in="urn:oasis:names:specification:ubl:schema:xsd:Invoice-1.0"
  xmlns:po="urn:oasis:names:specification:ubl:schema:xsd:Order-1.0"
  name="code-list-rules">
  <ValueLists>
    <ValueList xml:id="a1" uri="enumeration1.gc"/>
    <ValueList xml:id="a2" uri="enumeration2.gc"/>
    <ValueList xml:id="a3" uri="enumeration3.gc"/>
  </ValueLists>
  <Contexts>
    <Context address="@item-a" values="a2"/>
    <Context address="/po:Order//context-b1//@item-b" 
             values="a1 a3"/>
    <Context address="/in:Invoice//context-b1/@item-b"
             values="a3" mark="characteristic-1"/>
  </Contexts>
</cva:ContextValueAssociation>

Each <Context> element may have an optional mark= attribute that contains a single name token used to characterize the context. Downstream processes may choose to distinguish different constraint violations by their marked characterization.

The http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/1.0/ namespace URI string represents the committee draft version of the XML vocabulary for context/value association files. When the work becomes a committee specification the namespace URI string will likely be http://docs.oasis-open.org/codelist/ns/ContextValueAssociation/1.0/.

A set of associations from specified document contexts to referenced value lists is expressed in an XML instance using the context/value association XML vocabulary. The W3C Schema XSD file ContextValueAssociation.xsd expresses the document constraints of this XML vocabulary and references the xml.xsd expression of reserved XML attributes.

All normative W3C Schema XSD document fragments for this XML vocabulary can be obtained by dereferencing this XML namespace URI.

Two measures of conformance are described by this specification: (1) the conformance of a standalone context/value association instance and its contents; and (2) the conformance of an application acting on a context/value association file to interpret the values permitted for document contexts.