# Universal Business Language 1.0

##### Publication Date

15 September 2004

##### Document identifier

cd-UBL-1.0

##### Editorial Status

This document is an OASIS Committee Draft.

##### Location

http://docs.oasis-open.org/ubl/cd-UBL-1.0/

##### Downloadable Package Location

http://docs.oasis-open.org/ubl/cd-UBL-1.0.zip

##### Editors

Bill Meadows <meadows.bill@comcast.net>

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

##### Contributors

Members of the Technical Committee

##### Abstract

This specification defines the Universal Business Language.

##### Status

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:

> http://www.oasis-open.org/committees/comments/form.php?wg_abbrev=ubl

# 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.

- Developing and maintaining multiple versions of common business documents like purchase orders and invoices is a major duplication of effort.

- Creating and maintaining multiple adapters to enable trading relationships across domain boundaries is an even greater effort.

- The existence of multiple XML formats makes it much harder to integrate XML business messages with back-office systems.

- The need to support an arbitrary number of XML formats makes tools more expensive and trained workers harder to find.

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 library of XML schemas for reusable data components such as “Address,” “Item,” and “Payment” — the common data elements of everyday business documents.

- A small set of XML schemas for common business documents such as “Order,” “Despatch Advice,” and “Invoice” that are constructed from the UBL library components and can be used in a generic order-to-invoice trading context.

- Support for the customization of UBL in specific trading relationships.

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

- Lower cost of integration, both among and within enterprises, through the reuse of common data structures.

- Lower cost of commercial software, because software written to process a given XML tag set is much easier to develop than software that can handle an unlimited number of tag sets.

- An easier learning curve, because users need master just a single library.

- Lower cost of entry and therefore quicker adoption by small and medium-size enterprises (SMEs).

- Standardized training, resulting in many skilled workers.

- A universally available pool of system integrators.

- Standardized, inexpensive data input and output tools.

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:

- UML class diagrams of the document components on which the schemas are based

- UML class diagrams describing all the document assemblies

- Spreadsheet models defining the document assemblies

- Descriptions of two example implementations

- Sample instances of each of the UBL documents used in those two implementations

- Formatting specifications for rendering all of the documents in the example use cases

- Formatting specifications for the United Nations Layout Keys corresponding to each of the UBL basic business document types

- An ASN.1 specification to enable the transmission of UBL messages in binary form

# 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
  http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.zip
  http://www.oasis-open.org/committees/download.php/6320/X.680-X.693-0207w.zip
[CCTS] UN/CEFACT ebXML Core Components Technical Specification 2.01
  http://www.untmg.org/downloads/General/approved/CEFACT-CCTS-Version-2pt01.zip
  http://www.oasis-open.org/committees/download.php/6232/CEFACT-CCTS-Version-2pt01.zip
[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
  http://www.iso.org/iso/en/ittf/PubliclyAvailableStandards/c002349_ISO_IEC_11179-1_1999(E).zip
  http://www.oasis-open.org/committees/download.php/6233/c002349_ISO_IEC_11179-1_1999%28E%29.pdf
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels
  http://www.faqs.org/rfcs/rfc2119.html
  http://www.oasis-open.org/committees/download.php/6244/rfc2119.txt.pdf
[UML] Unified Modeling Language Version 1.5 (formal/03-03-01)
  http://www.omg.org/docs/formal/03-03-01.pdf
  http://www.oasis-open.org/committees/download.php/6240/03-03-01.zip
[XML] Extensible Markup Language (XML) 1.0 (Second Edition),W3C Recommendation 6 October 2000
  http://www.w3.org/TR/2000/REC-xml-20001006
  http://www.oasis-open.org/committees/download.php/6241/REC-xml-20001006.pdf
[XSD1] XML Schema Part 1: Structures, W3C Recommendation 2 May 2001
  http://www.w3.org/TR/xmlschema-1/
  http://www.oasis-open.org/committees/download.php/6248/xsd1.html
[XSD2] XML Schema Part 2: Datatypes, W3C Recommendation 2 May 2001
  http://www.w3.org/TR/xmlschema-2/
  http://www.oasis-open.org/committees/download.php/6247/xsd2.html

# 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.
Context
  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.
Document
  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.
Normalization
  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

ABIE
  Aggregate Business Information Entity
ACC
  Aggregate Core Component
ASBIE
  Association Business Information Entity
ASCC
  Association Core Component
BBIE
  Basic Business Information Entity
BCC
  Basic Core Component
BIE
  Business Information Entity
CC
  Core Component
EAN
  European Article Numbering Association
EDI
  Electronic Data Interchange
ISO
  International Organization for Standardization
NDR
  UBL Naming and Design Rules (see Appendix B.4)
UML
  Unified Modeling Language [UML]
UN/CEFACT
  United Nations Centre for Trade Facilitation and Electronic Business
XML
  Extensible Markup Language [XML]
XSD
  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

> Order Response Simple

> Order Response (detailed)

> Order Change

> Order Cancellation

> Despatch Advice

> Receipt Advice

> Invoice

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

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:

- Transport

  - Means

  - Mode

  - One- to many-legged shipment stages

    - Dates

    - Locations

  - Arrival “window”

- Consignment packaging

  - Type, e.g. Container, Pallet

  - Identifier, e.g. SSCC, Shipping label (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:

- Delivery date, offered by the Seller if not specifically requested by the Buyer

- Prices

- Trade Discount

- Charges

- Customs Commodity Classification codes

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:

- Transport

  - Means

  - Mode

  - One- to many-legged shipment stages

    - Dates

    - Locations

  - Arrival “window”

- Consignment packaging

  - Type, e.g. Container, Pallet

  - Identifier, e.g. SSCC, Shipping label (DespatchAdvice)

The Despatch Advice provides for two situations:

- Organization of the delivery set of items by Transport Handling Unit(s) so that the Receiver can check the Transport Handling Unit and then contained items. Quantities of the same item on the same Order Line may be separated into different Transport Handling Units, and hence appear on separate Despatch Lines within a Transport Handling Unit.

- Organization of the delivery set of items by Despatch Line, annotated by the Transport Handling Unit in which they are placed, to facilitate checking against the Order. For convenience, any Order Line split over multiple Transport Handling Units will result in a Despatch Line for each Transport Handling Unit they are contained in.

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

- Full Despatch — advising the Recipient and/or Buyer that all the items on the order will be, or are being, delivered in one complete consignment on a given date.

- Partial Despatch — advising the Recipient and/or Buyer that the items on the order will be, or are being, partially delivered in a consignment on a given date.

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:

- Indication of receipt by Transport Handling Unit(s) and contained Receipt Lines one-to-one with the Despatch Advice as detailed by the Seller party.

- Indication of receipt by Receipt Lines annotated by Transport Handling Unit, one-to-one with the Despatch Advice as detailed by the Seller party.

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:

- Prepayment invoice (payment expected)

- Pro-forma invoice (pre advice, payment not expected)

- Normal Invoice, on despatch for despatched items

- Invoice after return of ReceiptAdvice

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:

- Packaging

- Delivery/postage

- Freight

- Documentation

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:

- Buyer’s Item Identification, or

- Seller’s Item Identification, or

- Manufacturer’s Item Identification, or

- Catalogue Item Identification, or

- Item Identification according to a system promulgated by a standards body.

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:

#### 5.3.1.1 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.

#### 5.3.1.2 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.

#### 5.3.1.3 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
>   xsd/maindoc/UBL-Order-1.0.xsd
> Order Response
>   xsd/maindoc/UBL-OrderResponse-1.0.xsd
> Order Response Simple
>   xsd/maindoc/UBL-OrderResponseSimple-1.0.xsd
> Order Change
>   xsd/maindoc/UBL-OrderChange-1.0.xsd
> Order Cancellation
>   xsd/maindoc/UBL-OrderCancellation-1.0.xsd
> Despatch Advice
>   xsd/maindoc/UBL-DespatchAdvice-1.0.xsd
> Receipt Advice
>   xsd/maindoc/UBL-ReceiptAdvice-1.0.xsd
> Invoice
>   xsd/maindoc/UBL-Invoice-1.0.xsd

## 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
>   xsd/common/UBL-CommonBasicComponents-1.0.xsd
>   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
>   xsd/common/UBL-CommonAggregateComponents-1.0.xsd
>   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
>   xsd/common/UBL-CoreComponentTypes-1.0.xsd
>   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
>   xsd/common/UBL-UnspecializedDatatypes-1.0.xsd
>   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
>   xsd/common/UBL-SpecializedDatatypes-1.0.xsd
>   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
>   xsd/common/UBL-CoreComponentParameters-1.0.xsd
>   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
>   xsd/codelist/UBL-CodeList-AcknowledgementResponseCode-1.0.xsd
> Allowance Charge Reason Code
>   xsd/codelist/UBL-CodeList-AllowanceChargeReasonCode-1.0.xsd
> Channel Code
>   xsd/codelist/UBL-CodeList-ChannelCode-1.0.xsd
> Chip Code
>   xsd/codelist/UBL-CodeList-ChipCode-1.0.xsd
> Country Identification Code
>   xsd/codelist/UBL-CodeList-CountryIdentificationCode-1.0.xsd
> Currency Code
>   xsd/codelist/UBL-CodeList-CurrencyCode-1.0.xsd
> Document Status Code
>   xsd/codelist/UBL-CodeList-DocumentStatusCode-1.0.xsd
> Latitude Direction Code
>   xsd/codelist/UBL-CodeList-LatitudeDirectionCode-1.0.xsd
> Line Status Code
>   xsd/codelist/UBL-CodeList-LineStatusCode-1.0.xsd
> Longitude Direction Code
>   xsd/codelist/UBL-CodeList-LongitudeDirectionCode-1.0.xsd
> Operator Code
>   xsd/codelist/UBL-CodeList-OperatorCode-1.0.xsd
> Payment Means Code
>   xsd/codelist/UBL-CodeList-PaymentMeansCode-1.0.xsd
> Substitution Status Code
>   xsd/codelist/UBL-CodeList-SubstitutionStatusCode-1.0.xsd

## 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.

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.

> `art/`
>   Diagrams and illustrations used in this specification
> `asn/`
>   ASN.1 specification; see Appendix F
> `doc/`
>   Supporting documents created by the UBL TC and referenced in this specification
> `fs/`
>   Formatting specifications; see Appendix C
> `mod/`
>   UBL spreadsheet models; see Appendix B.3
> `uml/`
>   UML diagrams; see Appendices B.2, B.3, and B.6
> `xml/`
>   Example instances; see Appendix D
> `xsd/`
>   XSD schemas; see Section 6
> `xsdrt/`
>   “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:

> http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl-ssc.

## 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

> http://lists.oasis-open.org/archives/ubl-dev/

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

> http://lists.oasis-open.org/ob/adm.pl

## 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.

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:

- It facilitates the identification of the reusable components — i.e., the data structures that are common across the UBL 1.0 business documents

- It aids in understanding the information requirements of the total scenario

- It is the source from which the BIEs are derived and documented in the UBL document assembly models

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.

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.

Figure B-3. Party Component Package

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

> Address Package
>   uml/concept/comp/UBL-1.0-AddressPackage.jpg
> Contract Package
>   uml/concept/comp/UBL-1.0-ContractPackage.jpg
> Delivery Package
>   uml/concept/comp/UBL-1.0-DeliveryPackage.jpg
> Document Reference Package
>   uml/concept/comp/UBL-1.0-DocumentReferencePackage.jpg
> Hazardous Item Package
>   uml/concept/comp/UBL-1.0-HazardousItemPackage.jpg
> Item Package
>   uml/concept/comp/UBL-1.0-ItemPackage.jpg
> Party Package
>   uml/concept/comp/UBL-1.0-PartyPackage.jpg
> Payment Package
>   uml/concept/comp/UBL-1.0-PaymentPackage.jpg
> Procurement Package
>   uml/concept/comp/UBL-1.0-ProcurementPackage.jpg
> Tax Package
>   uml/concept/comp/UBL-1.0-TaxPackage.jpg

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.

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
>   uml/concept/assy/UBL-1.0-OrderDocumentAssembly.jpg
> Order Response assembly model
>   uml/concept/assy/UBL-1.0-OrderResponseDocumentAssembly.jpg
> Order Response Simple assembly model
>   uml/concept/assy/UBL-1.0-OrderResponseSimpleDocumentAssembly.jpg
> Order Change assembly model
>   uml/concept/assy/UBL-1.0-OrderChangeDocumentAssembly.jpg
> Order Cancellation assembly model
>   uml/concept/assy/UBL-1.0-OrderCancellationDocumentAssembly.jpg
> Despatch Advice assembly model
>   uml/concept/assy/UBL-1.0-DespatchAdviceDocumentAssembly.jpg
> Receipt Advice assembly model
>   uml/concept/assy/UBL-1.0-ReceiptAdviceDocumentAssembly.jpg
> Invoice assembly model
>   uml/concept/assy/UBL-1.0-InvoiceDocumentAssembly.jpg

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:

- The additional metadata required by [CCTS] is easily defined

- Formulas can be applied to naming rules

- Spreadsheets can be mapped directly to the submission format for candidate Core Components required byUN/CEFACT TBG17

- Spreadsheets are familiar to the business experts responsible for the data modeling

- The format has proven portable between applications

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.

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
>   mod/maindoc/UBL-Order-1.0.sxc
>   mod/maindoc/UBL-Order-1.0.xls
> Order Response document spreadsheet
>   mod/maindoc/UBL-OrderResponse-1.0.sxc
>   mod/maindoc/UBL-OrderResponse-1.0.xls
> Order Response Simple document spreadsheet
>   mod/maindoc/UBL-OrderResponseSimple-1.0.sxc
>   mod/maindoc/UBL-OrderResponseSimple-1.0.xls
> Order Change document spreadsheet
>   mod/maindoc/UBL-OrderChange-1.0.sxc
>   mod/maindoc/UBL-OrderChange-1.0.xls
> Order Cancellation document spreadsheet
>   mod/maindoc/UBL-OrderCancellation-1.0.sxc
>   mod/maindoc/UBL-OrderCancellation-1.0.xls
> Despatch Advice document spreadsheet
>   mod/maindoc/UBL-DespatchAdvice-1.0.sxc
>   mod/maindoc/UBL-DespatchAdvice-1.0.xls
> Receipt Advice document spreadsheet
>   mod/maindoc/UBL-ReceiptAdvice-1.0.sxc
>   mod/maindoc/UBL-ReceiptAdvice-1.0.xls
> Invoice document spreadsheet
>   mod/maindoc/UBL-Invoice-1.0.sxc
>   mod/maindoc/UBL-Invoice-1.0.xls

### 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).
  mod/common/UBL-Reusable-1.0.sxc
  mod/common/UBL-Reusable-1.0.xls
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).
  mod/common/UBL-CoreComponentTypes-1.0.sxc
  mod/common/UBL-CoreComponentTypes-1.0.xls
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).
  mod/common/UBL-UnspecializedDatatypes-1.0.sxc
  mod/common/UBL-UnspecializedDatatypes-1.0.xls
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).
  mod/common/UBL-SpecializedDatatypes-1.0.sxc
  mod/common/UBL-SpecializedDatatypes-1.0.xls

### 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:

- First, any modification of the spreadsheet models requires an understanding of their structure, the ebXML Core Components Technical Specification [CCTS], and the various UBL library constituents. For example, some columns are updated directly, while others have formulas in their cells which implement [CCTS] and UBL Naming and Design Rules. Awareness of this is necessary when adding or editing the row contents. Care should be taken to avoid updating cells that contain formulas.

- Second, schema generation should be compliant with the UBL Naming and Design Rules (B.4 below) to promote compatibility with other UBL component libraries.

- Third, the data types defined in the Core Component Types and Unspecialized Datatypes models are direct implementations of those defined in [CCTS] and should not be modified without recognition of this fact. The Specialized Data Types model is provided for implementation-specific data types.

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:

> http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-lcsc

## 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:

> doc/ndr/UBL-NDR-Checklist-1.0.pdf

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:

> http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-ndrsc

## 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.

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:

> http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-ttsc

## 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.

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
>   uml/implem/doctypes/UBL-OrderImplementationDiagram-1.0.gif
> Order Response implementation diagram
>   uml/implem/doctypes/UBL-OrderResponseImplementationDiagram-1.0.gif
> Order Response Simple implementation diagram
>   uml/implem/doctypes/UBL-OrderResponseSimpleImplementationDiagram-1.0.gif
> Order Change implementation diagram
>   uml/implem/doctypes/UBL-OrderChangeImplementationDiagram-1.0.gif
> Order Cancellation implementation diagram
>   uml/implem/doctypes/UBL-OrderCancellationImplementationDiagram-1.0.gif
> Despatch Advice implementation diagram
>   uml/implem/doctypes/UBL-DespatchAdviceImplementationDiagram-1.0.gif
> Receipt Advice implementation diagram
>   uml/implem/doctypes/UBL-ReceiptAdviceImplementationDiagram-1.0.gif
> Invoice implementation diagram
>   uml/implem/doctypes/UBL-InvoiceImplementationDiagram-1.0.gif

### 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.

Figure B-8. Implementation Model for Party Components

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

> Address implementation diagram
>   uml/implem/packages/UBL-AddressImplementationDiagram-1.0.gif
> Contract implementation diagram
>   uml/implem/packages/UBL-ContractImplementationDiagram-1.0.gif
> Despatch Line implementation diagram
>   uml/implem/packages/UBL-DespatchLineImplementationDiagram-1.0.gif
> Document Reference implementation diagram
>   uml/implem/packages/UBL-DocumentReferenceImplementationDiagram-1.0.gif
> Hazardous Item implementation diagram
>   uml/implem/packages/UBL-HazardousItemImplementationDiagram-1.0.gif
> Item implementation diagram
>   uml/implem/packages/UBL-ItemImplementationDiagram-1.0.gif
> Party implementation diagram
>   uml/implem/packages/UBL-PartyImplementationDiagram-1.0.gif
> Payment implementation diagram
>   uml/implem/packages/UBL-PaymentImplementationDiagram-1.0.gif
> Procurement implementation diagram
>   uml/implem/packages/UBL-ProcurementImplementationDiagram-1.0.gif
> Shipment implementation diagram
>   uml/implem/packages/UBL-ShipmentImplementationDiagram-1.0.gif
> Tax implementation diagram
>   uml/implem/packages/UBL-TaxImplementationDiagram-1.0.gif

## 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

> doc/cm/wd-ubl-cmsc-cmguidelines-1.0.html

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:

> http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-cmsc

# Appendix C (Informative): Formatting Specifications

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

> fs/index.html

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:

> http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-fpsc

# 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
>   xml/office/UBL-Order-1.0-Office-Example.xml
> Printouts
>   fs/Order/pdf/OfficeOrder.Example-a4.pdf
>   fs/Order/pdf/OfficeOrder.Example-us.pdf

The buyer decides to change the original order.

> Office supplies Order Change example instance
>   xml/office/UBL-OrderChange-1.0-Office-Example.xml
> Printouts
>   fs/OrderChange/pdf/OfficeOrderChange.Example-a4.pdf
>   fs/OrderChange/pdf/OfficeOrderChange.Example-us.pdf

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
>   xml/office/UBL-OrderResponseSimple-1.0-Office-Example.xml
> Printouts
>   fs/OrderResponseSimple/pdf/OfficeOrderResponseSimple.Example-a4.pdf
>   fs/OrderResponseSimple/pdf/OfficeOrderResponseSimple.Example-us.pdf

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

> Office supplies Order Cancellation example instance
>   xml/office/UBL-OrderCancellation-1.0-Office-Example.xml
> Printouts
>   fs/OrderCancellation/pdf/OfficeOrderCancellation.Example-a4.pdf
>   fs/OrderCancellation/pdf/OfficeOrderCancellation.Example-us.pdf

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

> Office supplies Despatch Advice example instance
>   xml/office/UBL-DespatchAdvice-1.0-Office-Example.xml
> Printouts
>   fs/DespatchAdvice/pdf/OfficeDespatchAdvice.Example-a4.pdf
>   fs/DespatchAdvice/pdf/OfficeDespatchAdvice.Example-us.pdf

The buyer notifies the seller of missing items.

> Office supplies Receipt Advice example instance
>   xml/office/UBL-ReceiptAdvice-1.0-Office-Example.xml
> Printouts
>   fs/ReceiptAdvice/pdf/OfficeReceiptAdvice.Example-a4.pdf
>   fs/ReceiptAdvice/pdf/OfficeReceiptAdvice.Example-us.pdf

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
>   xml/office/UBL-Invoice-1.0-Office-Example.xml
> Printouts
>   fs/Invoice/pdf/OfficeInvoice.Example-a4.pdf
>   fs/Invoice/pdf/OfficeInvoice.Example-us.pdf

### 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
>   xml/joinery/UBL-Order-1.0-Joinery-Example.xml
> Printouts
>   fs/Order/pdf/JoineryOrder.Example-a4.pdf
>   fs/Order/pdf/JoineryOrder.Example-us.pdf

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
>   xml/joinery/UBL-OrderResponse-1.0-Joinery-Example.xml
> Printouts
>   fs/OrderResponse/pdf/JoineryOrderResponse.Example-a4.pdf
>   fs/OrderResponse/pdf/JoineryOrderResponse.Example-us.pdf

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
>   xml/joinery/UBL-DespatchAdvice-1.0-Joinery-Example.xml
> Printouts
>   fs/DespatchAdvice/pdf/JoineryDespatchAdvice.Example-a4.pdf
>   fs/DespatchAdvice/pdf/JoineryDespatchAdvice.Example-us.pdf

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
>   xml/joinery/UBL-Invoice-1.0-Joinery-Example.xml
> Printouts
>   fs/Invoice/pdf/JoineryInvoice.Example-a4.pdf
>   fs/Invoice/pdf/JoineryInvoice.Example-us.pdf

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

> doc/cl/wd-ublclsc-codelist-20040420.pdf

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:

> http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-clsc

# 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
>   asn/ASN.1-UBL-1.0.html

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:

- Naming of Supplementary Components as attributes

- Use of XSD normalizedString for code, identifier, and text components

- Use of XSD built-in dataypes requiring format Supplementary Components (Date Time, Indicator and Numeric)

- Restrictions on Binary Object for Graphic, Picture, Sound and Video data type

- Patterns for Indicator data type

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.

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.