Universal Business Language v2.0

Public Review Draft, 20 September 2006

Artifact Type:

Specification

Artifact Identifier:

ubl-specification-PRD-2.0-3

Location:

http://docs.oasis-open.org/ubl/prd3-UBL-2.0/
http://docs.oasis-open.org/ubl/prd3-UBL-2.0.zip

Technical Committee:

OASIS Universal Business Language TC

Chairs:

Jon Bosak (Sun Microsystems)
Tim McGrath

Editors:

Jon Bosak
Tim McGrath
G. Ken Holman

Abstract:

This specification defines the Universal Business Language version 2.0.

Status:

This document was last revised or approved by the UBL TC on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.

Technical Committee members should send comments on this specification to the Technical Committee's email list. Others should send comments to the Technical Committee by using the "Send A Comment" button on the Technical Committee's web page at www.oasis-open.org/committees/ubl/ .

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page at http://www.oasis-open.org/committees/ubl/ipr.php .

See Appendix A: Release Notes for more information regarding this release package.

Notices

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.

Copyright © OASIS Open 2006. All Rights Reserved.

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.

Table of Contents

1. Introduction (Informative)

2. Normative References

3. Terms and Definitions

4. Symbols and Abbreviations

5. UBL 2.0 Context of Use

6. UBL 2.0 Schemas

7. Additional Document Constraints

Appendix A (Informative): Release Notes

Appendix B (Informative): Upgrading from UBL 1.0 to UBL 2.0

Appendix C (Informative): UBL Development Methodology

Appendix D (Informative): UBL 2.0 Document Models

Appendix E (Informative): UBL 2.0 Code Lists and Two-phase Validation

Appendix F (Informative): UBL 2.0 Naming and Design Rules

Appendix G (Informative): ASN.1 Specification

1. Introduction (Informative)

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

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

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

A standard basis for XML business schemas provides the following advantages:

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

UBL schemas are modular, reusable, and extensible in XML-aware ways. As the first standard 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 release.

Acknowledgements

The OASIS UBL TC thanks Altova for its contribution of XML Spy licenses for use in UBL schema design and Sparx Systems for its contribution of Enterprise Architect licenses for use in developing UML content models. Special thanks are due to GEFEG for its contribution of FX (EDIFIX) and technical expertise in the generation and quality review of UBL schemas.

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] ISO/TS 15000-5:2005 Electronic Business Extensible Markup Language (ebXML) — Part 5: ebXML Core Components Technical Specification, Version 2.01 (identical to Part 8 of the ebXML Framework)
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.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
[SCH] Document Schema Definition Languages (DSDL) - Part 3: Rule-based validation (Schematron)
http://www.iso.ch/iso/en/CatalogueDetailPage.CatalogueDetail?CSNUMBER=40833
http://www.schematron.com
[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. Second Edition. W3C Recommendation 28 October 2004
http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/
http://www.oasis-open.org/committees/download.php/19816/xsd1.html
[XSD2] XML Schema Part 2: Datatypes. Second Edition. W3C Recommendation 28 October 2004
http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/
http://www.oasis-open.org/committees/download.php/19817/xsd2.html
[XSLT] XSL Transformations (XSLT) Version 1.0, W3C Recommendation 16 November 1999
http://www.w3.org/TR/1999/REC-xslt-19991116
http://www.oasis-open.org/committees/download.php/18891/REC-xslt-19991116.html

3. Terms and Definitions

Assembly model
A tree-structured model of ABIEs 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.
Context
The circumstance or events that form the environment within which something exists or takes place.
Document
A set of information components that are interchanged as part of a business transaction; for example, in placing an order.
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
ASBIE
Association Business Information Entity
BBIE
Basic Business Information Entity
BIE
Business Information Entity
CC
Core Component
CV2
Credit Card Verification Numbering System
EDI
Electronic Data Interchange
ISO
International Organization for Standardization
NDR
UBL Naming and Design Rules (see Appendix F)
UML
Unified Modeling Language [UML]
UN/CEFACT
United Nations Centre for Trade Facilitation and Electronic Business
UNDG
United Nations Dangerous Goods
URI
Uniform Resource Identifier
UUID
Universally Unique Identifier
XML
Extensible Markup Language [XML]
XPath
The XML Path Language
XSD
W3C XML Schema Language [XSD1] [XSD2]

5. UBL 2.0 Context of Use

The processes described in this section, and the business rules associated with them, define a context for the use of UBL 2.0 business documents. They are normative insofar as they provide semantics for the UBL document schemas, but they should not be construed as limiting the application of those schemas.

UBL 2.0 extends the order-to-invoice processes of UBL 1.0 to cover a supply chain from sourcing to payment, including the commercial collaborations of international trade. The following diagram illustrates the process context assumed by UBL 2.0 documents.

[Use Case Diagram]

Figure 1. Processes Covered by UBL 2.0

It is important to note that the UBL 2.0 library is designed to support the construction of a wide variety of document types beyond those provided in the 2.0 package. It is expected that implementers will develop their own customized document types and components and that other UBL document types will be added as the library evolves.

5.1 General Business Requirements

This section describes some of the requirements and general business rules that are assumed for collaborations and document exchanges in UBL 2.0.

5.1.1 Items

5.1.2 Item Identification

One of the following identifiers may be used to identify each Item (for example, a product):

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.1.3 Item Instances

Certain Items may be identified and ordered as individual, unique objects, for example, a specific car rather than a make and model of a car. This form of identification may also be needed for product tracing (e.g., perishable goods) or because of the nature of the commodity (e.g., used, collectible, specialized, or rare).

In data modeling terms, an Item Instance is an extension of an Item.

5.1.4 Item Pricing

For any given Item, price ranges by amount, quantity, location, etc., are specified by the Seller during the sourcing stage. They are not repeated back to the Seller during Ordering; only the active price is specified.

In some cases, the Buyer may not know the Item Price, in which case it is not specified. This makes a detailed response from the Seller necessary; see Order Response.

5.1.5 Hazardous Items

Although ordered items may include Hazardous items, 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 and Transportation documents.

5.1.6 Parties

In UBL, a party is defined as an individual, a group, or a body having a role in a business function.

Dependent on the business process, a Party may play various roles in the document exchange.

5.1.7 Multilingual Text

Some textual components, such as Notes and Description, may be specified in several languages. Each should be a separate occurrence of the component, using the language attribute to define its presentation. However, multiple occurrences of the same textual components should not be in the same language.

5.2 Business Processes

The UBL 2.0 documents and library are designed to support the typical business processes outlined in Figure 1.

The following sections describe each business process in more detail. But first we should explain the roles that the parties involved in these processes may perform.

5.2.1 Party Roles

In the UBL supply chain processes, two main actors, Customer and Supplier, represent the key organizations or individuals involved in the processes. Each of these actors may play various roles. Processes may also involve supplementary roles that may be provided by different parties.

The actual role undertaken is dependent on the context of use. For example, the Despatch Party and Delivery Party as applied to the Procurement process may differ in the Transportation process. In other words, whether the Consignor in a Transportation process is actually equal to the Despatch Party or Seller in the Procurement process depends on the specific circumstances.

The following table contains a description of the typical roles for the actors known as Party, Customer Party, and Supplier Party.

Actor

Role

Description

Example

Synonyms

Sends

Receives

Customer Party

Originator

The party that had the original demand for the goods and/or services and therefore initiated the procurement transaction.

The Originator participates in pre-ordering activity either through RFQ and Quotation or by receiving a Quotation as a response to a punchout transaction on a marketplace or Seller’s website.

If the Originator subsequently places an Order, the Originator adopts the role of Buyer.

The Originator is the typically the contact point for queries regarding the original requirement and may be referred to in an Order Change, Order Cancellation, or Order Response.

If an employee requests a computer, the employing company may become the Buyer, but the employee is the Originator. They need to receive information about the order.

 

Request for Quotation

 

Quotation

Customer Party

Buyer

The party that purchases the goods or services on behalf of the Originator.

The Buyer may be referred to in Order Response, Despatch Advice, Invoice, Self Billed Invoice, Credit Note, and Account Statement.

A company may delegate the task of purchasing to a specialized group to consolidate orders and gain greater discounts.

Order Point

Order, Order Change, and Order Cancellation

Order Response

Supplier Party

Delivery

The party to whom goods should be delivered.

The Delivery Party may be the same as the Originator.

The Delivery Party must be referred to at line item level in RFQ, Quotation, Order, Order change, Order Cancellation, and Order Response.

The Delivery Party may be referred to at line level in Invoice, Self Billed Invoice, Credit Note, and Debit Note.

The Delivery Party may be stipulated in a transport contract.

If a municipality buys a wheelchair for a citizen, the wheelchair must be delivered to the citizen (the Delivery Party). In such cases the citizen may be notified before delivering the wheelchair.

Delivery Point, Destination Party, Receiver, Recipient

Receipt Advice

Despatch Advice

Customer Party

Accounting Customer

The party responsible for making settlement relating to a purchase and resolving billing issues using a Debit Note.

The Accounting Customer must be referred to in an Order and may be referred to in an Order Response.

In a Self Billing scenario, the Accounting Customer is responsible for calculating and issuing tax invoices.

If a kindergarten buys some toys they may be the Originator, Buyer, and Delivery Party, but the municipality may play the role of Accounting Customer — they are going to pay for it.

Invoicee, Accounts Payable, Debtor

In a traditional Billing scenario: Debit Note, Account Response, and Remittance Advice

In a Self Billing scenario: Self Billed Invoice, Self Billed Credit Note, and Remittance Advice

In a traditional Billing scenario: Invoice, Credit Note, and Statement of Account

In a Self Billing scenario: Credit Note, Account Response, and Statement of Account

Supplier Party

Seller

The party responsible for handling Originator and Buyer services.

The Seller party is legally responsible for providing the goods to the Buyer.

The Seller party receives and quotes against RFQs and may provide information to the Buyer’s requisitioning process through Catalogues and Quotations.

The organization that sells wheelchairs to municipalities.

Sales Point, Provider, Customer Manager

Quotation, Order Response, Order Response Simple, Catalogue, Catalogue Deletion, Catalogue Item Specification Update, Catalogue Pricing Update

RFQ, Order, Order Change, Order Cancellation, Request for Catalogue

Supplier Party

Despatch

The party where goods are to be collected from.

The Despatch Party may be stipulated in a transport contract.

The wheelchair Supplier may store chairs at a local warehouse. The warehouse will actually despatch the chair to the Delivery Party.

The local warehouse is then the Despatch Party.

Despatch Point, Shipper, Sender

Despatch Advice

Receipt Advice

Supplier Party

Accounting Supplier

The party who claims the payment and is responsible for resolving billing issues and arranging settlement.

There are cases where the Accounting Supplier is not the Seller party. For example, factoring, where the invoicing is outsourced to another company.

Accounts Receivable, Invoice Issuer, Creditor

In a traditional Billing scenario: Invoice, Credit Note, and Statement of Account

In a Self Billing scenario: Credit Note, Account Response and Statement of Account

In a traditional Billing scenario: Debit Note, Account Response, and Remittance Advice

In a Self Billing scenario: Self Billed Invoice, Self Billing Credit Note, and Remittance Advice

Supplier Party

Payee

The party to whom the Invoice is paid.

The Accounting Supplier may not be the party to be paid due to changes in the organization, e.g., a company merger.

Accounts Receivable, Creditor

 

Remittance Advice

Customer Party

Contractor

The party responsible for the contract to which the Catalogue relates.

An organization has a central office for maintaining catalogues of approved items for purchase.

Central Catalogue Party, Purchasing Manager

Request for Catalogue

Catalogue, Catalogue Deletion, Catalogue Item Specification Update, Catalogue Pricing Update

Party

Provider

The party responsible for the integrity of the information provided about an item.

The manufacturer may publish and maintain the data sheets about a product.

 

Catalogue, Catalogue Deletion, Catalogue Item Specification Update, Catalogue Pricing Update

 

Party

Receiver

The party receiving a document.

The party receiving a Catalogue.

Catalogue items may never be ordered, so the recipient of the catalogue is not an Originator or a Buyer.

A marketplace may receive an Application Response.

 

 

Catalogue, Catalogue Deletion, Catalogue Item Specification Update, Catalogue Pricing Update, Application Response

Party

Sender

The party sending a document.

A marketplace may send an Application Response.

 

Application Response

 

Party

Consignor

The party consigning the goods as stipulated in the transport contract. A Buyer, Delivery, Seller, or Despatcher Party may also play the role of Consignor.

Also known as the Transport Service Buyer.

The Consignor may be stipulated in a transport contract.

The wheelchair Supplier may source from a local warehouse. The Freight Forwarder will collect the chair from the local warehouse, which is thus the Consignor. In this case, the warehouse also plays the role of Despatch Party to the Freight Forwarder.

Despatch Point, Shipper, Sender, Transport Service Buyer

Forwarding Instruction, Packing List

Bill of Lading, Waybill, Freight Invoice, Transportation Status

Party

Consignee

The party receiving a consignment of goods as stipulated in the transport contract.

The party taking responsibility for the receipt of the consignment covering the wheelchair.

Delivery Point, Transport Service Buyer

Forwarding Instruction, Freight Invoice

Bill of Lading, Waybill, Freight Invoice, Transportation Status

Party

Freight Forwarder

The party arranging the carriage of goods, including connected services and/or associated formalities, on behalf of a Consignor or Consignee.

Also known as the Transport Service Provider.

The Freight Forwarder may also be the Carrier.

The Freight Forwarder may create an invoice and bill to the Transport Service Buyer for the transportation service provided.

The Consignor may have a contract with this Freight Forwarder, which is a Transport Services Provider, to arrange all their transport needs.

Shipping Agent, Broker, Courier, Transport Service Provider

Forwarding Instruction, Freight Invoice, Transportation Status

Bill of Lading, Waybill, Packing List

Party

Carrier

The party providing physical transport services.

The Freight Forwarder may engage an airline company to deliver the wheelchair. The airline is then the Carrier and delivers the chair to the Delivery Party.

Freight Haulier, Shipper, Ships Agent, Shipping Company, Airline, Rail Operator, Road Haulier

Bill of Lading, Waybill

Forwarding Instruction

Party

Exporter

The party who makes regulatory export declarations, or on whose behalf regulatory export declarations are made, and who is the owner of the goods or has similar right of disposal over them at the time when the declaration is accepted.

The wheelchair Supplier has to apply for a Certificate of Origin in order to sell the chairs overseas.

Seller, Consignor

Certificate of Origin

Application Response

Party

Endorser

The party appointed by the Government of a country who has the right to certify a Certificate of Origin.

This endorsement restricts goods imported from certain countries for political or other reasons.

The Government agency validates all the information provided by Exporter for Certificate of Origin approval.

Authorized Organization, Embassy

Certificate of Origin, Application Response

Certificate of Origin

Party

Importer

The party who makes, or on whose behalf an agent or other authorized person makes, an import declaration. This may include a person who has possession of the goods or to whom the goods are consigned.

A specialized group in a company consolidates the purchase request and handles the receiving of goods.

Order Point, Delivery Party, Buyer, Customer, Consignee

 

Certificate of Origin

Table 1. Party Roles

5.3 Sourcing

There are three kinds of sourcing:

A Seller Supplier Party, Contractor Customer Party, Originator Customer Party, or Buyer Customer Party may initiate sourcing.

Document types in these processes are Catalogue Request, Application Response, Catalogue Item Specification Update, Catalogue Pricing Update and Catalogue Deletion.

5.3.1 Catalogue Provision

A Catalogue is defined as a document produced by a party in the procurement chain that describes items and prices.

Catalogue provision is the case where a Provider sends information regarding items available for purchase to a Receiver. This may be on request or unsolicited.

Because they are only potential purchasers, a Receiver may never become a Customer Party.

5.3.1.1 Sourcing Business Rules Assumed

5.3.1.2 Create Catalogue

The process of creating a Catalogue is shown in the following diagram.

[Create Catalogue Activity Diagram]

Figure 2. Create Catalogue Process

5.3.1.3 Update Catalogue Item Specification

The process of updating a Catalogue Item Specification is shown in the following diagram.

[Update Item Specification Activity Diagram]

Figure 3. Update Item Specification Process

5.3.1.4 Update Catalogue Pricing

The process of updating Catalogue pricing is shown in the following diagram.

[Update Catalogue Pricing Activity Diagram]

Figure 4. Update Catalogue Pricing Process

5.3.1.5 Delete Catalogue

Deletion of a Catalogue is shown in the following diagram.

[Delete Catalogue Activity Diagram]

Figure 5. Delete Catalogue Process

5.3.2 Customer Initiated Sourcing

Customer initiated sourcing is the case where the Originator asks for a quotation, as shown in the following diagram.

[Customer Initiated Sourcing Activity Diagram]

Figure 6. Customer Initiated Sourcing Process

5.3.3 Sourcing Punchout

Punchout applications are a technological innovation whereby an Originator is able to directly access a Seller’s application from within their own procurement application.

[Sourcing Punchout Activity Diagram]

Figure 7. Punchout Sourcing Process

The Originators leave (“punch out” from) their system and interact with the Seller’s catalogue to locate and order products, while their application transparently gathers pertinent information.

While conceptually the punchout request is a form of Request for Quote, the exchange transaction is tightly coupled to the specific catalogue application and considered outside the scope of UBL 2.0.

5.4 Ordering

Ordering is the collaboration that creates a contractual obligation between the Seller Supplier Party and the Buyer Customer Party.

Document types in these processes are Order, Order Response, Order Response Simple, Order Change, and Order Cancellation.

[Ordering Activity Diagram]

Figure 8. Ordering Process

5.4.1 Ordering Business Rules Assumed

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 may 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 may 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.4.3).

The Order provides for multiple Order Lines.

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

The Buyer may indicate potential alternatives that are acceptable.

5.4.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 fulfil without change or that the Order has been rejected.

5.4.3 Order Response

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

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

The Seller may advise on replacements or substitutes which will be made, or changes necessary, using the Order Response.

5.4.4 Order Change

The Buyer may 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.4.5) followed by a new, complete replacement Order.

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

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

5.4.5 Order Cancellation

At any point of the process, a Buyer may 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 the initiation of the delivery process). 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.5 Fulfilment

Fulfilment is the collaboration in which the goods or services are transferred from the Despatch Party to the Delivery Party.

Document types in these processes are Despatch Advice, Receipt Advice, Order Cancellation and Order Change.

In common practice, fulfilment is either supported by a proactive Despatch Advice from the Despatch Party or by a reactive Receipt Advice from the Delivery Party.

If the Customer is not satisfied with the goods or services, they may then cancel or change the order (see Section 5.4, Ordering).

The Seller may have a fulfilment (or customer) service dealing with anomalies.

[Fulfilment with Despatch Advice Activity Diagram]

Figure 9. Fulfilment with Despatch Advice Process

5.5.1 Despatch Advice Business Rules Assumed

The Despatch Advice is sent by the Despatch Party to the Delivery Party to confirm shipment of items.

The Despatch Advice provides for two situations:

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

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

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

5.5.2 Receipt Advice Business Rules Assumed

The Receipt Advice is sent by the Delivery Party to the Despatch Party to confirm receipt of items and is capable of reporting shortages or damaged items.

[Fulfilment with Receipt Advice Activity Diagram]

Figure 10. Fulfilment with Receipt Advice Process

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

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

5.6 Billing

In the Billing collaboration, a request is made for payment for goods or services that have been ordered, received, or consumed. In practice, there are several ways in which goods or services may be billed.

Document types in these processes are Invoice, Credit Note, Debit Note, and Application Response.

For UBL 2.0, we assume the following methods:

  1. Traditional Billing

  2. Self Billing (also known as billing on receipt)

5.6.1 Billing Business Rules Assumed

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

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

Taxation on the Invoice allows for compound taxes, the sequence of calculation being implied by the sequence of information repeated in the data stream (e.g., Energy tax, with VAT — Value Added Tax — superimposed). The OASIS TaxML Technical Committee (http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tax) is developing UBL implementation profiles for various tax regimes, such as those required by the European Community.

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

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

5.6.2 Traditional Billing

Traditional billing is where the supplier invoices the customer when the goods are delivered or the services provided.

In this case, the invoice may be created at the time of despatch or when the Delivery Party acknowledges that the goods have been received (using a Receipt Advice).

When there are discrepancies between the Despatch Advice, Receipt Advice, and/or the Invoice and the goods actually received, or the goods are rejected for quality reasons, the customer may send an Application Response or a Debit Note to the supplier. The supplier may then issue a Credit Note or another Invoice as required.

A Credit Note or Debit Note may also be issued in the case of retrospective price change.

Credit Notes or Debit Notes may be also issued after the Billing collaboration (as part of the Payment collaboration).

5.6.2.1 Billing using Credit Notes

Billing using Credit Notes is shown in the following diagram.

[Billing with Credit Note Activity Diagram]

Figure 11. Billing with Credit Note Process

When using Credit Notes, the Supplier (in their Accounting role) is responsible for specifying the tax requirements.

5.6.2.2 Billing using Debit Notes

Billing using Debit Notes is shown in the following diagram.

[Billing with Debit Note Activity Diagram]

Figure 12. Billing with Debit Note Process

When using Debit Notes, both the Supplier (in their Accounting role) and the Customer (in their Accounting role) are responsible for providing taxation information.

5.6.3 Self Billing

A self billing process is where a Customer “invoices” itself, in the name and on behalf of the Supplier, and provides the Supplier with a copy of the self billed invoice.

5.6.3.1 Self Billing using Credit Notes

Self Billing using Credit Notes is shown in the following diagram.

[Self Billing with Credit Note Activity Diagram]

Figure 13. Self Billing with Credit Note Process

If the Supplier finds that the Self Billed Invoice is incorrect, e.g., wrong quantities or wrong prices, or if the goods have not been invoiced at all, it may send an Application Response or a Credit Note to the Customer. The customer may then verify whether the adjustment is acceptable or not and consequently issue another Self Billed Invoice or a Self Billed Credit Note.

5.6.3.2 Self Billing using Self Billed Credit Notes

Self Billing using Self Billed Credit Notes is shown in the following diagram.

[Self Billing with Self Billed Credit Note Activity Diagram]

Figure 14. Self Billing with Self Billed Credit Note Process

When using Self Billed Credit Notes, the Customer is raising the Self Billed Credit Note in the name and on behalf of the Supplier. Therefore the Supplier and the Customer are still both responsible for providing taxation information.

5.6.4 Freight Billing

An extension of the Billing process is that of Freight Billing. This represents the billing process between the Transport Service Buyer and Transport Service Provider through the use of an Invoice for freight charges.

The Transport Service Provider initiates the process of billing the Transport Service Buyer for logistic services.

The Freight Invoice lists the charges incurred in order to fulfill the agreed service.

[Freight Billing Activity Diagram]

Figure 15. Freight Billing Process

5.6.5 Reminder For Payment

A Reminder may be used to notify the Customer of accounts due to be paid.

[Reminder For Payment Process Diagram]

Figure 16. Reminder for Payment Process

5.7 Payment

In the payment collaboration, the Payee (who is most often the Accounting Customer) is notified of any funds transferred against the account of the Accounting Supplier using a Remittance Advice.

The document type in this process is the Remittance Advice.

[Payment Activity Diagram]

Figure 17. Payment Process

5.7.1 Report State of Accounts

A Statement of Account may be used to notify the Accounting Customer of the status of the billing.

[Statement Activity Diagram]

Figure 18. Statement Process

5.8 Initiate Transport Services

These process define the ordering of logistical services for international trade. With receipt of an order and acknowledgement by the Supplier Party that the goods are available and ready to be shipped, the Consignor or Consignee initiates the transportation arrangements. This includes booking the consignment with a Transport Service Provider such as the Freight Forwarder or Carrier and advising the Delivery Party of the arrangements as needed.

Document types in these processes are Forwarding Instructions, Packing List, Waybill, and Bill of Lading.

It should be noted that these processes do not cover regulatory notifications such as Customs declarations or arrangements between carriers, hauliers, and terminal operators for the physical movement of goods.

[Initiate Transport Services Activity Diagram]

Figure 19. Initiate Transport Services Process

5.8.1 Forwarding Instructions

Forwarding Instructions are normally used by any party who gives instructions for the transportation services required for a consignment of goods (the Transport Service Buyer) to any party who is contracted to provide the transportation services (called the Transport Service Provider). Forwarding Instructions may also be used by any party who requests a booking of shipment space to be made for the transportation services required for a consignment of goods to any party who will provide the underlying transportation services. The parties who issue this document are commonly referred to as the shipper, consignee, or consignor, while the parties who receive this document are forwarders, carriers, shipping agents, etc.

Forwarding Instructions may also be issued by a freight forwarder or shipping agent in their capacity as a Transport Service Buyer. This document may be used to arrange for the transportation:

5.8.2 Bill of Lading

A Bill of Lading is issued by the party who provides the physical transportation services (e.g., carrier) to the party who gives instructions for the transportation services (shipper, consignor, etc.) stating the details of the transportation, charges, and terms and conditions under which the transportation service is provided.

It may also be issued by the party who acts as an agent for the carrier or other agents to the party who gives instructions for the transportation services (shipper, consignor, etc.) stating the details of the transportation, charges, and terms and conditions under which the transportation service is provided but does not provide the physical transportation service.

A Bill of Lading corresponds to the information on the Forwarding Instruction. It is used for ocean or river modes of transport.

A Bill of Lading may serve as a contractual document between the parties for the transportation service. The document evidences a contract of carriage by sea and the acceptance of responsibility for the goods by the carrier, by which the carrier undertakes to deliver the goods against surrender of the document. A provision in the document that the goods are to be delivered to the order of a named person, or to order, or to bearer, constitutes such an undertaking.

5.8.3 Waybill

A Waybill is issued by the party who provides the physical transportation services to the party who gives instructions for the transportation services (shipper, consignor, etc.). It states the details of the transportation, charges, and terms and conditions under which the transportation service is provided.

Unlike a Bill of Lading, a Waybill is not negotiable and cannot be assigned to a third party. It is issued as a cargo receipt and is not required to be surrendered at the destination in order to pick up the cargo. This simplifies the documentation procedures between a transport service buyer and a transport service seller.

5.8.4 Packing List

A Packing List is normally issued by the Consignor. It states the distribution of goods in individual packages. Based on this detail, the party who provides the logistic services will make arrangement for the transportation of the goods.

5.9 Certification of Origin of Goods

A Certificate of Origin is a document required by governments declaring that goods in a particular international shipment are of a certain origin.

It is the responsibility of the Exporter to sign the Certificate of Origin document and submit it to a local chamber of commerce or any designated government agency or board. These parties are the endorser and issuer of the Certificate of Origin. The Endorser must have access to other documents, such as the commercial invoice and Bill of Lading, in order to verify the Exporter’s claims that the goods originated in that country. Finally, the issued Certificate of Origin is sent to the Importer.

[Certification Of Origin Of Goods Activity Diagram]

Figure 20. Certification of Origin of Goods Process

5.10 Report Status of Goods

The Transportation Status document is a means for a Freight Forwarder (also known as the Transport Service Provider) to communicate to the Consignee or Consignor (also known as the Transport Service Buyer) or Notify Party, the status of shipments that are currently under the Freight Forwarder’s management.

A Transportation Status document is provided by the Freight Forwarder, either through an individual specific request or through an agreed status reporting procedure.

[Report Status of Goods Activity Diagram]

Figure 21. Report Status of Goods Process

5.11 Document Types

The following table lists all the UBL 2.0 document types together with their target business processes and roles for parties who would typically submit and receive them.

Document Name

Description

Processes Involved

Submitter Role

Receiver Role

Catalogue Request

A document to request a Catalogue from a seller. May be either an entire new Catalogue or an update (at the discretion of the Seller).

Create Catalogue, Update Item Specification, Update Pricing

Contracting Party

Seller

Catalogue

A document produced by a party in the procurement chain that describes items and prices. The document typically enables the transmission of information regarding pricing and catalogue details for goods and services offered by a seller to a buyer.

Create Catalogue

Seller

Contracting Party

Catalogue Deletion

A document to cancel an entire Catalogue. All previous Catalogue information becomes obsolete.

Delete Catalogue

Seller

Contracting Party

Catalogue Item Specification Update

A document to update information about Items in an existing Catalogue.

Update Catalogue Item Specification

Seller

Contracting Party

Catalogue Pricing Update

A document to update information about Prices in an existing Catalogue.

Update Catalogue Pricing

Seller

Contracting Party

Request For Quotation

A document to request pricing and availability information about goods or services. The document may requesting a quote on specified goods or services.

Sourcing

Originator

Seller

Quotation

A document to specify pricing and availability information about goods or services. The document which, with a view to concluding a contract, sets out the conditions under which the goods are offered.

Sourcing

Seller

Originator

Order

A document that contains information directly relating to the economic event of ordering products. The document by means of which a customer initiates a transaction with a supplier for the supply of goods or services as specified, according to conditions set out in an offer, or otherwise known to the customer.

Ordering

Buyer

Seller

Order Response

A document responding to the customer to indicate detailed responses against a single order already received.

Ordering

Seller

Buyer

Order Response Simple

A document responding to the customer to indicate simple acceptance or rejection of an entire order. The document acknowledging an undertaking to fulfil an order and confirming conditions or acceptance of conditions.

Ordering

Seller

Buyer

Order Change

A document that contains information directly relating to the economic event of changing an order already sent.

Ordering, Fulfilment

Buyer

Seller

Order Cancellation

A document that advises either party of the cancellation of an Order.

Ordering, Fulfilment

Buyer

Seller

Despatch Advice

A document that describes the content of goods shipped. Document/message by means of which the seller or consignor informs the consignee about the despatch of goods.

Fulfilment

Despatch

Delivery

Receipt Advice

A document that advises the goods received and accepted by the buyer. The document acknowledges the receipt of goods and in addition may indicate receiving conditions.

Fulfilment

Delivery

Despatch

Invoice

A document claiming payment for goods or services supplied under conditions agreed between the supplier and the customer. In most cases this document describes the actual financial commitment of goods or services ordered from the supplier.

Billing

Supplier Accounting Party

Customer Accounting Party

Self Billed Invoice

A document provided by a customer, in the name and on behalf of the supplier, describing the claim for payment for goods or services supplied under conditions agreed between the supplier and the customer.

Billing

Customer Accounting Party

Supplier Accounting Party

Credit Note

A document for a supplier to specify a reduced payment. The document for providing credit information to the relevant party.

Billing

Supplier Accounting Party

Customer Accounting Party

Debit Note

A document for a customer to specify a reduced payment. The document for providing debit information to the relevant party.

Billing

Customer Accounting Party

Supplier Accounting Party

Self Billed Credit Note

A document for a customer to specify a reduced payment in a Self Billing environment. The document indicates that the customer is claiming credit in a self billing environment.

Billing

Customer Accounting Party

Supplier Accounting Party

Statement

A document to list the financial transactions between customer and supplier and notify of their status. This is a Statement of Account and not intended as a summary Invoice.

Billing

Supplier Accounting Party

Customer Accounting Party

Reminder

A document used to request payment.

Billing

Supplier Accounting Party and/or Payee

Customer Accounting Party and/or Payee

Remittance Advice

A document to specify that funds have been transferred from the customer to the supplier. The document advising of the remittance of payment.

Payment

Customer Accounting Party and/or Payee

Supplier Accounting Party and/or Payee

Forwarding Instructions

The document used by any party who gives instructions for the transportation services required for a consignment of goods to any party who is contracted to provide the transportation services. The parties who issue this document are commonly referred to as the shipper or consignor while the parties who receive this document are forwarders, carriers, shipping agents, etc. Note that this document may also be issued by a forwarder or shipping agent in their capacity as a Transport Service Buyer. This document may be used to arrange for the transportation (1) of different types of goods or cargoes; (2) whether containerized or non-containerized; (3) through different modes of transport including multi-modal, and (4) from any origin to any destination. The document issued to a freight forwarder, giving instructions regarding the action to be taken by the forwarder for the forwarding of goods described therein.

Initiate Transport Services

Consignor (or Consignee), Freight Forwarder

Freight Forwarder, Carrier

Bill of Lading

A document issued by the party who acts as an agent for the carrier or other agents, to the party who gives instructions for the transportation services (shipper, consignor, etc.) stating the details of the transportation, charges, and terms and conditions under which the transportation service is provided. The party issuing this document does not necessarily provide the physical transportation service. It corresponds to the information on the Forwarding Instructions. It is used for any mode of transport. A Bill of Lading may serve as a contractual document between the parties for the transportation service. The document evidences a contract of carriage by sea and the acceptance of responsibility for the goods by the carrier, and by which the carrier undertakes to deliver the goods against surrender of the document. A provision in the document that the goods are to be delivered to the order of a named person, or to order, or to bearer, constitutes such an undertaking. A negotiable document that evidences a contract of carriage by sea and the taking over or loading of goods by carrier, and by which carrier undertakes to deliver goods against surrender of the document.

Initiate Transport Services

Freight Forwarder, Carrier

Consignor (or Consignee), Freight Forwarder

Waybill

A document issued by the party who acts as an agent for the carrier or other agents to the party who gives instructions for the transportation services (shipper, consignor, etc.) stating the details of the transportation, charges, and terms and conditions under which the transportation service is provided. The party issuing this document may not provide the physical transportation service. It corresponds to the information on the Forwarding Instructions. It is used for all modes of transport. It may serve as a contractual document between the parties for the transportation service. A Waybill is a non-negotiable document evidencing the contract for the transport of cargo. It provides information similar to Bill of Lading but is not negotiable and cannot be assigned to a third party.

Initiate Transport Services

Freight Forwarder, Carrier

Consignor (or Consignee), Freight Forwarder

Packing List

A document stating the detail of how goods are packed. The document specifies the distribution of goods in individual packages (in trade environment the despatch advice message is used for the packing list).

Initiate Transport Services

Consignor

Freight Forwarder

Freight Invoice

A document issued by a transport operation specifying freight costs and charges incurred for a transport operation and stating conditions of payment.

Freight Billing

Freight Forwarder

Consignor or Consignee

Certificate of Origin

A document required by governments, declaring that goods in a particular international shipment are of a certain origin. Customs offices will use this document to determine whether or not a preferential duty rate applies on the products being imported and whether a shipment may be legally imported during a specific quota period. The document identifies which authority or body authorized to issue it certifies expressly that the goods to which the certificate relates originate in a specific country. The word "country" may include a group of countries, a region, or a part of a country. This certificate may also include a declaration by the manufacturer, producer, supplier, exporter, or other competent person.

Certification of Origin of Goods

Exporter, Issuer

Issuer, Importer

Transportation Status

A message to report the transport status and/or change in the transportation status (i.e. event) between agreed parties.

Initiate Transport Services

Freight Forwarder

Consignee, Consignor

Application Response

A document to indicate the application’s response to a transaction at the business application level concerning the processing of a document.

All

Sender

Receiver

Attached Document

In effect a ’wrapper’ UBL envelope that may contain anything. This allows a referenced document to be included in the package of documents being exchanged.

All

Sender

Receiver

Table 2. Summary of UBL 2.0 Document Types

6. UBL 2.0 Schemas

The UBL 2.0 XSD schemas are the only normative representations of the UBL 2.0 document types and library components.

All of the UBL 2.0 XSD schemas are contained in the xsd subdirectory of the UBL 2.0 release package (see Appendix A for more information regarding the structure of the 2.0 release package and Section 6.4 for information regarding dependencies among the schema modules). The xsd directory is further subdivided into xsd/maindoc and xsd/common 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 2.0 Document Schemas

XSD schemas defining the 31 UBL 2.0 document types are located in the xsd/maindoc directory, as listed below.

ApplicationResponse
xsd/maindoc/UBL-ApplicationResponse-2.0.xsd
AttachedDocument
xsd/maindoc/UBL-AttachedDocument-2.0.xsd
BillOfLading
xsd/maindoc/UBL-BillOfLading-2.0.xsd
Catalogue
xsd/maindoc/UBL-Catalogue-2.0.xsd
CatalogueDeletion
xsd/maindoc/UBL-CatalogueDeletion-2.0.xsd
CatalogueItemSpecificationUpdate
xsd/maindoc/UBL-CatalogueItemSpecificationUpdate-2.0.xsd
CataloguePricingUpdate
xsd/maindoc/UBL-CataloguePricingUpdate-2.0.xsd
CatalogueRequest
xsd/maindoc/UBL-CatalogueRequest-2.0.xsd
CertificateOfOrigin
xsd/maindoc/UBL-CertificateOfOrigin-2.0.xsd
CreditNote
xsd/maindoc/UBL-CreditNote-2.0.xsd
DebitNote
xsd/maindoc/UBL-DebitNote-2.0.xsd
DespatchAdvice
xsd/maindoc/UBL-DespatchAdvice-2.0.xsd
ForwardingInstructions
xsd/maindoc/UBL-ForwardingInstruction-2.0.xsd
FreightInvoice
xsd/maindoc/UBL-FreightInvoice-2.0.xsd
Invoice
xsd/maindoc/UBL-Invoice-2.0.xsd
Order
xsd/maindoc/UBL-Order-2.0.xsd
OrderCancellation
xsd/maindoc/UBL-OrderCancellation-2.0.xsd
OrderChange
xsd/maindoc/UBL-OrderChange-2.0.xsd
OrderResponse
xsd/maindoc/UBL-OrderResponse-2.0.xsd
OrderResponseSimple
xsd/maindoc/UBL-OrderResponseSimple-2.0.xsd
PackingList
xsd/maindoc/UBL-PackingList-2.0.xsd
Quotation
xsd/maindoc/UBL-Quotation-2.0.xsd
ReceiptAdvice
xsd/maindoc/UBL-ReceiptAdvice-2.0.xsd
Reminder
xsd/maindoc/UBL-Reminder-2.0.xsd
RemittanceAdvice
xsd/maindoc/UBL-RemittanceAdvice-2.0.xsd
RequestForQuotation
xsd/maindoc/UBL-RequestForQuotation-2.0.xsd
SelfBilledCreditNote
xsd/maindoc/UBL-SelfBilledCreditNote-2.0.xsd
SelfBilledInvoice
xsd/maindoc/UBL-SelfBilledInvoice-2.0.xsd
Statement
xsd/maindoc/UBL-Statement-2.0.xsd
TransportationStatus
xsd/maindoc/UBL-TransportationStatus-2.0.xsd
Waybill
xsd/maindoc/UBL-Waybill-2.0.xsd

6.2 UBL Common Schemas

The xsd/common directory contains schemas referenced by the document schemas in xsd/maindoc. The name of each schema file together with a brief description of its contents is given below.

6.2.1 Reusable BIE Schemas

CommonBasicComponents
xsd/common/UBL-CommonBasicComponents-2.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. BBIEs are the “leaf nodes” of UBL documents.
CommonAggregateComponents
xsd/common/UBL-CommonAggregateComponents-2.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

CCTS_CCT_SchemaModule
xsd/common/CCTS_CCT_SchemaModule-2.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 is defined by UN/CEFACT and should not be modified. It is provided here as a reference for implementers who wish to extend UBL and create new qualified datatypes in a CCTS-conformant manner.
UnqualifiedDataTypeSchemaModule
xsd/common/UnqualifiedDataTypeSchemaModule-2.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 is defined by UN/CEFACT and should not be modified.
QualifiedDatatypes
xsd/common/UBL-QualifiedDatatypes-2.0.xsd
This schema describes the Qualified Data Types defined by UBL as specified by [CCTS]. These XSD complexType structures are derived from Unqualified Data Types (see above), primarily to document code lists defined for use with UBL. These Types have been customized for UBL and may be further customized to support additional Data Types required for other business contexts.

6.2.3 Documentation Metadata Schema

CoreComponentParameters
xsd/common/UBL-CoreComponentParameters-2.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.
While not required by UBL schemas, this module is provided to encourage consistency of customized extensions.

6.2.4 Imported Code List Schemas

Four standard code list schemas imported for use in UBL 2.0 are included in the xsd/common directory. These are defined by UN/CEFACT for use with their Unqualified Data Type schema and should not be modified.

CodeList_CurrencyCode
xsd/common/CodeList_CurrencyCode_ISO_7_04.xsd
CodeList_MIMEMediaTypeCode
xsd/common/CodeList_MIMEMediaTypeCode_IANA_7_04.xsd
CodeList_UnitCode
xsd/common/CodeList_UnitCode_UNECE_7_04.xsd
CodeList_LanguageCode
xsd/common/CodeList_LanguageCode_ISO_7_04.xsd
This code list is not currently used in any UBL 2.0 documents. It is provided here to support customized implementation of textual content in different languages. For example, where a TextType component allows multiple occurrences, each different occurrence may be expressed in a different language. The actual language used may be identified using this code list.

Appendix E contains a description of UBL code list validation and an explanation of the role played by these imported code list schemas.

6.2.5 Extension Content Schemas

See Section B.3.3 for information regarding UBL extension.

CommonExtensionComponents
xsd/common/UBL-CommonExtensionComponents-2.0.xsd
This schema defines the extension structures that are used in all UBL document types, providing metadata regarding the use of an extension embedded in a UBL document instance.
ExtensionContentDatatype
xsd/common/UBL-ExtensionContentDatatype-2.0.xsd
This schema specifies the actual structure of the extension element containing the foreign non-UBL content. This is delivered as an unconstrained element and may be replaced by users to specify the validation of their foreign vocabulary in a customized UBL document.

6.3 Schema Dependencies

The following diagram shows the dependencies among the schema modules comprising a UBL 2.0 document schema.

[schema dependency diagram]

Figure 22. UBL Schema Dependencies

7. Additional Document Constraints

In addition to the UBL 2.0 document constraints formally expressed in the schemas described in Section 6 above, UBL mandates several other rules governing conformant UBL 2.0 instances that cannot be expressed using W3C Schema. These additional UBL document rules, addressing instance validation, character encoding, and empty elements, are specified below.

Note that these rules first appeared in the OASIS UBL 1.0 and UBL 1.0 NDR Standards. They are listed here because logically they belong with the great majority of UBL instance constraints specified in the schemas. To aid in coordinating references between these various publications, the rules below retain their original “IND” labels. The former IND4 was removed in the revision process leading to UBL 2.0.

7.1 Validation

The UBL library and document schemas are targeted at supporting business information exchanges. Business information exchanges require a high degree of precision to ensure that application processing and corresponding business cycle actions are reflective of the purpose, intent, and information content agreed to by both trading partners. Schemas provide the necessary mechanism for ensuring that instance documents do in fact support these requirements.

[IND1] All UBL instance documents MUST validate to a corresponding schema.

7.2 Character Encoding

XML supports a wide variety of character encodings. Processors must understand which character encoding is employed in each XML document. XML 1.0 supports a default value of UTF-8 for character encoding, but best practice is to always identify the character encoding being employed.

[IND2] All UBL instance documents MUST identify their character encoding within the XML declaration.

Example:

<?xml version="1.0" encoding="UTF-8"?>

UBL, as an OASIS TC, is obligated to conform to agreements OASIS has entered into. OASIS is a liaison member of the ISO IEC ITU UN/CEFACT eBusiness Memorandum of Understanding Management Group (MOUMG). Resolution 01/08 (MOU/MG01n83) requires the use of UTF-8.

[IND3] In conformance with ISO IEC ITU UN/CEFACT eBusiness Memorandum of Understanding Management Group (MOUMG) Resolution 01/08 (MOU/MG01n83) as agreed to by OASIS, all UBL XML SHOULD be expressed using UTF-8.

Example:

<?xml version="1.0" encoding="UTF-8"?>

7.3 Empty elements

Use of empty elements within XML instance documents is a source of controversy for a variety of reasons. An empty element does not simply represent data that is missing. It may express data that is not applicable for some reason, trigger the expression of an attribute, denote all possible values instead of just one, mark the end of a series of data, or appear as a result of an error in XML file generation. Conversely, missing data elements can also have meaning — data not provided by a trading partner. In information exchange environments, different trading partners may allow, require, or ban empty elements. UBL has determined that empty elements do not provide the level of assurance necessary for business information exchanges and therefore will not be used.

[IND5] UBL conformant instance documents MUST NOT contain an element devoid of content or containing null values, except in the case of extension, where the UBL ExtensionContent element is used.

To ensure that no attempt is made to circumvent rule IND5, UBL also prohibits attempting to convey meaning by not conveying an element.

[IND6] The absence of a construct or data in a UBL instance document MUST NOT carry meaning.

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

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

art
Diagrams and illustrations used in this specification
asn
ASN.1 UBL 2.0 schema; see Appendix G
cl
Code list specification files; see Appendix E
doc
Documents included with this release
etc
Miscellaneous supporting information
mod
Spreadsheet data models; see Appendix D
uml
UML class diagrams of the UBL 2.0 data models; see Appendix D
val
Test harness for demonstrating UBL 2.0 two-phase validation; see Appendix E
xml
Sample UBL 2.0 instances
xsd
XSD schemas; see Section 6
xsdrt
“Runtime” XSD schemas; see Section 6

This draft package also contains a PDF file, UBL-index-2.0.pdf, that is automatically generated from UBL-index-2.0.html. The UBL-index-2.0.pdf file is included to comply with a procedural requirement of the current OASIS Technical Committee process and has no other function. It lacks any practical purpose and should be ignored. Please do not submit comments relating to the formatting or any other aspect of the UBL-index-2.0.pdf file.

A.3 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://www.oasis-open.org/mlmanage/index.php

A.4 Known Issues

There are no known issues as of PRD3.

A.5 Support Package

As an aid to deployment, the standard XML schemas in UBL 1.0 were accompanied by a large quantity of supporting materials, most of them included in the UBL 1.0 release package as informative appendices and the remainder available from sites referenced in the release package.

Due to the greatly increased scope of UBL 2.0, some of the supporting documents and informative materials corresponding to those in the UBL 1.0 standard are being provided in a separate UBL 2.0 Support Package in order to reduce scheduling dependencies between the normative and informative parts of the specification. The Support Package is being developed in parallel with the UBL 2.0 specification and will be made available shortly after ratification of UBL 2.0 as an OASIS standard.

A.6 Taxation Rules

UBL 2.0 does not provide documents for tax reporting purposes. Instead, it provides structures to support the information on which tax is based. These aim to be generic and not based on any specific tax regime.

To implement specific tax regimes, the OASIS UBL Technical Committee is working with the OASIS TaxXML Technical Committee to provide guidelines for how specific taxation requirements (e.g., Value Added Tax for the European Community) may be implemented using UBL.

A.7 UBL Customization

See the description of the UBLExtensions element in B.3.3 below. Recommendations for the development and implementation of subsets, extensions, and profiles of UBL will be provided as part of the UBL 2.0 Support Package.

A.8 Viewing this Document

Older web browsers such as Internet Explorer may not correctly support the CSS styles and XHTML markup used for this document. For best results, the Firefox 1.5 and Opera 8.5 (or later) browsers are recommended.

Appendix B (Informative): Upgrading from UBL 1.0 to UBL 2.0

While every effort has been made to keep UBL 2.0 backward-compatible with UBL 1.0, several changes resulting from experience with 1.0 have proven extensive enough to make this a major release instead of a minor version update. This means that compatibility of UBL 1.0 with the UBL 2.0 specification is not assured.

This appendix identifies the areas that have changed or been extended between UBL 1.0 and UBL 2.0. These changes must be considered in upgrading existing UBL-based systems to take advantage of the greatly expanded applicability of UBL 2.0.

B.1 The Original UBL 1.0 Order-to-Invoice Process

UBL 2.0 builds upon the basic procurement process established in UBL 1.0. That process, based on eight basic document types shown in bold outline, is illustrated in the diagram below. (See Section 5 for the Sourcing-to-Payment business process assumed for UBL 2.0.)

[ubl 1.0 order-to-invoice diagram]

Figure 23. UBL 1.0 Order-to-Invoice Business Process

B.2 New in UBL 2.0

Though apparently limited in scope, the eight document types provided in UBL 1.0 are applicable to a very large number of real-world use cases and have been widely deployed.

Adoption of UBL 1.0 following ratification as an OASIS standard in November 2004 has resulted in major inputs of new content beyond the eight basic order-to-invoice business documents specified in the original release. In particular, contributions from representatives of government procurement, taxation, and transportation agencies in Europe, Asia, and North America have resulted in greatly expanded pre-order and post-invoice capabilities together with the addition of several transport-related document types. These additions have increased the number of UBL document types from eight in UBL 1.0 to 31 in UBL 2.0.

Original UBL 1.0 order-to-invoice document types (updated for UBL 2.0): Order, OrderResponse, OrderResponseSimple, OrderChange, OrderCancellation, DespatchAdvice, ReceiptAdvice, Invoice

New UBL 2.0 document types for sourcing: CatalogueRequest, Catalogue, CatalogueItemSpecificationUpdate, CataloguePricingUpdate, CatalogueDeletion, RequestForQuotation, Quotation

New UBL 2.0 document types for fulfilment: ForwardingInstructions, PackingList, BillOfLading, Waybill, CertificateOfOrigin, TransportationStatus

New UBL 2.0 document types for billing: CreditNote, DebitNote, SelfBilledInvoice, SelfBilledCreditNote, FreightInvoice, Reminder

New UBL 2.0 document types for payment: RemittanceAdvice, Statement

New UBL 2.0 supplementary document types: ApplicationResponse, AttachedDocument

The role of the 23 new UBL 2.0 document types is described in Section 5.

B.3 Other Differences between UBL 1.0 and UBL 2.0

B.3.1 Global Scoping

In UBL 1.0, the great majority of element types were globally scoped, the only exceptions being identifiers and codes. In UBL 2.0, all types are globally scoped.

B.3.2 New Approach to Code List Validation

The UBL mechanism for specifying and validating code lists has been completely revamped. A two-phase validaton approach using the power of XSLT [XSLT] (a W3C Recommendation) and Schematron [SCH] (ISO/IEC 19757-3) has been developed to make it easier to modify code lists and perform basic business rule checking. For further details, see Appendix E, UBL 2.0 Code Lists and Two-phase Validation.

B.3.3 New Extension Element

An optional container element named UBLExtensions may now appear as the first child of any UBL 2.0 document. UBLExtensions was provided to meet user demand for an area in which to include non-UBL data elements, in particular, elements containing data whose inclusion is mandated by law for certain business documents in certain regulatory environments. Note that unlike every other data element in UBL, UBLExtensions has no associated business semantics in itself and is therefore not derived from a CCTS data type.

Each ext:UBLExtension child element of the ext:UBLExtensions container element contains the metadata and content associated with a single extension. To accommodate the widest range of possible extensions, the ext:ExtensionContent element is specified in xsd/common/UBL-ExtensionContentDatatype-2.0.xsd as having a single child element of type xsd:any with a processContents value of “skip”. This means, in essence, that any well-formed XML element (and all of its children and descendants) from any vocabulary can be the one child of the ext:ExtensionContent element; however, it is not recommended that this child element come from a UBL namespace, because the semantics of such use at this location are undefined. Descendants of the one child of ext:ExtensionContent, on the other hand, may meaningfully include elements from the standard UBL namespace, and this can minimize the creation of nonstandard information items.

The metadata recorded for an extension is part of the UBL vocabulary, specified in xsd/common/UBL-CommonExtensionComponents-2.0.xsd as optional elements that are siblings to the ext:ExtensionContent element.

Injudicious use of UBLExtensions will obviously have damaging consequences for interoperability of UBL documents. UBLExtensions should be used with great care and should never be used for data that is properly conveyed in standard UBL elements allowed elsewhere in the document. In general, UBLExtensions should be used only as a last resort for data that cannot be accommodated by the constructs provided in the standard. Practical use of UBLExtensions will require out-of-band agreements among specific trading partner communities together with publication and maintenance procedures outside the scope of standard UBL.

B.3.4 Changes to Basic Information Entities

A number of Basic Information Entities and the corresponding XML elements have been changed to better reflect business requirements, as shown in the following two tables.

Aggregate BIEBasic or Association BIEChanges for UBL 2.0Change reason
Address   
  Added TypeCodeAdopted from UN/CEFACT
  Added FormatCodeAdopted from UN/CEFACT
  Added BlockNameAdopted from UN/CEFACT
  Added MarkAttentionAdopted from UN/CEFACT
  Added MarkCareAdopted from UN/CEFACT
  Added PlotIdentificationAdopted from UN/CEFACT
  Added CitySubdivisionNameAdopted from UN/CEFACT
 AddressLineChanged cardinality to 0..nThe number of address lines needed varies from country to country
AddressLine   
 LineChanged cardinality to 1Since AddressLines are optional, each Line should not be optional
AllowanceCharge   
 ReasonCodeRenamed to AllowanceChargeReasonCodeReason codes may be for more than just allowance charges
  Added AllowanceChargeReasonFor textual description of reasons
 CurrencyCodeRemovedRedundant information. Currency is expressed in the Amount type
  Added BaseAmountThe amount to which the MultiplierFactorNumeric is applied to calculate the Allowance Charge
  Added AccountingCostCodeThe Buyer’s accounting code as applied to the Allowance Charge
  Added AccountingCostThe Buyer’s accounting center as applied to the Allowance Charge
  Added TaxTotalFor taxes applying to the allowance or charge
BasePrice Renamed to PriceThe term Base was ambiguous
 MaximumQuantityRemovedQuantity is not the only parameter for a price. Could not explain a use for it
 MinimumQuantityRemovedQuantity is not the only parameter for a price. Could not explain a use for it
 MaximumAmountRemovedCould not explain a use for it
 MinimumAmountRemovedCould not explain a use for it
  Added PriceChangeReasonThe reason for the Price change expressed as text
  Added PriceTypeCodeThe Price type expressed as a code
  Added PriceTypeThe Price type expressed as text
  Added OrderableUnitFactorRateThe factor by which the base price unit can be converted to the orderable unit
BuyerParty Renamed to CustomerPartyCustomer is now the general term for buyer party. Buyer is the one sending the order and doing the purchasing
 BuyerAssignedAccountIDRenamed to CustomerAssignedAccountIDCustomer is now the general term for buyer party. Buyer is the one sending the order and doing the purchasing
 SellerAssignedAccountIDRenamed to SupplierAssignedAccountIDSupplier is now the general term for seller party. Seller is the one receiving the order
CommodityClassification   
  Added ItemClassificationCodeThe trade commodity classification expressed as a code
Communication   
  Added ChannelThe method of communication expressed as text
Contact   
  Added NoteA note describing the circumstances in which the Contact can be used such as “Emergency” or “After Hours”
Contract   
  Added IssueTimeThe time at which the Contract was issued
  Added ContractTypeThe type of Contract expressed as text
Delivery   
 RequestedDeliveryDateTimeReplaced by RequestedDeliveryPeriodDelivery may be requested over a period of time
 PromisedDeliveryDateTimeReplaced by PromisedDeliveryPeriodDelivery may be promised for a period of time
 ActualDeliveryDateTimeReplaced by ActualDeliveryDate and Actual DeliveryTimeAll DateTimes are now separate Date and Time
  Added LatestDeliveryDateThe latest delivery date allowed by the Buyer
  Added LatestDeliveryTimeThe latest delivery time allowed by the Buyer
  Added TrackingIDThe delivery Tracking ID (for transport tracking)
 DespatchAddressReplaced by new association to DespatchDespatch Address is within Despatch
  Added DeliveryLocationThe Location for a Delivery
  Added EstimatedDeliveryPeriodThe estimated Period for Delivery
  Added DeliveryPartyThe party to whom the goods/services are delivered
 OrderLineReferenceRemovedReference not meaningful at this level
DeliveryTerms   
 RelevantLocationReplaced by DeliveryLocationProvide structured details of location
DespatchLine   
  Added UUIDUniversally unique identification of the line within the Despatch note
  Added OutstandingQuantityThe quantity outstanding (which will follow in a later despatch)
  Added OutstandingReasonThe reason for the Outstanding Quantity
  Added OversupplyQuantityThe quantity over supplied
 DeliveryReplaced by ShipmentShipment covers all the details of the movement of goods
 DeliveryTermsReplaced by ShipmentShipment covers all the details of the movement of goods
 TransportHandlingUnitReplaced by ShipmentShipment covers all the details of the movement of goods
  Added DocumentReferenceA reference to any other documents
DocumentReference   
 GUIDRenamed to UUIDUUID is the standard term
  Added DocumentTypeCodeThe document type expressed as a code
  Added DocumentTypeThe document type expressed as text
  Added XpathRefers to another part of the same document instance
FinancialAccount   
  Added PaymentNoteFree-form text applying to the Payment to the owner of this account
HazardousGoodsTransit   
  Added TransportAuthorizationCodeCode specifying the authorisation for the transportation of hazardous cargo
HazardousItem   
  Added CategoryNameName of a kind of hazard for a material
  Added CategoryCodeCode specifying a kind of hazard for a material
  Added UpperOrangeHazardPlacardIDTo specify the identity number for the upper part of the orange hazard placard required on the means of transport
  Added LowerOrangeHazardPlacardIDTo specify the identity number for the lower part of the orange hazard placard required on the means of transport
  Added MarkingIDTo identify the marking of dangerous goods
  Added HazardClassIDTo identify a hazard class
InvoiceLine   
 LineStatusCodeRemovedInvoice line cannot be updated
  Added UUIDA computer-generated universally unique identifier (UUID) for the Invoice Line instance
  Added TaxPointDtaeThe date of the Invoice Line used to indicate the point at which tax becomes applicable
  Added AccountingCostCodeThe Buyer’s accounting code applied to the Invoice Line
  Added AccountingCostThe Buyer’s accounting cost center applied to the Invoice Line
  Added FreeOfChargeIndicatorIndicates whether the Invoice Line is Free Of Charge (default = False)
 BasePriceRenamed to PriceThe term Base was ambiguous
  Added BillingReferenceReference to the billing information
  Added PricingReferenceReference to pricing details
  Added DocumentReferenceReference to other documents
  Added OriginatorPartyThe party who originated Order (to which the Invoice is related)
  Added DeliveryTermsDelivery terms for the invoice line
  Added ItemInstanceIdentifies the specific item instance
Item   
  Added NameA short name (optionally) given to an item, such as a name from a catalogue, as distinct from a description
  Added HazardousRiskIndicatorIndicates whether the item as delivered is hazardous
  Added AdditionalInformationTo provide more details of the item (e.g., URL of a relevant web page)
  Added KeywordA Seller Party-defined search string for the item. Also could be synonyms
  Added BrandNameThe brand name for the item
  Added ModelNameModel name for the item
 SalesConditionsRenamed to TransactionConditionsThe conditions relates to the transaction not only to the trade
 TaxCategoryRenamed to ClassifiedTaxCategoryA way to classify items independent of their participation in a transaction. These are classifications (luxury, essential goods, etc.) rather than rates of tax
 BasePriceRemovedThe price is not dependent on the item
  Added ItemSpecificationDocumentReferenceAn association to item specification
  AdditionalItemPropertyFor additional properties of the item
  ManufacturerPartyThe manufacturer’s details
  InformationContentProviderPartyThe party responsible for providing specifications
  OriginAddressThe origin of the item
  ItemInstanceIdentifies a specific instance of the item
ItemIdentification   
  Added ExtendedIDIdentifies the item with specific properties e.g. Item 123 = Chair / Item 123 Ext 45 = brown chair
LegalTotal   
 TaxInclusiveAmountmade optionalMay not be specified
  Added AllowanceTotalAmountThe total amount of all allowances
  Added ChargeTotalAmountThe total amount of all charges
  Added PrepaidAmountThe total prepaid amount
  Added PayableRoundingAmountThe rounding amount (positive or negative) added to the calculated Line Extension Total Amount to produce the rounded Line Extension Total Amount
  Added PayableAmount (mandatory)The total amount to be paid
LineItem   
 BuyersIDRenamed to IDTo not violate the rule that every document has an ID, the BuyersID has become the mandatory ID
 SellersIDRenamed to SalesOrderIDSeller has only an ID if it is a SalesOrder
  Added UUIDA computer-generated universally unique identifier (UUID) for the Line Item instance
  Added InspectionMethodCodeInspection requirements for a Line Item expressed as a code
  Added PartialDeliveryIndicatorIndicates whether a partial delivery is allowed
  Added BackOrderAllowedIndicatorIndicates whether back order is allowed
  Added AccountingCostCodeThe Buyer’s accounting code applied to the Line Item
  Added AccountingCostThe Buyer’s accounting code applied to the Line Item expressed as text
 DestinationPartyChanged to OriginatorPartyMore useful to know who originated the line item
 BasePriceRenamed as PriceThe term Base was ambiguous
LineReference   
  Added UUIDA computer-generated universally unique identifier (UUID) for the referenced document line instance
LotIdentification   
  Added AdditionalItemPropertyTo identify an item by its properties
OrderLine   
  Added CatalogueLineReferenceReference to a catalogue
  Added QuotationLineReferenceReference to a quote
  Added DocumentReferenceReference to any other documents
OrderLineReference   
 BuyersLineIDRenamed to LineID and changed cardinality to 1According to Lineitem/ID
 SellersLineIDRenamed to SalesOrderLineIDAccording to Lineitem/SalesOrderID
  Added UUIDA computer-generated universally unique identifier (UUID) for the referenced Order Line instance
OrderReference   
 BuyersIDRenamed to ID and changed cardinality 10 1According to Lineitem/ID
 SellersIDRenamed to SalesOrderIDAccording to Lineitem/SalesOrderID
 GUIDRenamed to UUIDThe standard term is UUID
 DocumentStatusCodeReplaced by DocumentReferenceMore details on documents
  Added IssueTimeReferences may be required for time of day
  Added CustomerReferenceA reference used [CRI] for tagging purchasing card transactions
Package   
  Added PackageLevelCodeCode specifying a level of packaging
  Added PackagingTypeCodeCode specifying the type of packaging of an item
  Added PackingMaterialDescription of the type of packaging of an item
 ContainedPackageChanged cardinality to 0..nA package may contain many other packages
  Added GoodsItemReference to goods in the package
  Added MeasurementDimensionFor dimensions of the package
  Added DeliveryUnitTo specify the delivery units in each package
Party   
  Added WebsiteURIThe Uniform Resource Identifier (URI) of the Party
  Added LogoReferenceIDA Party’s logo
  Added EndPointIDIdentifies the end point of the routing service, e.g., EAN Location Number, GLN
 PartyNameChanged cardinality to 0..nA Party may have various names
 AddressRenamed to PostalAddressAligning with UN/CEFACT
  Added VisitingAddressThe address for visiting the Party
  Added PartyLegalEntityFor details of corporate registration
  Added PersonPersonal details when a person is a type of party
PartyName   
 NameChanged cardinality to 1Each PartyName needs only one Name. A Party may have many PartyNames
PartyTaxScheme   
  Added ExemptionReasonCodeA reason for a Party’s exemption from tax expressed as a code
Payment   
  Added PaidDateThe date at which the Payment was made
  Added PaidTimeThe time at which the Payment was made
  Added InstructionIDThe identifier for the Payment Instruction
PaymentMeans   
  Added IDThe identifier for the Payment Means
  Added InstructionIDThe identifier for the Payment Instruction
  Added InstructionNoteFree-form text applying to the Payment
 PaymentReplaced by PaymentIDThe identifier for the Payment(s)
PaymentTerms   
  Added PaymentMeansIDThe identifier for the applicable Payment Means
  Added PrepaidPaymentReferenceIDAn identifier for prepaid payment
  Added AmountThe payment amount for the Payment Terms
Period   
 StartDateTimeChanged to StartDate and StartTimeSeparated dates and times
 EndDateTimeChnaged to EndDate and EndTimeSeparated dates and times
  Added DescriptionA description of the Period as text
ReceiptLine   
 LineStatusCodeRemovedA receipt line cannot change status
  Added UUIDA computer-generated universally unique identifier (UUID) for the Receipt Line instance
  Added RejectReasonThe reason for rejection expressed as a code
  Added OverSupplyQuantityTo indicate fluctuating quantity with regard to ordered/despatched quantity
  Added TimingComplaintA complaint about the timing of delivery as text
 DeliveryReplaced by ShipmentShipment covers all the details of the movement of goods
 TransportHandlingUnitReplaced by ShipmentShipment covers all the details of the movement of goods
 OrderedItemIdentificationReplaced by ItemAllows for more complex description of items
  Added DocumentReferenceTo reference other documents
SalesConditions Renamed to TransactionConditionsThe conditions relates to the transaction not only to the trade
  Added DocumentReferenceTo reference other documents
SellerParty Renamed to SupplierPartyChanged according to the extended procurement process and to match UN/CEFACT terms
 BuyerAssignedAccountIDRenamed to CustomerAssignedAccountIDBuyer term changed to Customer
 SellerAssignedAccountIDRemovedSellers do not give themselves identifiers
  Added DataSendingCapabilityCapability to send invoice data via the Purchase Card provider (VISA/MasterCard/American Express)
 AccountsContactRenamed to AccountingContactConsistent with other role names
Shipment   
  Added TotalGoodsItemQuantityCount of the total number of goods items within a shipment
  Added TotalTransportHandlingUnitQuantityCount of the number of pieces of transport handling equipment in a shipment
  Added InsuranceValueAmountThe total sum covered by an insurance for the shipment
  Added DeclaredCustomsValueAmountAmount declared for customs purposes of those goods in a shipment which are subject to the same customs procedure, and have the same tariff/statistical heading, country information, and duty regime.
  Added DeclaredForCarriageValueAmount"Value, declared by the shipper or his agent solely for the purpose of varying the carrier’s level of liability from that provided in the contract of carriage, in case of loss or damage to goods or delayed delivery."
  Added DeclaredStatisticsValueAmountValue declared for statistical purposes of those goods in a consignment which have the same statistical heading
  Added FreeOnBoardValueAmountMonetary amount that has to be or has been paid as calculated under the applicable trade delivery
  Added SpecialInstructionsSpecial instructions relating to a shipment
  Added DeliveryInstructionsDelivery instructions relating to a shipment
  Added SplitConsignmentIndicatorIndicates if the consignment has been split in transit
 TransportEquipmentReplaced by TransportHandlingUnitThe Transport Handling Unit contains the Transport Equipment
  Added ConsignmentIdentifies the details of the consignment
  Added GoodsItemAn association to Goods Item (for Bulk Goods)
  Added OriginAddressAn association to the region in which the goods have been produced or manufactured, according to criteria laid down for the purposes of application of the Customs tariff, or quantitative restrictions, or of any other measure related to trade
  Added FirstArrivalPortLocationTo identify the first arrival location
  Added LastExitPortLocationTo identify the final exporting location
  Added ExportCountryTo identify the country from which the goods are originally exported without any commercial transaction taken place in intermediate countries
  Added FreightAllowanceChargeCosts incurred by the shipper in moving goods
ShipmentStage   
  Added PreCarriageIndicatorIndicates whether the stage is before the main carriage of the shipment
  Added OnCarriageIndicatorIndicates whether the stage is after the main carriage of the shipment
  Added TransportMeansDescribes the means of transport
  Added LoadingPortLocationIdentifies the port of loading
  Added UnloadingPortLocationIdentifies the port of unloading
  Added TransshipPortLocationIdentifies the port of transshipment
TaxCategory   
 ExemptionReasonRemovedTax exemption is dependent on both the transaction and the party, so exemption is in those ABIEs
  Added NameThe name of the Tax Category
  Added BaseUnitMeasureWhere a tax is applied at a certain rate per unit, the measure of units on which the tax calculation is based
  Added PerUnitAmountWhere a tax is applied at a certain rate per unit, the rate per unit applied
  Added TierRangeWhere a tax is tiered, the range of tiers applied in the calculation of the Tax Sub Total for the Tax Category
  Added TierRatePercentWhere a tax is tiered, the rate of tax applied to the range of tiers in the calculation of the Tax Sub Total for the Tax Category
TaxScheme   
  Added NameThe name of the Tax Scheme
 JurisdictionAddressRenamed to JurisdictionRegionAddressJurisdictions may be any part of an Address, not just city, state, or country (e.g., certain regions)
TaxSubTotal   
  Added CalculationSequenceNumericIdentifies the numerical order sequence in which taxes are applied when multiple taxes are attracted
  Added TransactionCurrencyTaxAmountThe tax amount expressed in the currency used for invoicing
  Added PercentThe Tax Rate for the category expressed as a percentage
  Added ExemptionReasonThe reason for tax being exempted
  Added BaseUnitMeasureWhere a tax is applied at a certain rate per unit, the measure of units on which the tax calculation is based
  Added PerUnitAmountWhere a tax is applied at a certain rate per unit, the rate per unit applied
  Added TierRangeWhere a tax is tiered, the range of tiers applied in the calculation of the Tax Sub Total for the Tax Category
  Added TierRatePercentWhere a tax is tiered, the rate of tax applied to the range of tiers in the calculation of the Tax Sub Total for the Tax Category
TaxTotal   
 TotalTaxAmountRenamed to TaxAmountThe word “Total” is redundant
  Added RoundingAmountThe rounding amount (positive or negative) added to the calculated tax total to produce the rounded TotalTaxAmount
  Added TaxEvidenceIndicatorIndicates whether these totals are recognized as legal evidence for taxation purposes
TransportEquipment   
  Added ReturnabilityIndicatorIndicates whether a particular item of transport equipment is returnable
  Added LegalStatusIndicatorLegal status of the transport equipment with respect to the Container Convention code
 DimensionRenamed to MeasurementDimensionClarification
  Added MinimumTemperatureThe minimum required operating temperature for the container (e.g., reefer)
  Added MaximumTemperatureThe maximum required operating temperature for the container (e.g., reefer)
  Added ProviderPartyThe party that provides the Transport Equipment
  Added LoadingProofPartyThe authorized party responsible for certifying that the goods were loaded into the transport equipment
  Added LoadingLocationTo identify the location where the goods are loaded into the transport equipment
TransportEquipmentSeal   
 IssuerTypeCodeRenamed to SealIssuerTypeCodeClarification
  Added SealingPartyTypeTextual description of the role of a sealing party
TransportHandlingUnit   
 UnitTypeCodeRenamed to TransportHandlingUnitTypeCodeClarification
  Added HandlingCodeThe handling required for a Shipment expressed as a code
  Added HandlingInstructionsFree-form text describing Handling Instructions for a Shipment
  Added HazardousRiskIndicatorIndicates whether the shipment contains hazardous materials
  Added TotalGoodsItemQuantityThe total number of goods items in the Transport Handling Unit
  Added TotalPackageQuantityThe total number of packages in the Transport Handling Unit
  Added DamageRemarksDescription of a type of damage
  Added ShippingMarksFree-form description of the marks and numbers on a transport unit or package
  Added TransportEquipmentAny Transport Equipment used for this THU
  Added HazardousGoodsTransitInformation about the transportation of hazardous goods
  Added MeasurementDimensionDimensions of the THU
  Added MinimumTemperatureThe minimum required operating temperature
  Added MaximumTemperatureThe maximum required operating temperature

Table 3. Changes to Library Elements in UBL 2.0

Aggregate BIEBasic or Association BIEChanges for UBL 2.0Change reason
ALL   
  UBLVersionIDAdded as first BBIE to all document types
  SubsetIDAdded to all document types
  ProfileIDAdded to all document types
DespatchAdvice   
 GUIDRenamed to UUIDStandard term is UUID
  Added IssueTimeAllow for time of day
 BuyerPartyRenamed to BuyerCustomerPartyType changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierPartyType changed to SupplierType. SellerParty is now the seller and the one who receives the order
 FreightForwarderPartyReplaced by ShipmentAlignment with terms in transport documents
 DeliveryReplaced by ShipmentAlignment with terms in transport documents
 DeliveryTermsReplaced by ShipmentAlignment with terms in transport documents
 DespatchedTransportHandlingUnitReplaced by ShipmentAlignment with terms in transport documents
 ActualShipmentReplaced by ShipmentAlignment with terms in transport documents
  Added AdditionalDocumentReferenceReference to other documents
Invoice   
 GUIDRenamed to UUIDStandard term is UUID
  Added IssueTimeAllow for time of day
 InvoiceCurrencyCodeRenamed to DocumentCurrencyCode and changed cardinality to 1This is the currency the invoice is expressed in
  Added PaymentCurrencyCodeThe currency used for payment in the Invoice
  Added PaymentAlternativeCurrencyCodeThe alternative currency used for payment in the Invoice
  Added AccountingCostCodeThe Buyer’s accounting code applied to the Invoice as a whole
  Added AccountingCostThe Buyer’s accounting cost center applied to the Invoice as a whole
 BuyerPartyRenamed to BuyerCustomerParty and changed cardinality to 0..1Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierParty and changed cardinality to 0..1Type changed to SupplierType. SellerParty is now the seller and the one who receives the order
 PaymentMeansChanged cardinality to 0..nRequiment from sweden more than one PaymentMeans can be used
 ExchangeRateRenamed to PaymentExchangeRateClarification.
  Added BillingReferenceReference to other billing documents
  Added OriginatorDocumentReferenceReference to the originator’s documents
  Added ContractDocumentReferenceReference to contract documents
  Added SignatureAuthorization details
  Added AccountingSupplierPartyThe party responsible for the supplier’s accounting
  Added AccountingCustomerPartyThe party responsible for the customer’s accounting
  Added PayeePartyThe party acting as payee
  Added TaxRepresentativePartyParty responsible for taxation
  Added DeliveryTermsTerms of delivery
  Added PrepaidPaymentDetails of any prepayments
  Added TaxExchangeRateExchange rate for tax exchange currency
  Added PricingExchangeRateExchange rate for pricing currency
  Added PaymentAlternativeExchangeRateExchange rate for alternative payment currency
Order   
 GUIDRenamed to UUIDStandard term is UUID
  Added IssueTimeAllow for time of day
 BuyersIDRenamed to ID and changed cardinality to 1According to Lineitem/ID
 SellersIDRenamed to SalesOrderIDAccording to Lineitem/SalesOrderID
 AcknowledgementResponseCodeRemovedIt is assumed that whether a response is needed and what kind is explained in the business process definition
 TransactionCurrencyCodeRenamed to DocumentCurrencyCode and changed cardinality to 1DocumentCurrencyCode is the important one.
  Added RequestedInvoiceCurrencyCodeThe currency requested for amount totals in Invoices related to this Order
  Added TaxCurrencyCodeThe currency requested for tax amounts in Invoices related to this Order
 EarliestDateReplaced with ValidityPeriodReplaced with ValidityPeriod
 ExpiryDateReplaced with ValidityPeriodReplaced with ValidityPeriod
 ValidityDurationMeasureReplaced with ValidityPeriodReplaced with ValidityPeriod
 TaxTotalAmountRemovedReplaced with TaxTotal
 LineExtensionTotalAmountRemovedReplaced with LegalTotal
 TotalPackagesQuantityRemovedUnable to explain the usage of it
 GrossWeightMeasureRemovedUnable to explain the usage of it
 NetWeightMeasureRemovedUnable to explain the usage of it
 NetNetWeightMeasureRemovedUnable to explain the usage of it
 GrossVolumeMeasureRemovedUnable to explain the usage of it
 NetVolumeMeasureRemovedUnable to explain the usage of it
  Added CustomerReferenceA supplementary reference for the Order
  Added AccountingCostCodeThe Buyer’s accounting code applied to the Order as a whole
  Added AccountingCostThe Buyer’s accounting cost center applied to the Order as a whole
 ContractDocumentReferenceReplaced by ContractContract has been extended with this element
 QuoteDocumentReferenceRenamed to QuotationDocumentReferenceTerm Quote changed to Quotation
 BuyerPartyRenamed to BuyerCustomerPartyType changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierPartyType changed to SupplierType. SellerParty is now the seller and the one who receives the order
 OriginatorPartyRenamed to OriginatorCustomerPartyType has changed (it is a customer type)
 SalesConditionsRenamed to TransactionConditionsThe conditions relates to the transaction not only to the trade
  Added SignatureAuthorization details
  Added AccountingCustomerPartyThe party responsible for the customer’s accounting
  Added TaxTotalTax totals for the Order
  Added LegalTotalTotal amounts for the Order
OrderCancellation   
 IssueDateTimeRenamed to IssueDate and changed to Date datatypeThe time may be optional
  Added IssueTimeSeparate time of day
 GUIDRenamed to UUIDStandard term is UUID
 DocumentStatusCodeRemovedAn order cancellation does not change status.
 ResponseRequiredIndicatorRemovedCould not explain the business use of this
 AcceptedIndicatorRemovedAn Order response is sent if accepted, not a cancellation. It must always be true.
 BuyerPartyRenamed to BuyerCustomerPartyType changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierPArtyType changed to SupplierType. SellerParty is now the seller and the one who receives the order
  Added OriginatorDocumentReferenceReference to document from the originator
  Added OriginatorCustomerPartyDetails of the originating party
  Added ContractA framework agreement for the order
  Added SignatureAuthorization details
OrderChange   
 GUIDRenamed to UUIDStandard term is UUID
  Added IssueTimeAllow for time of day
 BuyersIDRenamed to IDAccording to Lineitem/ID
 SellersIDRenamed to SalesOrderIDAccording to Lineitem/SalesOrderID
 DocumentStatusCodeRemovedAn OrderChange cannot be updated
 AcknowledgementResponseCodeRemovedIt is assumed that whether a response is needed and what kind is explained in the business process definition
 TransactionCurrencyCodeRenamed to DocumentCurrencyCode and changed cardinality to 1DocumentCurrencyCode is the currency of this document
  Added TaxCurrencyCodeThe currency requested for amount taxation amounts
  Added RequestedInvoiceCurrencyCodeThe currency requested for amount totals in Invoices related to this Order
  Added CustomerReferenceA supplementary reference for the transaction (eg CRI when using purchasing card)
 EarliestDateReplaced with ValidityPeriodReplaced with ValidityPeriod
 ExpiryDateReplaced with ValidityPeriodReplaced with ValidityPeriod
 ValidityDurationMeasureReplaced with ValidityPeriodReplaced with ValidityPeriod
 TaxTotalAmountRemovedReplaced with TaxTotal
 LineExtensionTotalAmountRemovedReplaced with LegalTotal
 TotalPackagesCountQuantityRemovedUnable to explain the usage of it
 GrossWeightMeasureRemovedUnable to explain the usage of it
 NetWeightMeasureRemovedUnable to explain the usage of it
 NetNetWeightMeasureRemovedUnable to explain the usage of it
 GrossVolumeMeasureRemovedUnable to explain the usage of it
 NetVolumeMeasureRemovedUnable to explain the usage of it
  Added AccountingCostCodeThe Buyer’s accounting code applied to the Order as a whole
  Added AccountingCostThe Buyer’s accounting cost center applied to the Order as a whole
 OrderReferenceChanged cardinality to 1There must be an order before an order change
 ContractDocumentReferenceReplaced by ContractContract has been extended with this element
 QuoteDocumentReferenceRenamed to QuotationDocumentReferenceTerm Quote changed to Quotation
 BuyerPartyRenamed to BuyerCustomerPartyType changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierPartyType changed to SupplierType. SellerParty is now the seller and the one who receives the order
 OriginatorPartyRenamed to OriginatorCustomerPartyType has changed (it is a customer type)
 SalesConditionsRenamed to TransactionConditionsThe conditions relates to the transaction not only to the trade
  Added TaxTotalTax totals for the Order
  Added LegalTotalTotal amounts for the Order
OrderResponse   
 BuyersIDRenamed to ID and changed cardinality to 1According to Lineitem/ID
 SellersIDRenamed to SalesOrderIDAccording to Lineitem/SalesOrderID
  Added IssueTimeSeparate time of day
 GUIDRenamed to UUIDStandard term is UUID
 DocumentStatusCodeRemovedAn OrderChange can not be updated
 EarliestDateRemovedIt is assumed that whether a response is needed and what kind is explained in the business process definition
 ExpiryDateRemovedDocumentCurrencyCode is the important one. Do we miss transactionCurrencyCode?
 ValidityDurationMeasureRemovedReplaced with period
 TaxTotalAmountRemovedReplaced with period
 LineExtensionTotalAmountRemovedReplaced with LegalTotal
 TotalPackagesCountQuantityRenamed to TotalPackagesQuantityThe word “Count” is not needed
  Added CustomerReferenceA supplementary reference for the Order
  Added AccountingCostCodeThe Buyer’s accounting code applied to the Order as a whole
  Added AccountingCostThe Buyer’s accounting cost center applied to the Order as a whole
 BuyerPartyRenamed to BuyerCustomerPartyType changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierPartyType changed to SupplierType. SellerParty is now the seller and the one who receives the order
 OriginatorPartyRenamed to OriginatorCustomerPartyType has changed (it is a customer type)
 SalesConditionsRenamed to TransactionConditionsThe conditions relates to the transaction not only to the trade
 RespondedOrderLineRenamed to OrderLineThe qualifier Responded is redundant, this is the Order Response document
  Added ContractA framework agreement for the order
  Added SignatureAuthorization details
OrderResponseSimple   
  Added IssueTimeSeparate time of day
 GUIDRenamed to UUIDStandard term is UUID
 DocumentStatusCodeRemovedOrderResponseSimple cannot be updated
  Added CustomerReferenceA supplementary reference for the Order
  Added AccountingCostCodeThe Buyer’s accounting code applied to the Order as a whole
  Added AccountingCostThe Buyer’s accounting cost center applied to the Order as a whole
 BuyerPartyRenamed to BuyerCustomerPartyType changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierPartyType changed to SupplierType. SellerParty is now the seller and the one who receives the order
  Added OriginatorCustomerPartyDetails of the originator of the Order
  Added AdditionalDocumentReferenceReference to other documents
  Added SignatureAuthorization details
ReceiptAdvice   
  Added IssueTimeSeparate time of day
 GUIDRenamed to UUIDStandard term is UUID
  Added LineCountNumericCheck number of lines on the Receipt Advice
  Added AdditionalDocumentReferenceReference to other documents
  Added SignatureAuthorization details
  Added DeliveryCustomerPartyThe party for delivery
  Added DespatchSupplierPartyThe party for despatch
 BuyerPartyRenamed to BuyerCustomerPartyType changed to CustomerType. BuyerParty is now the one who purchase and sends the order
 SellerPartyRenamed to SellerSupplierPartyType changed to SupplierType. SellerParty is now the seller and the one who receives the order
 FreightForwarderPartyReplaced by ShipmentShipment covers all the details of the movement of goods
 DeliveryReplaced by ShipmentShipment covers all the details of the movement of goods
 ReceivedTransportHandlingUnitReplaced by ShipmentShipment covers all the details of the movement of goods

Table 4. Changes to Document Elements in UBL 2.0

B.3.5 Attributes

Several attribute names have been changed as a result of adopting UN/CEFACT Core Component Type schemas, as shown in the following table.

TypeAttributeChange in UBL 2.0
AmountType  
 amountCurrencyIDRenamed to CurrencyID
 amountCurrencyCodeListVersionIDRemoved
BinaryObjectType  
 formatAdded
 mimeCodeAdded
 encodingCodeAdded
 uriAdded
 filenameAdded
GraphicType  
 formatAdded
 mimeCodeAdded
 encodingCodeAdded
 uriAdded
 filenameAdded
 characterSetCodeRemoved
PictureType  
 formatAdded
 mimeCodeAdded
 encodingCodeAdded
 uriAdded
 filenameAdded
 characterSetCodeRemoved
SoundType  
 formatAdded
 mimeCodeAdded
 encodingCodeAdded
 uriAdded
 filenameAdded
 characterSetCodeRemoved
VideoType  
 formatAdded
 mimeCodeAdded
 encodingCodeAdded
 uriAdded
 filenameAdded
 characterSetCodeRemoved
CodeType  
 codeListIDRenamed to listID
 codeListAgencyIDRenamed to listAgencyID
 codeListAgencyNameRenamed to listAgencyName
 codeListNameRenamed to listName
 codeListVersionIDRenamed to listVersionID
 codeListURIRenamed to listURI
 codeListSchemeURIRenamed to listSchemeURI
IdentifierType  
 identificationSchemeIDRenamed to schemeID
 identificationSchemeNameRenamed to schemeName
 identificationSchemeAgencyIDRenamed to schemeAgencyID
 identificationSchemeAgencyNameRenamed to schemeAgencyName
 identificationSchemeVersionIDRenamed to schemeVersionID
 identificationSchemeURIRenamed to schemeURI
 identificationSchemeDataURIRenamed to schemeDataURI
MeasureType  
 measureUnitCodeRenamed to unitCode
 measureUnitCodeListVersionIDRenamed to unitCodeListVersionID
QuantityType  
 quantityUnitCodeRenamed to unitCode
 quantityUnitCodeListIDRemoved
 quantityUnitCodeListAgencyIDRemoved
 quantityUnitCodeListAgencyNameRemoved

Table 5. Changes to Attributes in UBL 2.0

Appendix C (Informative): UBL Development Methodology

Based on the principles of the ebXML Core Components Technical Specification [CCTS], UBL has been designed as a reusable library of Business Information Entities (BIEs). BIEs include BBIEs (“basic” individual pieces of information), ABIEs (aggregations of other BIEs), and ASBIEs (associations to other ABIEs).

In accordance with the defined processes and business rules for the UBL context of use (see Section 5), Business Information Entities were identified and aggregated using normalization techniques to maximize re-use and clarify meanings. This resulted in a comprehensive model of all BIEs relevant to the UBL 2.0 context of use.

The design objective has been to provide an 80/20 solution — describing 80 percent of the required components with 20 percent of the complexity. This meant that in some cases, components less commonly used or used only in particular contexts were dropped or given looser cardinality on the understanding that specific implementations may customize UBL to satisfy these requirements.

All UBL document models are assembled from a single conceptual model. Each assembly creates the hierarchical structure necessary to represent an XML document schema.

This model and the resultant assembly models are described in Appendix D, UBL 2.0 Document Models.

UBL schemas are automatically generated from the models according to the UBL Naming and Design rules. As was the case in UBL 1.0, the UBL 2.0 schemas were generated by the FX software tool from GEFEG. An electronic copy of the UBL 2.0 FX data model will be provided as part of the UBL 2.0 Support Package.

Appendix D (Informative): UBL 2.0 Document Models

The UBL 2.0 artefacts used to represent the document models are expressed as both UML Class Diagrams and UBL-specific spreadsheets.

Spreadsheets are used to provide the supplementary metadata required by [CCTS]. Their format has been developed by UBL and follows the spreadsheet format used for UBL 1.0. They are provided in OASIS/ISO/IEC Open Document (.ods) format as well as in proprietary Excel (.xls) format. Free software for reading .ods files is available from openoffice.org.

The following diagram shows the dependencies among the spreadsheets used for UBL 2.0.

[spreadsheet architecture diagram]

Figure 24. UBL Spreadsheet Architecture

The diagram below show how these spreadsheet modules are realized in the UBL 2.0 schema modules.

[spreadsheet realization diagram]

Figure 25. UBL Spreadsheet Realization

Class diagrams are also provided as useful graphical guides to the overall UBL library structures.

To assist those migrating from UBL 1.0 to UBL 2.0, these diagrams use pink boxes to represent ABIEs that existed in UBL 1.0 and red lines for ASBIEs that existed in UBL 1.0. BBIEs that existed in UBL 1.0 are marked with a “#” symbol. An electronic copy of the UBL 2.0 UML model will be provided as part of the UBL 2.0 Support Package.

D.1 The Common Library

UBL has been designed as a reusable library of Business Information Entities.

The entire UBL 2.0 library of reusable Business Information Entities is provided as a single spreadsheet.

mod/common/UBL-CommonLibrary-2.0.ods
mod/common/UBL-CommonLibrary-2.0.xls

As an aid to understanding, a cross-reference table of Business Information Entities is also provided.

etc/UBL-ABIE-Reuse-Table-2.0.ods
etc/UBL-ABIE-Reuse-Table-2.0.xls

To aid readability of the UML class diagrams, this library is graphically presented using three views, based on the primary contexts of use for the given business areas.

A Common Library view containing ABIEs used throughout the various document types.
uml/UBL-2.0-CommonLibrary.html
A Procurement view containing ABIEs used mainly for documents associated with a supply chain.
uml/UBL-2.0-ProcurementLibrary.html
A Transportation view containing ABIEs used mainly for documents associated with the commercial aspects of transporting goods.
uml/UBL-2.0-TransportationLibrary.html

Note that these diagrams can be navigated using the up arrow and down arrow arrows.

D.2 Document Assembly Models

A UBL 2.0 document model only needs to define its “root” Aggregate BIE. This may contain several Basic BIEs and Association BIEs. Assembling the components of all Association BIEs from this root creates the hierarchical structure necessary to represent the document type.

As with the UBL Library, the document models are provided as both spreadsheets and as UBL class diagrams that can be navigated using the up and down arrows.

Application Response
Application Response Class Diagram
mod/maindoc/UBL-ApplicationResponse-2.0.ods
mod/maindoc/UBL-ApplicationResponse-2.0.xls
Attached Document
Attached Document Class Diagram
mod/maindoc/UBL-AttachedDocument-2.0.ods
mod/maindoc/UBL-AttachedDocument-2.0.xls
Bill Of Lading
Bill Of Lading Class Diagram
mod/maindoc/UBL-BillOfLading-2.0.ods
mod/maindoc/UBL-BillOfLading-2.0.xls
Catalogue
Catalogue Class Diagram
mod/maindoc/UBL-Catalogue-2.0.ods
mod/maindoc/UBL-Catalogue-2.0.xls
Catalogue Deletion
Catalogue Deletion Class Diagram
mod/maindoc/UBL-CatalogueDeletion-2.0.ods
mod/maindoc/UBL-CatalogueDeletion-2.0.xls
Catalogue Item Specification Update
Catalogue Item Specification Update Class Diagram
mod/maindoc/UBL-CatalogueItemSpecificationUpdate-2.0.ods
mod/maindoc/UBL-CatalogueItemSpecificationUpdate-2.0.xls
Catalogue Pricing Update
Catalogue Pricing Update Class Diagram
mod/maindoc/UBL-CataloguePricingUpdate-2.0.ods
mod/maindoc/UBL-CataloguePricingUpdate-2.0.xls
Catalogue Request
Catalogue Request Class Diagram
mod/maindoc/UBL-CatalogueRequest-2.0.ods
mod/maindoc/UBL-CatalogueRequest-2.0.xls
Certificate Of Origin
Certificate Of Origin Class Diagram
mod/maindoc/UBL-CertificateOfOrigin-2.0.ods
mod/maindoc/UBL-CertificateOfOrigin-2.0.xls
Credit Note
Credit Note Class Diagram
mod/maindoc/UBL-CreditNote-2.0.ods
mod/maindoc/UBL-CreditNote-2.0.xls
Debit Note
Debit Note Class Diagram
mod/maindoc/UBL-DebitNote-2.0.ods
mod/maindoc/UBL-DebitNote-2.0.xls
Despatch Advice
Despatch Advice Class Diagram
mod/maindoc/UBL-DespatchAdvice-2.0.ods
mod/maindoc/UBL-DespatchAdvice-2.0.xls
Forwarding Instruction
Forwarding Instruction Class Diagram
mod/maindoc/UBL-ForwardingInstructions-2.0.ods
mod/maindoc/UBL-ForwardingInstructions-2.0.xls
Freight Invoice
Freight Invoice Class Diagram
mod/maindoc/UBL-FreightInvoice-2.0.ods
mod/maindoc/UBL-FreightInvoice-2.0.xls
Invoice
Invoice Class Diagram
mod/maindoc/UBL-Invoice-2.0.ods
mod/maindoc/UBL-Invoice-2.0.xls
Order
Order Class Diagram
mod/maindoc/UBL-Order-2.0.ods
mod/maindoc/UBL-Order-2.0.xls
Order Cancellation
Order Cancellation Class Diagram
mod/maindoc/UBL-OrderCancellation-2.0.ods
mod/maindoc/UBL-OrderCancellation-2.0.xls
Order Change
Order Change Class Diagram
mod/maindoc/UBL-OrderChange-2.0.ods
mod/maindoc/UBL-OrderChange-2.0.xls
Order Response
Order Response Class Diagram
mod/maindoc/UBL-OrderResponse-2.0.ods
mod/maindoc/UBL-OrderResponse-2.0.xls
Order Response Simple
Order Response Simple Class Diagram
mod/maindoc/UBL-OrderResponseSimple-2.0.ods
mod/maindoc/UBL-OrderResponseSimple-2.0.xls
Packing List
Packing List Class Diagram
mod/maindoc/UBL-PackingList-2.0.ods
mod/maindoc/UBL-PackingList-2.0.xls
Quotation
Quotation Class Diagram
mod/maindoc/UBL-Quotation-2.0.ods
mod/maindoc/UBL-Quotation-2.0.xls
Receipt Advice
Receipt Advice Class Diagram
mod/maindoc/UBL-ReceiptAdvice-2.0.ods
mod/maindoc/UBL-ReceiptAdvice-2.0.xls
Reminder
Reminder Class Diagram
mod/maindoc/UBL-Reminder-2.0.ods
mod/maindoc/UBL-Reminder-2.0.xls
Remittance Advice
Remittance Advice Class Diagram
mod/maindoc/UBL-RemittanceAdvice-2.0.ods
mod/maindoc/UBL-RemittanceAdvice-2.0.xls
Request For Quotation
Request For Quotation Class Diagram
mod/maindoc/UBL-RequestForQuotation-2.0.ods
mod/maindoc/UBL-RequestForQuotation-2.0.xls
Self Billed Credit Note
Self Billed Credit Note Class Diagram
mod/maindoc/UBL-SelfBilledCreditNote-2.0.ods
mod/maindoc/UBL-SelfBilledCreditNote-2.0.xls
Self Billed Invoice
Self Billed Invoice Class Diagram
mod/maindoc/UBL-SelfBilledInvoice-2.0.ods
mod/maindoc/UBL-SelfBilledInvoice-2.0.xls
Statement
Statement Class Diagram
mod/maindoc/UBL-Statement-2.0.ods
mod/maindoc/UBL-Statement-2.0.xls
Transportation Status
Transportation Status Class Diagram
mod/maindoc/UBL-TransportationStatus-2.0.ods
mod/maindoc/UBL-TransportationStatus-2.0.xls
Waybill
Waybill Class Diagram
mod/maindoc/UBL-Waybill-2.0.ods
mod/maindoc/UBL-Waybill-2.0.xls

D.3 Qualified Datatypes

[CCTS] permits the definition of Qualified Datatypes as derivations from CCTS-specified Unqualified Datatypes. UBL uses this facility primarily to describe code lists. These Datatypes are provided as a single spreadsheet.

mod/common/UBL-qDT-2.0.ods
mod/common/UBL-qDT-2.0.xls

Appendix E (Informative): UBL 2.0 Code Lists and Two-phase Validation

E.1 Introduction

Code lists — the sets of codes such as “FR” and “USD” that are used to specify countries, currencies, and so on — play an important role in UBL, just as they do in all electronic business messaging schemes. By default, UBL uses several lists of standard codes published by agencies such as ISO and UN/CEFACT, as well as various codes that are specific to UBL.

In UBL 1.0 (2004), standard and default code list values are specified directly in the UBL schemas as enum (enumeration) constraints. This allows all UBL 1.0 instances to be validated in a single pass using generic XML XSD (W3C Schema) processors. However, the specification of the default values directly in the schemas also makes it difficult to modify the code lists to suit individual trading partner relationships and impossible to extend the list of allowable code list values while still using the standard UBL schemas as published by OASIS.

To give users maximum flexibility in configuring and updating UBL code lists without changing the standard UBL schemas, UBL 2.0 assumes a two-phase validation model. In the first validation phase, the UBL instance is checked for structure and vocabulary against a standard UBL 2.0 XSD schema using a generic XSD validator (or custom-built software performing the same function). This is exactly the same procedure used in UBL 1.0, except that the UBL 2.0 schemas (with a few exceptions noted later in this appendix) do not contain default code list values. In the second validation phase, new in UBL 2.0, code list values in the instance are checked against values obtained from external code list configuration files using an XSLT 1.0 processor driven by an XSLT 1.0 stylesheet. The default values assumed by the UBL 2.0 specification are incorporated into a file named defaultCodeList.xsl located in the val directory, as described in more detail below.

The separation of structural and vocabulary checking from code value checking allows trading partners to easily and precisely specify code list subsets and extensions and to apply them not just to individual UBL document types but also to particular elements and subtrees within UBL document instances. Another way to say this is that the the UBL code list methodology allows different versions of the same code list to be used in different document contexts. Thus, for example, a business in Canada might agree with a business in the United States to use a set of code list configuration files that allow the Buyer to be associated with either a U.S. state or a Canadian province but restrict the Seller to just U.S. states — that is, to apply a code list subset containing state and province codes in one place in a document instance and a different code list subset containing just state codes in another place in the instance.

The process for creating custom XSLT code list files to enable this context-specific functionality is described in a separate specification called the UBL Code List Methodology, a copy of which can be obtained from the UBL TC web site at OASIS. A set of support files to aid implementors in creating custom XSLT code list files will be included in the UBL 2.0 Support Package from the same site.

E.2 Default validation setup

To facilitate the processing of UBL 2.0 instances using the two-phase method, an “out-of-the-box” collection of open-source software that can be used to perform default validation of UBL 2.0 documents is included in the val directory of this release package. The default validation assumes a Linux or Windows XP system with no currently installed XML or XSLT processing software.

The Java Runtime Environment (JRE) 1.5 or later is required to use the programs in the val directory; JRE versions below 1.5 will throw an error from the xjparse.jar module used to invoke the xerces schema parser. If necessary, download and install the latest JRE from the following location before continuing:

http://www.java.com/en/download/manual.jsp

To test UBL 2.0 default validation:

  1. Change to the val directory.

  2. From within that directory, enter the test command

    test.bat (XP)

    or

    ./test.sh (Linux)

    The output, which is explained in the next section, should resemble the following (the spacing has been adjusted to make this easier to read):

    ############################################################
    Validating order-test-good.xml
    ############################################################
    ============== Phase 1: XSD schema validation ==============
    No schema validation errors.
    ============ Phase 2: XSLT code list validation ============
    No code list validation errors.
    
    ############################################################
    Validating order-test-bad1.xml
    ############################################################
    ============== Phase 1: XSD schema validation ==============
    Attempting validating, namespace-aware parse
    Error:file:///c:/d/ubl/2/val/order-test-bad1.xml:48:23:cvc-complex-type.2.4.a:
    Invalid content was found starting with element 'cbc:ChannelCod'.
    One of '{"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2":ChannelCode,
    "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2":Channel,
    "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2":Value}' is expected.
    Parse succeeded (0.822) with 1 error and no warnings.
    
    ############################################################
    Validating order-test-bad2.xml
    ############################################################
    ============== Phase 1: XSD schema validation ==============
    No schema validation errors.
    ============ Phase 2: XSLT code list validation ============
    Value supplied ' LA ' is unacceptable for codes identified by 'ChannelCodeType'
    in the context: cbc:ChannelCode
    Processing terminated by xsl:message at line 18
    
  3. From within the val directory, you can now validate any UBL document against the UBL 2.0 schemas by executing commands of the form

    validate <appropriate-schema> <ubl-document>

    where <ubl-document> is the path of a document to be validated and <appropriate-schema> is the UBL 2.0 schema for that document type (Order, Invoice, etc.). For example, the scripts val/testsamples.bat and val/testsamples.sh show this process being used to validate the sample XML instances in the xml directory.

E.3 Discussion of the default validation test

The test output displayed above in E.2 demonstrates the default validation process with three test files: a valid UBL Order (order-test-good.xml); a UBL Order containing a bad (misspelled) element (order-test-bad1.xml); and a UBL Order that is schema-valid but contains an illegal code list value (order-test-bad2.xml). The file test.bat (XP) or test.sh (Linux) is used to run the script validate.bat or validate.sh against each of the test files.

The first run using order-test-good.xml demonstrates both phases of the default validation process running normally. In the first phase, a standard W3C Schema (XSD) validator, xerces, is invoked from w3cschema.bat (or w3cschema.sh) to validate the specified UBL document (.xml) against the specified UBL 2.0 runtime schema (.xsd). Since the input is a valid UBL Order, the output of the first phase simply indicates that the file is valid against the given Order schema.

The second phase of validation uses a standard XSLT 1.0 engine, saxon, to verify that the values of various codes used in the UBL document to be tested (country codes, currency codes, etc.) are valid in terms of the default UBL 2.0 code list values specified in defaultCodeList.xsl. Here the output line “No code list validation errors” from the validate script indicates that the saxon run (invoked from xslt.bat or xslt.sh) finds no illegal code values in the document.

The second run shows what happens when the input document (order-test-bad1.xml) contains an actual structure or vocabulary error, in this case due to omission of the trailing “e” from the element named cbc:ChannelCode. When the xerces parser encounters the malformed element name, it emits the error message shown in the example, and the validate script reacts to a non-zero status code from w3cschema.bat (or w3cschema.sh) by terminating the validation process.

In the third run, the input document order-test-bad2.xml is structurally valid according to the Order schema, but it contains an illegal code list value (the ChannelCode “AL” for cell phone has been mistyped as “LA”). Thus it passes the first phase when tested against the schema but fails the second phase when tested against defaultCodeList.xsl.

To summarize, input documents are checked in the first validation phase for correctness of structure and vocabulary, using the constraints expressed in the appropriate UBL schema, and then they are checked in the second phase for correctness of default code list values, using the default constraints expressed in the XSLT file defaultCodeList.xsl. This process is illustrated in the following diagram.

[two-phase validation]

Figure 26. Two-phase Default UBL 2.0 Validation

It should be clear from the foregoing that the second phase of the default validation process can safely be omitted if it is considered unnecessary to check code list values. However, the reverse is not true. The second phase depends for correct operation on a prior check for structural validity, and therefore it will not give reliable results if run in the absence of the first (schema) validation phase.

E.4 Customizing the default XSLT file

The validation framework provided in the val directory can be used to implement code list changes, define variant code lists to fit specific trading partner agreements, associate different versions of the same code list with different parts of the same UBL document, and even perform fairly sophisticated business rule checking, simply by building additional logic into the XSLT file that drives the second validation phase — and without changing the standard UBL 2.0 schemas. Schematron-based techniques for creating a custom XSLT file to take the place of defaultCodeList.xsl are explained in the UBL Code List Methodology, the latest draft of which is available from the UBL TC web site. Using these techniques, the business analyst can offload a large proportion of input filtering from the backend business application to a simpler input processing area. And, of course, additional XSLT scripts can be added to extract logical subtrees of incoming UBL documents for allocation to different downstream processes and to perform even more sophisticated front-end processing.

E.5 Sources for the default validation framework

Components of several freely available software distributions were used to create the val directory. Sources are given below so that you can update these components as later releases become available.

E.6 Code list documentation

While the defaultCodeList.xsl file is what actually drives the second validation phase where the code list values get checked, it doesn’t function well as documentation of those values. For listings of the default codes, it’s better to consult the separate code list files from which defaultCodeList.xsl was compiled.

These files, which can be found in the cl/gc directory, use an XML format called genericode that is specially designed to represent code lists. The version of genericode adopted for this release is an early draft that is now being worked on by another OASIS technical committee. While still unfinished, this version provides all of the functionality needed for UBL and is the one intended for use in the UBL 2.0 Code List Support Package.

The genericode files are separated into three subdirectories as follows:

E.6.1 cl/gc/default

These code lists contain most of the default codes represented in defaultCodeList.xsl. Note that the majority of these code lists are “placebos” or placeholders included to provide extension points for users wishing to assign their own code values when generating custom XSLT files. The files in this directory that contain actual default code values are:

cl/gc/default/AllowanceChargeReasonCode-2.0.gc
cl/gc/default/ChannelCode-2.0.gc
cl/gc/default/ChipCode-2.0.gc
cl/gc/default/CountryIdentificationCode-2.0.gc
cl/gc/default/DocumentStatusCode-2.0.gc
cl/gc/default/LatitudeDirectionCode-2.0.gc
cl/gc/default/LineStatusCode-2.0.gc
cl/gc/default/LongitudeDirectionCode-2.0.gc
cl/gc/default/OperatorCode-2.0.gc
cl/gc/default/PackagingTypeCode-2.0.gc
cl/gc/default/PaymentMeansCode-2.0.gc
cl/gc/default/SubstitutionStatusCode-2.0.gc
cl/gc/default/TransportationStatusCode-2.0.gc
cl/gc/default/TransportEquipmentTypeCode-2.0.gc
cl/gc/default/TransportModeCode-2.0.gc

The other genericode files in the cl/gc/default directory — the ones that do not contain default code values defined by the UBL Technical Committee — contain sufficient metadata for properly specifying custom code lists. For convenience, an XML comment embedded in each file illustrates the method by which coded values are added. This comment surrounds a SimpleCodeList element defining a sample set of values. A custom genericode code list is defined by removing the comment delimiters and associated text, then replacing the sample values with the desired actual values. As noted above, the scripts required to generate a new XSLT driver file from custom code lists will be found in the UBL 2.0 Support Package.

E.6.2 cl/gc/cefact

This directory contains genericode versions of four standard code lists (currency codes, unit codes, MIME content codes, and language codes) specified by UN/CEFACT (United Nations Centre for Trade Facilitation and Electronic Business).

cl/gc/cefact/BinaryObjectMimeCode-2.0.gc
cl/gc/cefact/CurrencyCode-2.0.gc
cl/gc/cefact/LanguageCode-2.0.gc
cl/gc/cefact/UnitOfMeasureCode-2.0.gc

These genericode files correspond to the four schema modules listed in Section 6.2.4. As noted there, the language codes are not currently used in the document schemas included in the UBL 2.0 release.

Unlike all other code values in UBL 2.0, the UN/CEFACT code values are “hardwired” into the UBL schemas as a result of UBL’s adoption of the UN/CEFACT unqualifed data type (UDT) module. Consequently, these values are actually checked twice — once during the first validation phase against the code values bound into the UBL schemas via the UDT module, and then once again against the same values compiled into defaultCodeList.xsl. Of course, any nonstandard value used for one of these codes will end the validation in the first phase.

The practical result of this is that code values can be removed from any of these UN/CEFACT code lists (for example, the set of acceptable currencies could be narrowed down to just the currencies used by a company’s trading partners), but no values can be added. This is because customizing the defaultCodeList.xsl file so that a given code list has fewer values will trap the omitted values in the second validation phase, but customizing the same file to give the code list additional values will have no effect, because an occurrence of one of the new values will be trapped in the first validation phase before the second phase can be applied.

In summary: the code lists in the cl/cefact directory can only be subsetted; they cannot be extended. As in the case of the default UBL code lists, the genericode files containing the UN/CEFACT code lists also serve as documentation of the code values. The schema modules from which these “hardwired” values are actually imported into the UBL document schemas can be found in the xsd/common directory in files whose names begin CodeList_.

E.6.3 cl/gc/special-purpose

This directory contains genericode versions of two code lists that are used only in certain application contexts. Due to the large size of these lists, they are not included in defaultCodeList.xsl, but are provided here so that they can be incorporated into custom XSLT scripts.

The files in this directory are:

cl/gc/special-purpose/ContainerSizeTypeCode-2.0.gc
cl/gc/special-purpose/PortCode-2.0.gc

E.6.4 cl/xsdcl

This directory contains two directories of XSD schema fragments expressing enumeration constraints mirroring the coded values in the genericode files described in sections E.6.1 and E.6.3. These are provided here only as a convenience for users who may wish to modify their schema expressions to incorporate enumeration constraints. These files do not comprise part of standard UBL.

Appendix F (Informative): UBL 2.0 Naming and Design Rules

The XML Naming and Design Rules (NDRs) used in creating the UBL schemas in this draft specification are given in the checklist at doc/ndr/NDR-checklist.pdf. The entire NDR document (including explanatory prose) will be released following publication of UBL 2.0.

Appendix G (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 2.0 ASN.1 Specification
asn/ASN.1-UBL-2.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.