![[Order-to-invoice diagram]](art/UBL-1.0-ProcurementActivity-300dpi.jpg)
![[OASIS logo]](art/oasis-logo.jpg){kind=logo}
16 March 2004
Document identifier:
UBL-1.0 [***not really***]
Location:
http://www.oasis-open.org/committees/ubl/lcsc/UBLv1-beta *** revise ***
Editors:
Bill Meadows, Sun Microsystems <bill.meadows@sun.com>
Lisa Seaburg, Aeon LLC <lseaburg@aeon-llc.com>
Contributors:
Members of the Technical Committee
Abstract:
This specification defines the Universal Business Language.
Status:
[The present document is a rewrite in progress; the paragraph below describes the document as it will be when sent out for balloting as a CD.]
Upon approval, this document will be a Committee Draft of the OASIS Universal Business Language (UBL) Technical Committee. The OASIS UBL Technical Committee invites interested parties to comment on this release directly to the UBL Library Content Subcommittee Editor, Bill Meadows.
Copyright © 2004 OASIS Open, Inc. All Rights Reserved.
Appendix A (Informative): Release Notes
Appendix B (Informative): UBL Methodology
Appendix C (Informative): Formatting Specifications
Appendix D (Informative): Example Instances
Appendix E (Informative): Code Lists
Appendix F (Informative): ASN.1 Specification
Since its introduction 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 small set of XML schemas for common business documents such as "Order," "Despatch Advice," and "Invoice" that are constructed from the UBL library components and can be used in a generic order-to-invoice trading context.
Guidelines for the extension of UBL in specific trading relationships.
A standard basis for XML business schemas is expected to have the following advantages:
Lower cost of integration, both among and within enterprises, through the reuse of common data structures.
Lower cost of commercial software, because software written to process a given XML tag set is much easier to develop than software that can handle an unlimited number of tag sets.
An easier learning curve, because users need master just a single library.
Lower cost of entry and therefore quicker adoption by small and medium-size enterprises (SMEs).
Standardized training, resulting in many skilled workers.
A universally available pool of system integrators.
Standardized, inexpensive data input and output tools.
UBL is designed to provide a universally understood and recognized commercial syntax for legally binding business documents and to operate within a standard business framework such as ISO 15000 (ebXML) to provide a complete, standards-based infrastructure that can extend the benefits of existing EDI systems to businesses of all sizes. UBL is freely available to everyone without legal encumbrance or licensing fees.
UBL schemas are modular, reusable, and extensible in XML-aware ways. As an implementation of ebXML Core Components Technical Specification 2.01, the UBL Library consists of Business Information Entities (BIES) that are assembled into specific hierarchical document models such as an Order and Invoice. These document models are then transformed in accordance with UBL Naming and Design Rules into XML Schema syntax. This approach allows the creation of UBL-based document types beyond those specified in this 1.0 release.
To aid in deployment, the standard UBL schemas are accompanied by a multitude of non-normative supporting materials, some of which are included in this package and some of which are available from referenced sites. These materials include:
UML class diagrams of the conceptual models on which the schemas are based
UML class diagrams describing the documents themselves
Descriptions of two example implementations
Sample instances of each of the UBL documents used in those implementations
Formatting specifications for sample renderings of the instances
An ASN.1 specification to enable the transmission of UBL messages in binary form
The supporting materials can be found in the informative appendices to this specification.
The terms Core Component and Business Information Entityare used in this specification with the meanings given in [CCTS].
The terms Object Class, Property Term, Representation Term, andQualifier 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].
The UBL 1.0 documents and component library are designed to support a typical order-to-invoice procurement cycle. This section describes the business rules and choreography of the generic process and the role played by each of the UBL 1.0 document types in that process.
The UBL library is designed to support the construction of a wide variety of document types beyond those provided in the 1.0 package. It is expected that other standard business processes will be added as UBL evolves.
This model describes a basic trading cycle from Order to Invoice that involves three parties: a Buyer of goods, a Seller of goods, and a Recipient of goods, who may or may not be the Buyer. The document types needed to support this process include the following:
Order
OrderResponseSimple
OrderResponse (detailed)
OrderChange
OrderCancellation
DespatchAdvice
ReceiptAdvice
Invoice
The role of each document type in the generic process is shown in the diagram below.
Figure 1. Order-to-Invoice Business Process (click on image to enlarge)
Item structures are found throughout the document types in the generic process.
An Identifier identifies each Item (e.g. a product identifier), which shall be one of the following:
Buyer's Item Identification, or
Seller's Item Identification, or
Manufacturer's Item Identification, or
Catalogue Item Identification, or
Item Identification according to a Standard body's system.
The Item Identification assumes that each different packaging of an Item (e.g. a 6-pack and a 12-pack of the same item) has a different Item Identifier.
The Item may be further distinguished by the specification of Measurement(s) or Physical Attribute(s). This enables specification of the following kinds of item:
This is an item that is not identified by an unambiguous, machine processable, product code and where it is necessary to provide additional descriptive information about the item to precisely identify what is required.
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.
This is an item in which it is necessary to specify one or more measurements as part of the descriptive specification of the item.
For an Item, price ranges by amount, quantity, etc. are not repeated back to the Seller; only the active price is specified. The Buyer may not know the Item Base Price, in which case it is not specified. This makes a detailed response from the Seller necessary; see OrderResponse (detailed).
Ordered items may include Hazardous items, as it is not necessary to specify related information at the order stage. The Buyer may not be aware of the nature of the Item. Indication of the Hazardous nature of the Item, and any relevant information, would be indicated in the Despatch Advice.
This section describes the role in the generic order-to-invoice process of each of the document types defined in UBL 1.0.
The Order may specify Charge Payment (e.g. freight, documentation etc) instructions that identify the type of charge and who pays which charges. The Order can be placed "on account" against a trading credit account held by the Seller, or against a credit/debit card account, or a direct debit agreement. The Order allows for an overall currency defining a default for all pricing and also a specific currency to be used for Invoicing. Within an Order, additional currencies can be specified both for individual item pricing and for any allowances or charges.
Trade discount may be specified at 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 OrderResponse (detailed).
The Order may specify delivery terms and constraints that apply for the delivery location in relation to the following information that would normally not appear until the Despatch Advice:
Transport
Means
Mode
One- to many-legged journey
Dates
Locations
Arrival "window"
Consignment packaging
Type, e.g. Container, Pallet
Identifier, e.g. SSCC, Shipping label (Despatch Advice)
The Order provides for multiple Order Lines. Each Order Line provides for specification of a single place of delivery, and a schedule of quantities and requested delivery dates.
The Order may specify delivery terms, while the Order Line may provide instructions for delivery.
The Buyer may indicate potential alternatives that are acceptable. For each Order Line, an Alternative Item can be included. The Alternative Item may be specified by any one of the range of Item identifiers. For example, the specified Quantity may change, e.g. 20x6-packs as an alternative to 10x12-packs.
The Order ResponseSimple is the means by which the Seller confirms receipt of the Order from the Buyer, indicating either commitment to fulfill without change or that the Order has been rejected.
Proposed changes by the Seller would be accomplished through the detailed OrderResponse.
The detailed Order Response is a complete replacement of the Order. It reflects the entire state of the order transaction. It also is the means by which the Seller confirms or supplies Order-related details to the Buyer that were not available to, or specified by, the Buyer at the time of ordering. These may include:
Delivery date, offered by the Seller if not specifically requested by the Buyer
Prices
Trade Discount
Charges
Customs Commodity Classification codes
The Seller may advise replacements or substitutes which will be made, or changes necessary, using the Order Response. The Substitute or Replacement Item may be specified by any one of the range of Item identifiers. For example, the specified Quantity may change, e.g. 20x6-packs as a replacement for 10x12-packs.
The Buyer can change an Order, subject to the legal contract or trading partner agreement, by sending an OrderChange, or by sending an OrderCancellation followed by a new, complete replacement, Order.
An OrderChange reflects the entire state of the order transaction.
Buyers can initiate a change to a previously accepted order. Buyers may change an order for various reasons such as changing the ordered items, quantity, delivery date, ship-to address, etc. Suppliers can accept or reject the change order using either OrderResponse or OrderResponseSimple.
At any point of the process, a Buyer can cancel an active order transaction using the OrderCancellation document. Legal contracts, trading partner agreements, and business rules would restrict at what point a OrderCancellation would be ignored (e.g. at the point of manufacture or delivery process initiation). Given the agreements and rules, an OrderCancellation may or may not be an automated business transaction. The terms and conditions of a contract formation for business commitments will dictate which if any of these restrictions and/or guidelines will apply.
The following information may appear in the DespatchAdvice:
Transport
Means
Mode
One- to many-legged journey
Dates
Locations
Arrival "window"
Consignment packaging
Type, e.g. Container, Pallet
Identifier, e.g. SSCC, Shipping label (DespatchAdvice)
The DespatchAdvice caters for two situations:
Organisation of the delivery set of items by Transport Handling Unit(s) so that the Receiver can check Transport Handling Unit and then contained items. Quantities of the same item on the same Order Line may be separated into different Transport Handling Units, and hence appear on separate Despatch Lines within a Transport Handling Unit.
Organisation of the delivery set of items by Despatch Line, annotated by the Transport Handling Unit in which they are placed, to facilitate checking against the Order. For convenience, any Order Line split over multiple Transport Handling Units will result in a Despatch Line for each Transport Handling Unit they are contained in.
Additionally, in either case, the DespatchAdvice can advise:
Full Despatch — Advising the Recipient and/or Buyer that all the items on the order will be, or are being, delivered in one complete consignment on a given date.
Partial Despatch — Advising the Recipient and/or Buyer that the items on the order will be, or are being, partially delivered in a consignment on a given date.
Despatch Lines of the DespatchAdvice may not correspond one-to-one with Order Lines, but these need to be linked by reference. The information structure of the DespatchAdvice, geared to physical considerations, may result in multiple Despatch Lines from one Order Line. Equally, partial despatch may result in some Order Lines not being matched by any Line in a DespatchAdvice.
Within a DespatchAdvice, an Item may also indicate the Country of Origin and the Hazardous nature of the Item.
The ReceiptAdvice is sent by the Receiver (Buyer) to the Seller to confirm receipt of items, and is capable of reporting shortages and/or damaged items.
The ReceiptAdvice caters for two situations. For ease of processing claimed receipt against claimed delivery, it needs to be organised in the same way as the matching DespatchAdvice:
Indication of receipt by Transport Handling Unit(s) and contained Receipt Lines one-to-one with the DespatchAdvice as detailed by the Seller party.
Indication of receipt by Receipt Lines annotated by Transport Handling Unit, one-to-one with the DespatchAdvice as detailed by the Seller party.
The ReceiptAdvice allows the Receiver to state any shortages from the claimed despatch quantity and to state any quantities rejected for a given reason.
As presently arranged, the Receipt Line only allows for one rejection quantity and reason. However, any rejection of quantities of same item for different reasons could be achieved by subdividing the Receipt Line so that there are multiple Receipt Lines to one Despatch Line.
The Invoice is normally issued on the basis of one despatch event triggering one invoice. An Invoice may also be issued for pre-payment on a whole or partial basis. The possibilities are:
Pre-payment invoice (payment expected)
Pro-forma invoice (pre advice, payment not expected)
Normal Invoice, on despatch for despatched items
Invoice after return of ReceiptAdvice
The invoice only contains the information that is necessary for invoicing purposes. It does not reiterate information already established in the Order, OrderChange, OrderResponse, DespatchAdvice, or ReceiptAdvice that is not necessary when invoicing. The Invoice refers to the Order, DespatchAdvice or ReceiptAdvice by a Reference of those documents.
Taxation on the Invoice allows for compound taxes, the sequence of calculation implied by the sequence of information repeated in the data stream. (e.g., Energy tax, with VAT — Value Added Tax — superimposed).
Charges can be specified either as a lump sum or by percentage applied to the whole Invoice value prior to calculation of taxes. Such charges cover:
Packaging
Delivery/postage
Freight
Documentation
The 1.0 Invoice does not cover Debit and Credit Notes. Nor does the cycle include a Customer Account Statement that summarises Invoices, Credit Notes and Debit Notes to be paid.
Each Invoice Line refers to the related Order Line and may refer to the DespatchAdvice Line and/or ReceiptAdvice Line.
The UBL XSD schemas are implementations of the conceptual models defined by UBL. They are the only normative representation of the UBL 1.0 document types and library components.
All of the UBL1.0 XSD schemas are contained in the xsd/ subdirectory of the UBL 1.0 release package (see Appendix A for more
information regarding the package structure and Section 6.4 for information
regarding relationships between the schema modules). The xsd/ directory is further subdivided into xsd/maindoc/, xsd/common/, and xsd/codelist/ subdirectories. [***revisit this***]
The schemas defining the eight basic document types that support the
generic UBL 1.0 order-to-invoice process are located in the xsd/maindoc/ directory, as listed below.
- Order
- xsd/maindoc/UBL-Order-1.0.xsd
- OrderResponse
- xsd/maindoc/UBL-OrderResponse-1.0.xsd
- OrderResponseSimple
- xsd/maindoc/UBL-OrderResponseSimple-1.0.xsd
- OrderChange
- xsd/maindoc/UBL-OrderChange-1.0.xsd
- OrderCancellation
- xsd/maindoc/UBL-OrderCancellation-1.0.xsd
- DespatchAdvice
- xsd/maindoc/UBL-DespatchAdvice-1.0.xsd
- ReceiptAdvice
- xsd/maindoc/UBL-ReceiptAdvice-1.0.xsd
- Invoice
- xsd/maindoc/UBL-Invoice-1.0.xsd
- CommonAggregateComponents
- xsd/common/UBL-CommonAggregateComponents-1.0.xsd
- CommonBasicComponents
- xsd/common/UBL-CommonBasicComponents-1.0.xsd
- CoreComponentParameters
- xsd/common/UBL-CoreComponentParameters-1.0.xsd
- CoreComponentTypes
- xsd/common/UBL-CoreComponentTypes-1.0.xsd
- SpecialisedDatatypes
- xsd/common/UBL-SpecialisedDatatypes-1.0.xsd
- UnspecialisedDatatypes
- xsd/common/UBL-UnspecialisedDatatypes-1.0.xsd
The xsd/common directory contains five schemas referenced by the eight document
schemas in xsd/maindoc. Four of these common schemas contain definitions needed to implement
CCTS conformance; the fifth contains the library of reusable data components
from which the document schemas are assembled. The name of each schema file and
a brief description of its contents are given below.
xsd/common/UBL-CoreComponentParameters-1.0.xsd- This file provides the structure description of fields that go into the annotation/documentation section of the type definitions used in all the other schemas. Metadata such as the object class, representation terms, etc.is stored here in a consistent format, allowing the source derivation information to be extracted instead of reverse-engineered or guessed.
xsd/common/UBL-CoreComponentTypes-1.0.xsd- This file provides Core Component Types as defined by CCTS. These types are used to construct higher level representation types in a standardized and consistent manner.
xsd/common/UBL-RepresentationTerms-1.0.xsd- This file provides the Representation Terms (RT) used to construct main document schemas.
xsd/common/UBL-DataTypes-1.0.xsd- This file is a placeholder to implement data types that may be required by main document schemas in the future. The content of this schema is therefore empty, although the necessary namespace and imports are already set in place.
xsd/common/UBL-Reusable-1.0.xsd- This file provides the Aggregate Business Information Entities (ABIEs) that are used throughout UBL, serving, in effect, as ang “ABIE type-database” for constructing the main documents.
For a detailed description of the schema structure, see ***reference to the schema module paper in doc/ ***
- CodeList AcknowledgementResponseCode
- xsd/codelist/UBL-CodeList-AcknowledgementResponseCode-1.0.xsd
- CodeList AllowanceChargeReasonCode
- xsd/codelist/UBL-CodeList-AllowanceChargeReasonCode-1.0.xsd
- CodeList ChannelCode
- xsd/codelist/UBL-CodeList-ChannelCode-1.0.xsd
- CodeList ChipCode
- xsd/codelist/UBL-CodeList-ChipCode-1.0.xsd
- CodeList CountryIdentificationCode
- xsd/codelist/UBL-CodeList-CountryIdentificationCode-1.0.xsd
- CodeList CurrencyCode
- xsd/codelist/UBL-CodeList-CurrencyCode-1.0.xsd
- CodeList DocumentStatusCode
- xsd/codelist/UBL-CodeList-DocumentStatusCode-1.0.xsd
- CodeList LatitudeDirectionCode
- xsd/codelist/UBL-CodeList-LatitudeDirectionCode-1.0.xsd
- CodeList LineStatusCode
- xsd/codelist/UBL-CodeList-LineStatusCode-1.0.xsd
- CodeList LongitudeDirectionCode
- xsd/codelist/UBL-CodeList-LongitudeDirectionCode-1.0.xsd
- CodeList OperatorCode
- xsd/codelist/UBL-CodeList-OperatorCode-1.0.xsd
- CodeList PaymentMeansCode
- xsd/codelist/UBL-CodeList-PaymentMeansCode-1.0.xsd
- CodeList SubstitutionStatusCode
- xsd/codelist/UBL-CodeList-SubstitutionStatusCode-1.0.xsd
Certain components in the library allow recursive nesting. For example, a Package may contain other Packages, a Delivery may specify another Delivery, etc. These are legitimate business data structures. Most real-world applications will limit the depth of recursion in such structures, but XSD schemas are incapable of expressing this constraint. Implementors should be aware of this and may wish to set limits on the depth of recursive structures in their applications.
The UBL Library does not currently define any UBL-specific Data Types as specified in the Core Components Technical Specification. The only DataTypes used in this release are the Data Types of primary and secondary Representation Terms.
The downloadable version of this release is available from***UBLv10-beta Downloadable Release***. (This is a zip file that will unpack to give you a replica of the online release directories.)
If there are any problems with the links in this document, you can find the full online version at:
***http://www.oasis-open.org/committees/ubl/lcsc/UBLv1-beta*** .
The UBL 1.0 specification is published as a zip archive which, when uncompressed, contains a master hypertext document (this document, index.html) in the root directory. The master document links to a number of files containing the various normative and informational pieces of the 1.0 release, most of them stored in subdirectories created by uncompressing the zip archive as shown below.
art/- Diagrams and illustrations used in this specification
asn/- ASN.1 specification; see Appendix F
doc/- Supporting documents created by the UBL TC and referenced in this specification
fs/- Formatting specifications; see Appendix C
mod/- UBL spreadsheet models; see Appendix B.3 [*** this used to be sss/***]
uml/- UML class diagrams; see Appendix B.6
xml/- Example instances; see Appendix D
xsd/- XSD schemas; see Section 6
It is expected that UBL will inspire the creation of UBL tools, some commercial and some free. A link to the current list of tools available for UBL will be found on the UBL TC web page at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl. [***the tools page referred to needs to be implemented***]
UBL is a volunteer project of the global business community. Inquiries regarding UBL may be posted to the public ubl-dev list whose archives are located at http://lists.oasis-open.org/archives/ubl-dev/. Subscriptions to ubl-dev can be made through the OASIS list manager at http://lists.oasis-open.org/ob/adm.pl.
UBL does not mandate the use of a specific formal development method. The purpose of this section is to describe the process that evolved during the course of UBL development so that users can understand the role of the various technical artifacts included in this package.
The process used to develop UBL 1.0 is shown in the diagram below.
![[Development process diagram]](art/UBL-1.0-DevProcess.gif)
Figure B-1. The UBL Development Process
The initial library of UBL business information entities (BIEs) was based upon the xCBL 3.0 schema library. Upon reivew, it was felt necessary to create an abstracted model of the entities in a form that would better support an iterative development lifecycle. This abstraction is known as the UBL conceptual model, and the modelling language used is UML. The conceptual model used for UBL 1.0 is described further in section B.2 of this appendix.
The next stage of the process was to identify and document the artifacts required by the ebXML Core Component Technical Specification [CCTS] — Aggregate Business Information Entities (ABIE)s, their Basic Business Information Entitie (BBIE) properties, and their Associations with other ABIEs (ASBIE)s. This process was carried out manually using business knowledge of the domain, the UML conceptual model, and the CCTS. The resultant BIEs were documented in a spreadsheet format. Additional individual spreadsheets were developed for each document type in the initial UBL context scenario, as shown in Section B.3.
The normative UBL schemas contained in Section 6 of this specification were then generated from the spreadsheets according to UBL Naming and Design Rules, as described further in Sections B.4. The structure of the schemas themselves is described in B.5. Finally, UML implementation models were generated from the schemas; these models are provided in Section B.6.
The UBL conceptual model incorporates the data requirements of all of the documents supported by UBL 1.0. It was developed as a series of UML class diagrams. The model is restricted to the data aspects of the UBL process scenario: it does not include other UML diagram notations such as use case models and interaction diagrams.
The conceptual model is the result of a detailed analysis of the data requirements to support the initial UBL Business Process Scenario. During the modeling process, common items of data were identified by a process of normalization to identify aggregates based on functional dependency. Where appropriate, these were generalized so that they could be re-used to support the various business documents.
The conceptual model is used for the following purposes:
It facilitates the identification of the re-usable components — i.e., the data that are common across the UBL 1.0 business documents
It provides for the understanding of the total data scenario in a visual way
It is the source from which the BIEs are derived and documented in a spreadsheet
The conceptual model is included in this document as a series of diagrams. For the purposes of clarity the model represented here does not include any attributes, nor does it contain any of the additional semantics that were developed to assist in the documentation of BIEs.
Figure B-2 shows the overall UBL conceptual model.
[*** some labels in the diagram overprint each other (see enlarged view); this needs to be fixed ***]
![[ubl conceptual model]](uml/concept/UBL-ConceptualModel-1.0-HiRes.gif)
Figure B-2. UBL conceptual model (click on image to enlarge)
Each of the components of the model is further described in its own UML class diagram. For example, the Party re-usable component in UML is shown below.
![[conceptual party diagram]](uml/concept/packages/UBL-PartyClassdiagram-1.0.gif)
Figure B-3. Conceptual class diagram of Party component
As shown above, the Party component consists in turn of smaller data components such as Address and LineItem that are shared among many UBL data structures. The set of conceptual class diagrams for all the UBL components, grouped in packages, is listed below.
- Address
- uml/concept/packages/UBL-AddressClassdiagram-1.0.gif
- Contract
- uml/concept/packages/UBL-ContractClassdiagram-1.0.gif
- Delivery
- uml/concept/packages/UBL-DeliveryClassdiagram-1.0.gif
- Document reference
- uml/concept/packages/UBL-DocumentReferenceClassdiagram-1.0.gif
- Hazardous item
- uml/concept/packages/UBL-HazardousItemClassdiagram-1.0.gif
- Item
- uml/concept/packages/UBL-ItemClassdiagram-1.0.gif
- Party
- uml/concept/packages/UBL-PartyClassdiagram-1.0.gif
- Payment
- uml/concept/packages/UBL-PaymentClassdiagram-1.0.gif
- Procurement
- uml/concept/packages/UBL-ProcurementClassdiagram-1.0.gif
- Tax
- uml/concept/packages/UBL-TaxClassdiagram-1.0.gif
Each of the business documents comprising UBL 1.0 is also documented as a class in the UML model. The class for each document represents the top level Aggregate BIE for the document type. All the other BIEs for the business document are derived by traversing the associations from this class and by applying knowledge of the hierarchy required. As an example, the conceptual model for the Order document is shown below.
![[Conceptual UBL diagram]](uml/concept/doctypes/UBL-OrderClassdiagram-1.0.gif)
Figure B-4. Conceptual class diagram of Order document
The full list of class diagrams for the business documents is shown below.
- Order
- uml/concept/doctypes/UBL-OrderClassdiagram-1.0.gif
- OrderResponse
- uml/concept/doctypes/UBL-OrderResponseClassdiagram-1.0.gif
- OrderChange
- uml/concept/doctypes/UBL-OrderChangeClassdiagram-1.0.gif
- OrderCancellation
- uml/concept/doctypes/UBL-OrderCancellationClassdiagram-1.0.gif
- DespatchAdvice
- uml/concept/doctypes/UBL-DespatchAdviceClassdiagram-1.0.gif
- ReceiptAdvice
- uml/concept/doctypes/UBL-ReceiptAdviceClassdiagram-1.0.gif
- Invoice
- uml/concept/doctypes/UBL-InvoiceClassdiagram-1.0.gif
***PARAGRAPH DESCRIBING THE DEPENDENCY DIAGRAMS GOES HERE***
![[order dependency diagram]](uml/concept/depends/UBL-OrderDependencydiagram-1.0.gif)
Figure B-5. Dependency diagram for Order document
- Order dependency diagram
- uml/concept/depends/UBL-OrderDependencydiagram-1.0.gif
- OrderResponse dependency diagram
- uml/concept/depends/UBL-OrderResponseDependencydiagram-1.0.gif
- OrderChange dependency diagram
- uml/concept/depends/UBL-OrderChangeDependencydiagram-1.0.gif
- OrderCancellation dependency diagram
- uml/concept/depends/UBL-OrderCancellationDependencydiagram-1.0.gif
- DespatchAdvice dependency diagram
- uml/concept/depends/UBL-DespatchAdviceDependencydiagram-1.0.gif
- ReceiptAdvice dependency diagram
- uml/concept/depends/UBL-ReceiptAdviceDependencydiagram-1.0.gif
- Invoice dependency diagram
- uml/concept/depends/UBL-InvoiceDependencydiagram-1.0.gif
- Packages dependency diagram
- uml/concept/depends/UBL-PackagesDependencydiagram-1.0.gif
The conceptual model represented in these diagrams is just a skeleton of the complete model (it contains only the classes and their associations) and is not a complete enough artifact for implementors to use if they wish to modify the UBL schemas to suit a specific business community.
Spreadsheets are used to design and maintain the UBL document models. Following the terminology of [CCTS], the library and its documents are composed of a combination of Basic Business Information Entities (BBIEs), which are the "leaf nodes" of the data structures; Aggregate Business Information Entities (ABIEs), which are larger structures that contain both BBIEs and smaller ABIEs; and Association Business Information Entities (ASBIEs), which indicate a relationship between two ABIEs. Many of the spreadsheet columns are determined by requirements of the ebXML Core Components Technical Specification [CCTS], others by UBL Naming and Design Rules [NDR].
Each business information entity (BIE) is defined in a single row. Row background colour distinguishes between BBIE (white), ABIE (pink) and ASBIE (green). Annotations in the first row of each column provide further explanation of the conventions and design aspects of the spreadsheets.
UBL document schemas are automatically generated from these spreadsheet models. Note that the normative form of UBL documents definitions is not the spreadsheet model but the XSD XML Schemas. The spreadsheets provide:
A starting point for model editing and for schema regeneration using a scripting or transformation tool such as that used by the UBL team.
For those wishing to customise UBL or use it as the basis for a new vocabulary, the spreadsheets can be manually edited. It is intended that there be levels of conformance to UBL, depending on how customisation is performed. Any schema generation should be compliant with the UBL Naming and Design Rules [NDR] to promote compatibility of component libraries. Automated context methodology to replace manual customization is planned for UBL 2.0.
Modifying the current spreadsheets requires an understanding of their structure, the ebXML Core Components Technical Specification [CCTS] and the various UBL library constituents. For example, some columns are updated manually. Others have formulas in their cells which implement ebXML CCTS and UBL Naming and Design Rules [NDR]. Awareness of this is necessary when adding or editing the row contents. Care should be taken to avoid updating cells that contain formulae.
A supplementary, non-normative documentation of the UBL models.
An aid to understanding the UBL data architecture.
All of the UBL business document types are defined in individual spreadsheets. Each document type references the Re-usable Component Library spreadsheet.
The spreadsheets are provided in both Microsoft Excel format (.xls) and Open Office format (.sxc).
- Order
- mod/UBL-Order-1.0.sxc
- mod/UBL-Order-1.0.xls
- OrderResponse
- mod/UBL-OrderResponse-1.0.sxc
- mod/UBL-OrderResponse-1.0.xls
- OrderResponseSimple
- mod/UBL-OrderResponseSimple-1.0.sxc
- mod/UBL-OrderResponseSimple-1.0.xls
- OrderChange
- mod/UBL-OrderChange-1.0.sxc
- mod/UBL-OrderChange-1.0.xls
- OrderCancellation
- mod/UBL-OrderCancellation-1.0.sxc
- mod/UBL-OrderCancellation-1.0.xls
- DespatchAdvice
- mod/UBL-DespatchAdvice-1.0.sxc
- mod/UBL-DespatchAdvice-1.0.xls
- ReceiptAdvice
- mod/UBL-ReceiptAdvice-1.0.sxc
- mod/UBL-ReceiptAdvice-1.0.xls
- Invoice
- mod/UBL-Invoice-1.0.sxc
- mod/UBL-Invoice-1.0.xls
- CodeListCatalogue
- mod/UBL-CodeListCatalogue-1.0.sxc
- mod/UBL-CodeListCatalogue-1.0.xls
- Reusable
- mod/UBL-Reusable-1.0.sxc
- mod/UBL-Reusable-1.0.xls
The UBL 1.0 data models are the product of the OASIS UBL Library Content Subcommittee. The work of the UBL LCSC can be viewed on the LCSC web page:
http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-lcsc
The UBL XML Naming and Design Rules (NDR) document included in this package describes the rules used to determine UBL 1.0 XML schema structures and element/attribute names. The NDR document can be found in this package as the following file:
doc/UBL-NDR-1.0.pdf
Highlights of the UBL Naming and Design Rules include:
Adherence to the Core Component Technical Specification, 2.0, Dated August 2003. [***needs update to 2.01***]
Implementation of the Core Component Types schema module.
The UBL Naming and Design Rules are the product of the OASIS UBL NDR Subcommittee. The work of the UBL NDRSC can be viewed on the NDRSC web page:
http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-ndrsc
[*** DESCRIPTION OF THE CCTS SCHEMAS GOES HERE; OLD LANGUAGE FOLLOWS: ***] The Manual Schemas shown on the lower left of the diagram serve as input to the generation of the UBL Library document schemas described above, and represent the only schemas that are manually crafted and edited in UBL. There are 4 schemas that belong to this category: CoreComponentParameters, CoreComponentTypes, RepresentationTerms and DataTypes. CoreComponentParameters defines the structure of metadata information that is used by all schemas delivered by UBL. The other 3 manually crafted schemas implement the Core Component Technical Specifications v2.0.
The normative UBL 1.0 XSD schemas listed in Section 6 of this specification were generated from the following inputs:
A commercial CC-aware schema generation tool, [*** GEFEG tool***], was used to generate the final XSD schemas, as illustrated below. For further details regarding [*** the GEFEG tool ***], see [*** GEFEG URL ***].
[***updated illustration goes here***]
Figure B-6. UBL Schema Generation Process
The choice of tool for final UBL schema generation was based on availability. Previous drafts of the UBL specification used different tools for this process. For a description of the process used to produce the UBL 1.0 Beta schemas, see Appendix D of the 1.0 Beta Committee Draft at http://www.oasis-open.org/committees/ubl/lcsc/UBLv1-beta/.
UBL 1.0 schema generation was performed under the direction of the OASIS UBL Tools and Techniques Subcommittee. The work of the UBL TTSC can be viewed on the TTSC web page:
http://www.oasis-open.org/committees/sc_home.php?wg_abbrev=ubl-ttsc
The implementation model of UBL represents the actual UBL XSD schemas as a UML model. This is produced by automatically transforming the schemas into a model conformant with the Unified Modeling Language [UML]. This model is then used to produce a set of class diagrams that illustrate each of the main documents and several views of the reusable components. The automated transformation and diagram creation was performed using a commercial schema-to-UML transformation tool, Ontogenics hyperModel. For further details regarding this product, see http://www.xmlmodeling.com/.
The UML class diagrams contained in this section are intended to help understand the UBL schemas without requiring an understanding of XSD syntax. In order to do this, the diagrams intentionally suppress some of the detail contained in the schemas. For example, information regarding the order of elements within a complex type definition is not preserved in the diagrams. Other changes were made to make the UML model useful for software engineering; for example, the "Type" suffixes of XSD complexType names are removed when creating the UML class name to yield an object class name independent of XSD syntax, and complex type child elements with simple content values are represented as class attributes, whereas elements with complex content are represented as associations to those type classes.
An implementation class diagram has been created for each of the eight UBL 1.0 document types. As noted above, the implementation diagrams are simplified views that suppress details of the types contained in these aggregate structures. As an example, the class diagram for the UBL Order document is shown in the diagram below.
![[order implementation model]](uml/implem/doctypes/UBL-OrderImplementationDiagram-1.0.gif)
Figure B-7. Implementation model for the Order document
The document implementation class diagrams contained in the UBL 1.0 package are listed below.
- Order implementation diagram
- uml/implem/doctypes/UBL-OrderImplementationDiagram-1.0.gif
- OrderResponse implementation diagram
- uml/implem/doctypes/UBL-OrderResponseImplementationDiagram-1.0.gif
- OrderResponseSimple implementation diagram
- uml/implem/doctypes/UBL-OrderResponseSimpleImplementationDiagram-1.0.gif
- OrderChange implementation diagram
- uml/implem/doctypes/UBL-OrderChangeImplementationDiagram-1.0.gif
- OrderCancellation implementation diagram
- uml/implem/doctypes/UBL-OrderCancellationImplementationDiagram-1.0.gif
- DespatchAdvice implementation diagram
- uml/implem/doctypes/UBL-DespatchAdviceImplementationDiagram-1.0.gif
- ReceiptAdvice implementation diagram
- uml/implem/doctypes/UBL-ReceiptAdviceImplementationDiagram-1.0.gif
- Invoice implementation diagram
- uml/implem/doctypes/UBL-InvoiceImplementationDiagram-1.0.gif
In addition to the main document diagrams, this release contains ten class diagrams that present views of the packages of reusable components used in the documents. For example, the Order diagram includes associations to Party, SellerParty, and BuyerParty. The following implementation diagram shows these components in detail.
![[Party implementation model]](uml/implem/packages/UBL-PartyImplementationDiagram-1.0.gif)
Figure B-8. Implementation model for Party components
The component implementation diagrams provided with UBL 1.0 are as follows:
- Address implementation diagram
- uml/implem/packages/UBL-AddressImplementationDiagram-1.0.gif
- Contract implementation diagram
- uml/implem/packages/UBL-ContractImplementationDiagram-1.0.gif
- Delivery implementation diagram
- uml/implem/packages/UBL-DeliveryImplementationDiagram-1.0.gif
- DocumentReference implementation diagram
- uml/implem/packages/UBL-DocumentReferenceImplementationDiagram-1.0.gif
- HazardousItem implementation diagram
- uml/implem/packages/UBL-HazardousItemImplementationDiagram-1.0.gif
- Item implementation diagram
- uml/implem/packages/UBL-ItemImplementationDiagram-1.0.gif
- Party implementation diagram
- uml/implem/packages/UBL-PartyImplementationDiagram-1.0.gif
- Payment implementation diagram
- uml/implem/packages/UBL-PaymentImplementationDiagram-1.0.gif
- Procurement implementation diagram
- uml/implem/packages/UBL-ProcurementImplementationDiagram-1.0.gif
- Tax implementation diagram
- uml/implem/packages/UBL-TaxImplementationDiagram-1.0.gif
This collection contains examples of formatting specifications that can be follwed to to display instances of Universal Business Language (UBL) document types in human-readable form. Presentational semantics have not been formalized in this version of the UBL schema library, and they may never be formalized due to differing international requirements and conventions for the presentation of information found in business documents.
These specifications must not be considered as reference implementations of UBL or as normative components of the UBL specification; they are merely examples from one of what will probably be many available UBL stylesheet libraries.
The formatting specifications referenced below point to various layouts for the presentation of the information found in UBL instances. Some layouts are simplified presentations. Some layouts are intended to conform to the UN Layout Key for printed business documents, mimicking the intent of the UN Layout Key where official layouts do not currently exist.
The following collection of formatting specifications describes candidate renderings for the following UBL document types:
The following is an example of the documentation found in a formatting specification for a given field of a form on the rendered output.
|
XPath addresses |
|
/po:Order/cat:BuyerParty/cat:Address/cat:Street |
|
/po:Order/cat:BuyerParty/cat:Address/cat:Country/@countryId |
The box above includes two fictitious XML Path Language (XPath) addresses that documents the locations of information found in an XML instance. XPath addresses are used in XSLT stylesheets but can be used as above just for documentation because they are independent of the technology being used for transformation. The path is the route from the document element (the first step in the path) through to the information item actually being displayed.
In the first of the two examples above, the item being addressed is thecat:Streetelement that is a child of the cat:Addresselement. In the second of the two examples, the item being addressed is thecountryIdattribute of the cat:Countryelement.
The documented sections of the formatting specifications are oriented in the order of the fields found in the rendered result, approximately in the order of left to right from top to bottom (with some differences to accommodate logical groupings).
The formatting specifications are meant to be transformation technology agnostic. The specifications indicate what information goes where in the result, not how it gets there. Different implementations of transformation technologies can meet the need for the information found at the specified XPath address to appear at the specified location on the page.
These example implementations must not be considered as reference implementations of UBL formatting specifications or as normative components of the UBL delivery.
See FS-implementations.htmlfor a list of known implementations of UBL Formatting Specifications at the time of publication.
If you have any input to these formatting specifications, please do not hesitate to contact the UBL Forms Presentation Subcommittee following the directions on the home page cited above.
This appendix provides example instances of UBL documents being used in two different versions of the order-to-invoice process. The first set of examples illustrates the buying of office supplies, and the second set illustrates the buying of joinery (building supplies). Also included are printed versions of each example document created by generating PDF files from the example instances in accordance with stylesheets referenced in Appendix C.
The buyer, Bill's Microdevices, orders several different items from an office supply store. The buyer knows the supplier's codes for the items and the price for each.
- Office supplies Order example instance:
- xml/office/UBL-Order-1.0-Office-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The buyer decides to change the original order.
- Office supplies OrderChange example instance:
- xml/office/UBL-OrderChange-1.0-Office-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The seller, Joe's Office Supply, replies with an Order ResponseSimple to indicate the acceptance of the order. The seller also gives his reference number for the order, i.e., the sales order in his system, and tells the buyer whom to contact if he has any queries.
- Office supplies OrderResponseSimple example instance:
- xml/office/UBL-OrderResponseSimple-1.0-Office-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The buyer cancels a different Order. [*** what means "a different order"? ***]
- Office supplies OrderCancellation example instance:
- xml/office/UBL-OrderCancellation-1.0-Office-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The seller advises the buyer of the despatch of the items ordered.
- Office supplies DespatchAdvice example instance:
- xml/office/UBL-DespatchAdvice-1.0-Office-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The buyer notifies the seller of missing items.
- Office supplies ReceiptAdvice example instance:
- xml/office/UBL-ReceiptAdvice-1.0-Office-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The seller raises the Invoice automatically when the despatch occurs, and the resolution of shortages etc. will be handled post-invoicing. The Invoice shows the tax amount. The seller notes that payment is due within 30 days of Invoice.
- Office supplies Invoice example instance:
- xml/office/UBL-Invoice-1.0-Office-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The buyer, Jerry Builders, PLC. in the UK, orders a number of windows, a door set and some lengths of timber for delivery to a building site. He knows the supplier's codes for the items and that he must also specify a number of physical attributes to get the precise item that he wants. Some windows are asymmetric and are 'handed' left or right: most door sets are handed as they are hinged on one side. The wood and its finish, the 'fittings' are the handles, stays etc. Items can be glazed in different ways. Loose timber is coded according to its cross section and the length must be specified. While the buyer knows these things from the catalogue he does not know the current prices or any discount rate he may get.
- Joinery Order example instance:
- xml/joinery/UBL-Order-1.0-Joinery-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The seller, Specialist Windows PLC, replies with an Order Response (complex) so as to indicate the unit price of each item and to inform the buyer of the trade discount that he will be given. At the same time, the seller gives his reference number of the order, i.e. the identity of the order in his system, and also tells the buyer whom to contact if he has any queries.
- Joinery OrderResponse example instance:
- xml/joinery/UBL-OrderResponse-1.0-Joinery-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The seller advises the buyer of the despatch of the items ordered, which will in fact be delivered on two pallets identified as "A" and "B" (i.e. transportation units). The Despatch Advice lists the items in order line sequence and refers to the pallet on which the item is delivered.
- Joinery DespatchAdvice example instance:
- xml/joinery/UBL-DespatchAdvice-1.0-Joinery-Example.xml
- Generated printout:
- [pdf file not yet assigned]
The Despatch Advice travels with the delivery; a paper copy is signed
and returned as proof of receipt. Hence the UBL Receipt Advice is not used.
The Seller raises the Invoice automatically when the despatch occurs, and
the resolution of any shortages would be handled post-invoicing. The Invoice
has to show the tax point date, the VAT (Value Added Tax) category to which the
item belongs and also to show the VAT rate and total for each tax category on
the invoice. VAT is also applied to charges such as the delivery surcharge. In
order to encourage speedy payment of the amount due, the Seller offers a
discount for prompt settlement, which the buyer can deduct if paying within 30
days. (Note that VAT regulations assume it will be taken and so the tax is
calculated on the trade discounted total of line items plus any charges and
less the settlement discount amount.)
- Joinery Invoice example instance:
- xml/joinery/UBL-Invoice-1.0-Joinery-Example.xml
- Generated printout:
- [pdf file not yet assigned]
This scenario is based on the products, product identification, business requirements and practices of a real UK joinery manufacturer and sales company. It operated its own specialised transport fleet delivering all over the United Kingdom and to offshore islands.
UBL also provides an ASN.1 specification for UBL messages that provides an alternative XML schema definition for the XML documents. This ASN.1 specification defines the same valid XML documents as the XSD Schema, which is the primary definition of valid XML documents. Use of this ASN.1 XML schema enables ASN.1 tools to be used for UBL transfers, and in conjunction with the ASN.1 Packed Encoding Rules, provides a specification for an efficient "binary XML" encoding of UBL messages.
This is the definition of binary XML encodings of UBL messages.
The ASN.1 definition for the current release of UBL can be found at:
The ASN.1 schemas for UBL were created by using a tool from OSS Nokalva (www.oss.com) that conforms to ITU-T Recommendation X.694 | ISO/IEC 8825-5 for converting XML Schema to ASN.1. After feeding the UBL XSD to the OSS Nokalva XSD to ASN.1 conversion tool, the generated ASN.1 was fed to the PrettyPrint tool athttp://asn1.elibel.tm.frwebsite to produce the nicely formatted HTML version of the UBL ASN.1 schemas.