UBL Naming and Design Rules Version 3.1

These UBL Naming and Design Rules (NDR) describe the application of the OASIS Business Document Naming and Design Rules [BDNDR] by which the XML document user data syntax constraint mechanisms are created from the abstract definition of the UBL business object information bundles. This is illustrated in Figure 1, “Open-edi Application”, reproduced from OASIS Standard UBL 2.3 Figure H.2 with an annotation highlighting the relationship of the NDR applied to UBL. The original figure depicts the roles of the four normative sections of the UBL 2.3 specification. This figure adds the JSON serialization as an additional representation of user data.

Figure 1. Open-edi Application

This work product fulfills a commitment by the UBL Technical Committee to document the maintenance of the information bundles and the application of the Business Document NDR to produce the validation artefacts for UBL 2.3 [UBL-2.3] documents expressing user data. The UBL information bundles are described in the abstract using CCTS [CCTS]. The UBL XML user data document model validation artefacts are described using W3C XML Schema [XSD schema] and OASIS Context/value association [CVA] expressions.

This work also provides guidance when writing custom extensions for UBL document models and when writing custom documents using the UBL common library.

In UBL 2.3 no document-level ABIE is referenced by an ASBIE. This merely reflects user requirements to date and in a future revision of UBL there may be such references.

There are 86 document ABIEs representing information bundles in UBL 2.3. The class names for these ABIEs are as follows:

In UBL 2.3 the common library contains 267 ABIEs for reference as ASBIEs in the document ABIEs, library ABIEs and extension ABIEs.

Per the Business Document NDR every document and library ABIE has as its first child a reference to an optional extension point that can be used to add supplemental information not already defined by UBL to the document.

In the UBL 2.3 distribution there is one extension made available to be used, that being for digital signatures. The information in this extension is modeled primarily using CCTS but with an additional data item modeled by the W3C in [xmldsig]. The components described using CCTS are in a single collection of two ABIEs describing the signature extension ABIE and another ABIE for reference by the extension's ASBIEs.

The UBL TC uses office spreadsheet worksheets as the collaborative tool to maintain the CCTS model of the UBL documents, the common library and the signature extension. A worksheet row is used for each component. A worksheet column is used for each mandatory and optional CCTS facet. In the UBL distribution this information is split into individual spreadsheets as follows.

The 65 document ABIEs are described using individual spreadsheets that are all found here:

The common library ABIEs are in a single spreadsheet and the signature extension ABIEs are in a single spreadsheet that are both found here:

UBL imposes an additional constraint on the values of recorded CCTS information that all characters used be ASCII characters. This prohibits accented letters, exotic symbols, and stylized punctuation such as "smart quotes". The rationale for this is that the resulting character sequences are then not subject to character encoding vagaries that may not be properly handled by downstream processing applications.

UBL abbreviates the following name value words when used in a component's name:

UBL considers the following name value words equivalent when used in a component's name:

UBL allows the use of the following abbreviations in name values and in a component's name:

The CCTS information "Name" value for a BIE definition is labeled "UBL Name" in the UBL spreadsheets.

In addition to the CCTS columns indicated as having to be maintained by these NDR, the UBL spreadsheets contain the following columns of additional information used and recorded during analysis, all of which are optional:

Object classes are never qualified in UBL. Accordingly, the "Object Class Qualifier" and "Associated Object Class Qualifier" columns are present but always empty in instances of the spreadsheets.

Every Document ABIE contains as its first four BBIE children, in order and all with property Term Primary Noun "Identifier" and Representation Term "Identifier", items with the following Property Term Possessive Nouns and cardinality "0..1":

Every Document ABIE contains a Signature ASBIE with cardinality "0..n" to the Signature ABIE.

These NDR to not vary from the Business Document NDR in this regard. This section of the documentation exists to maintain alignment of sections.

While the information bundles are described using CCTS principles, it is the document models that govern the structure of documents expressing in a machine-readable format the information described by the bundles. These NDR provide for expressing the model of an information bundle using validation artefacts that describe constraints on the structure and content of documents. Validation processes report violations of these model constraints found in a document.

There are two types of validation artefacts. W3C XSD schemas are used to validate the structure of elements and the structure of data content. OASIS CVA expressions and OASIS genericode files are used to validate the values of data content.

The UBL distribution organizes the documented XSD schemas (with BIE XSD annotations) under the xsd/ subdirectory and the runtime XSD schemas (without BIE XSD annotations) under the xsdrt/ subdirectory:

The CVA file and formatted report are distributed in the cva/ subdirectory:

The genericode files referenced by the CVA file are distributed in the gc/ subdirectories of each of the UBL 2.2, UBL 2.1, and UBL 2.0 distributions:

The UBL CVA and genericode files are compiled into an XSLT stylesheet expression for runtime testing against XML instances that have been validated using the UBL XSD schemas. This stylesheet is named UBL-DefaultDTQ-2.3.xsl and is distributed in the val/ subdirectory:

The following namespace URI strings are associated with the indicated documentary namespace prefixes:

Figure 3, “UBL import/include hierarchy of XSD schema expressions” depicts the UBL implementation of the import and include directives described in the naming and design rules.

Figure 3. UBL import/include hierarchy of XSD schema expressions

The documented XSD schemas include CCTS information in annotations of the Library and Document ABIE complex types (not of the element declarations). Only those values found in the columns referenced in Section 4.4, “Dictionary information for BIEs” are included. An example of each of an ABIE, BBIE and ASBIE is as follows:

<xsd:complexType name="WinningPartyType">
  <xsd:annotation>
     <xsd:documentation>
        <ccts:Component>
           <ccts:ComponentType>ABIE</ccts:ComponentType>
           <ccts:DictionaryEntryName>Winning Party. 
           Details</ccts:DictionaryEntryName>
           <ccts:Definition>A party that is identified as the awarded by
           a tender result.</ccts:Definition>
           <ccts:ObjectClass>Winning Party</ccts:ObjectClass>
        </ccts:Component>
     </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
     <xsd:element ref="cbc:Rank" minOccurs="0" maxOccurs="1">
        <xsd:annotation>
           <xsd:documentation>
              <ccts:Component>
                 <ccts:ComponentType>BBIE</ccts:ComponentType>
                 <ccts:DictionaryEntryName>Winning Party. Rank.
                 Text</ccts:DictionaryEntryName>
                 <ccts:Definition>Indicates the rank obtained in the
                 award.</ccts:Definition>
                 <ccts:Cardinality>0..1</ccts:Cardinality>
                 <ccts:ObjectClass>Winning Party</ccts:ObjectClass>
                 <ccts:PropertyTerm>Rank</ccts:PropertyTerm>
                 <ccts:RepresentationTerm>Text</ccts:RepresentationTerm>
                 <ccts:DataType>Text. Type</ccts:DataType>
              </ccts:Component>
           </xsd:documentation>
        </xsd:annotation>
     </xsd:element>
     <xsd:element ref="cac:Party" minOccurs="1" maxOccurs="1">
        <xsd:annotation>
           <xsd:documentation>
              <ccts:Component>
                 <ccts:ComponentType>ASBIE</ccts:ComponentType>
                 <ccts:DictionaryEntryName>Winning Party.
                 Party</ccts:DictionaryEntryName>
                 <ccts:Definition>Information about an organization,
                 sub-organization, or individual fulfilling a role in a
                 business process.</ccts:Definition>
                 <ccts:Cardinality>1</ccts:Cardinality>
                 <ccts:ObjectClass>Winning Party</ccts:ObjectClass>
                 <ccts:PropertyTerm>Party</ccts:PropertyTerm>
                 <ccts:AssociatedObjectClass>Party</ccts:Associated
ObjectClass>
                 <ccts:RepresentationTerm>Party</ccts:RepresentationTerm>
              </ccts:Component>
           </xsd:documentation>
        </xsd:annotation>
     </xsd:element>
  </xsd:sequence>
</xsd:complexType>

Every schema fragment generated for UBL 2.3 includes an XML comment at both the beginning of the document and the end of the document. These comments are present in both the documented schemas and the runtime schemas.

The comment at the beginning of every schema fragment includes identification information and revision metadata, as in this example from the common aggregate components fragment:

<!--
  Library:           OASIS Universal Business Language (UBL) 2.3 OS
                     http://docs.oasis-open.org/ubl/os-UBL-2.3/
  Release Date:      14 April 2020
  Module:            xsd/common/UBL-CommonAggregateComponents-2.3.xsd
  Generated on:      2020-04-03 17:20z
  Copyright (c) OASIS Open 2020. All Rights Reserved.
-->

The comment at the end of the document is a detailed copyright notice as follows:

<!-- ===== Copyright Notice ===== --><!--
  OASIS takes no position regarding the validity or scope of any 
  intellectual property or other rights that might be claimed to pertain 
  to the implementation or use of the technology described in this 
  document or the extent to which any license under such rights 
  might or might not be available; neither does it represent that it has 
  made any effort to identify any such rights. Information on OASIS's 
  procedures with respect to rights in OASIS specifications can be 
  found at the OASIS website. Copies of claims of rights made 
  available for publication and any assurances of licenses to be made 
  available, or the result of an attempt made to obtain a general 
  license or permission for the use of such proprietary rights by 
  implementors or users of this specification, can be obtained from 
  the OASIS Executive Director.

  OASIS invites any interested party to bring to its attention any 
  copyrights, patents or patent applications, or other proprietary 
  rights which may cover technology that may be required to 
  implement this specification. Please address the information to the 
  OASIS Executive Director.
  
  This document and translations of it may be copied and furnished to 
  others, and derivative works that comment on or otherwise explain 
  it or assist in its implementation may be prepared, copied, 
  published and distributed, in whole or in part, without restriction of 
  any kind, provided that the above copyright notice and this 
  paragraph are included on all such copies and derivative works. 
  However, this document itself may not be modified in any way, 
  such as by removing the copyright notice or references to OASIS, 
  except as needed for the purpose of developing OASIS 
  specifications, in which case the procedures for copyrights defined 
  in the OASIS Intellectual Property Rights document must be 
  followed, or as required to translate it into languages other than 
  English. 

  The limited permissions granted above are perpetual and will not be 
  revoked by OASIS or its successors or assigns. 

  This document and the information contained herein is provided on 
  an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, 
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 
  WARRANTY THAT THE USE OF THE INFORMATION HEREIN 
  WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 
  WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 
  PARTICULAR PURPOSE.    
-->

Throughout the fragments are short XML comments delineating sections with declarations for different purposes.

The built-in version annotation of the schema document element is used to reflect the version of the UBL release. For example, this is used for every schema fragment in the UBL 2.3 release:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="2.3" ...

The UBL common ABIE library schema fragment is named UBL-CommonAggregateComponents-2.3.xsd in UBL 2.3.

Each UBL document ABIE schema fragment is named UBL-XXXXX-2.3.xsd in UBL 2.3, where XXXXX is the component name of the document ABIE.

There is only one addition in the UBL implementation of declarations as in the naming and design rules. The element declaration in a document ABIE includes an annotation as follows:

<xsd:annotation>
   <xsd:documentation>This element MUST be conveyed as the root element 
in any instance document based on this Schema expression</xsd:documentation>
</xsd:annotation>

The UBL common BBIE library schema fragment is named UBL-CommonBasicComponents-2.3.xsd in UBL 2.3.

There are no differences in the UBL implementation of declarations as in the naming and design rules.

The UBL common extension library schema fragment is named UBL-CommonExtensionComponents-2.3.xsd in UBL 2.3.

The UBL extension collection element is named "UBLExtensions" and its type is named "UBLExtensionsType". It is comprised of one or more UBL extension elements.

The UBL extension element is named "UBLExtension" and its type is named " UBLExtensionType". It is comprised of the following elements, in order, each with a type named by the element name suffixed with "Type", each with a cardinality of 0..1, and those declared in the module are declared with the given unqualified data type:

The UBL implementation of the extension content data type schema fragment imposes "lax" processing on a single, mandatory element of type xsd:any. The schema fragment imports the UBL common digital signature extension in order to impose that extension's schema constraints when the signature extension element is used.

The UBL common digital signature extension schema fragment is named UBL-CommonSignatureComponents-2.3.xsd in UBL 2.3.

The UBL qualified data type schema fragment is named UBL-QualifiedDataTypes-2.3.xsd in UBL 2.3.

The UBL implementation of qualified data types is pass-through. There are no data type qualifications expressed in XSD semantics. Data type qualifications are validated solely through the expression of code list constraints using CVA expressions and genericode code list expressions.

The UBL unqualified data type schema fragment in UBL 2.3 is the BDNDR 1.1 fragment named BDNDR-UnqualifiedDataTypes-1.1.xsd.

The UBL CCTS Core Component Types schema fragment in UBL 2.3 is the BDNDR 1.1 fragment named BDNDR-CCTS_CCT_SchemaModule-1.1.xsd.

These NDR do not vary from the Business Document NDR in this regard. This section of the documentation exists to maintain alignment of subsequent sections.

The data type qualifications in UBL 2.3 reference code lists whose name matches a name found in the Data Type Qualification information item of all BBIEs. These code lists are found in the following directories:

For completeness, the Binary Object. Mime. Code and Measure. Unit. Code lists, using the names "BinaryObjectMime" and "UnitOfMeasure" respectively, also are included from these directories:

Instance metadata is described for the supplementary components as follows:

<InstanceMetadataSets>
<Annotation>
  <Description>
    <x:p>
      A supplementary component is a piece of metadata describing a
      property of the list of values in which a particular value is
      found.  For example, each code list of currency values has a
      version and when a currency value is specified in a UBL document
      it may be important to specify which version of the currency 
      code list that value is found.  By knowing the list from which a
      value is found, the semantics representated by that value are
      unambiguous.
    </x:p>
    <x:p>
      These sets of supplementary components describe where instance-level
      metadata is found that contains values of list-level metadata from
      genericode files.  Each set is identified in a context using that
      set's unique <x:samp>xml:id=</x:samp> attribute.
    </x:p>
    <x:p>
      Each component pairs an XPath address of the supplementary component
      (specified in <x:samp>address=</x:samp>) relative to the item with
      the code list value in the UBL document, with the XPath address of
      the corresponding list-level metadata item in the genericode file
      (specified in <x:samp>identification=</x:samp>) relative to the
      <x:samp>&lt;Identification></x:samp> element in the code
      list file.
    </x:p>
    <x:p>
      All supplementary components in UBL are defined by the UN/CEFACT Core
      Component Technical Specification (CCTS) Version 2.01 dated
      15 November 2003
      <x:a href="http://www.unece.org/cefact/ebxml/CCTS_V2-01_Final.pdf">
    <x:samp>http://www.unece.org/cefact/ebxml/CCTS_V2-01_Final.
               pdf</x:samp>.</x:a>
      Table 8-2 "Approved Core Component Type Content
      and Supplementary Components" lists the various supplementary
      components available.  The UN/CEFACT 
      UnqualifiedDataTypeSchemaModule-2.0.xsd schema fragment specifies
      the names of the attributes for supplementary components.
    </x:p>
  </Description>
</Annotation>
<InstanceMetadataSet xml:id="cctsV2.01-amount">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Amount. Type</x:samp> supplementary component.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="../@currencyCodeListVersionID"
                    identification="Version"/>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-binary">
  <Annotation>
    <Description>
      <x:p>
        There are no supplementary components for the
        <x:samp>Binary Object. Type</x:samp>.
      </x:p>
    </Description>
  </Annotation>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-code">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Code. Type</x:samp> supplementary components.
      </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>
        The <x:samp>Identifier. Type</x:samp> supplementary components.
      </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>
<InstanceMetadataSet xml:id="cctsV2.01-measure">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Measure. Type</x:samp> supplementary component.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="../@unitCodeListVersionID"
                    identification="Version"/>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-quantity">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Quantity. Type</x:samp> supplementary components.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="../@unitCodeListID"
                    identification="LongName[@Identifier='listID']"/>
  <InstanceMetadata address="../@unitCodeListAgencyName"
                    identification="Agency/LongName"/>
  <InstanceMetadata address="../@unitCodeListAgencyID"
                    identification="Agency/Identifier"/>
</InstanceMetadataSet>
</InstanceMetadataSets>

The following contexts are described for attributes:

The following contexts are described for elements: