Universal Business Language (UBL) 2.0 Naming and Design Rules

A document schema is a schema within a specific namespace that conveys the business document functionality of that namespace. The document schema declares a target namespace and is likely to include (xsd:include) internal schema modules or import (xsd:import) external schema modules. Each namespace will have one, and only one, major version of a document schema as well as any related minor versions.

In order to facilitate the management and reuse of UBL constructs, all global elements, excluding the root element of the document schema, must be declared in either the Common Aggregate Components (CAC) or Common Basic Components (CBC) schema modules and referenced from within the document schema.

Only a single global element is declared inside a UBL document schema. The single global element is the root element of every conforming instance.

A primary aspect of the UBL library documentation is its spreadsheet models. The entries in these spreadsheet models fully define the constructs available for use in UBL business documents. The spreadsheet entries contain fully conformant CCTS Dictionary Entry Names (DENs) as well as truncated UBL XML element names developed in conformance with the rules in Section 4. The XML element name is the short form of the DEN. The rules for element naming differ from the rules for DEN naming.

The FQP anchors the use of the element or attribute to a particular location in a business message. Any semantic dependencies that the element or attribute has on other elements and attributes within the UBL library that are not otherwise enforced or made explicit in its structural definition can be found in its prose definition.

UBL elements are global and qualified. Hence in the example below, the Address element is directly reusable as a modular component.

<xsd:element name="Party" type="PartyType"/>
  <xsd:complexType name="PartyType">
    <xsd:annotation>
      <!-- Documentation goes here -->
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element ref="cbc:MarkCareIndicator" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      <xsd:element ref="cbc:MarkAttentionIndicator" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      <xsd:element ref="PartyIdentification" minOccurs="0" maxOccurs="unbounded">
          ...
      </xsd:element>
      <xsd:element ref="PartyName" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      <xsd:element ref="Address" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
          ...
    </xsd:sequence>
  </xsd:complexType>

  <xsd:element name="Address" type="AddressType"/>

  <xsd:complexType name="AddressType">
      ...
    <xsd:sequence>
      <xsd:element ref="cbc:CityName" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      <xsd:element ref="cbc:PostalZone" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
          ...
    </xsd:sequence>
  </xsd:complexType>

Software written to work with UBL's standard library should work with new assemblies of the same components, since global elements will remain consistent and unchanged. The globally declared <Address> element is fully reusable without regard to the reusability of types and provides a solid mechanism for ensuring that extensions to the UBL core library will provide consistency and semantic clarity regardless of their placement within a particular type.

Neither XML 1.0 nor XSD requires the use of namespaces. However, the use of namespaces is essential to managing the complex UBL library. UBL uses UBL-defined schemas (created by the UBL TC) and UBL-used schemas (created by external activities), and both require a consistent approach to namespace declarations.

Each UBL schema module consists of a logical grouping of lower level artefacts that can be used in a variety of UBL schemas. These schema modules are grouped into a schema set. Each schema set is assigned a namespace that identifies that group of schema modules. As constructs are changed, new versions are to be created. The schema set is the versioned entity; all schema modules within that package are of the same version, and each major version has a unique namespace.

Schema validation ensures that an instance conforms to its declared schema. In keeping with Rule NMS1, each UBL schema module is part of a versioned namespace.

UBL's extension methodology encourages a wide variety in the number of schema modules that are created as derivations from UBL schema modules. Customized schemas should not be confused with those developed by UBL.

A UBL namespace name must be a URI that conforms to RFC 2396. UBL has adopted the Uniform Resource Name (URN) scheme as the standard for URIs for UBL namespaces, in conformance with IETF's RFC 3121.

Rule NMS2 requires separate namespaces for each UBL major version schema set. In accordance with OASIS procedures, the UBL namespace rules differentiate between committee draft and OASIS Standard status. For each schema holding draft status, a UBL namespace must be declared and named.

The format for document-id is found in Section 3.6.

For each UBL schema holding OASIS Committee Specification or Standard status, a UBL namespace must be declared and named using the same notation, but with the value "specification" replacing the value "tc".

UBL schemas use a URN namespace scheme. In contrast, schema locations are defined as a Uniform Resource Locator (URL). UBL schemas must be available both at design time and run time. Therefore, the UBL schema locations will differ from the UBL namespace declarations. UBL uses an OASIS URL for hosting retrievable copies of UBL schemas.

UBL namespaces use URNs to provide name persistence. UBL namespaces must never change once they have been declared. Conversely, changes to a schema may result in a new namespace declaration. Thus, a published schema version and its namespace association will always be inviolate.

UBL namespaces conform to the OASIS namespace rules defined in RFC 3121. All UBL namespace URIs have the form:

urn:oasis:names:specification:ubl:schema:xsd:<modulename>-<major>

where <modulename> is the name of the schema module and <major> is a positive integer representing the major version. The field containing <modulename>-<major> is called the document-id.

The value of <major> is "1" for the first release of a namespace. For example, the namespace URI for the first major release of the Invoice domain has the form:

urn:oasis:names:specification:ubl:schema:xsd:Invoice-1

Subsequent major releases increment the value by 1. For example, the second major release of the Invoice domain has the URI

urn:oasis:names:specification:ubl:schema:xsd:Invoice-2

The rule for minor version releases is as follows:

For example, the fifth minor version of the release based on the second major release mentioned above will have the URI

urn:oasis:names:specification:ubl:schema:xsd:Invoice-2

As can be seen, both the rule and the example for the minor version releases is exactly the same as that for the major version. There is even a rule stating this directly.

However, minor versioning is handled differently in the xsd:schema element.

UBL uses the version attribute in the xsd:schema element to convey minor version releases of the schema module.

UBL version information can also be captured in instances of UBL document schemas via the ubl:UBLVersionID element.

UBL relies extensively on modularity in schema design. There is no single UBL root schema. Rather, there are a number of UBL document schemas used to perform different business functions. UBL is structured so that users can reuse individual document schemas without having to import the entire UBL document schema library. A document schema can import individual modules without having to import all UBL schema modules. Each document schema defines its own dependencies. The UBL schema modularity approach reflects logical associations that exist between document and internal schema modules,and it ensures that individual modules can be reused to the maximum extent possible. If the contents of a namespace are small enough then they can be completely specified within a single document. Document and internal schema modules are shown in Figure 5.

Figure 5. UBL Schema Modularity Model

Figure 5 shows the one-to-one correspondence between document schemas and namespaces. It also shows the one-to-one correspondence between files and schema modules. As shown here, there are two types of schemas in the UBL library — document schemas and schema modules. Both types of schemas are conformant with XSD.

Each document schema occupies its own namespace and may include zero or more internal modules. The namespace for a document schema includes any of its internal modules. Schema modules that are not internal to a document occupy a different namespace, as in the qdt, cbc, and cac schema modules.

Figure 6. Schema Modules

Another way to visualize the structure is by example. Figure 6 depicts instances of the various schema modules from the previous diagram.

Figure 7 shows how the Order and Invoice document schemas import the CommonAggregateComponents and CommonBasicComponents external schema modules. It also shows how the Order document schema may include internal schema modules — modules local to that namespace. The clear boxes show how the various schema modules are grouped into namespaces.

Any UBL schema module, be it a document schema or an internal module, may import other document schemas from other namespaces.

Figure 7. Order and Invoice Schema Import of Common Component Schema Modules

If two namespaces are mutually dependent, then importing one will cause the other to be imported as well. For this reason there must not exist circular dependencies between UBL schema modules. By extension, there must notexist circular dependencies between namespaces. A namespace A dependent upon type definitions or element declarations defined in another namespace B must import B's document schema.

An additional rule is necessary to address potentially circular dependencies as well — schema A must not import internal schema modules of schema B.

As illustrated in figures 5 and 6, UBL schema modules are either internal or external.

UBL internal schema modules do not declare a target namespace, but instead reside in the namespace of their parent schema. All internal schema modules are accessed using xsd:include.

UBL internal schema modules must have semantically meaningful names. Internal schema module names identify the parent schema module, the internal schema module function, and the schema module itself.

Example: ExtensionContentDatatype

External schema modules are used to group complex types and global elements that are used in multiple document schemas.

UBL external schema modules organize the reusable components into logical groupings. At a minimum, UBL defines the following external schema modules:

In addition, UBL 2.0 uses the following schema modules provided by UN/CEFACT.

Furthermore, where extensions are used, an extension schema module must be provided. This schema module must be named:

CommonExtensionComponents

To ensure consistency in expressing the CommonExtensionComponents schema module, a namespace prefix that will be used in all UBL schemas must be defined.

The annotation needed to satisfy CCTS requirements considerably increases the size of the UBL schemas, with undesirable performance impacts. To address this issue, a cut-down alternative has been developed for each UBL schema. A normative, fully annotated schema is provided to facilitate greater understanding of the schema module and its components and to meet the CCTS metadata requirements. A non-normative schema devoid of annotation is provided that can be used at run-time if required to meet processor resource constraints.

UBL spreadsheets contain all necessary information to produce fully annotated schemas, including information about each UBL BBIE. UBL annotations consist of information currently required by Section 7 of the CCTS and supplemented by metadata from the UBL spreadsheet models.

The absence of an optional annotation from the structured set of annotations in a documentation element implies the use of the default value. For example, there are several annotations relating to context, such as CCTS Business Context and CCTS Industry Context; their absence implies that their value is "all contexts".

The following rules describe the documentation requirements for each UBL Qualified Datatype and UBL Unqualified Datatype definition. None of these documentation rules apply in the case of extension where the UBL Extensions element is used.

The following rule describes the documentation requirements for each Basic Business Information Entity definition.

The following rule describes the documentation requirements for each CCTS Aggregate Business Information Entity definition.

The following rule describes the documentation requirements for each CCTS Association Business Information Entity definition.

UBL xsd:complexType names for ABIEs are derived from their DENs by removing separators to follow general naming rules and appending the suffix "Type" to replace the word "Details".

All BBIE Properties are reusable across multiple BBIEs. The CCTS does not specify, but implies, that BBIE Property names are the reusable property term and representation term of the family of BBIEs that are based on them. The UBL xsd:complexType names for BBIE Properties are derived from the shared Property and Representation terms portion of the DENs in which they appear by removing separators to follow general naming rules and appending the suffix "Type".

For example, a UBL xsd:complexType name based on the ABIE Party. Details will be PartyType. The global element based on PartyType will be named Party.

<xsd:element name="Party" type="PartyType"/>
  <xsd:complexType name="PartyType">
    <xsd:annotation>
      <!-- Documentation goes here -->
    </xsd:annotation>
    <xsd:sequence>
      <xsd:element ref="cbc:MarkCareIndicator" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      <xsd:element ref="cbc:MarkAttentionIndicator" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      <xsd:element ref="PartyIdentification" minOccurs="0" maxOccurs="unbounded">
          ...
      </xsd:element>
      <xsd:element ref="PartyName" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      <xsd:element ref="Address" minOccurs="0" maxOccurs="1">
          ...
      </xsd:element>
      ...
    </xsd:sequence>

The same naming concept used for ABIEs applies to BBIE Properties.

<!--===== Basic Business Information Entity Type Definitions =====-->
<xsd:complexType name="ChargeIndicatorType">
    ...
</xsd:complexType>
    ...
<!--===== Basic Business Information Entity Property Element Declarations =====-->
<xsd:element name="ChargeIndicator" type="ChargeIndicatorType"/>

An ASBIE is not a class like an ABIE or a BBIE Property that is reused as a BBIE. Rather, it is an association between two classes. Therefore, an element representing an ASBIE does not have its own unique xsd:complexType. Instead, when an element representing an ASBIE is declared, the element is bound to the xsd:complexType of its associated ABIE by referencing the ABIE's global element declaration.

Since UBL elements and types are intended to be reusable, all types must be named. This permits other types to establish elements that reference these types, and also supports the use of extensions for the purposes of versioning and customization.

<xsd:complexType name="QuantityType">
    ...
</xsd:complexType>

UBL disallows the use of the type xsd:anyType, because this feature permits the introduction of potentially unknown types into an XML instance.

CCTS provides a set of constructs called Core Component Types (CCTs) for the modeling of basic data. These are represented in UBL with a library of complex types. Most "simple" data is represented as property sets defined according to the CCTs, made up of content components and supplementary components. In most cases, the supplementary components are expressed as XML attributes, the content component becomes element content, and the CCT is represented with an xsd:complexType. There are exceptions to this rule in those cases where all of a CCT's properties can be expressed without the use of attributes. In these cases, an xsd:simpleType is used.

UBL does not define its own simple types. These are defined in the UN/CEFACT Unqualified Datatype schema module. UBL defines restrictions of these simple types in the UBL Qualified Datatype schema module.

Since even simple datatypes are modeled as property sets in most cases, the XML expression of these models primarily employs xsd:complexType. To facilitate reuse, versioning, and customization, all complex types are named. In the UBL model, ABIEs are considered classes (objects) .

<xsd:complexType name="BuildingNameType">
</xsd:complexType>

Every class identified in the UBL model consists of properties. These properties are either ASBIEs, when the property represents another class, or BBIEs.

<xsd:complexType name="AddressType">
    ...
  <xsd:sequence>
    <xsd:element ref="cbc:CityName" minOccurs="0" maxOccurs="1">
        ...
    </xsd:element>
    <xsd:element ref="cbc:PostalZone" minOccurs="0" maxOccurs="1">
        ...
    </xsd:element>
    ...
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="StreetNameType">
  <xsd:simpleContent>
    <xsd:extension base="udt:NameType"/>
  </xsd:simpleContent>
</xsd:complexType>

The binding of UBL elements to their xsd:complexTypes is based on the associations identified in the UBL model. For the BBIEs and ABIEs, the UBL elements are directly associated to their corresponding xsd:complexTypes.

<xsd:element name="SupplierParty" type="SupplierPartyType"/>
	<xsd:complexType name="SupplierPartyType"/>
    ...
</xsd:complexType>

An ASBIE is not a class like an ABIE. Rather, it is an association between two classes, and therefore the element declaration binds the element to the xsd:complexType of the associated ABIE. There are two types of ASBIEs — those that have qualifiers in the object class, and those that do not.