Universal Business Language v2.0Standard, 12 December 2006- Technical committee:
-
OASIS Universal Business Language (UBL) TC
- Subject / Keywords:
-
Universal Business Language, UBL
- OASIS Conceptual Model Topic Area:
- Electronic Commerce
- Abstract:
This specification defines the Universal Business Language, version 2.0.
- Related Work:
This specification supersedes UBL 1.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
http://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. The non-normative errata page for this specification is
located at http://www.oasis-open.org/committees/ubl/. See Appendix A, Release Notes (Informative) for more
information regarding this release package.
- Notices:
Copyright © OASIS Open 2006. All Rights Reserved. All capitalized terms in the following text have the
meanings assigned to them in the OASIS Intellectual Property
Rights Policy (the “OASIS IPR Policy”). The full Policy
may be found at the OASIS website. 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 section are included on all such copies and
derivative works. However, this document itself may not be
modified in any way, including by removing the copyright notice or
references to OASIS, except as needed for the purpose of
developing any document or deliverable produced by an OASIS
Technical Committee (in which case the rules applicable to
copyrights, as set forth in the OASIS IPR Policy, 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 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE. OASIS requests that any OASIS Party or any other party that
believes it has patent claims that would necessarily be infringed
by implementations of this OASIS Committee Specification or OASIS
Standard, to notify OASIS TC Administrator and provide an
indication of its willingness to grant patent licenses to such
patent claims in a manner consistent with the IPR Mode of the
OASIS Technical Committee that produced this specification. OASIS invites any party to contact the OASIS TC
Administrator if it is aware of a claim of ownership of any patent
claims that would necessarily be infringed by implementations of
this specification by a patent holder that is not willing to
provide a license to such patent claims in a manner consistent
with the IPR Mode of the OASIS Technical Committee that produced
this specification. OASIS may include such claims on its website,
but disclaims any obligation to do so. 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 any document or deliverable produced by an OASIS
Technical Committee can be found on 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 implementers or users of this OASIS
Committee Specification or OASIS Standard, can be obtained from
the OASIS TC Administrator. OASIS makes no representation that any
information or list of intellectual property rights will at any
time be complete, or that any claims in such list are, in fact,
Essential Claims.
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. Developing and maintaining multiple versions of common
business documents like purchase orders and invoices is a major
duplication of effort. Creating and maintaining multiple adapters to enable trading
relationships across domain boundaries is an even greater
effort. The existence of multiple XML formats makes it much harder
to integrate XML business messages with back-office
systems. The need to support an arbitrary number of XML formats makes
tools more expensive and trained workers harder to
find.
The OASIS Universal Business Language (UBL) is intended to help
solve these problems by defining a generic XML interchange format
for business documents that can be extended to meet the
requirements of particular industries. Specifically, UBL provides
the following: A library of XML schemas for reusable data components such
as “Address,” “Item,” and
“Payment” — the common data elements of
everyday business documents. A set of XML schemas for common business documents such as
“Order,” “Despatch Advice,” and
“Invoice” that are constructed from the UBL
library components and can be used in generic procurement and
transportation contexts.
A standard basis for XML business schemas provides the
following advantages: Lower cost of integration, both among and within
enterprises, through the reuse of common data
structures. Lower cost of commercial software, because software written
to process a given XML tag set is much easier to develop than
software that can handle an unlimited number of tag
sets. An easier learning curve, because users need master just a
single library. Lower cost of entry and therefore quicker adoption by small
and medium-size enterprises (SMEs). Standardized training, resulting in many skilled
workers. A universally available pool of system integrators. Standardized, inexpensive data input and output tools. A standard target for inexpensive off-the-shelf business
software.
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. 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. -
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]. 3. 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]
4. UBL 2.0 Context of UseThe 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. 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. 4.1. General Business RequirementsThis section describes some of the requirements and general
business rules that are assumed for collaborations and document
exchanges in UBL 2.0. An item may be a product or a service Items may have multiple classifications A contract may influence prices An item may be part of another item An item may have a price per unit and an order unit An item may reference pictures and documents An item may have a validity period An item may refer to other relevant or necessary items
4.1.2. Item IdentificationOne of the following identifiers may be used to identify each
Item (for example, a product): Buyer’s Item Identification, or Seller’s Item Identification, or Manufacturer’s Item Identification, or Catalogue Item Identification, or Item Identification according to a system promulgated by a
standards body
The Item may be further distinguished by the specification of
Measurement(s) or Physical Attribute(s). This enables
specification of the following kinds of item: Item Requiring Description This is an item that is
not identified by an unambiguous machine-processable product code
and requires additional descriptive information to precisely
identify it. Customer Defined Item This is an item that the
customer describes according to his need, and in the specification
of which the customer may make some reference to comparable
“standard” items. Item Requiring Measurements This is an item for which
it is necessary to specify one or more measurements as part of the
descriptive specification of the item.
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. 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. 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. 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. 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. 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. 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. Table 1. Party Roles
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 Instructions, 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 Instructions, 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 Instructions, 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 Instructions
|
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
|
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. 4.3.1. Catalogue ProvisionA 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. 4.3.1.1. Sourcing Business Rules AssumedAny conditions specified in the contract shall overrule
those stated in the common Catalogue. A Catalogue exchange shall be between one Provider and one
Receiver Party. A classification system may have its own set of
properties. A classification scheme shall have metadata. A Catalogue may have a validity period. A Catalogue should include item
classifications. Classification schemes should include standard and
specific properties. A Catalogue may refer to the lot (sub-section) of a
contract. A Catalogue may explicitly specify the framework
contract reference. A Catalogue may refer to a DPS contract number. When a Catalogue item is updated, the item shall be replaced
in the Catalogue. When a Catalogue item is updated, historical information
about replaced or updated items must be available to reconcile
with outstanding transactions. Prices may be updated independently of other Catalogue
information. Catalogue distribution may be Provider or Receiver Party
initiated. If a Receiver initiates a request for a Catalogue, they
may request an entire Catalogue or only updates to either
pricing or item specification details. Whether Receiver Party initiated or not, the decision to
issue a new Catalogue or update an existing one shall be at the
discretion of the Provider Party. If an updated Catalogue is issued, then an action code
shall define the status of the items in the Catalogue.
4.3.1.2. Create CatalogueThe process of creating a Catalogue is shown in the following
diagram. 4.3.1.3. Update Catalogue Item SpecificationThe process of updating a Catalogue Item Specification is shown
in the following diagram. 4.3.1.4. Update Catalogue Pricing The process of updating Catalogue pricing is shown in the
following diagram. 4.3.1.5. Delete CatalogueDeletion of a Catalogue is shown in the following diagram. 4.3.2. Customer Initiated SourcingCustomer initiated sourcing is the case where the Originator
asks for a quotation, as shown in the following diagram. Punchout applications are a technological innovation whereby an
Originator is able to directly access a Seller’s application from
within their own procurement application. 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. 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. 4.4.1. Ordering Business Rules AssumedThe 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. 4.4.2. Order Response SimpleThe 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. 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: Delivery date, offered by the Seller if not
specifically requested by the Buyer Prices Discounts Charges Item Classification codes
The Seller may advise on replacements or substitutes which will
be made, or changes necessary, using the Order Response. 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. 4.4.5. Order CancellationAt 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. 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 4.4,
Ordering). The Seller may have a fulfilment (or customer) service dealing
with anomalies. 4.5.1. Despatch Advice Business Rules AssumedThe Despatch Advice is sent by the Despatch Party to the
Delivery Party to confirm shipment of items. The Despatch Advice provides for two situations: Organization of the delivery set of items by Transport
Handling Unit(s) so that the Receiver can check the Transport
Handling Unit and then contained items. Quantities of the same
item on the same Order Line may be separated into different
Transport Handling Units, and hence appear on separate Despatch
Lines within a Transport Handling Unit. Organization of the delivery set of items by Despatch
Line, annotated by the Transport Handling Unit in which they
are placed, to facilitate checking against the Order. For
convenience, any Order Line split over multiple Transport
Handling Units will result in a Despatch Line for each
Transport Handling Unit they are contained in.
Additionally, in either case, the Despatch Advice may
advise: Full Despatch — advising the Recipient and/or
Buyer that all the items on the order will be, or are being,
delivered in one complete consignment on a given date. Partial Despatch — advising the Recipient and/or
Buyer that the items on the order will be, or are being,
partially delivered in a consignment on a given date.
Despatch Lines of the Despatch Advice need not correspond
one-to-one with Order Lines, and are linked by a reference. The
information structure of the Despatch Advice may result in
multiple Despatch Lines from one Order Line. Equally, partial
despatch may result in some Order Lines not being matched by any
Line in a Despatch Advice. Within a Despatch Advice, an Item may also indicate the Country
of Origin and the Hazardous nature of the Item. 4.5.2. Receipt Advice Business Rules AssumedThe 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. The Receipt Advice provides for two situations. For ease of
processing claimed receipt against claimed delivery, it must be
organised in the same way as the corresponding Despatch
Advice: Indication of receipt by Transport Handling Unit(s) and
contained Receipt Lines one-to-one with the Despatch Advice as
detailed by the Seller party. Indication of receipt by Receipt Lines annotated by
Transport Handling Unit, one-to-one with the Despatch Advice as
detailed by the Seller party.
The Receipt Advice allows the Delivery Party to state any
shortages from the claimed despatch quantity and to state any
quantities rejected for a given reason. 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: Traditional Billing Using Credit Note Using Debit Note
Self Billing (also known as billing on receipt)
4.6.1. Billing Business Rules AssumedThe Invoice is normally issued on the basis of one
despatch event triggering one invoice. An Invoice may also be issued
for pre-payment on a whole or partial basis. The possibilities are: Prepayment invoice (payment expected) Pro-forma invoice (pre advice, payment not expected) Normal Invoice, on despatch for despatched items Invoice after return of Receipt Advice
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: Packaging Delivery/postage Freight Documentation
Each Invoice Line refers to any related Order Line(s) and may
also refer to the Despatch Line and/or Receipt Line. 4.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). 4.6.2.1. Billing using Credit NotesBilling using Credit Notes is shown in the following
diagram. When using Credit Notes, the Supplier (in their Accounting
role) is responsible for specifying the tax requirements. 4.6.2.2. Billing Using Debit NotesBilling using Debit Notes is shown in the following
diagram. When using Debit Notes, both the Supplier (in their Accounting
role) and the Customer (in their Accounting role) are responsible
for providing taxation information. 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. 4.6.3.1. Self Billing Using Credit NotesSelf Billing using Credit Notes is shown in the following
diagram. 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. 4.6.3.2. Self Billing Using Self Billed Credit NotesSelf Billing using Self Billed Credit Notes is shown in the
following diagram. 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. 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. 4.6.5. Reminder For PaymentA Reminder may be used to notify the Customer of accounts due
to be paid. 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. 4.7.1. Report State of AccountsA Statement of Account may be used to notify the Accounting
Customer of the status of the billing. 4.8. Initiate Transport ServicesThese 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. 4.8.1. Forwarding InstructionsForwarding 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: of different types of goods or cargoes whether containerized or non-containerized through different modes of transport, and from any origin to any destination.
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 Instructions. 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. 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. 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. 4.9. Certification of Origin of GoodsA 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. 4.10. Report Status of GoodsThe 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. 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. Table 2. Summary of UBL 2.0 Document Types
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
|
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 5.3 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. 5.1. UBL 2.0 Document SchemasXSD schemas defining the 31 UBL 2.0 document types are located
in the xsd/maindoc directory, as listed below. 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. 5.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.
5.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.
5.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.
5.2.4. Imported Code List SchemasFour 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. Appendix E contains a description of UBL code list validation
and an explanation of the role played by these imported code list
schemas. 5.2.5. Extension Content SchemasSee 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.
The following diagram shows the dependencies among the schema
modules comprising a UBL 2.0 document schema. 6. Additional Document ConstraintsIn addition to the UBL 2.0 document constraints formally
expressed in the schemas described in Section 5 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. 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.
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"?>
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. Release Notes (Informative)Online and downloadable versions of this release are available
from the locations specified at the top of this document. The UBL 2.0 specification is published as a zip
archive named os-UBL-2.0.zip. Unzipping this archive creates a
directory named os-UBL-2.0 containing a master DocBook XML file
(UBL-2.0.xml), a generated hypertext version of this file
(UBL-2.0.html), and a number of subdirectories. The files in these
subdirectories, linked to from UBL-2.0.xml and UBL-2.0.html,
contain the various normative and informational pieces of the 2.0
release. A description of each subdirectory is given below. Note
that while the UBL-2.0.xml file is the “original” of
this specification, it may not be viewable in all currently
available web browsers.
-
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 -
css
CSS stylesheets for viewing UBL-2.0.html -
db
DocBook stylesheets for viewing UBL-2.0.xml -
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 5 -
xsdrt
“Runtime” XSD schemas; see Section 5
The UBL 2.0 distribution also contains a PDF file,
UBL-2.0.pdf, that is automatically generated from UBL-2.0.html.
The UBL-2.0.pdf file is included to comply with a procedural
requirement of the current OASIS Technical Committee process; it
does not constitute the UBL 2.0 specification (most of which
consists of schema files) and is not intended to perform any real
function. Please do not submit comments relating to the
formatting or any other aspect of the UBL-2.0.pdf file. UBL is a volunteer project of the international business
community. Inquiries regarding UBL may be posted to the public
ubl-dev list, archives for which are located at Subscriptions to ubl-dev can be made through the OASIS list
manager at 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. 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. 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. Appendix B. Upgrading from UBL 1.0 to UBL 2.0 (Informative)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 ProcessUBL 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 4 for the Sourcing-to-Payment business process assumed for
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 4. B.3. Other Differences between UBL 1.0 and UBL 2.0In 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 ValidationThe 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 ElementAn 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 EntitiesA 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. Table B.1. Changes to Library Elements in UBL 2.0 Aggregate BIE | Basic or Association BIE | Changes for UBL 2.0 | Change reason |
---|
Address | | | | | | Added TypeCode | Adopted from UN/CEFACT | | | Added FormatCode | Adopted from UN/CEFACT | | | Added BlockName | Adopted from UN/CEFACT | | | Added MarkAttention | Adopted from UN/CEFACT | | | Added MarkCare | Adopted from UN/CEFACT | | | Added PlotIdentification | Adopted from UN/CEFACT | | | Added CitySubdivisionName | Adopted from UN/CEFACT | | AddressLine | Changed cardinality to 0..n | The number of address lines needed varies from country to country | AddressLine | | | | | Line | Changed cardinality to 1 | Since AddressLines are optional, each Line should not be optional | AllowanceCharge | | | | | ReasonCode | Renamed to AllowanceChargeReasonCode | Reason codes may be for more than just allowance charges | | | Added AllowanceChargeReason | For textual description of reasons | | CurrencyCode | Removed | Redundant information. Currency is expressed in the Amount type | | | Added BaseAmount | The amount to which the MultiplierFactorNumeric is applied to calculate the Allowance Charge | | | Added AccountingCostCode | The Buyer’s accounting code as applied to the Allowance Charge | | | Added AccountingCost | The Buyer’s accounting center as applied to the Allowance Charge | | | Added TaxTotal | For taxes applying to the allowance or charge | BasePrice | | Renamed to Price | The term Base was ambiguous | | MaximumQuantity | Removed | Quantity is not the only parameter for a price. Could not explain a use for it | | MinimumQuantity | Removed | Quantity is not the only parameter for a price. Could not explain a use for it | | MaximumAmount | Removed | Could not explain a use for it | | MinimumAmount | Removed | Could not explain a use for it | | | Added PriceChangeReason | The reason for the Price change expressed as text | | | Added PriceTypeCode | The Price type expressed as a code | | | Added PriceType | The Price type expressed as text | | | Added OrderableUnitFactorRate | The factor by which the base price unit can be converted to the orderable unit | BuyerParty | | Renamed to CustomerParty | Customer is now the general term for buyer party. Buyer is the one sending the order and doing the purchasing | | BuyerAssignedAccountID | Renamed to CustomerAssignedAccountID | Customer is now the general term for buyer party. Buyer is the one sending the order and doing the purchasing | | SellerAssignedAccountID | Renamed to SupplierAssignedAccountID | Supplier is now the general term for seller party. Seller is the one receiving the order | CommodityClassification | | | | | | Added ItemClassificationCode | The trade commodity classification expressed as a code | Communication | | | | | | Added Channel | The method of communication expressed as text | Contact | | | | | | Added Note | A note describing the circumstances in which the Contact can be used such as “Emergency” or “After Hours” | Contract | | | | | | Added IssueTime | The time at which the Contract was issued | | | Added ContractType | The type of Contract expressed as text | Delivery | | | | | RequestedDeliveryDateTime | Replaced by RequestedDeliveryPeriod | Delivery may be requested over a period of time | | PromisedDeliveryDateTime | Replaced by PromisedDeliveryPeriod | Delivery may be promised for a period of time | | ActualDeliveryDateTime | Replaced by ActualDeliveryDate and Actual DeliveryTime | All DateTimes are now separate Date and Time | | | Added LatestDeliveryDate | The latest delivery date allowed by the Buyer | | | Added LatestDeliveryTime | The latest delivery time allowed by the Buyer | | | Added TrackingID | The delivery Tracking ID (for transport tracking) | | DespatchAddress | Replaced by new association to Despatch | Despatch Address is within Despatch | | | Added DeliveryLocation | The Location for a Delivery | | | Added EstimatedDeliveryPeriod | The estimated Period for Delivery | | | Added DeliveryParty | The party to whom the goods/services are delivered | | OrderLineReference | Removed | Reference not meaningful at this level | DeliveryTerms | | | | | RelevantLocation | Replaced by DeliveryLocation | Provide structured details of location | DespatchLine | | | | | | Added UUID | Universally unique identification of the line within the Despatch note | | | Added OutstandingQuantity | The quantity outstanding (which will follow in a later despatch) | | | Added OutstandingReason | The reason for the Outstanding Quantity | | | Added OversupplyQuantity | The quantity over supplied | | Delivery | Replaced by Shipment | Shipment covers all the details of the movement of goods | | DeliveryTerms | Replaced by Shipment | Shipment covers all the details of the movement of goods | | TransportHandlingUnit | Replaced by Shipment | Shipment covers all the details of the movement of goods | | | Added DocumentReference | A reference to any other documents | DocumentReference | | | | | GUID | Renamed to UUID | UUID is the standard term | | | Added DocumentTypeCode | The document type expressed as a code | | | Added DocumentType | The document type expressed as text | | | Added Xpath | Refers to another part of the same document instance | FinancialAccount | | | | | | Added PaymentNote | Free-form text applying to the Payment to the owner of this account | HazardousGoodsTransit | | | | | | Added TransportAuthorizationCode | Code specifying the authorisation for the transportation of hazardous cargo | HazardousItem | | | | | | Added CategoryName | Name of a kind of hazard for a material | | | Added CategoryCode | Code specifying a kind of hazard for a material | | | Added UpperOrangeHazardPlacardID | To specify the identity number for the upper part of the orange hazard placard required on the means of transport | | | Added LowerOrangeHazardPlacardID | To specify the identity number for the lower part of the orange hazard placard required on the means of transport | | | Added MarkingID | To identify the marking of dangerous goods | | | Added HazardClassID | To identify a hazard class | InvoiceLine | | | | | LineStatusCode | Removed | Invoice line cannot be updated | | | Added UUID | A computer-generated universally unique identifier (UUID) for the Invoice Line instance | | | Added TaxPointDtae | The date of the Invoice Line used to indicate the point at which tax becomes applicable | | | Added AccountingCostCode | The Buyer’s accounting code applied to the Invoice Line | | | Added AccountingCost | The Buyer’s accounting cost center applied to the Invoice Line | | | Added FreeOfChargeIndicator | Indicates whether the Invoice Line is Free Of Charge (default = False) | | BasePrice | Renamed to Price | The term Base was ambiguous | | | Added BillingReference | Reference to the billing information | | | Added PricingReference | Reference to pricing details | | | Added DocumentReference | Reference to other documents | | | Added OriginatorParty | The party who originated Order (to which the Invoice is related) | | | Added DeliveryTerms | Delivery terms for the invoice line | | | Added ItemInstance | Identifies the specific item instance | Item | | | | | | Added Name | A short name (optionally) given to an item, such as a name from a catalogue, as distinct from a description | | | Added HazardousRiskIndicator | Indicates whether the item as delivered is hazardous | | | Added AdditionalInformation | To provide more details of the item (e.g., URL of a relevant web page) | | | Added Keyword | A Seller Party-defined search string for the item. Also could be synonyms | | | Added BrandName | The brand name for the item | | | Added ModelName | Model name for the item | | SalesConditions | Renamed to TransactionConditions | The conditions relates to the transaction not only to the trade | | TaxCategory | Renamed
to ClassifiedTaxCategory | A
way to classify items independent of their participation in a
transaction. These are classifications (luxury, essential goods, etc.)
rather than rates of tax | | BasePrice | Removed | The price is not dependent on the item | | | Added ItemSpecificationDocumentReference | An association to item specification | | | AdditionalItemProperty | For additional properties of the item | | | ManufacturerParty | The manufacturer’s details | | | InformationContentProviderParty | The party responsible for providing specifications | | | OriginAddress | The origin of the item | | | ItemInstance | Identifies a specific instance of the item | ItemIdentification | | | | | | Added ExtendedID | Identifies the item with specific properties e.g. Item 123 = Chair / Item 123 Ext 45 = brown chair | LegalTotal | | | | | TaxInclusiveAmount | made optional | May not be specified | | | Added AllowanceTotalAmount | The total amount of all allowances | | | Added ChargeTotalAmount | The total amount of all charges | | | Added PrepaidAmount | The total prepaid amount | | | Added PayableRoundingAmount | The
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 | | | | | BuyersID | Renamed to ID | To not violate the rule that every document has an ID, the BuyersID has become the mandatory ID | | SellersID | Renamed to SalesOrderID | Seller has only an ID if it is a SalesOrder | | | Added UUID | A computer-generated universally unique identifier (UUID) for the Line Item instance | | | Added InspectionMethodCode | Inspection requirements for a Line Item expressed as a code | | | Added PartialDeliveryIndicator | Indicates whether a partial delivery is allowed | | | Added BackOrderAllowedIndicator | Indicates whether back order is allowed | | | Added AccountingCostCode | The Buyer’s accounting code applied to the Line Item | | | Added AccountingCost | The Buyer’s accounting code applied to the Line Item expressed as text | | DestinationParty | Changed to OriginatorParty | More useful to know who originated the line item | | BasePrice | Renamed as Price | The term Base was ambiguous | LineReference | | | | | | Added UUID | A computer-generated universally unique identifier (UUID) for the referenced document line instance | LotIdentification | | | | | | Added AdditionalItemProperty | To identify an item by its properties | OrderLine | | | | | | Added CatalogueLineReference | Reference to a catalogue | | | Added QuotationLineReference | Reference to a quote | | | Added DocumentReference | Reference to any other documents | OrderLineReference | | | | | BuyersLineID | Renamed to LineID and changed cardinality to 1 | According to Lineitem/ID | | SellersLineID | Renamed to SalesOrderLineID | According to Lineitem/SalesOrderID | | | Added UUID | A computer-generated universally unique identifier (UUID) for the referenced Order Line instance | OrderReference | | | | | BuyersID | Renamed to ID and changed cardinality 10 1 | According to Lineitem/ID | | SellersID | Renamed to SalesOrderID | According to Lineitem/SalesOrderID | | GUID | Renamed to UUID | The standard term is UUID | | DocumentStatusCode | Replaced by DocumentReference | More details on documents | | | Added IssueTime | References may be required for time of day | | | Added CustomerReference | A reference used [CRI] for tagging purchasing card transactions | Package | | | | | | Added PackageLevelCode | Code specifying a level of packaging | | | Added PackagingTypeCode | Code specifying the type of packaging of an item | | | Added PackingMaterial | Description of the type of packaging of an item | | ContainedPackage | Changed cardinality to 0..n | A package may contain many other packages | | | Added GoodsItem | Reference to goods in the package | | | Added MeasurementDimension | For dimensions of the package | | | Added DeliveryUnit | To specify the delivery units in each package | Party | | | | | | Added WebsiteURI | The Uniform Resource Identifier (URI) of the Party | | | Added LogoReferenceID | A Party’s logo | | | Added EndPointID | Identifies the end point of the routing service, e.g., EAN Location Number, GLN | | PartyName | Changed cardinality to 0..n | A Party may have various names | | Address | Renamed to PostalAddress | Aligning with UN/CEFACT | | | Added VisitingAddress | The address for visiting the Party | | | Added PartyLegalEntity | For details of corporate registration | | | Added Person | Personal details when a person is a type of party | PartyName | | | | | Name | Changed cardinality to 1 | Each PartyName needs only one Name. A Party may have many PartyNames | PartyTaxScheme | | | | | | Added ExemptionReasonCode | A reason for a Party’s exemption from tax expressed as a code | Payment | | | | | | Added PaidDate | The date at which the Payment was made | | | Added PaidTime | The time at which the Payment was made | | | Added InstructionID | The identifier for the Payment Instruction | PaymentMeans | | | | | | Added ID | The identifier for the Payment Means | | | Added InstructionID | The identifier for the Payment Instruction | | | Added InstructionNote | Free-form text applying to the Payment | | Payment | Replaced by PaymentID | The identifier for the Payment(s) | PaymentTerms | | | | | | Added PaymentMeansID | The identifier for the applicable Payment Means | | | Added PrepaidPaymentReferenceID | An identifier for prepaid payment | | | Added Amount | The payment amount for the Payment Terms | Period | | | | | StartDateTime | Changed to StartDate and StartTime | Separated dates and times | | EndDateTime | Chnaged to EndDate and EndTime | Separated dates and times | | | Added Description | A description of the Period as text | ReceiptLine | | | | | LineStatusCode | Removed | A receipt line cannot change status | | | Added UUID | A computer-generated universally unique identifier (UUID) for the Receipt Line instance | | | Added RejectReason | The reason for rejection expressed as a code | | | Added OverSupplyQuantity | To indicate fluctuating quantity with regard to ordered/despatched quantity | | | Added TimingComplaint | A complaint about the timing of delivery as text | | Delivery | Replaced by Shipment | Shipment covers all the details of the movement of goods | | TransportHandlingUnit | Replaced by Shipment | Shipment covers all the details of the movement of goods | | OrderedItemIdentification | Replaced by Item | Allows for more complex description of items | | | Added DocumentReference | To reference other documents | SalesConditions | | Renamed to TransactionConditions | The conditions relates to the transaction not only to the trade | | | Added DocumentReference | To reference other documents | SellerParty | | Renamed to SupplierParty | Changed according to the extended procurement process and to match UN/CEFACT terms | | BuyerAssignedAccountID | Renamed to CustomerAssignedAccountID | Buyer term changed to Customer | | SellerAssignedAccountID | Removed | Sellers do not give themselves identifiers | | | Added DataSendingCapability | Capability to send invoice data via the Purchase Card provider (VISA/MasterCard/American Express) | | AccountsContact | Renamed to AccountingContact | Consistent with other role names | Shipment | | | | | | Added TotalGoodsItemQuantity | Count of the total number of goods items within a shipment | | | Added TotalTransportHandlingUnitQuantity | Count of the number of pieces of transport handling equipment in a shipment | | | Added InsuranceValueAmount | The total sum covered by an insurance for the shipment | | | Added DeclaredCustomsValueAmount | Amount
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 DeclaredStatisticsValueAmount | Value declared for statistical purposes of those goods in a consignment which have the same statistical heading | | | Added FreeOnBoardValueAmount | Monetary amount that has to be or has been paid as calculated under the applicable trade delivery | | | Added SpecialInstructions | Special instructions relating to a shipment | | | Added DeliveryInstructions | Delivery instructions relating to a shipment | | | Added SplitConsignmentIndicator | Indicates if the consignment has been split in transit | | TransportEquipment | Replaced by TransportHandlingUnit | The Transport Handling Unit contains the Transport Equipment | | | Added Consignment | Identifies the details of the consignment | | | Added GoodsItem | An association to Goods Item (for Bulk Goods) | | | Added OriginAddress | An
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 FirstArrivalPortLocation | To identify the first arrival location | | | Added LastExitPortLocation | To identify the final exporting location | | | Added ExportCountry | To
identify the country from which the goods are originally exported
without any commercial transaction taken place in intermediate countries | | | Added FreightAllowanceCharge | Costs incurred by the shipper in moving goods | ShipmentStage | | | | | | Added PreCarriageIndicator | Indicates whether the stage is before the main carriage of the shipment | | | Added OnCarriageIndicator | Indicates whether the stage is after the main carriage of the shipment | | | Added TransportMeans | Describes the means of transport | | | Added LoadingPortLocation | Identifies the port of loading | | | Added UnloadingPortLocation | Identifies the port of unloading | | | Added TransshipPortLocation | Identifies the port of transshipment | TaxCategory | | | | | ExemptionReason | Removed | Tax exemption is dependent on both the transaction and the party, so exemption is in those ABIEs | | | Added Name | The name of the Tax Category | | | Added BaseUnitMeasure | Where a tax is applied at a certain rate per unit, the measure of units on which the tax calculation is based | | | Added PerUnitAmount | Where a tax is applied at a certain rate per unit, the rate per unit applied | | | Added TierRange | Where a tax is tiered, the range of tiers applied in the calculation of the Tax Sub Total for the Tax Category | | | Added TierRatePercent | Where
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 Name | The name of the Tax Scheme | | JurisdictionAddress | Renamed to JurisdictionRegionAddress | Jurisdictions may be any part of an Address, not just city, state, or country (e.g., certain regions) | TaxSubTotal | | | | | | Added CalculationSequenceNumeric | Identifies the numerical order sequence in which taxes are applied when multiple taxes are attracted | | | Added TransactionCurrencyTaxAmount | The tax amount expressed in the currency used for invoicing | | | Added Percent | The Tax Rate for the category expressed as a percentage | | | Added ExemptionReason | The reason for tax being exempted | | | Added BaseUnitMeasure | Where a tax is applied at a certain rate per unit, the measure of units on which the tax calculation is based | | | Added PerUnitAmount | Where a tax is applied at a certain rate per unit, the rate per unit applied | | | Added TierRange | Where a tax is tiered, the range of tiers applied in the calculation of the Tax Sub Total for the Tax Category | | | Added TierRatePercent | Where
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 | | | | | TotalTaxAmount | Renamed to TaxAmount | The word “Total” is redundant | | | Added RoundingAmount | The rounding amount (positive or negative) added to the calculated tax total to produce the rounded TotalTaxAmount | | | Added TaxEvidenceIndicator | Indicates whether these totals are recognized as legal evidence for taxation purposes | TransportEquipment | | | | | | Added ReturnabilityIndicator | Indicates whether a particular item of transport equipment is returnable | | | Added LegalStatusIndicator | Legal status of the transport equipment with respect to the Container Convention code | | Dimension | Renamed to MeasurementDimension | Clarification | | | Added MinimumTemperature | The minimum required operating temperature for the container (e.g., reefer) | | | Added MaximumTemperature | The maximum required operating temperature for the container (e.g., reefer) | | | Added ProviderParty | The party that provides the Transport Equipment | | | Added LoadingProofParty | The authorized party responsible for certifying that the goods were loaded into the transport equipment | | | Added LoadingLocation | To identify the location where the goods are loaded into the transport equipment | TransportEquipmentSeal | | | | | IssuerTypeCode | Renamed to SealIssuerTypeCode | Clarification | | | Added SealingPartyType | Textual description of the role of a sealing party | TransportHandlingUnit | | | | | UnitTypeCode | Renamed to TransportHandlingUnitTypeCode | Clarification | | | Added HandlingCode | The handling required for a Shipment expressed as a code | | | Added HandlingInstructions | Free-form text describing Handling Instructions for a Shipment | | | Added HazardousRiskIndicator | Indicates whether the shipment contains hazardous materials | | | Added TotalGoodsItemQuantity | The total number of goods items in the Transport Handling Unit | | | Added TotalPackageQuantity | The total number of packages in the Transport Handling Unit | | | Added DamageRemarks | Description of a type of damage | | | Added ShippingMarks | Free-form description of the marks and numbers on a transport unit or package | | | Added TransportEquipment | Any Transport Equipment used for this THU | | | Added HazardousGoodsTransit | Information about the transportation of hazardous goods | | | Added MeasurementDimension | Dimensions of the THU | | | Added MinimumTemperature | The minimum required operating temperature | | | Added MaximumTemperature | The maximum required operating temperature |
Table B.2. Changes to Document Elements in UBL 2.0 Aggregate BIE | Basic or Association BIE | Changes for UBL 2.0 | Change reason |
---|
ALL | | | | | | UBLVersionID | Added as first BBIE to all document types | | | CustomizationID | Added to all document types | | | ProfileID | Added to all document types | DespatchAdvice | | | | | GUID | Renamed to UUID | Standard term is UUID | | | Added IssueTime | Allow for time of day | | BuyerParty | Renamed to BuyerCustomerParty | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierParty | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | FreightForwarderParty | Replaced by Shipment | Alignment with terms in transport documents | | Delivery | Replaced by Shipment | Alignment with terms in transport documents | | DeliveryTerms | Replaced by Shipment | Alignment with terms in transport documents | | DespatchedTransportHandlingUnit | Replaced by Shipment | Alignment with terms in transport documents | | ActualShipment | Replaced by Shipment | Alignment with terms in transport documents | | | Added AdditionalDocumentReference | Reference to other documents | Invoice | | | | | GUID | Renamed to UUID | Standard term is UUID | | | Added IssueTime | Allow for time of day | | InvoiceCurrencyCode | Renamed to DocumentCurrencyCode and changed cardinality to 1 | This is the currency the invoice is expressed in | | | Added PaymentCurrencyCode | The currency used for payment in the Invoice | | | Added PaymentAlternativeCurrencyCode | The alternative currency used for payment in the Invoice | | | Added AccountingCostCode | The Buyer’s accounting code applied to the Invoice as a whole | | | Added AccountingCost | The Buyer’s accounting cost center applied to the Invoice as a whole | | BuyerParty | Renamed to BuyerCustomerParty and changed cardinality to 0..1 | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierParty and changed cardinality to 0..1 | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | PaymentMeans | Changed cardinality to 0..n | Requiment from sweden more than one PaymentMeans can be used | | ExchangeRate | Renamed to PaymentExchangeRate | Clarification. | | | Added BillingReference | Reference to other billing documents | | | Added OriginatorDocumentReference | Reference to the originator’s documents | | | Added ContractDocumentReference | Reference to contract documents | | | Added Signature | Authorization details | | | Added AccountingSupplierParty | The party responsible for the supplier’s accounting | | | Added AccountingCustomerParty | The party responsible for the customer’s accounting | | | Added PayeeParty | The party acting as payee | | | Added TaxRepresentativeParty | Party responsible for taxation | | | Added DeliveryTerms | Terms of delivery | | | Added PrepaidPayment | Details of any prepayments | | | Added TaxExchangeRate | Exchange rate for tax exchange currency | | | Added PricingExchangeRate | Exchange rate for pricing currency | | | Added PaymentAlternativeExchangeRate | Exchange rate for alternative payment currency | Order | | | | | GUID | Renamed to UUID | Standard term is UUID | | | Added IssueTime | Allow for time of day | | BuyersID | Renamed to ID and changed cardinality to 1 | According to Lineitem/ID | | SellersID | Renamed to SalesOrderID | According to Lineitem/SalesOrderID | | AcknowledgementResponseCode | Removed | It is assumed that whether a response is needed and what kind is explained in the business process definition | | TransactionCurrencyCode | Renamed to DocumentCurrencyCode and changed cardinality to 1 | DocumentCurrencyCode is the important one. | | | Added RequestedInvoiceCurrencyCode | The currency requested for amount totals in Invoices related to this Order | | | Added TaxCurrencyCode | The currency requested for tax amounts in Invoices related to this Order | | EarliestDate | Replaced with ValidityPeriod | Replaced with ValidityPeriod | | ExpiryDate | Replaced with ValidityPeriod | Replaced with ValidityPeriod | | ValidityDurationMeasure | Replaced with ValidityPeriod | Replaced with ValidityPeriod | | TaxTotalAmount | Removed | Replaced with TaxTotal | | LineExtensionTotalAmount | Removed | Replaced with LegalTotal | | TotalPackagesQuantity | Removed | Unable to explain the usage of it | | GrossWeightMeasure | Removed | Unable to explain the usage of it | | NetWeightMeasure | Removed | Unable to explain the usage of it | | NetNetWeightMeasure | Removed | Unable to explain the usage of it | | GrossVolumeMeasure | Removed | Unable to explain the usage of it | | NetVolumeMeasure | Removed | Unable to explain the usage of it | | | Added CustomerReference | A supplementary reference for the Order | | | Added AccountingCostCode | The Buyer’s accounting code applied to the Order as a whole | | | Added AccountingCost | The Buyer’s accounting cost center applied to the Order as a whole | | ContractDocumentReference | Replaced by Contract | Contract has been extended with this element | | QuoteDocumentReference | Renamed to QuotationDocumentReference | Term Quote changed to Quotation | | BuyerParty | Renamed to BuyerCustomerParty | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierParty | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | OriginatorParty | Renamed to OriginatorCustomerParty | Type has changed (it is a customer type) | | SalesConditions | Renamed to TransactionConditions | The conditions relates to the transaction not only to the trade | | | Added Signature | Authorization details | | | Added AccountingCustomerParty | The party responsible for the customer’s accounting | | | Added TaxTotal | Tax totals for the Order | | | Added LegalTotal | Total amounts for the Order | OrderCancellation | | | | | IssueDateTime | Renamed to IssueDate and changed to Date datatype | The time may be optional | | | Added IssueTime | Separate time of day | | GUID | Renamed to UUID | Standard term is UUID | | DocumentStatusCode | Removed | An order cancellation does not change status. | | ResponseRequiredIndicator | Removed | Could not explain the business use of this | | AcceptedIndicator | Removed | An Order response is sent if accepted, not a cancellation. It must always be true. | | BuyerParty | Renamed to BuyerCustomerParty | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierPArty | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | | Added OriginatorDocumentReference | Reference to document from the originator | | | Added OriginatorCustomerParty | Details of the originating party | | | Added Contract | A framework agreement for the order | | | Added Signature | Authorization details | OrderChange | | | | | GUID | Renamed to UUID | Standard term is UUID | | | Added IssueTime | Allow for time of day | | BuyersID | Renamed to ID | According to Lineitem/ID | | SellersID | Renamed to SalesOrderID | According to Lineitem/SalesOrderID | | DocumentStatusCode | Removed | An OrderChange cannot be updated | | AcknowledgementResponseCode | Removed | It is assumed that whether a response is needed and what kind is explained in the business process definition | | TransactionCurrencyCode | Renamed to DocumentCurrencyCode and changed cardinality to 1 | DocumentCurrencyCode is the currency of this document | | | Added TaxCurrencyCode | The currency requested for amount taxation amounts | | | Added RequestedInvoiceCurrencyCode | The currency requested for amount totals in Invoices related to this Order | | | Added CustomerReference | A supplementary reference for the transaction (eg CRI when using purchasing card) | | EarliestDate | Replaced with ValidityPeriod | Replaced with ValidityPeriod | | ExpiryDate | Replaced with ValidityPeriod | Replaced with ValidityPeriod | | ValidityDurationMeasure | Replaced with ValidityPeriod | Replaced with ValidityPeriod | | TaxTotalAmount | Removed | Replaced with TaxTotal | | LineExtensionTotalAmount | Removed | Replaced with LegalTotal | | TotalPackagesCountQuantity | Removed | Unable to explain the usage of it | | GrossWeightMeasure | Removed | Unable to explain the usage of it | | NetWeightMeasure | Removed | Unable to explain the usage of it | | NetNetWeightMeasure | Removed | Unable to explain the usage of it | | GrossVolumeMeasure | Removed | Unable to explain the usage of it | | NetVolumeMeasure | Removed | Unable to explain the usage of it | | | Added AccountingCostCode | The Buyer’s accounting code applied to the Order as a whole | | | Added AccountingCost | The Buyer’s accounting cost center applied to the Order as a whole | | OrderReference | Changed cardinality to 1 | There must be an order before an order change | | ContractDocumentReference | Replaced by Contract | Contract has been extended with this element | | QuoteDocumentReference | Renamed to QuotationDocumentReference | Term Quote changed to Quotation | | BuyerParty | Renamed to BuyerCustomerParty | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierParty | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | OriginatorParty | Renamed to OriginatorCustomerParty | Type has changed (it is a customer type) | | SalesConditions | Renamed to TransactionConditions | The conditions relates to the transaction not only to the trade | | | Added TaxTotal | Tax totals for the Order | | | Added LegalTotal | Total amounts for the Order | OrderResponse | | | | | BuyersID | Renamed to ID and changed cardinality to 1 | According to Lineitem/ID | | SellersID | Renamed to SalesOrderID | According to Lineitem/SalesOrderID | | | Added IssueTime | Separate time of day | | GUID | Renamed to UUID | Standard term is UUID | | DocumentStatusCode | Removed | An OrderChange can not be updated | | EarliestDate | Removed | It is assumed that whether a response is needed and what kind is explained in the business process definition | | ExpiryDate | Removed | DocumentCurrencyCode is the important one. Do we miss transactionCurrencyCode? | | ValidityDurationMeasure | Removed | Replaced with period | | TaxTotalAmount | Removed | Replaced with period | | LineExtensionTotalAmount | Removed | Replaced with LegalTotal | | TotalPackagesCountQuantity | Renamed to TotalPackagesQuantity | The word “Count” is not needed | | | Added CustomerReference | A supplementary reference for the Order | | | Added AccountingCostCode | The Buyer’s accounting code applied to the Order as a whole | | | Added AccountingCost | The Buyer’s accounting cost center applied to the Order as a whole | | BuyerParty | Renamed to BuyerCustomerParty | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierParty | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | OriginatorParty | Renamed to OriginatorCustomerParty | Type has changed (it is a customer type) | | SalesConditions | Renamed to TransactionConditions | The conditions relates to the transaction not only to the trade | | RespondedOrderLine | Renamed to OrderLine | The qualifier Responded is redundant, this is the Order Response document | | | Added Contract | A framework agreement for the order | | | Added Signature | Authorization details | OrderResponseSimple | | | | | | Added IssueTime | Separate time of day | | GUID | Renamed to UUID | Standard term is UUID | | DocumentStatusCode | Removed | OrderResponseSimple cannot be updated | | | Added CustomerReference | A supplementary reference for the Order | | | Added AccountingCostCode | The Buyer’s accounting code applied to the Order as a whole | | | Added AccountingCost | The Buyer’s accounting cost center applied to the Order as a whole | | BuyerParty | Renamed to BuyerCustomerParty | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierParty | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | | Added OriginatorCustomerParty | Details of the originator of the Order | | | Added AdditionalDocumentReference | Reference to other documents | | | Added Signature | Authorization details | ReceiptAdvice | | | | | | Added IssueTime | Separate time of day | | GUID | Renamed to UUID | Standard term is UUID | | | Added LineCountNumeric | Check number of lines on the Receipt Advice | | | Added AdditionalDocumentReference | Reference to other documents | | | Added Signature | Authorization details | | | Added DeliveryCustomerParty | The party for delivery | | | Added DespatchSupplierParty | The party for despatch | | BuyerParty | Renamed to BuyerCustomerParty | Type changed to CustomerType. BuyerParty is now the one who purchase and sends the order | | SellerParty | Renamed to SellerSupplierParty | Type changed to SupplierType. SellerParty is now the seller and the one who receives the order | | FreightForwarderParty | Replaced by Shipment | Shipment covers all the details of the movement of goods | | Delivery | Replaced by Shipment | Shipment covers all the details of the movement of goods | | ReceivedTransportHandlingUnit | Replaced by Shipment | Shipment covers all the details of the movement of goods |
B.3.5. Changes to AttributesSeveral attribute names have been changed as a result of
adopting UN/CEFACT Core Component Type schemas, as shown in the
following table. Table B.3. Changes to Attributes in UBL 2.0 Type | Attribute | Change in UBL 2.0 |
---|
AmountType | | | | amountCurrencyID | Renamed to CurrencyID | | amountCurrencyCodeListVersionID | Removed | BinaryObjectType | | | | format | Added | | mimeCode | Added | | encodingCode | Added | | uri | Added | | filename | Added | GraphicType | | | | format | Added | | mimeCode | Added | | encodingCode | Added | | uri | Added | | filename | Added | | characterSetCode | Removed | PictureType | | | | format | Added | | mimeCode | Added | | encodingCode | Added | | uri | Added | | filename | Added | | characterSetCode | Removed | SoundType | | | | format | Added | | mimeCode | Added | | encodingCode | Added | | uri | Added | | filename | Added | | characterSetCode | Removed | VideoType | | | | format | Added | | mimeCode | Added | | encodingCode | Added | | uri | Added | | filename | Added | | characterSetCode | Removed | CodeType | | | | codeListID | Renamed to listID | | codeListAgencyID | Renamed to listAgencyID | | codeListAgencyName | Renamed to listAgencyName | | codeListName | Renamed to listName | | codeListVersionID | Renamed to listVersionID | | codeListURI | Renamed to listURI | | codeListSchemeURI | Renamed to listSchemeURI | IdentifierType | | | | identificationSchemeID | Renamed to schemeID | | identificationSchemeName | Renamed to schemeName | | identificationSchemeAgencyID | Renamed to schemeAgencyID | | identificationSchemeAgencyName | Renamed to schemeAgencyName | | identificationSchemeVersionID | Renamed to schemeVersionID | | identificationSchemeURI | Renamed to schemeURI | | identificationSchemeDataURI | Renamed to schemeDataURI | MeasureType | | | | measureUnitCode | Renamed to unitCode | | measureUnitCodeListVersionID | Renamed to unitCodeListVersionID | QuantityType | | | | quantityUnitCode | Renamed to unitCode | | quantityUnitCodeListID | Removed | | quantityUnitCodeListAgencyID | Removed | | quantityUnitCodeListAgencyName | Removed |
Appendix C. UBL Development Methodology (Informative)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 4), 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. UBL 2.0 Document Models (Informative)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. The diagram below show how these spreadsheet modules are
realized in the UBL 2.0 schema modules. 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. 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. As an aid to understanding, a cross-reference table of Business
Information Entities is also provided. 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. Note that these diagrams can be navigated using the and arrows. D.2. Document Assembly ModelsA 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.
[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. Appendix E. UBL 2.0 Code Lists and Two-phase Validation (Informative)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 Value Validation Methodology, a copy of
which can be obtained from the UBL TC web site at OASIS. A set of
support files to aid implementers 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 SetupTo 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: To test UBL 2.0 default validation: Change to the val directory. 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
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 TestThe 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. 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 fileThe 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 Value Validation 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 FrameworkComponents of several freely available software distributions
were used to create the val directory. Sources
are given below so that these components can be updated as later
releases become available. The files resolver.jar and xercesImpl.jar are taken from
the xerces-j 2.8.0 binary distribution at The file xjparse.jar (renamed from xjparse-1.0.jar) is
taken from the xjparse 1.0 distribution at The file saxon.jar is taken from the saxon 6.5.5
distribution at
E.6. Code List DocumentationWhile 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: 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: 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. 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). These genericode files correspond to the four schema modules
listed in Section 5.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-purposeThis 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: 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. UBL 2.0 Naming and Design Rules (Informative)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. ASN.1 Specification (Informative)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 5 that constitute the normative definitions of
valid UBL documents. The UBL ASN.1 XML specification 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. The ASN.1 modules constituting the UBL ASN.1 specification were 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. The UBL ASN.1 modules themselves are provided in a zip
archive for use by ASN.1 implementers. |