Universal Business Language 1.0

Publication Date

15 September 2004

Document identifier


Editorial Status

This document is an OASIS Committee Draft.



Downloadable Package Location



Bill Meadows <meadows.bill@comcast.net>

Lisa Seaburg, Aeon LLC <lseaburg@aeon-llc.com>


Members of the Technical Committee


This specification defines the Universal Business Language.


This document is a Committee Draft of the OASIS Universal Business Language (UBL) Technical Committee. The OASIS UBL Technical Committee invites interested parties to comment on this release using the comment link on the UBL TC web page:


Table of Contents

1 Introduction

2 Normative References

3 Terms and Definitions

4 Symbols and Abbreviations

5 UBL 1.0 Procurement Process

6 UBL 1.0 Schemas

Appendix A (Informative): Release Notes

Appendix B (Informative): UBL Methodology

Appendix C (Informative): Formatting Specifications

Appendix D (Informative): Example Instances

Appendix E (Informative): Code Lists

Appendix F (Informative): ASN.1 Specification

Appendix G (Informative): Ongoing Work Items

Appendix H: Notices

1 Introduction

Since its approval as a W3C recommendation in 1998, XML has been adopted in a number of industries as a framework for the definition of the messages exchanged in electronic commerce. The widespread use of XML has led to the development of multiple industry-specific XML versions of such basic documents as purchase orders, shipping notices, and invoices.

While industry-specific data formats have the advantage of maximal optimization for their business context, the existence of different formats to accomplish the same purpose in different business domains is attended by a number of significant disadvantages as well.

The OASIS Universal Business Language (UBL) is intended to help solve these problems by defining a generic XML interchange format for business documents that can be extended to meet the requirements of particular industries. Specifically, UBL 1.0 provides the following:

A standard basis for XML business schemas is expected to have the following advantages:

UBL is designed to provide a universally understood and recognized commercial syntax for legally binding business documents and to operate within a standard business framework such as ISO 15000 (ebXML) to provide a complete, standards-based infrastructure that can extend the benefits of existing EDI systems to businesses of all sizes. UBL is freely available to everyone without legal encumbrance or licensing fees.

UBL schemas are modular, reusable, and extensible in XML-aware ways. Designed as an implementation of ebXML Core Components Technical Specification 2.01, the UBL Library is based on a conceptual model of information components known as Business Information Entities (BIEs). These components are assembled into specific document models such as Order and Invoice. These document assembly models are then transformed in accordance with UBL Naming and Design Rules into W3C XSD schema syntax. This approach facilitates the creation of UBL-based document types beyond those specified in this 1.0 release. This document describes the basic order-to-invoice business process that the UBL document types are designed to support.

To aid in deployment, the standard UBL schemas are accompanied by a multitude of informative supporting materials, some of which are included in this package as informative appendices and some of which are available from referenced sites. These materials include:

2 Normative References

[ASN.1] ITU-T X.680-X.683: Abstract Syntax Notation One (ASN.1); ITU-T X.690-X.693: ASN.1 encoding rules
[CCTS] UN/CEFACT ebXML Core Components Technical Specification 2.01
[ISO11179] ISO/IEC 11179-1:1999 Information technology — Specification and standardization of data elements — Part 1: Framework for the specification and standardization of data elements
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels
[UML] Unified Modeling Language Version 1.5 (formal/03-03-01)
[XML] Extensible Markup Language (XML) 1.0 (Second Edition),W3C Recommendation 6 October 2000
[XSD1] XML Schema Part 1: Structures, W3C Recommendation 2 May 2001
[XSD2] XML Schema Part 2: Datatypes, W3C Recommendation 2 May 2001

3 Terms and Definitions

Assembly model
A tree-structured model that can be implemented as a document schema.
Class diagram
A graphical notation used by [UML] to describe the static structure of a system, including object classes and their attributes and associations.
Component model
A representation of normalized data components describing a potential network of associations and roles between object classes.
The circumstance or events that form the environment within which something exists or takes place.
Dependency diagram
A refinement of a class diagram that emphasizes the dependent associations between object classes.
A set of information components that are interchanged as part of a business transaction; for example, in placing an order.
Functional dependency
A means of aggregating components based on whether the values of a set of properties change when another set of properties changes, that is, whether the former is dependent on the latter.
A formal technique for identifying and defining functional dependencies.
Spreadsheet model
A representation of an assembly model in tabular form.
XSD schema
An XML document definition conforming to the W3C XML Schema language [XSD1][XSD2].

The terms Core Component (CC), Basic Core Component (BCC), Aggregate Core Component (ACC), Association Core Component (ASCC), Business Information Entity (BIE), Basic Business Information Entity (BBIE), and Aggregate Business Information Entity (ABIE) are used in this specification with the meanings given in [CCTS].

The terms Object Class, Property Term, Representation Term, and Qualifier are used in this specification with the meanings given in [ISO11179].

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL, when they appear in this document, are to be interpreted as described in [RFC2119].

4 Symbols and Abbreviations

Aggregate Business Information Entity
Aggregate Core Component
Association Business Information Entity
Association Core Component
Basic Business Information Entity
Basic Core Component
Business Information Entity
Core Component
European Article Numbering Association
Electronic Data Interchange
International Organization for Standardization
UBL Naming and Design Rules (see Appendix B.4)
Unified Modeling Language [UML]
United Nations Centre for Trade Facilitation and Electronic Business
Extensible Markup Language [XML]
W3C XML Schema Language [XSD1] [XSD2]

5 UBL 1.0 Procurement Process

The UBL 1.0 documents and component library are designed to support a typical order-to-invoice procurement cycle. This section describes the business rules and choreography of the generic process and the role played by each of the UBL 1.0 document types in that process.

It is important to note that the UBL library is designed to support the construction of a wide variety of document types beyond those provided in the 1.0 package. It is expected that other document types will be added as UBL evolves.

5.1 The Order-to-Invoice Cycle

This model describes a basic trading cycle from Order to Invoice that involves three parties: a Buyer of goods, a Seller of goods, and a Recipient of goods, who may or may not be the Buyer. The document types provided by UBL to support this process include the following:


Order Response Simple

Order Response (detailed)

Order Change

Order Cancellation

Despatch Advice

Receipt Advice


The bold boxes in the diagram below show the role of each document type in the generic process.

[order-to-invoice diagram]

Figure 1. Order-to-Invoice Business Process

5.2 Document Business Rules

This section describes the business rules of the generic order-to-invoice process that are assumed as information requirements for the document types in UBL 1.0.

5.2.1 Order

The Order may specify allowance and charge instructions (e.g. freight, documentation, etc.) that identify the type of charge and who pays which charges. The Order can be placed “on account” against a trading credit account held by the Seller, or against a credit/debit card account, or a direct debit agreement. The Order allows for an overall currency defining a default for all pricing and also a specific currency to be used for Invoicing. Within an Order, additional currencies can be specified both for individual item pricing and for any allowances or charges.

Trade discount may be specified at the Order level. The Buyer may not know the trade discount, in which case it is not specified. This makes a detailed response from the Seller necessary; see Order Response (5.2.3).

The Order may specify delivery terms and constraints that apply for the delivery location in relation to the following information that would normally not appear until the Despatch Advice:

The Order provides for multiple Order Lines. Each Order Line provides for specification of a single place of delivery, and a schedule of quantities and requested delivery dates.

The Order may specify delivery terms, while the Order Line may provide instructions for delivery.

The Buyer may indicate potential alternatives that are acceptable. For each Order Line, an Alternative Item can be included. The Alternative Item may be specified by any one of the range of Item identifiers. For example, the specified Quantity may change, e.g. 20x6-packs as an alternative to 10x12-packs.

5.2.2 Order Response Simple

The Order Response Simple is the means by which the Seller confirms receipt of the Order from the Buyer, indicating either commitment to fulfill without change or that the Order has been rejected.

5.2.3 Order Response

Proposed changes by the Seller are accomplished through the full Order Response document.

The Order Response proposes to replace the original Order. It reflects the entire new state of an order transaction. It also is the means by which the Seller confirms or supplies Order-related details to the Buyer that were not available to, or specified by, the Buyer at the time of ordering. These may include:

The Seller may advise replacements or substitutes which will be made, or changes necessary, using the Order Response. The Substitute or Replacement Item may be specified by any one of the range of Item identifiers. For example, the specified Quantity may change, e.g. 20x6-packs as a replacement for 10x12-packs.

5.2.4 Order Change

The Buyer can change an established Order in two ways, subject to the legal contract or trading partner agreement: first, by sending an Order Change, or second, by sending an Order Cancellation (see 5.2.5) followed by a new, complete replacement Order.

An Order Change reflects the entire current state of an order transaction.

Buyers can initiate a change to a previously accepted order for various reasons, such as changing ordered items, quantity, delivery date, ship-to address, etc. Suppliers can accept or reject the Order Change using either Order Response or Order Response Simple.

5.2.5 Order Cancellation

At any point of the process, a Buyer can cancel an established order transaction using the Order Cancellation document. Legal contracts, trading partner agreements, and business rules will restrict at what point an Order Cancellation will be ignored (e.g. at the point of manufacture or delivery process initiation). Given the agreements and rules, an Order Cancellation may or may not be an automated business transaction. The terms and conditions of contract formation for business commitments will dictate which, if any, of these restrictions or guidelines will apply.

5.2.6 Despatch Advice

The following information may appear in the Despatch Advice:

The Despatch Advice provides for two situations:

Additionally, in either case, the Despatch Advice can advise:

Despatch Lines of the Despatch Advice need not correspond one-to-one with Order Lines, and are linked by a reference. The information structure of the Despatch Advice may result in multiple Despatch Lines from one Order Line. Equally, partial despatch may result in some Order Lines not being matched by any Line in a Despatch Advice.

Within a Despatch Advice, an Item may also indicate the Country of Origin and the Hazardous nature of the Item.

5.2.7 Receipt Advice

The Receipt Advice is sent by the Receiver (Buyer) to the Seller to confirm receipt of items and is capable of reporting shortages or damaged items.

The Receipt Advice provides for two situations. For ease of processing claimed receipt against claimed delivery, it must be organised in the same way as the corresponding Despatch Advice:

The Receipt Advice allows the Receiver to state any shortages from the claimed despatch quantity and to state any quantities rejected for a given reason.

As presently arranged, the Receipt Line allows for one rejection quantity and reason. However, additional reasons for rejection of quantities of the same item could be achieved by subdividing the Receipt Line so that there are multiple Receipt Lines to one Despatch Line.

5.2.8 Invoice

The Invoice is normally issued on the basis of one despatch event triggering one invoice. An Invoice may also be issued for pre-payment on a whole or partial basis. The possibilities are:

The Invoice only contains the information that is necessary for invoicing purposes. It does not reiterate any information already established in the Order, Order Change, Order Response, Despatch Advice, or Receipt Advice that is not necessary when invoicing. If necessary, the Invoice refers to the Order, Despatch Advice or Receipt Advice by a Reference for those documents.

Taxation on the Invoice allows for compound taxes, the sequence of calculation being implied by the sequence of information repeated in the data stream (e.g., Energy tax, with VAT — Value Added Tax — superimposed).

Charges can be specified either as a lump sum or by percentage applied to the whole Invoice value prior to calculation of taxes. Such charges cover:

Each Invoice Line refers to any related Order Line(s) and may also refer to the Despatch Line and/or Receipt Line.

The Invoice does not cover Debit and Credit Notes, nor does the process include a Customer Account Statement that summarises Invoices, Credit Notes, and Debit Notes to be paid.

5.3 Item Business Rules

Item structures are found throughout the document types in the generic process.

5.3.1 Item Identification

An Identifier identifies each Item (e.g. a product identifier), which shall be one of the following:

The Item Identification assumes that each different packaging of an Item (e.g. a 6-pack and a 12-pack of the same item) has a different Item Identifier.

The Item may be further distinguished by the specification of Measurement(s) or Physical Attribute(s). This enables specification of the following kinds of item: Item Requiring Description

This is an item that is not identified by an unambiguous machine-processable product code and requires additional descriptive information to precisely identify it. Customer Defined Item

This is an item that the customer describes according to his need, and in the specification of which the customer may make some reference to comparable “standard” items. Item Requiring Measurements

This is an item for which it is necessary to specify one or more measurements as part of the descriptive specification of the item.

5.3.2 Item Pricing

For any given Item, price ranges by amount, quantity, etc. are not repeated back to the Seller; only the active price is specified. The Buyer may not know the Item Base Price, in which case it is not specified. This makes a detailed response from the Seller necessary; see OrderResponse.

5.3.3 Other Item Details

Although ordered items may include Hazardous items, as it is not necessary to specify related information at the order stage. The Buyer may not be aware of the nature of the Item. Indication of the Hazardous nature of the Item, and any relevant information, would be indicated in the Despatch Advice.

6 UBL 1.0 Schemas

The UBL XSD schemas are implementations of the document assembly models defined by UBL. They are the only normative representation of the UBL 1.0 document types and library components.

All of the UBL 1.0 XSD schemas are contained in the xsd/ subdirectory of the UBL 1.0 release package (see Appendix A for more information regarding the structure of the 1.0 release package and Section 6.4 for information regarding dependencies among the schema modules). The xsd/ directory is further subdivided into xsd/maindoc/, xsd/common/, and xsd/codelist/ subdirectories.

For convenience in implementing the schemas, a parallel (and technically non-normative) “runtime” set with the annotation elements stripped out is provided in the xsdrt/ directory.

6.1 UBL Document Schemas

The XSD schemas defining the eight basic document types that support the generic UBL 1.0 order-to-invoice process are located in the xsd/maindoc/ directory, as listed below.

Order Response
Order Response Simple
Order Change
Order Cancellation
Despatch Advice
Receipt Advice

6.2 UBL Common Schemas

The xsd/common directory contains six schemas referenced by the eight document schemas in xsd/maindoc. Two of these common schemas contain the UBL library of reusable data components from which the main document schemas are assembled; three contain definitions needed to implement [CCTS] conformance; and one provides a consistent format for schema metadata. The name of each schema file together with a brief description of its contents is given below.

6.2.1 Reusable BIE Schemas

Common Basic Components
This schema defines the global Basic Business Information Entities (BBIEs) that are used throughout UBL, serving, in effect, as a “global BBIE type database” for constructing documents. As specified by the UBL Naming and Design Rules, this schema does not include BBIEs having Code or Identifier datatypes; these are defined locally wherever they are used.
Common Aggregate Components
This schema defines the Aggregate Business Information Entities (ABIEs) that are used throughout UBL, serving, in effect, as an “ABIE type database” for constructing the main documents.

6.2.2 Reusable Datatype Schemas

Core Component Types
This schema provides Core Component Types as defined by [CCTS]. These types are used to construct higher-level datatypes in a standardized and consistent manner. This schema should not be modified.
Unspecialized Datatypes
This schema defines Unqualified Data Types for primary and secondary representation terms as specified by [CCTS]. Derived from Core Component Types, these XSD complexType structures are the basic data types from which all other data types must derive. This schema should not be modified.
Specialized Datatypes
This schema provides Qualified Data Types as defined by [CCTS]. These XSD complexType structures are derived from Unspecialized Datatypes by extension, restriction, and other contextual constraints, such as facets. The Specialized Datatypes have been customized for the UBL 1.0 procurement process and may be further extended to support additional datatypes required for other business contexts.

NOTE: The terms “specialized” and “unspecialized” are used instead of the terms “qualified” and “unqualified” in order to avoid confusion with qualified and unqualified names in [XSD1][XSD2].

6.2.3 Documentation Metadata Schema

Core Component Parameters
This schema defines the structure of the annotation/documentation sections that appear in all the other schemas, providing a consistent format for metadata such as object class, representation terms, semantic descriptions, and other supplementary information.

6.3 UBL Code List Schemas

The thirteen code list schemas required for UBL 1.0 are included in the xsd/codelist directory. These code list schemas allow component instances conformant to any of the main document schemas to be validated against code list values. See Appendix E for further information about the form of representation used for UBL code lists.

Acknowledgement Response Code
Allowance Charge Reason Code
Channel Code
Chip Code
Country Identification Code
Currency Code
Document Status Code
Latitude Direction Code
Line Status Code
Longitude Direction Code
Operator Code
Payment Means Code
Substitution Status Code

6.4 Schema Dependencies

The following diagram shows the dependencies among the schema modules comprising a UBL 1.0 document schema. Note that (as in the other UML diagrams used in this release) dependent components point to the components upon which they depend.

[schema dependency diagram]

Figure 2. UBL Schema Dependencies

Appendix A (Informative): Release Notes

A.1 Availability

Online and downloadable versions of this release are available from the locations specified at the top of this document.

A.2 Package Structure

The UBL 1.0 specification is published as a zip archive named cd-UBL-1.0.zip. Unzipping this archive creates a directory named cd-UBL-1.0 containing a master hypertext document (this document, index.html) and a number of subdirectories. The files in these subdirectories, linked to from index.html, contain the various normative and informational pieces of the 1.0 release. A description of each subdirectory is given below.

Diagrams and illustrations used in this specification
ASN.1 specification; see Appendix F
Supporting documents created by the UBL TC and referenced in this specification
Formatting specifications; see Appendix C
UBL spreadsheet models; see Appendix B.3
UML diagrams; see Appendices B.2, B.3, and B.6
Example instances; see Appendix D
XSD schemas; see Section 6
“Runtime” XSD schemas; see Section 6

A.3 Tools

UBL has inspired the creation of both free and commercial UBL tools. A list of tools currently available for UBL can be found on the web page of the UBL Software Subcommittee:


A.4 Support

UBL is a volunteer project of the international business community. Inquiries regarding UBL may be posted to the public ubl-dev list, archives for which are located at


Subscriptions to ubl-dev can be made through the OASIS list manager at


A.5 Recursive Structures

Certain components in the library allow recursive nesting. For example, a Package may contain other Packages, a Delivery may specify another Delivery, etc. These are legitimate business data structures. Most real-world applications will limit the depth of recursion in such structures, but XSD schemas are incapable of expressing this constraint. Implementors should be aware of this and may wish to set limits on the depth of recursive structures in their applications.

Appendix B (Informative): UBL Methodology

B.1 The UBL Development Approach

UBL does not mandate the use of a specific formal development method. The purpose of this section is to describe the process that evolved during the development of UBL so that implementers can understand the role of the various technical artifacts included in this package. They may also choose to adapt this approach to suit their requirements.

The approach used to develop UBL 1.0 is shown in the diagram below.

[development process diagram]

Figure B-1. The UBL Development Process

The initial UBL library of data components was based upon the xCBL 3.0 schema library, which was itself based on the UN/EDIFACT and ANSI X12 EDI component libraries. Upon review, it was felt necessary to create an abstracted conceptual model of the entities in a form that would better support an iterative development lifecycle.

UBL uses two types of conceptual models, a single model for defining information components and a set of models for describing how these components are assembled into document definitions. The former is referred to as the document component model and is generally presented using UML class diagrams (see B.2 below); the latter are referred to as the document assembly models and are generally presented using spreadsheets.

The identification and assembly of the components required by the UBL 1.0 Procurement Process was carried out manually using business knowledge of the domain, the component model, and the requirements of [CCTS]. Individual spreadsheets were developed for each document type in the UBL 1.0 procurement scenario, and all re-used components were combined into a separate spreadsheet. Additional spreadsheets were used to model the Core Component Types (CCTs), Unspecialized Datatypes (UDTs), and Specialized Datatypes (SDTs) as specified by [CCTS]. The full set of spreadsheet assembly models used by UBL 1.0 is described in Section B.3.

The UBL schemas contained in Section 6 of this specification were then generated automatically from the spreadsheet assembly models following the UBL Naming and Design Rules referenced in Section B.4 according to the process described in Section B.5. Implementation models were then generated from the schemas to serve as an aid in implementing UBL. These UML class diagrams, provided in Section B.6, represent the implementation of the document assembly models described in the spreadsheets.

B.2 Component Model

The UBL document component model describes the information components used in all of the documents defined by UBL 1.0.

The document component model is the result of a detailed analysis of the data requirements to support the UBL 1.0 Procurement Process (see Section 5). During the modeling process, common items of data were identified by a process of normalization to identify aggregates based on functional dependency. Where appropriate, these were generalized so that they could be re-used to support the various business documents.

The document component model is used for the following purposes:

The component model is best viewed as a series of UML Class Diagrams. For legibility, the model does not contain all the metadata required for document assembly.

Figure B-2 shows the overall UBL document component model.

[ubl document component model]

Figure B-2. UBL Document Component Model (click on image to enlarge)

To facilitate comprehension of this diagram, it has been decomposed into several packages. Each package represents a logical grouping of components and is described by its own UML class diagram, which displays both the attributes (Basic BIEs) and object classes (Aggregate BIEs) belonging to the components grouped in the package. The scope of each package is arbitrary and does not hold any significance beyond these diagrams.

For example, the Party reusable component package is shown below.

[party component diagram]

Figure B-3. Party Component Package

The complete set of packages for all the UBL components is listed below.

Address Package
Contract Package
Delivery Package
Document Reference Package
Hazardous Item Package
Item Package
Party Package
Payment Package
Procurement Package
Tax Package

No specific directions are defined for the associations in these models; they can be navigated in either direction. The specific navigation path for each association is defined when documents are assembled.

B.3 Document Assembly Models

To define different types of documents, the components described in the previous section are assembled into hierarachical structures based on the requirements of the context — in this case the UBL 1.0 Procurement Process — and the metadata requirements of [CCTS].

Document assembly starts with the definition of each of the business documents comprising UBL 1.0 as an Aggregate BIE (object class) for the document type. All the other Aggregate BIEs (object classes) for the document type are derived by traversing the associations from this Aggregate BIE to form the required hierarchy. The roles chosen for each association between Aggregate BIEs become Association BIEs.

For example, the document assembly model for the top level of the UBL 1.0 Order document is shown below using a UML class diagram.

[order assembly diagram]

Figure B-4. Order Document Assembly Model

The top level document assembly models for the eight business documents defined by UBL 1.0 are given below.

Order assembly model
Order Response assembly model
Order Response Simple assembly model
Order Change assembly model
Order Cancellation assembly model
Despatch Advice assembly model
Receipt Advice assembly model
Invoice assembly model

While it is possible to develop document assembly models using UML, it was found easier in practice to use a spreadsheet notation, the key advantages being:

These advantages were felt to outweigh the main disadvantage of spreadsheet notation, which is the lack of referential integrity controls in the modeling language itself; manual editing is required to control the impact of changes. In this case, fortunately, the commercial tool used to generate the final schemas from the spreadsheets was also capable of verifying model integrity.

B.3.1 Spreadsheet Models

UBL uses spreadsheets to describe the assembly of components into specific types of documents. There is one spreadsheet assembly model for each document type.

Following the terminology of [CCTS], the document assembly models are composed of a combination of Basic Business Information Entities (the attributes of the component model), Aggregate Business Information Entities (the object classes of the component model), and Association Business Information Entities (the roles of associations in the component model). BBIEs can be considered the “leaf nodes” of the data structures, ABIEs as structures that contain BBIEs, and ASBIEs as the containership of one ABIE within another.

The spreadsheet models use rows to define components. Components are either BIEs or Data Types. Columns define the metadata associated with each component type. Many of the spreadsheet columns are determined by [CCTS] requirements.

A spreadsheet assembly model will therefore consist of a “root” ABIE, a set of BBIEs, and a set of ASBIEs. The ABIEs associated with the “root” ABIE are defined in a Reusable BIE spreadsheet model.

The data types for all BBIEs are defined either in the Unspecialized Datatypes spreadsheet model or the Specialized Datatypes spreadsheet model.

The dependencies among these spreadsheet assembly models are shown in the diagram below.

[spreadsheet model dependency diagram]

Figure B-5. Spreadsheet Model Dependencies

The spreadsheet files included in this package are provided in both Microsoft Excel format (.xls) and Open Office format (.sxc) as described below.

NOTE: The UBL document schemas are automatically generated from these spreadsheet models. However, the normative forms of the UBL documents are not these spreadsheet models but the XSD schemas themselves, which are provided in Section 6.

B.3.2 Document Spreadsheets

Each business information entity (BIE) is defined in a single row. Row background colour distinguishes between BBIE (white), ABIE (pink), and ASBIE (green).

Order document spreadsheet
Order Response document spreadsheet
Order Response Simple document spreadsheet
Order Change document spreadsheet
Order Cancellation document spreadsheet
Despatch Advice document spreadsheet
Receipt Advice document spreadsheet
Invoice document spreadsheet

B.3.3 Common Component Spreadsheets

Reusable BIEs spreadsheet
This model provides the Aggregate Business Information Entities (ABIEs) that are used throughout UBL, serving, in effect, as an “ABIE type database” for constructing the main documents. This model may be modified in customization.
Key: each business information entity (BIE) is defined in a single row. Row background colour distinguishes between BBIE (white), ABIE (pink) and ASBIE (green).
Core Component Types spreadsheet
This model provides Core Component Types as defined by [CCTS]. These types are used to construct higher-level datatypes in a standardized and consistent manner. This model should not be modified.
Key: each core component type (CCT) is defined in a single row. Row background colour distinguishes between Supplementary Components (white) and core component types (pink).
Unspecialized Datatypes spreadsheet
This model specifies Unqualified Data Types as defined by [CCTS]. These types are used to construct higher-level datatypes in a standardized and consistent manner. This model should not be modified.
Key: each data type (DT) is defined in a single row. Row background colour distinguishes between Supplementary Components (white) and data types (pink).
Specialized Datatypes spreadsheet
This model specifies Qualified Data Types as defined by [CCTS]. These types are used to construct higher-level datatypes customized to specific implementations. UBL has chosen to define datatypes for BBIEs that require validation against a code list as Specialized Datatypes. They are specialized forms of the Code datatype with fixed values as given in this model. Note that the implementation of these code lists is realized as individual schemas for each code list. This model may be modified in customization.
Key: each data type (DT) is defined in a single row. Row background colour distinguishes between Supplementary Components (white) and data types (pink).

B.3.4 Customizing Models

While those wishing to customize UBL should follow the guidelines for the customization of UBL 1.0 schemas referenced from B.7 below, those who choose to modify either the Component or Assembly models directly and use UBL as the basis for a new vocabulary should be aware of the following considerations that may impact compatibility with UBL:

The UBL 1.0 document component and document assembly models are the product of the OASIS UBL Library Content Subcommittee. The work of the UBL LCSC can be viewed on the LCSC web page:


B.4 UBL Naming and Design Rules

The UBL XML Naming and Design Rules (NDR) checklist included in this package describes the rules used to determine UBL 1.0 XSD schema structures and element/attribute names. The NDR checklist can be found in this package as the following file:


The UBL Naming and Design Rules are the product of the OASIS UBL NDR Subcommittee. The work of the UBL NDRSC can be viewed on the NDRSC web page:


B.5 Schema Generation

The UBL 1.0 XSD schemas are the output of a transformation that applies schema construction rules to the Data Model represented by the UBL spreadsheets described in B.3 above. The transformation process consisted of the following steps:

  1. Reading in the data model spreadsheets
  2. Building from each spreadsheet an internal UML-based model
  3. Identifying external standards for code lists and including standard code list values as appropriate
  4. Applying UBL Naming and Design Rules
  5. Outputting conformant XSD schemas

A commercial CC-aware schema generation tool, GEFEG EDIFIX® 5.0, was used to read the spreadsheets as UML data models, perform Q/A with them, and produce a schema representation adhering to the UBL 1.0 Naming and Design Rules, as illustrated below. For information regarding GEFEG EDIFIX®, see http://www.gefeg.com/en/standard/xml/ubl.htm. The GEFEG EDIFIX® 5.0 UBL Reader is free and offers easy viewing of UBL schemas and data models. For information regarding GEFEG EDIFIX® UBL Reader, see http://www.gefeg.com/en/edifix/reader-ubl.html.

[ubl schema generation]

Figure B-6. UBL Schema Generation Process

Previous drafts of the UBL specification used different tools for this process. For a description of the process used to produce the UBL 1.0 Beta schemas, see Appendix D of the 1.0 Beta Committee Draft at http://www.oasis-open.org/committees/ubl/lcsc/UBLv1-beta/.

UBL 1.0 schema generation was performed under the direction of the OASIS UBL Tools and Techniques Subcommittee. The work of the UBL TTSC can be viewed on the TTSC web page:


B.6 Implementation Model

The implementation model of UBL represents the actual UBL XSD schemas as a UML model. This is produced by automatically transforming the schemas into a model conformant with the Unified Modeling Language [UML]. This model is then used to produce a set of class diagrams that illustrate each of the main documents and several views of the reusable components. The automated transformation and diagram creation was performed using a commercial schema-to-UML transformation tool, Ontogenics hyperModel. For further details regarding this product, see http://www.xmlmodeling.com/.

The UML class diagrams contained in this section are intended to help understand the UBL schemas without requiring an understanding of XSD syntax. In order to do this, the diagrams intentionally suppress some of the detail contained in the schemas. For example, information regarding the order of elements within a complex type definition is not preserved in the diagrams. Other changes were made to make the UML model useful for software engineering; for example, the “Type” suffixes of XSD complexType names are removed when creating the UML class name to yield an object class name independent of XSD syntax, and complex type child elements with simple content values are represented as class attributes, whereas elements with complex content are represented as associations to those type classes.

These diagrams are the UML equivalent of the document assembly spreadsheet models.

B.6.1 Document Implementation Diagrams

An implementation class diagram has been created for each of the eight UBL 1.0 document types. As noted above, the implementation diagrams are simplified views that suppress details of the types contained in these aggregate structures. As an example, the class diagram for the UBL Order document is shown in the figure below.

[order implementation model]

Figure B-7. Implementation Model for the Order Document

The document implementation class diagrams contained in the UBL 1.0 package are listed below.

Order implementation diagram
Order Response implementation diagram
Order Response Simple implementation diagram
Order Change implementation diagram
Order Cancellation implementation diagram
Despatch Advice implementation diagram
Receipt Advice implementation diagram
Invoice implementation diagram

B.6.2 Reusable Component Implementation Diagrams

In addition to the main document diagrams, this release contains ten class diagrams that present views of the packages of reusable components used in the documents. For example, the Order diagram includes associations to Party, SellerParty, and BuyerParty. The following implementation diagram shows these components in detail.

[party implementation model]

Figure B-8. Implementation Model for Party Components

The component implementation diagrams provided with UBL 1.0 are as follows:

Address implementation diagram
Contract implementation diagram
Despatch Line implementation diagram
Document Reference implementation diagram
Hazardous Item implementation diagram
Item implementation diagram
Party implementation diagram
Payment implementation diagram
Procurement implementation diagram
Shipment implementation diagram
Tax implementation diagram

B.7 Customization Guidelines

Guidelines for performing a compatible customization of UBL schemas, together with suggestions for how to proceed when a compatible customization is not possible, can be found in this package at


The UBL Customization Guidelines are the product of the OASIS UBL Context Methodology Subcommittee. The work of the UBL CMSC can be viewed on the CMSC web page:


Appendix C (Informative): Formatting Specifications

The UBL 1.0 package includes an extensive set of formatting specifications in a hyperdocument rooted at


This part of the package also includes PDF renderings of the example instances provided in Appendix D below.

The UBL Formatting Specifications are the product of the OASIS UBL Forms Presentation Subcommittee. The work of the UBL FPSC can be viewed on the FPSC web page:


Appendix D (Informative): Example Instances

This appendix provides example instances of UBL documents being used in two different versions of the order-to-invoice process. The first set of examples illustrates the buying of office supplies, and the second set illustrates the buying of joinery (building supplies). Also included are printed versions of each example document created in accordance with the formatting specifications referenced in Appendix C.

D.1 Example One: Buying Office Supplies

The buyer, Bill’s Microdevices, orders several different items from an office supply store. The buyer knows the supplier’s codes for the items and the price for each.

Office supplies Order example instance

The buyer decides to change the original order.

Office supplies Order Change example instance

The seller, Joe’s Office Supply, replies with an Order Response Simple to indicate the acceptance of the order. The seller also gives his reference number for the order, i.e., the sales order in his system, and tells the buyer whom to contact if he has any queries.

Office supplies Order Response Simple example instance

The buyer cancels an Order (for purposes of illustration, not the same one).

Office supplies Order Cancellation example instance

The seller advises the buyer of the despatch of the items ordered.

Office supplies Despatch Advice example instance

The buyer notifies the seller of missing items.

Office supplies Receipt Advice example instance

The seller raises the Invoice automatically when the despatch occurs, and the resolution of shortages etc. is handled post-invoicing. The Invoice shows the tax amount. The seller notes that payment is due within 30 days of Invoice.

Office supplies Invoice example instance

D.2 Example Two: Buying Joinery (Building Supplies)

The buyer, Jerry Builders, PLC. in the UK, orders a number of windows, a door set, and some lengths of timber for delivery to a building site. Jerry knows the supplier’s codes for the items, and that he must also specify a number of physical attributes to get the precise item that he wants: some windows are asymmetric and are “handed” left or right; most door sets are handed, as they are hinged on one side; the wood and its finish must be specified, as must the “fittings” (handles, stays etc.). Items can be glazed in different ways. Loose timber is coded according to its cross section, and the length must be specified. While the buyer knows these things from the catalogue, he does not know the current prices or any discount rate he may get.

Joinery Order example instance

The seller, Specialist Windows PLC, replies with a detailed Order Response to indicate the unit price of each item and to inform the buyer of the trade discount that he will be given. At the same time, the seller gives his reference number for the order, i.e. the identity of the order in his system, and also tells the buyer whom to contact if he has any queries.

Joinery Order Response example instance

The seller advises the buyer of the despatch of the items ordered, which will in fact be delivered on two pallets (i.e., transportation units) identified as “A” and “B”. The Despatch Advice lists the items in order line sequence and refers to the pallet on which the item is delivered.

Joinery Despatch Advice example instance

The Despatch Advice travels with the delivery; a paper copy is signed and returned as proof of receipt. Hence the UBL Receipt Advice is not used.

The Seller raises the Invoice automatically when the despatch occurs, and the resolution of any shortages is handled post-invoicing. The Invoice has to show the tax point date, the VAT (Value Added Tax) category to which the item belongs, and also the VAT rate and total for each tax category on the invoice. VAT is also applied to charges such as the delivery surcharge. In order to encourage speedy payment of the amount due, the Seller offers a discount for prompt settlement, which the buyer can deduct if paying within 30 days. (This example was written for a context in which regulations assume the VAT will be taken, so the tax here is calculated on the trade discounted total of line items plus any charges and less the settlement discount amount.)

Joinery Invoice example instance

This example is based on the products, product identification, business requirements, and practices of a real UK joinery manufacturer and sales company. It operates its own specialized transport fleet, delivering all over the United Kingdom and to offshore islands.

Appendix E (Informative): Code Lists

The code list schemas included in UBL 1.0 conform to the UBL specification for Code List Representation, which can be found in this package at


The UBL Code List Representation specification is the product of the OASIS UBL Code List Subcommittee. The work of the UBL CLSC can be viewed on the CLSC web page:


Appendix F (Informative): ASN.1 Specification

The UBL ASN.1 specification referenced below provides an alternative schema definition for UBL documents in accordance with ITU-T X.680-X.693 [ASN.1]. The UBL ASN.1 specification defines the same UBL documents as the UBL XSD schemas in Section 6 that constitute the normative definitions of valid UBL documents. The UBL ASN.1 XML schema enables ASN.1 tools to be used for UBL transfers, and in conjunction with the ASN.1 Packed Encoding Rules, it provides a specification for an efficient binary encoding of UBL messages.

UBL ASN.1 Specification

The ASN.1 UBL specification was created using a tool from OSS Nokalva (http://www.oss.com/) that conforms to ITU-T Recommendation X.694 | ISO/IEC 8825-5 for converting XSD Schema to ASN.1. After conversion, the generated ASN.1 was formatted by the PrettyPrint tool at the ASN.1 Information Site (http://asn1.elibel.tm.fr) to produce the HTML file included in this package.

Appendix G (Informative): Ongoing Work Items

UBL 1.0 achieves the basic objective of the first phase of the UBL charter — to develop a workable standard library of XML business documents. The second phase (UBL 2.0) is intended to produce additions to the UBL library and schema set and a mechanism for the automatic generation of context-specific business schemas.

Between these milestones lie a number of work items that for one reason or another could not be completed in time for delivery of UBL 1.0. Some of these items represent work of continuing interest; others represent cases where an issue could not achieve a consensus solution within the time set for UBL 1.0 delivery but for which an acceptable short-term strategy could be adopted with little or no impact on the long-term validity of UBL 1.0 document instances. The UBL TC intends to resolve these issues and release an updated version called UBL 1.1 that will be backward-compatible with UBL 1.0 instances.

In the following, these work items have been loosely grouped under four headings: NDR Work Items, Interoperability Work Items, Registry Work Items, and Localization Work Items. Persons interested in participating in this program of work are invited to join the OASIS UBL TC.

G.1 NDR Work Items

The following items are related to UBL Naming and Design Rules (NDR).

G.1.1 Publication of UBL NDR as a Separate Specification

Time constraints prevented completion of the UBL Naming and Design Rules (NDR) document as a separate specification for delivery with UBL 1.0; the document included in this package and referenced as [NDR] contains only the rules checklist for 1.0. Work continues to prepare the NDR document for submission as a separate OASIS technical specification.

G.1.2 Substitution Groups for Code List Customization

The UBL Code List Subcommittee has produced a comprehensive solution for code lists (see Appendix E) that relies upon XSD substitution groups for code list customization. Lacking a clear industry consensus on the use of XSD substitution groups in business document schemas, the UBL TC has deferred the adoption of this extension mechanism for code lists pending further discussion. Care has been taken to construct UBL 1.0 in a way that will allow the adoption of substitution groups (if deemed appropriate) in later releases without invalidating UBL 1.0 instances.

G.1.3 Importation of Codelist Schema Modules

It is an open question whether it is better to import the codelist schema modules (Section 6.3) indirectly via the Specialized Datatype schema (Section 6.2.2) or directly into the Common Aggregate Component schema (Section 6.2.1) and any individual document schemas where they are used. In UBL 1.0, codelist schema modules are imported directly, but concerns have been raised regarding a possible impact on performance. Feedback from UBL 1.0 implementation will be relied upon in resolving this issue. A change to the alternative is not expected to affect UBL 1.0 instances.

G.1.4 Location of Qualified BBIE Property Element Definitions

In UBL 1.0, all BBIE properties are declared as elements and defined as complex types in the Common Basic Components schema (Section 6.2.1). Alternatively, the qualified BBIE property elements could be declared in either the Common Aggregate Components schema or in the individual document schemas where they are used. This issue remains open, but any change in future releases will not affect UBL 1.0 instances.

G.2 Registry Work Items

The following issues relate to the storage and registration of UBL schemas.

G.2.1 Relative Paths in Schema Modules

UBL NDR identified a requirement for absolute path names for schema locations as a necessary requirement for standards based schemas to ensure consistency, clarity, and absolute assurances that the UBL normative schemas are in fact being used. However, current OASIS architecture limitations preclude the availability of a suitable registry/repository to support this requirement. As a result, UBL 1.0 has been released using relative path names for the location of schemas in order to facilitate offline validation and to work around those limitations. Use of absolute paths and a registry for the component library will be implemented in a future version as the supporting infrastructure becomes available.

G.2.2 Version Element in the Documentation of Every BIE

UBL 1.0 assumes that the version number of each UBL datatype and BIE is also 1.0. However, there is some debate as to whether this is a schema construct artifact or a storage artifact. The outcome of this decision may result in a requirement to assign a version number in the annotation documentation for each datatype and BIE schema construct.

G.3 Interoperability Work Items

The following work items relate to the interoperability of UBL documents across industries and in relation to other business document standards.

G.3.1 UBL Conformance

While much initial work has been done toward defining the concept of UBL conformance in the UBL 1.0 Customization Guidelines (see Appendix B.7), further work is necessary to create a definition of UBL conformance that is usable in legal and regulatory contexts.

G.3.2 Industry Profiles

It is considered likely that UBL 1.0 will be modified according to the UBL Customization Guidelines to create versions that are standard within particular industries and geographical regions. Further work is needed to develop guidelines specific to this use case.

G.3.3 Common CCTS Schemas

The schemas for Core Component Types and Datatypes included in this package (Section 6.2.2) were developed in cooperation with representatives of the Open Applications Group, Inc., but the versions currently used by the two organizations are not yet identical. Differences between the CCTS schemas used in UBL 1.0 and OAGIS 9.0 have been identified in these five areas:

A common set of CCTS schemas are expected to be available for UBL 1.1 and will be included at that time. This is not expected to affect the validity of UBL 1.0 instances.

G.3.4 Core Component Harmonization

As an implementation of [CCTS], UBL supports the concept of a common semantic library of business components. To achieve this, UBL is working with the UN/CEFACT International Trade and Business Processes Working Group on Harmonization, known as TBG17 (http://webster.disa.org/cefact-groups/tbg/wg/tbg17_main.cfm). This group is responsible for consistency and harmonization of business process models and core components across business domains and sectors, contributing to a concise and well-defined glossary of business terms, business data semantic definitions, and structuring of data exchanges. Cooperation with TBG17 is a continuing work item for UBL.

G.3.5 Context Methodology

While the delivery of an automatic context methodology belongs to UBL 2.0, work on this item continues in the UBL 1.1 time frame. This includes further refinement of the Customization Guidelines referenced in B.7 of this specification.

G.4 Localization Work Items

UBL has formed several localization subcommittees (LSCs) to translate the UBL specification and associated documentation into languages other than English and to represent the UBL effort in non-English-speaking regional contexts. These regional initiatives will account for much of the work to be performed in the UBL 1.1 time frame. As of April 2004, UBL localization subcommittees had been established for Chinese, Japanese, Korean, and Spanish.

Appendix H: Notices

Copyright © 2001-2004 OASIS Open, Inc. All Rights Reserved.

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.