Table of Contents

• 1. Introduction
  • 1.1 Notes About This Release
  • 1.2 Support for this Release
  • 1.3 General comments about OASIS UBL TC
  • 1.4 Document Conventions
  • 1.5 Disclaimer
• 2. Document Scope
• 3. Normative References
• 4. Terms and Definitions
• 5. Symbols and Abbreviations
• 6. Initial UBL Business Scenario
  • 6.1 The Order-to-Payment Business Process
    • 6.1.1 Items
      • 6.1.1.1 Item Requiring Description
      • 6.1.1.2 Customer Defined Item
      • 6.1.1.3 Item Measurements
      • 6.1.1.4 Other Item Details
    • 6.1.2 Order
      • 6.1.2.1 Order Line
    • 6.1.3 Order Response (Simple)
    • 6.1.4 Order Response (Complex)
    • 6.1.5 Order Change
    • 6.1.6 Order Cancellation
    • 6.1.7 Despatch Advice
    • 6.1.8 Receipt Advice
    • 6.1.9 Invoice
      • 6.1.9.1 Invoice Item Line
  • 6.2 Adapting UBL for other scenarios
• 7. UBL Library
  • 7.1 Description
• 8. UBL Document Schemas
• 9. Code Lists
• Annex A: UBL Conceptual Data Model (informative)
  • A.1 Introduction
• Annex B: UBL Document Descriptions (informative)
  • B.1 UBL Document Spreadsheets
  • B.2 UML Class Diagrams
    • B.2.1 Document Models
    • B.2.2 Packages
  • B.3 XSD Schema
    • B.3.1 UBL XSD Schema
• Annex C: UBL Document Descriptions (informative)
  • C.1 UBL Document Spreadsheets
  • C.2 UML Class Diagrams
• Annex D: UBL Supplemental Materials (informative)
  • D.1 Introduction
  • D.2 Non-Normative References
  • D.3 ASN.1 Specification of UBL
  • D.4 Formatting specifications and stylesheets
  • D.5 Other Document Samples
    • D.5.1 Example One Buying Office Supplies
    • D.5.2 Example Two Buying Joinery

---

1. Introduction

XML was designed to specify multiple data formats optimized for different data exchange applications. So the recent explosion of XML specifications resulting from the efforts of industry associations to develop domain-specific markup languages is neither unexpected nor detrimental. In one area, however, these otherwise beneficial XML industry initiatives are creating interoperability problems and impeding the development of inexpensive software. That area is the specification of XML schemas for common business documents such as purchase orders and invoices.

While different industries frequently do have slightly different requirements for these common business forms, their similarities far outweigh their differences, and most of the work devoted to the design of these forms in each industry segment is simply wasted effort that would better be deployed in work on XML schemas for the data that is truly specific to a given industry. The goal of UBL is to standardize XML schemas for common business documents so that industry organizations can concentrate on the part of the data interchange problem in which they have special expertise and truly divergent needs.

We hope the arrival of a standard set of XML business schemas will solve major interoperability problems for both vendors and users and speed the entry of small and medium-size businesses into the electronic marketplace. The OASIS UBL (Universal Business Language) defines a set of XML building blocks together with a framework that will enable trading partners to unambiguously identify and exchange basic e-commerce documents in specific business contexts. It initially provides a common XML library for basic business documents for a typical procurement ("order to payment") business process.

Significantly, UBL leverages knowledge from existing EDI and XML B2B systems. It is user-driven, with deep experience and partnership resources to call on. Our goal is to unite and harmonize a number of currently existing XML and EDI business libraries into a set of internationally legally recognized international standards. We are committed to truly global trade and information interoperability. UBL will be freely available to everyone without legal encumbrance or licensing fees.

The design of UBL schemas is modular, reusable, and extensible in XML-aware ways. The UBL Library has been designed as a collection of object classes, their properties and associations expressed as a conceptual model. We call these components business information entities (BIES). The analysis and design processes used by the UBL Library Content team are described in Annex A. These business information entities (BIES) are assembled into a specific hierarchical, document structures, such as an Order or an Invoice. These document models are then transformed based upon specific UBL Naming and Design rules [NDR] into XML Schema syntax [XSD1][XSD2]. By publishing the models, methodology and rules for schema creation, we hope that UBL components will also be used to assemble new and customised document structures. UBL is designed to be layered on existing successful standards. For example, the ebXML infrastructure developed by OASIS and the UN/CEFACT provides for XML registry services, reliable XML messaging, standardized trading partner agreements, a standard data dictonary, and a business process methodology. UBL provides an XML implementation of Electronic Business XML (ebXML) Core Components that provide the data content to this framework. In addition, UBL re-usable components and even entire UBL document schemas are usable in a wide variety of other ecommerce frameworks, for example as the content for Web Services.

Back to top

1.1 Notes about this Release

This release, known as UBL 1.0 Beta, is provided to enable trial implementations of UBL in realistic business environments. Subsequent to this release will be the submission of this specification to OASIS as a Committee Draft suitable for approval as a Tehcnical Specification. The downloadable version of this release is available here: UBLv10-alpha Downloadable Release. (This is a zip file that will unpack to give you a replica of the online release directories.)

If there are any problems with the links in this document, you can find the full online version at http://www.oasis-open.org/committees/ubl/lcsc/UBLv10-alpha/ . [[NB this cannot be the OASIS web site]]

Back to top

1.2 Support for this Release

Support for this release is available via the UBL discussion list or by email to the Library Content Subcommittee Editor, Bill Meadows This support period applies from Friday, October 31, 2003 until Monday, January 19th, 2004.

In addition, we welcome any comments and suggestions arising from any trial implementations.

Back to top

1.3 General comments about OASIS UBL TC

The work of the OASIS UBL Technical Committee is open to public view through the mail archives linked from the UBL home page: http://www.oasis-open.org/home/index.php [[ there is anew URL

Formal input to UBL from industry data exchange organizations is provided through the UBL Liaison Subcommittee: http://oasis-open.org/committees/ubl/lsc/

Input from the general public is accepted through the ubl-comment mail list: http://lists.oasis-open.org/archives/ubl-comment/ [[ NB This is going to disappear soon ]]

Interested parties are invited to comment on the work of the UBL TC by subscribing to the ubl-comment list using the OASIS list manager: http://lists.oasis-open.org/ob/adm.pl

Back to top

1.4 Document Conventions

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] as quoted here:

" MUST: This word, or the terms "REQUIRED" or "SHALL", means that the definition is an absolute requirement of the specification."

" MUST NOT: This phrase, or the phrase "SHALL NOT", means that the definition is an absolute prohibition of the specification."

" SHOULD: This word, or the adjective "RECOMMENDED", means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course."

" SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED", means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label."

" MAY: This word, or the adjective "OPTIONAL", mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides)."

Back to top

1.5 Disclaimer

This document and its associated components are Copyright © 2003 OASIS and are protected by applicable law as works in progress within the OASIS Universal Business Language Technical Committee. As works in progress, they do not yet have the status of an OASIS Standard or an OASIS Committee Specification. This draft and its associated components are provided on a royalty-free basis and may be freely circulated for purposes of experimentation and review. While the construction of experimental prototypes based on these materials is encouraged for the purpose of generating input back to the committee process, implementers are strongly advised against basing commercial or mission-critical applications on the draft specifications contained in this package. THESE MATERIALS ARE FURNISHED WITH NO WARRANTY, EXPRESS OR IMPLIED, AS TO THEIR SUITABILITY FOR ANY APPLICATION.

Back to top

2. Document Scope

The Library Content part of UBL specifies a library of business information entities to be used in the construction of business documents together with a set of common XML business documents assembled from those entities.

This document contains normative and non-normative references used by UBL: the context scenario and business rules used to construct the business models and business documents; and the schema instances of the business documents.

Back to top

3. Normative References

[ISO11179] International Standards Organisation's Specification and Standardization of Data Elements for Information Technology

http://isotc.iso.ch/livelink/livelink/fetch/2000/2489/Ittf_Home/PubliclyAvailableStandards.htm??Redirect=1

[ISO 8601] Data elements and interchange formats -- Information interchange -- Representation of dates and times

http://www.iso.org/iso/en/CombinedQueryResult.CombinedQueryResult?queryString=8601

[CCTS] UN/CEFACT ebXML Core Components Technical Specification 1.90

http://xml.coverpages.org/CCTSv190-2002.pdf Should this be the CCTS 2.0??

[NDR]  Universal Business Language Naming and Design Rules

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

[UML]  Unified Modeling Language 1.4 (formal/01-09-67) Should this be updated to 2.0??

http://www.omg.org/cgi-bin/doc?formal/01-09-67

[XML]  Extensible Markup Language (XML) 1.0 (Second Edition),W3C Recommendation 6 October 2000

http://www.w3.org/TR/2000/REC-xml-20001006

[XSD1] XML Schema Part 1: Structures, W3C Recommendation 2 May 2001

http://www.w3.org/TR/xmlschema-1/

[XSD2] XML Schema Part 2: Datatypes, W3C Recommendation 02 May 2001

http://www.w3.org/TR/xmlschema-2/

Back to top

4. Terms and Definitions

Business Context

The formal description of a specific business circumstance as identified by the values of a set of context categories, allowing different business circumstances to be uniquely distinguished.

Class Diagram

A graphical notation used by the UML [UML] to describe the static structure of a system, including object classes and their associations.

Container

A modular and self-contained group of data components.

Containership

Aggregating components (nested elements in an XML schema [XML]).

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 emphasises the dependent associations to between object classes.

Document

A set of information components that are interchanged as part of a business activity; for example placing an order.

Document Assembly

A description of an hierarchical pathway through a normalized model of information components.

Hierarchical Model

A tree-structured model that can be implemented as a document schema.

Normalization

A formal technique for identifying and defining functional dependencies.

Normalized Model

A representation of normalized data components.

Schema

An XML document definition based on the W3C XML Schema language [XSD1][XSD2].

schema

Any XML document definition.

Spreadsheet Model

A representation of a data model in tabular form.

The terms Core Component and Business Information Entity are used in this specification with the meanings given in [CCTS].

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

Back to top

5. 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 Standards Organisation

NDR

UBL Naming and Design Rules [NDR]

UML

Unified Modeling Language [UML]

UN/CEFACT

United Nations Centre for Trade Facilitation and Electronic Business

XML

Extensible Markup Language [XML]

XSD

World Wide Web Consortium's XML Schema Language [XSD1][XSD2]

Back to top

6. Initial UBL Business Scenario

The specific context adopted for UBL 1.0 is based on a typical trading cycle- that of procurement.  We have used this context as a means of developing a set of common, re-usable Business Information Entities and their accompanying document definitions.

This section describes the scenario, business rules, transactions and choreography of  a rudimentary order-to-payment business process.  A set of UBL documents have been assembled to demonstrate the information exchanges required by these transactions.  We have adopted an 80/20 rule for this scenario - recognising this is not the definitive description of this process but a generalised case.

Of course, this is not the entire scope of the UBL Library.  The components and their documents can also be used as a basis for extension to create more function-rich, but separately defined, scenarios. As this occurs, we envisage that this section will become part of a registry of available business processes from different, complementary sources.

Back to top

6.1 The Order-to-Payment Business Process

This model addresses the requirements of a basic, usable trading cycle from Order to Invoice between Buyer and Seller. It includes specifications for:

Figure 1. Order-to-Payment Business Process

Back to top

6.1.1 Items

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 Standard body's system.

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:

Back to top

6.1.1.1 Item Requiring Description

This is an item that is not identified by an unambiguous, machine processable, product code and where it is necessary to provide additional descriptive information about the item to precisely identify what is required.

Back to top

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

Back to top

6.1.1.3 Item Measurements

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

Back to top

6.1.1.4 Other Item Details

For an 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 Order Response (Complex)].

Ordered items may include Hazardous items, insofar 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.

Back to top

6.1.2 Order

The Order may specify Charge Payment (e.g. freight, documentation etc) instructions 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 overall allows only for specification of Currency (e.g. £, $, € etc by ISO currency code) for Pricing, for Invoice presentation, for Tax accounting. In the case of International freight/documentation charges, it may also be necessary to specify the Currency.

Trade discount may be specified at 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 (Complex)].

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 journey
    • 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.

Back to top

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

Back to top

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

Back to top

6.1.4 Order Response (Complex)

Proposed changes by the Seller would be accomplished through the OrderResponse (Complex).

The Order Response (complex) is a complete replacement of the Order. It reflects the entire state of the 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 (complex).  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.

Back to top

6.1.5 Order Change

The Buyer can change an Order, subject to the legal contract or trading partner agreement, by sending an OrderChange, or by sending an Order Cancellation followed by a new, complete replacement, Order.

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

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

Back to top

6.1.6 Order Cancellation

At any point of the process, a Buyer can cancel an active order transaction using the Order Cancellation document. Legal contracts, trading partner agreements and business rules would restrict at what point a Order Cancellation would 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 a contract formation for business commitments will dictate what if any of these restrictions and/or guidelines will apply.

Back to top

6.1.7 Despatch Advice

The following information may appear in the Despatch Advice:

• Transport
  • Means
  • Mode
  • One- to many-legged journey
    • Dates
    • Locations
  • Arrival 'window'
• Consignment packaging
  • Type, e.g. Container, Pallet
  • Identifier, e.g. SSCC, Shipping label (Despatch Advice)

The Despatch Advice caters for two situations:

• Organisation of the delivery set of items by Transport Handling Unit(s) so that the Receiver can check 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.
• Organisation 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 may not correspond one-to-one with Order Lines, but these need to be linked by reference. The information structure of the Despatch Advice, geared to physical considerations, 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.

Back to top

6.1.8 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 and/or damaged items.

The Receipt Advice caters for two situations. For ease of processing claimed receipt against claimed delivery, it needs to be organised in the same way as the matching 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, to state any quantities rejected for a given reason.

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

Back to top

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

• Pre-payment invoice (payment expected)
• Pro-forma invoice (pre advice, payment not expected)
• Normal Invoice, on despatch for despatched items
• Invoice after return of Receipt Advice

The invoice only contains the information that is necessary for invoicing purposes. It does not re-iterate information already established in the Order, Order Change, Order Response (complex), Despatch Advice, or Receipt Advice that is not necessary when invoicing. The Invoice refers to the Order, Despatch Advice or Receipt Advice by a Reference of those documents.

Taxation on the Invoice allows for compound taxes, the sequence of calculation 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

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

Back to top

6.1.9.1 Invoice Item Line

Each Invoice Line refers to the related Order Line and may refer to the Despatch Advice Line and/or Receipt Advice Line.

Back to top

6.2 Adapting UBL for other scenarios

Different business scenarios to meet different ways of trading cycle operation can, and should, be developed by separate, appropriate teams of business experts. Ideally they should take advantage of the basic UBL model as a starting point and as an exemplar. However, part of the UBL charter is to develop a context methodology which will formalize the way that documents for other scenarios can be implementated.  When this is in place as part of UBL 2.0 it will ensure interoperability, reduce ambiguity, and avoid unnecessary overlap.  Meanwhile we encourage the UBL community to share their customisation and developments, both to improve the quality of the underlying library and provide valuable input into the UBL context methodology work.

For example within the procurement domain, suggested other scenarios include situations of:

• Vendor managed inventory
• Self-billing
• Master Order and Call-offs
• Prior Quote Request & Quotation
• International Trade requiring Multi-party Transportation
• Hire Trade (e.g. tool hire, scaffolding hire)
• etc.

Back to top