Party RolesActorRoleDescriptionExampleSynonymsSendsReceivesCustomer PartyOriginatorThe 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 Request for Quotation and Quotation or by receiving a Quotation as a response to a punch-out 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 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 PartyBuyerThe party that purchases the goods or services on behalf of the Originator. The Buyer may be referred to in Order Response, Despatch Advice, Fulfilment Cancellation, Invoice, Self Billed Invoice, Credit Note, and 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, Order Cancellation, Fulfilment Cancellation
Order Response, Fulfilment Cancellation
Customer PartyDeliveryThe 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 Request for Quotation, 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 delivery of the wheelchair.Delivery Point, Destination Party, Receiver, Recipient
Receipt Advice
Despatch Advice
Customer PartyAccounting CustomerThe 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.Invoice, Accounts Payable, DebtorIn a traditional Billing scenario: Debit Note, Application 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; in a Self Billing scenario: Credit Note, Application Response, and Statement
Supplier PartySellerThe 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 Request for Quotation documents 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, Fulfilment Cancellation
Request for Quotation, Order, Order Change, Order Cancellation, Catalogue Request, Fulfilment Cancellation
Supplier PartyDespatchThe 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 PartyAccounting SupplierThe 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, CreditorIn a traditional Billing scenario: Invoice, Credit Note, and Statement; in a Self Billing scenario: Credit Note, Application Response, and Statement
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
Supplier PartyPayeeThe 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 PartyContractorThe 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
Catalogue Request
Catalogue, Catalogue Deletion, Catalogue Item Specification Update, Catalogue Pricing Update
PartyProviderThe 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
PartyReceiverA general role, describing the receiver of a document. For a catalogue, this can be the customer, a potential customer, or a third party exposing the document, for instance, an interim broker.A marketplace may receive an Application Response.
Catalogue, Catalogue Deletion, Catalogue Item Specification Update, Catalogue Pricing Update, Application Response
PartySenderThe party sending a document.A marketplace may send an Application Response.
Application Response
Customer PartyContracting AuthorityThe party responsible for making the contract relating to a tender ending up with a purchase.If a kindergarten buys a lot of toys they may be a Contracting Authority in a Public Tender.Customer, Debtor
Expression Of Interest Response, Qualification Application Request, Tender Contract, Tender Status, Unsubscribe From Procedure Response
Expression Of Interest Request, Qualification Application Response, and Tender Status Request, Tender Withdrawal, Unsubscribe From Procedure Request
Supplier PartyTendererThe party responsible for handling Originator and Buyer services. The Tenderer party is legally responsible for providing the goods to the Contracting Authority. The Tenderer party receives the Expression Of Interest Response.The organization that sells wheelchairs to municipalities.Seller, Provider, Economic Operator
Expression Of Interest Request, Qualification Application Response, Tender Status Request, Tender Withdrawal, Unsubscribe From Procedure Request
Expression Of Interest Response, Qualification Application Request, Tender Contract, Tender Status, Unsubscribe From Procedure Response
PartyConsignorThe 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 User. 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 User
Forwarding Instructions, Packing List
Bill of Lading, Waybill, Freight Invoice, Transportation Status
PartyConsigneeThe 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
PartyFreight ForwarderThe 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
PartyCarrierThe 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
PartyExporterThe 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
PartyEndorserThe 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
PartyImporterThe 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
Import Customs Declaration
Certificate of Origin
PartyTransport UserThe Transport User is the role representing anyone who has a demand for transport services, books transport services, and follows up the execution of such services.The manufacturer has to order transport of products from a carrier or freight forwarder (Transport Service Provider).Transport Buyer, Logistics Service Client
Transport Execution Plan Request, Transportation Status Request, Transport Service Description Request
Transport Execution Plan, Transportation Status, Transport Service Description, Goods Item Itinerary
PartyTransport Service ProviderThe Transport Service Provider is the role that plans, markets and performs transport services.The carrier or freight forwarder who arranges for transport services on behalf of a manufacturer (Transport User)Transport Provider, Transport Seller, Logistics Service Provider
Transport Execution Plan, Transportation Status, Transport Service Description, Transport Progress Status Request, Goods Item Itinerary
Transport Execution Plan Request, Transportation Status Request, Transport Service Description Request, Transport Progress Status
PartyTransportation Network ManagerThe Transportation Network Manager is the role that extracts all information available regarding the infrastructure (static/dynamic) related to planning and executing transport and makes this information available to the Transport Service Provider. During a transport service, or even during a single leg, the Transport Service Provider may rely on information from several Transportation Network Managers.The Traffic Information Centre (TIC) issuing information related to road work and/or traffic conditions as a service to a Transport Service ProviderRoad Administration, Traffic Information Centre, Coastal Administration, Harbor Master, Railway Administration, Infrastructure Manager
Transport Progress Status
Transport Progress Status Request
PartyGovernorThe Governor is the role that governs an agreement or contract.A legal entity who creates and maintain an agreement.PartyParticipantThe Participant is the role agreeing on a set of digital processes, terms and conditions to ensure interoperability within a business network. A Buyer, Seller, Accounting Customer, Accounting Supplier, Service Provider Party may also play the role of Participant. A Participant in the role of a Business Party communicates its digital capabilities using a Digital Capability document.A Service Provider agreeing on multi-lateral trading partner agreement governed by an e-Procurement network.
Digital Agreement, Application Response
Digital Agreement, Application Response
PartyBusinessThe Business Party is a general role that may be played by any other Party doing business according to a set of business and digital capabilities. A Business Party communicates its business information and capabilities to other parties using a Business Card. A Business Party communicates its digital capabilities to other parties using a Digital Capability document.A Business Party supports the procurement business process according to a specific profile governed by an UBL user group.Trading Partner, Service Provider, Economic Operator, Contracting Authority, Participant
Business Card, Digital Capability, Application Response
Business Card, Digital Capability, Application Response
PartyWeighingThe Weighing Party is a role played by weighing stations, shippers, terminal operators and possibly other parties executing a weight measurement including verified gross mass measurements.A Business Party supports the procurement business process according to a specific profile governed by an UBL user group.Weighing Station, Weighing Provider
Weight Statement
Application Response
PartyResponsibleThe party responsible for signing the VGM on behalf of the Shipper.A Weighing Party playing the role of a Responsible who signs a VGM.PartyExporterThe party who initiates the export of goods and is authorized to perform the export. The exporter is often the owner of the goods being exported.A slaughterhouse is the owner of the goods being exported, but not necessarily the party who presents the Goods Certificate for exportation.
Goods Certificate
Export Customs Declaration
PartyImporterThe party who initiates the import of goods and is authorized to perform the import. A grocery store importing meat
Goods Certificate
Goods Certificate
Application Response
PartyPreparationAn authenticated party who performs the import or export in service to the importer or exporter. This is often a terminal operator who stores the goods before it is being exported or imported.A cold store that is keeping the meat before export.Terminal Operator
Goods Certificate
Application Response
Goods Certificate
Application Response
PartyCertificationA legal authority who certifies the goods being imported or exported and signs the Goods Certificate.A food standards agency
Goods Certificate
PartyIssuerThe organisation authorized by the legal authority party to issue the Goods Item Passport.A chamber of commerce
Goods Item Passport
PartyImporting GuarantorThe party fiscal responsible for customs of the goods that has been temporary imported.A chamber of commerce, member of the ICC
Proof Of Reexportation Request
Proof Of Reexportation
Application Response
PartyExporting GuarantorThe party fiscal responsible for customs of the goods that has been temporary exported.A chamber of commerce, member of the ICC
Proof Of Reexportation
Application Response
Proof Of Reexportation Request
PartyHolderThe holder of the Goods Item Passport, often the temporary exporter of the goods and the one the Goods Item Passport is applied to. A manufacturer who wants to present some goods at an exhibition and brings them in on a temporary basis.
Goods Item Passport
Application Response
PartyAccompanyingThe party accompanying the goods during the exportation and importation.A representative for the holder who wants to go to an exhibition with commercial goods not for sale.Representing party
Goods Item Passport
Application Response
PartyExporting CustomsThe party legal responsible for the export of the goods.A chamber of commerce
Goods Item Passport
Application Response
Export Customs Declaration
Goods Item Passport
Export Customs Declaration
Application Response
PartyImporting CustomsThe party legal responsible for the import of the goods. The original requester for the Proof Of Reexportation Request.A chamber of commerce
Goods Item Passport
Application Response
Goods Item Passport
Authenticated PartyExporterThe party who initiates the export and holds an authentication to perform the export. The exporter is often the owner of the goods being exportedA slaughterhouse are the owner of the goods being exported, but not necessarily the party who presents the Goods Certificate for exportation
Goods Certificate
Authenticated PartyImporterThe party who initiates the import and holds an authentication to perform the import. A grocery store importing meet
Goods Certificate
Authenticated PartyRepresentativeA authenticated party who perform the import or export on behalf of the importer or exporter. This is often a terminal operator who stores the goods before it is being exported or imported.A cold store that are keeping the meet before export.
Goods Certificate
PartyLegal AuthorityA legal authority who validates the goods being imported or exported and signs the Goods CertificateA food standard agency
Goods Certificate
PartyIssuerThe organisation authorized by the legal authority party to issue the certificate.A chamber of commerce
Goods Certificate
PartyImporting GuarantorThe party fiscal responsible for customs of the goods that has been temporary importedA chamber of commerce, member of the ICC
Proof Of Reexportation Request
Proof Of Reexportation
Application Response
PartyExporting GuarantorThe party fiscal responsible for customs of the goods that has been temporary exportedA chamber of commerce, member of the ICC
Proof Of Reexportation Request
Proof Of Reexportation
Application Response
PartyExporting GuarantorThe party fiscal responsible for customs of the goods that has been temporary exportedA chamber of commerce, member of the ICC
Proof Of Reexportation
Application Response
Proof Of Reexportation Request
PartyHolderThe holder of the Goods Item passport, often the temporary exporter of the goods and the one the Goods Item Passport is applied to. A exporter who wants presents some goods at an exhibition and bring in some goods temporary
Goods Item Passport
Application Response
PartyRepresentativeThe party accompanying the goods during the importation.A representative for the holder who wants to go for an exhibition
Goods Item Passport
Application Response
PartyGuarantorThe party (often chambers) that provides the fiscal guarantee of the Goods Item passport.A chamber of commerce member of the ICCPartyIssuerThe organisation authorized by the guarantor party to issue the Goods Item PassportA chamber of commerce
Goods Item Passport
Application Response
Goods Item Passport
PartyTransit ExporterThe party who makes regulatory export declarations, or on whose behalf regulatory transit customs 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.A Norwegian exporter may have to do a Transit Customs Declaration in order to export to RussiaSeller, Consignor
Transit Customs Declaration
Application Response
PartyReceiving Logistic OperatorThe party who in the role of a logistic operator is receiving a Manifest
A ground handling in an airport receives a Manifest from a logistic operator.
Manifest
PartySending Logistic OperatorThe party who in the role of a logistic operator is sending a Manifest
A logistic operator consolidates some goods in a terminal and ships it along with a Manifest to a ground handler in an AirportFreight Forwarder
Manifest
PartyCustomsThe party who is receiving a Customs DeclarationA Customs Party receives a Export Customs Declaration from a Exporter Party
Export Customs Declaration
PartyAuthorityThe party who is receiving a Common Transportation Report
An Authority party receives a Common Transportation Report from a Logistics operator as reporter
Common Transportation Report
PartyReporterThe party who is sending a Common Transportation Report
A Logistic operator sends a Common Transportation Report to a harbourLogistics Operator
Common Transportation Report
UBL 2.3 SchemasUBL 2.3 Schemas IntroductionThe UBL XSD schemas are the only normative representations of the UBL document types and library components for the purposes of XML document validation and conformance.All of the UBL XSD schemas are contained in the xsd subdirectory of the UBL release package (see for more information regarding the structure of the release package and for information regarding
dependencies among the schema modules). The xsd directory is further subdivided into an xsd/maindoc subdirectory containing the schemas for individual document types and an xsd/common subdirectory containing schemas in the UBL common
library. For convenience in implementing the schemas, parallel (and technically non-normative) “runtime” sets with the annotation elements stripped out are provided in the xsdrt/ directory.UBL 2.3 Document SchemasUBL 2.3 Document Schemas IntroductionThe tables that follow describe each of the UBL document types. Along with a link to the normative schema for each document type, each table provides links to the corresponding “runtime” schema, model spreadsheets and summary report in HTML (see ), and example instance, if any (see ).Application Response SchemaDescription: A document to indicate the application’s response to a transaction. This may be a
business response and/or a technical response, sent automatically by an application or
initiated by a user.Processes involvedAny collaborationSubmitter roleSenderReceiver roleReceiverNormative schemaxsd/maindoc/UBL-ApplicationResponse-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ApplicationResponse-2.3.xsdSummary reportmod/summary/reports/UBL-ApplicationResponse-2.3.htmlAttached Document SchemaDescription: A UBL wrapper that allows a document of any kind to be packaged with the UBL
document that references it.Processes involvedAny collaborationSubmitter roleSenderReceiver roleReceiverNormative schemaxsd/maindoc/UBL-AttachedDocument-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-AttachedDocument-2.3.xsdSummary reportmod/summary/reports/UBL-AttachedDocument-2.3.htmlAwarded Notification SchemaDescription: The document used to communicate a contract award to the winner.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-AwardedNotification-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-AwardedNotification-2.3.xsdSummary reportmod/summary/reports/UBL-AwardedNotification-2.3.htmlBill Of Lading SchemaDescription: A document that conveys information about an instance of a transportation service
and may under some circumstances serve as a contractual document For the service. See
Bill of Lading and compare with Waybill.Processes involved
Transport
Submitter roleFreight Forwarder, CarrierReceiver roleConsignor (or Consignee), Freight ForwarderNormative schemaxsd/maindoc/UBL-BillOfLading-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-BillOfLading-2.3.xsdSummary reportmod/summary/reports/UBL-BillOfLading-2.3.htmlBusiness Card SchemaDescription: A document used to provide information about a business party and its business capabilities. Processes involved
Business Directory and Agreements
Submitter roleSenderReceiver roleReceiverNormative schemaxsd/maindoc/UBL-BusinessCard-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-BusinessCard-2.3.xsdSummary reportmod/summary/reports/UBL-BusinessCard-2.3.htmlUBL 2.2 example instancexml/UBL-BusinessCard-2.2-Example.xmlCall For Tenders SchemaDescription: A document used by a Contracting Party to define a procurement project to buy
goods, services, or works during a specified period.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-CallForTenders-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CallForTenders-2.3.xsdSummary reportmod/summary/reports/UBL-CallForTenders-2.3.htmlCatalogue SchemaDescription: A document that describes items, prices, and price validity. See
Catalogue.Processes involved
Catalogue, Create Catalogue, Delete Catalogue, Update Catalogue Item Specification, Update Catalogue Pricing, Initial Stocking of the Area by Producer, Permanent Replenishment, Price Adjustments, Transfer of Base Item Catalogue, Changes to the Item Catalogue, Changes to the Article Catalogue
Submitter roleSellerReceiver roleContracting PartyNormative schemaxsd/maindoc/UBL-Catalogue-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Catalogue-2.3.xsdSummary reportmod/summary/reports/UBL-Catalogue-2.3.htmlCatalogue Deletion SchemaDescription: A document used to cancel an entire Catalogue.Processes involved
Catalogue
Submitter roleSellerReceiver roleContracting PartyNormative schemaxsd/maindoc/UBL-CatalogueDeletion-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CatalogueDeletion-2.3.xsdSummary reportmod/summary/reports/UBL-CatalogueDeletion-2.3.htmlCatalogue Item Specification Update SchemaDescription: A document used to update information (e.g., technical descriptions and properties)
about Items in an existing Catalogue.Processes involved
Catalogue
Submitter roleSellerReceiver roleContracting PartyNormative schemaxsd/maindoc/UBL-CatalogueItemSpecificationUpdate-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CatalogueItemSpecificationUpdate-2.3.xsdSummary reportmod/summary/reports/UBL-CatalogueItemSpecificationUpdate-2.3.htmlCatalogue Pricing Update SchemaDescription: A document used to update information about prices in an existing
Catalogue.Processes involved
Catalogue
Submitter roleSellerReceiver roleContracting PartyNormative schemaxsd/maindoc/UBL-CataloguePricingUpdate-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CataloguePricingUpdate-2.3.xsdSummary reportmod/summary/reports/UBL-CataloguePricingUpdate-2.3.htmlCatalogue Request SchemaDescription: A document used to request a Catalogue.Processes involved
Catalogue
Submitter roleContracting PartyReceiver roleSellerNormative schemaxsd/maindoc/UBL-CatalogueRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CatalogueRequest-2.3.xsdSummary reportmod/summary/reports/UBL-CatalogueRequest-2.3.htmlCertificate Of Origin SchemaDescription: A document that describes the Certificate of Origin.Processes involved
Certification of Origin of Goods
Submitter roleExporter, IssuerReceiver roleIssuer, ImporterNormative schemaxsd/maindoc/UBL-CertificateOfOrigin-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CertificateOfOrigin-2.3.xsdSummary reportmod/summary/reports/UBL-CertificateOfOrigin-2.3.htmlCommon Transportation Report SchemaDescription: A document used report transportation events to an authority.Processes involved
Common Transportation Report
Submitter roleReporter partyReceiver roleAuthority partyNormative schemaxsd/maindoc/UBL-CommonTransportationReport-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CommonTransportationReport-2.3.xsdSummary reportmod/summary/reports/UBL-CommonTransportationReport-2.3.htmlUBL 2.3 example instancexml/UBL-CommonTransportationReport-2.3-Example.xmlContract Award Notice SchemaDescription: A document published by a Contracting Party to announce the awarding of a
procurement project.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-ContractAwardNotice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ContractAwardNotice-2.3.xsdSummary reportmod/summary/reports/UBL-ContractAwardNotice-2.3.htmlContract Notice SchemaDescription: A document used by a Contracting Party to announce a project to buy goods, services
or works.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-ContractNotice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ContractNotice-2.3.xsdSummary reportmod/summary/reports/UBL-ContractNotice-2.3.htmlCredit Note SchemaDescription: A document used to specify credits due to the Debtor from the
Creditor.Processes involved
Billing
Submitter roleSupplier Accounting PartyReceiver roleCustomer Accounting PartyNormative schemaxsd/maindoc/UBL-CreditNote-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-CreditNote-2.3.xsdSummary reportmod/summary/reports/UBL-CreditNote-2.3.htmlUBL 2.0 example instancexml/UBL-CreditNote-2.0-Example.xmlUBL 2.1 example instancexml/UBL-CreditNote-2.1-Example.xmlDebit Note SchemaDescription: A document used to specify debts incurred by the Debtor.Processes involved
Billing
Submitter roleCustomer Accounting PartyReceiver roleSupplier Accounting PartyNormative schemaxsd/maindoc/UBL-DebitNote-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-DebitNote-2.3.xsdSummary reportmod/summary/reports/UBL-DebitNote-2.3.htmlUBL 2.1 example instancexml/UBL-DebitNote-2.1-Example.xmlDespatch Advice SchemaDescription: A document used to describe the despatch or delivery of goods and
services.Processes involved
Logistics
Submitter roleDespatchReceiver roleDeliveryNormative schemaxsd/maindoc/UBL-DespatchAdvice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-DespatchAdvice-2.3.xsdSummary reportmod/summary/reports/UBL-DespatchAdvice-2.3.htmlUBL 2.0 example instancexml/UBL-DespatchAdvice-2.0-Example.xmlDigital Agreement SchemaDescription: A document used to support business parties agreeing on a set of digital processes, terms and conditions to ensure interoperability.Processes involved
Business Directory and Agreements
Submitter roleAgreement ParticipantReceiver roleAgreement ParticipantNormative schemaxsd/maindoc/UBL-DigitalAgreement-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-DigitalAgreement-2.3.xsdSummary reportmod/summary/reports/UBL-DigitalAgreement-2.3.htmlUBL 2.2 example instancexml/UBL-DigitalAgreement-2.2-Example.xmlUBL 2.2 example instancexml/UBL-DigitalAgreement-2.2-Example-Multilateral.xmlDigital Capability SchemaDescription: A document used to provide information about a business party and its digital capabilities. Processes involved
Business Directory and Agreements
Submitter roleSenderReceiver roleReceiverNormative schemaxsd/maindoc/UBL-DigitalCapability-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-DigitalCapability-2.3.xsdSummary reportmod/summary/reports/UBL-DigitalCapability-2.3.htmlUBL 2.2 example instancexml/UBL-DigitalCapability-2.2-Example.xmlDocument Status SchemaDescription: A document used to provide information about document status.Processes involvedAny collaborationSubmitter roleParty currently controlling Status of the collaborationReceiver roleParty requesting Status on collaborationNormative schemaxsd/maindoc/UBL-DocumentStatus-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-DocumentStatus-2.3.xsdSummary reportmod/summary/reports/UBL-DocumentStatus-2.3.htmlDocument Status Request SchemaDescription: A document used to request the status of another document.Processes involvedAny collaborationSubmitter roleParty requesting Status on collaborationReceiver roleParty currently controlling Status of the collaborationNormative schemaxsd/maindoc/UBL-DocumentStatusRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-DocumentStatusRequest-2.3.xsdSummary reportmod/summary/reports/UBL-DocumentStatusRequest-2.3.htmlEnquiry SchemaDescription: A document sent by a requestor to a responder requesting information about a particular business process.
Processes involvedAny collaborationSubmitter roleRequestorReceiver roleResponderNormative schemaxsd/maindoc/UBL-Enquiry-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Enquiry-2.3.xsdSummary reportmod/summary/reports/UBL-Enquiry-2.3.htmlEnquiry Response SchemaDescription: A document sent by a responder to a requester answering a particular enquiry.Processes involvedAny collaborationSubmitter roleResponderReceiver roleRequestorNormative schemaxsd/maindoc/UBL-EnquiryResponse-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-EnquiryResponse-2.3.xsdSummary reportmod/summary/reports/UBL-EnquiryResponse-2.3.htmlException Criteria SchemaDescription: A document used to specify the thresholds for forecast variance, product activity,
and performance history beyond which exceptions should be triggered.Processes involved
Collaborative Planning, Forecasting, and Replenishment
Submitter roleBuyer, SellerReceiver roleBuyer, SellerNormative schemaxsd/maindoc/UBL-ExceptionCriteria-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ExceptionCriteria-2.3.xsdSummary reportmod/summary/reports/UBL-ExceptionCriteria-2.3.htmlUBL 2.1 example instancexml/UBL-ExceptionCriteria-2.1-Example.xmlException Notification SchemaDescription: A document used to notify an exception in forecast variance, product activity, or
performance history.Processes involved
Collaborative Planning, Forecasting, and Replenishment
Submitter roleBuyer, SellerReceiver roleBuyer, SellerNormative schemaxsd/maindoc/UBL-ExceptionNotification-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ExceptionNotification-2.3.xsdSummary reportmod/summary/reports/UBL-ExceptionNotification-2.3.htmlUBL 2.1 example instancexml/UBL-ExceptionNotification-2.1-Example.xmlExport Customs Declaration SchemaDescription: A document used to declare goods for exportationProcesses involved
Export Customs Declaration
Submitter roleExporter PartyReceiver roleCustoms PartyNormative schemaxsd/maindoc/UBL-ExportCustomsDeclaration-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ExportCustomsDeclaration-2.3.xsdSummary reportmod/summary/reports/UBL-ExportCustomsDeclaration-2.3.htmlUBL 2.3 example instancexml/UBL-ExportCustomsDeclaration-2.3-Example.xmlExpression Of Interest Request SchemaDescription: A document whereby an Economic Operator (the tenderer) makes an Expression Of
Interest in a Call For Tenders to a Contracting Authority Processes involved
Pre-award
Submitter roleTenderer (Economic Operator)Receiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-ExpressionOfInterestRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ExpressionOfInterestRequest-2.3.xsdSummary reportmod/summary/reports/UBL-ExpressionOfInterestRequest-2.3.htmlUBL 2.2 example instancexml/UBL-ExpressionOfInterestRequest-2.2-Example.xmlExpression Of Interest Response SchemaDescription: A document whereby a Contracting Authority accepts receiving an Expression Of
Interest from an Economic Operator (the tenderer) Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTenderer (Economic Operator)Normative schemaxsd/maindoc/UBL-ExpressionOfInterestResponse-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ExpressionOfInterestResponse-2.3.xsdSummary reportmod/summary/reports/UBL-ExpressionOfInterestResponse-2.3.htmlForecast SchemaDescription: A document used to forecast sales or orders.Processes involved
Collaborative Planning, Forecasting, and Replenishment
Submitter roleBuyer, SellerReceiver roleBuyer, SellerNormative schemaxsd/maindoc/UBL-Forecast-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Forecast-2.3.xsdSummary reportmod/summary/reports/UBL-Forecast-2.3.htmlUBL 2.1 example instancexml/UBL-Forecast-2.1-Example.xmlForecast Revision SchemaDescription: A document used to revise a Forecast.Processes involved
Collaborative Planning, Forecasting, and Replenishment
Submitter roleBuyer, SellerReceiver roleBuyer, SellerNormative schemaxsd/maindoc/UBL-ForecastRevision-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ForecastRevision-2.3.xsdSummary reportmod/summary/reports/UBL-ForecastRevision-2.3.htmlUBL 2.1 example instancexml/UBL-ForecastRevision-2.1-Example.xmlForwarding Instructions SchemaDescription: A document issued to a forwarder, giving instructions regarding the action to be
taken for the forwarding of goods described therein. See Forwarding Instructions.Processes involved
Transport
Submitter roleConsignor (or Consignee), Freight ForwarderReceiver roleFreight Forwarder, CarrierNormative schemaxsd/maindoc/UBL-ForwardingInstructions-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ForwardingInstructions-2.3.xsdSummary reportmod/summary/reports/UBL-ForwardingInstructions-2.3.htmlUBL 2.0 example instancexml/UBL-ForwardingInstructions-2.0-Example-International.xmlFreight Invoice SchemaDescription: A document stating the charges incurred for a logistics service.Processes involved
Freight Billing
Submitter roleFreight ForwarderReceiver roleConsignor or ConsigneeNormative schemaxsd/maindoc/UBL-FreightInvoice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-FreightInvoice-2.3.xsdSummary reportmod/summary/reports/UBL-FreightInvoice-2.3.htmlUBL 2.1 example instancexml/UBL-FreightInvoice-2.1-Example.xmlFulfilment Cancellation SchemaDescription: A document used to cancel an entire Despatch Advice or Receipt Advice.Processes involved
Logistics
Submitter roleBuyer or SellerReceiver roleSeller or BuyerNormative schemaxsd/maindoc/UBL-FulfilmentCancellation-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-FulfilmentCancellation-2.3.xsdSummary reportmod/summary/reports/UBL-FulfilmentCancellation-2.3.htmlUBL 2.1 example instancexml/UBL-FulfilmentCancellation-2.1-Example.xmlGoods Certificate SchemaDescription: A document used to prove one or more requirements about goods under transportProcesses involved
Export Goods Certificate
Submitter roleExporter partyReceiver roleLegal Authority PartyNormative schemaxsd/maindoc/UBL-GoodsCertificate-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-GoodsCertificate-2.3.xsdSummary reportmod/summary/reports/UBL-GoodsCertificate-2.3.htmlUBL 2.3 example instancexml/UBL-GoodsCertificate-2.3-Example.xmlGoods Item Itinerary SchemaDescription: A document providing details relating to a transport service, such as transport
movement, identification of equipment and goods, subcontracted service providers,
etc.Processes involved
Intermodal Freight Management
Submitter roleTransport Service ProviderReceiver roleTransport UserNormative schemaxsd/maindoc/UBL-GoodsItemItinerary-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-GoodsItemItinerary-2.3.xsdSummary reportmod/summary/reports/UBL-GoodsItemItinerary-2.3.htmlUBL 2.1 example instancexml/UBL-GoodsItemItinerary-2.1-Example.xmlGoods Item Passport SchemaDescription: A document used to declare goods for temporary exportationProcesses involved
Goods Item Passport (Carnet)
Submitter roleHolderPartyReceiver roleIssuerPartyNormative schemaxsd/maindoc/UBL-GoodsItemPassport-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-GoodsItemPassport-2.3.xsdSummary reportmod/summary/reports/UBL-GoodsItemPassport-2.3.htmlUBL 2.3 example instancexml/UBL-GoodsItemPassport-2.3-Example-Issued.xmlGuarantee Certificate SchemaDescription: A document to notify the deposit of a bid bond guarantee.Processes involved
Pre-award
Submitter roleTendererReceiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-GuaranteeCertificate-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-GuaranteeCertificate-2.3.xsdSummary reportmod/summary/reports/UBL-GuaranteeCertificate-2.3.htmlImport Customs Declaration SchemaDescription: A document used to declare goods for importProcesses involved
Import Customs Declaration
Submitter roleImporter PartyReceiver roleCustoms PartyNormative schemaxsd/maindoc/UBL-ImportCustomsDeclaration-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ImportCustomsDeclaration-2.3.xsdSummary reportmod/summary/reports/UBL-ImportCustomsDeclaration-2.3.htmlUBL 2.3 example instancexml/UBL-ImportCustomsDeclaration-2.3-Example.xmlInstruction For Returns SchemaDescription: A document used to initiate a return of goods. The producer is requesting the
return of products that are not selling well, either to use in other places or to free up rack
or shelf space.Processes involved
Cyclic Replenishment Program (CRP)
Submitter roleSellerReceiver roleBuyerNormative schemaxsd/maindoc/UBL-InstructionForReturns-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-InstructionForReturns-2.3.xsdSummary reportmod/summary/reports/UBL-InstructionForReturns-2.3.htmlUBL 2.1 example instancexml/UBL-InstructionForReturns-2.1-Example.xmlInventory Report SchemaDescription: A report on the quantities of each item that are, or will be, in stock. This
document is sent by a Buyer (for example a retailer) to a Seller (for example a
producer).Processes involved
Cyclic Replenishment Program (CRP)
Submitter roleBuyerReceiver roleSellerNormative schemaxsd/maindoc/UBL-InventoryReport-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-InventoryReport-2.3.xsdSummary reportmod/summary/reports/UBL-InventoryReport-2.3.htmlUBL 2.1 example instancexml/UBL-InventoryReport-2.1-Example.xmlInvoice SchemaDescription: A document used to request payment.Processes involved
Billing
Submitter roleSupplier Accounting PartyReceiver roleCustomer Accounting PartyNormative schemaxsd/maindoc/UBL-Invoice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Invoice-2.3.xsdSummary reportmod/summary/reports/UBL-Invoice-2.3.htmlUBL 2.0 example instancexml/UBL-Invoice-2.0-Example.xmlUBL 2.1 example instancexml/UBL-Invoice-2.1-Example.xmlUBL 2.1 example instancexml/UBL-Invoice-2.1-Example-Trivial.xmlItem Information Request SchemaDescription: A document used to request product activity, forecast, or performance
data.Processes involved
Collaborative Planning, Forecasting, and Replenishment
Submitter roleBuyer, SellerReceiver roleBuyer, SellerNormative schemaxsd/maindoc/UBL-ItemInformationRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ItemInformationRequest-2.3.xsdSummary reportmod/summary/reports/UBL-ItemInformationRequest-2.3.htmlManifest SchemaDescription: A document used to specify the quantity and nature of cargo and personel for a single shipment stage often expressed as a set of consignments.Processes involved
Manifest
Submitter roleSending Logistic Operator partyReceiver roleReceiving Logistic Operator partyNormative schemaxsd/maindoc/UBL-Manifest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Manifest-2.3.xsdSummary reportmod/summary/reports/UBL-Manifest-2.3.htmlUBL 2.3 example instancexml/UBL-Manifest-2.3-Example-Reference-Only.xmlUBL 2.3 example instancexml/UBL-Manifest-2.3-Example-Shipment.xmlOrder SchemaDescription: A document used to order goods and services.Processes involved
Ordering (post-award)
Submitter roleBuyerReceiver roleSellerNormative schemaxsd/maindoc/UBL-Order-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Order-2.3.xsdSummary reportmod/summary/reports/UBL-Order-2.3.htmlUBL 2.0 example instancexml/UBL-Order-2.0-Example.xmlUBL 2.1 example instancexml/UBL-Order-2.1-Example.xmlUBL 2.0 example instancexml/UBL-Order-2.0-Example-International.xmlOrder Cancellation SchemaDescription: A document used to cancel an entire Order.Processes involved
Ordering (post-award), Logistics
Submitter roleBuyerReceiver roleSellerNormative schemaxsd/maindoc/UBL-OrderCancellation-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-OrderCancellation-2.3.xsdSummary reportmod/summary/reports/UBL-OrderCancellation-2.3.htmlUBL 2.1 example instancexml/UBL-OrderCancellation-2.1-Example.xmlOrder Change SchemaDescription: A document used to specify changes to an existing Order.Processes involved
Ordering (post-award), Logistics
Submitter roleBuyerReceiver roleSellerNormative schemaxsd/maindoc/UBL-OrderChange-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-OrderChange-2.3.xsdSummary reportmod/summary/reports/UBL-OrderChange-2.3.htmlUBL 2.1 example instancexml/UBL-OrderChange-2.1-Example.xmlOrder Response SchemaDescription: A document used to indicate detailed acceptance or rejection of an
Order or to make a counter-offer.Processes involved
Ordering (post-award)
Submitter roleSellerReceiver roleBuyerNormative schemaxsd/maindoc/UBL-OrderResponse-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-OrderResponse-2.3.xsdSummary reportmod/summary/reports/UBL-OrderResponse-2.3.htmlUBL 2.1 example instancexml/UBL-OrderResponse-2.1-Example.xmlOrder Response Simple SchemaDescription: A document used to indicate simple acceptance or rejection of an entire
Order.Processes involved
Ordering (post-award)
Submitter roleSellerReceiver roleBuyerNormative schemaxsd/maindoc/UBL-OrderResponseSimple-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-OrderResponseSimple-2.3.xsdSummary reportmod/summary/reports/UBL-OrderResponseSimple-2.3.htmlUBL 2.0 example instancexml/UBL-OrderResponseSimple-2.0-Example.xmlUBL 2.1 example instancexml/UBL-OrderResponseSimple-2.1-Example.xmlPacking List SchemaDescription: A document describing how goods are packed.Processes involved
Transport
Submitter roleConsignorReceiver roleFreight ForwarderNormative schemaxsd/maindoc/UBL-PackingList-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-PackingList-2.3.xsdSummary reportmod/summary/reports/UBL-PackingList-2.3.htmlPrior Information Notice SchemaDescription: A document used by a contracting party to declare the intention to buy goods,
services, or works during a specified period.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-PriorInformationNotice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-PriorInformationNotice-2.3.xsdSummary reportmod/summary/reports/UBL-PriorInformationNotice-2.3.htmlUBL 2.2 example instancexml/UBL-PriorInformationNotice-2.2-Example-Embedded.xmlUBL 2.2 example instancexml/UBL-PriorInformationNotice-2.2-Example-External.xmlProduct Activity SchemaDescription: A document reporting the movement of goods at specified retail locations for
inventory tracking purposes.Processes involved
Collaborative Planning, Forecasting, and Replenishment, Vendor Managed Inventory
Submitter roleBuyerReceiver roleSellerNormative schemaxsd/maindoc/UBL-ProductActivity-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ProductActivity-2.3.xsdSummary reportmod/summary/reports/UBL-ProductActivity-2.3.htmlUBL 2.1 example instance 1xml/UBL-ProductActivity-2.1-Example-1.xmlUBL 2.1 example instance 2xml/UBL-ProductActivity-2.1-Example-2.xmlUBL 2.1 example instance 3xml/UBL-ProductActivity-2.1-Example-3.xmlProof Of Reexportation SchemaDescription: A document used to prove reexportation of goodsProcesses involved
Goods Item Passport Proof of Re-exportation
Submitter roleExporting Guarantor partyReceiver roleImporting Guarantor partyNormative schemaxsd/maindoc/UBL-ProofOfReexportation-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ProofOfReexportation-2.3.xsdSummary reportmod/summary/reports/UBL-ProofOfReexportation-2.3.htmlUBL 2.3 example instancexml/UBL-ProofOfReexportation-2.3-Example.xmlProof Of Reexportation Reminder SchemaDescription: A reminder that a requested Proof of Reexportation is pendingProcesses involved
Goods Item Passport Proof of Re-exportation
Submitter roleCustoms PartyReceiver roleExporting Guarantor partyNormative schemaxsd/maindoc/UBL-ProofOfReexportationReminder-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ProofOfReexportationReminder-2.3.xsdSummary reportmod/summary/reports/UBL-ProofOfReexportationReminder-2.3.htmlUBL 2.3 example instancexml/UBL-ProofOfReexportationReminder-2.3-Example.xmlProof Of Reexportation Request SchemaDescription: A document used request a proof of reexportationProcesses involved
Goods Item Passport Proof of Re-exportation
Submitter roleCustoms PartyReceiver roleExporting Guarantor partyNormative schemaxsd/maindoc/UBL-ProofOfReexportationRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ProofOfReexportationRequest-2.3.xsdSummary reportmod/summary/reports/UBL-ProofOfReexportationRequest-2.3.htmlUBL 2.3 example instancexml/UBL-ProofOfReexportationRequest-2.3-Example.xmlQualification Application Request SchemaDescription: A document whereby a Contracting Authority makes a description of the required
qualification Application (In Europe: ESPD Request) to an Economic Operator (the tenderer) Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTenderer (Economic Operator)Normative schemaxsd/maindoc/UBL-QualificationApplicationRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-QualificationApplicationRequest-2.3.xsdSummary reportmod/summary/reports/UBL-QualificationApplicationRequest-2.3.htmlQualification Application Response SchemaDescription: A document whereby an Economic Operator (the tenderer) makes a description of the
required qualification Application (In Europe: ESPD Response) to an Contracting Authority Processes involved
Pre-award
Submitter roleTenderer (Economic Operator)Receiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-QualificationApplicationResponse-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-QualificationApplicationResponse-2.3.xsdSummary reportmod/summary/reports/UBL-QualificationApplicationResponse-2.3.htmlQuotation SchemaDescription: A document used to quote for the provision of goods and services.Processes involved
Quotation
Submitter roleSellerReceiver roleOriginatorNormative schemaxsd/maindoc/UBL-Quotation-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Quotation-2.3.xsdSummary reportmod/summary/reports/UBL-Quotation-2.3.htmlUBL 2.0 example instancexml/UBL-Quotation-2.0-Example.xmlUBL 2.1 example instancexml/UBL-Quotation-2.1-Example.xmlReceipt Advice SchemaDescription: A document used to describe the receipt of goods and services.Processes involved
Logistics
Submitter roleDeliveryReceiver roleDespatchNormative schemaxsd/maindoc/UBL-ReceiptAdvice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-ReceiptAdvice-2.3.xsdSummary reportmod/summary/reports/UBL-ReceiptAdvice-2.3.htmlUBL 2.0 example instancexml/UBL-ReceiptAdvice-2.0-Example.xmlReminder SchemaDescription: A document used to remind a customer of payments overdue.Processes involved
Billing
Submitter roleSupplier Accounting Party and/or PayeeReceiver roleCustomer Accounting Party and/or PayeeNormative schemaxsd/maindoc/UBL-Reminder-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Reminder-2.3.xsdSummary reportmod/summary/reports/UBL-Reminder-2.3.htmlUBL 2.1 example instancexml/UBL-Reminder-2.1-Example.xmlRemittance Advice SchemaDescription: A document that specifies details of an actual payment.Processes involved
Payment Notification
Submitter roleSupplier Accounting Party and/or PayeeReceiver roleCustomer Accounting Party and/or PayeeNormative schemaxsd/maindoc/UBL-RemittanceAdvice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-RemittanceAdvice-2.3.xsdSummary reportmod/summary/reports/UBL-RemittanceAdvice-2.3.htmlUBL 2.0 example instancexml/UBL-RemittanceAdvice-2.0-Example.xmlRequest For Quotation SchemaDescription: A document used to request a Quotation for goods and services from a
seller.Processes involved
Quotation
Submitter roleOriginatorReceiver roleSellerNormative schemaxsd/maindoc/UBL-RequestForQuotation-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-RequestForQuotation-2.3.xsdSummary reportmod/summary/reports/UBL-RequestForQuotation-2.3.htmlUBL 2.0 example instancexml/UBL-RequestForQuotation-2.0-Example.xmlUBL 2.1 example instancexml/UBL-RequestForQuotation-2.1-Example.xmlRetail Event SchemaDescription: A document used to specify basic information about retail events (such as
promotions, product introductions, and community or environmental events) that affect supply
or demand.Processes involved
Cyclic Replenishment Program (CRP)
Submitter roleBuyer, SellerReceiver roleBuyer, SellerNormative schemaxsd/maindoc/UBL-RetailEvent-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-RetailEvent-2.3.xsdSummary reportmod/summary/reports/UBL-RetailEvent-2.3.htmlUBL 2.1 example instancexml/UBL-RetailEvent-2.1-Example.xmlSelf Billed Credit Note SchemaDescription: A credit note created by the debtor in a self billing arrangement with a creditor;
Self Billed Credit Note replaces Debit Note in such arrangements.Processes involved
Billing
Submitter roleCustomer Accounting PartyReceiver roleSupplier Accounting PartyNormative schemaxsd/maindoc/UBL-SelfBilledCreditNote-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-SelfBilledCreditNote-2.3.xsdSummary reportmod/summary/reports/UBL-SelfBilledCreditNote-2.3.htmlUBL 2.1 example instancexml/UBL-SelfBilledCreditNote-2.1-Example.xmlSelf Billed Invoice SchemaDescription: An invoice document created by the customer (rather than the supplier) in a Self
Billing relationship.Processes involved
Billing
Submitter roleCustomer Accounting PartyReceiver roleSupplier Accounting PartyNormative schemaxsd/maindoc/UBL-SelfBilledInvoice-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-SelfBilledInvoice-2.3.xsdSummary reportmod/summary/reports/UBL-SelfBilledInvoice-2.3.htmlStatement SchemaDescription: A document used to report the status of orders, billing, and payment. This document
is a statement of account, not a summary invoice.Processes involved
Billing
Submitter roleSupplier Accounting PartyReceiver roleCustomer Accounting PartyNormative schemaxsd/maindoc/UBL-Statement-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Statement-2.3.xsdSummary reportmod/summary/reports/UBL-Statement-2.3.htmlUBL 2.0 example instancexml/UBL-Statement-2.0-Example.xmlStock Availability Report SchemaDescription: A report on the quantities of each item that are, or will be, in stock. This
document is sent by a Seller (for example a producer) to a Buyer (for example a
retailer).Processes involved
Cyclic Replenishment Program (CRP)
Submitter roleSeller (Producer)Receiver roleBuyer (Retailer)Normative schemaxsd/maindoc/UBL-StockAvailabilityReport-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-StockAvailabilityReport-2.3.xsdSummary reportmod/summary/reports/UBL-StockAvailabilityReport-2.3.htmlUBL 2.1 example instancexml/UBL-StockAvailabilityReport-2.1-Example.xmlTender SchemaDescription: A document whereby an economic operator (the tenderer) makes a formal offer (the
tender) to a contracting authority to execute an order for the supply or purchase of goods, or
for the execution of work, according to the terms of a proposed contract.Processes involved
Pre-award
Submitter roleTendererReceiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-Tender-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Tender-2.3.xsdSummary reportmod/summary/reports/UBL-Tender-2.3.htmlTender Contract SchemaDescription: A document whereby a Contracting Authority sends information to the Economic
Operator describing the final contract after a tendering procedure.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTenderer (Economic Operator)Normative schemaxsd/maindoc/UBL-TenderContract-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TenderContract-2.3.xsdSummary reportmod/summary/reports/UBL-TenderContract-2.3.htmlTender Receipt SchemaDescription: A document sent by a contracting party to an economic operator acknowledging
receipt of a Tender.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-TenderReceipt-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TenderReceipt-2.3.xsdSummary reportmod/summary/reports/UBL-TenderReceipt-2.3.htmlTender Status SchemaDescription: A document whereby a Contracting Authority sends information to the Economic
Operator describing the status of a tendering procedure.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTenderer (Economic Operator)Normative schemaxsd/maindoc/UBL-TenderStatus-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TenderStatus-2.3.xsdSummary reportmod/summary/reports/UBL-TenderStatus-2.3.htmlTender Status Request SchemaDescription: A document whereby an Economic Operator (the tenderer) asking about the details and
status of a tendering procedure Processes involved
Pre-award
Submitter roleTenderer (Economic Operator)Receiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-TenderStatusRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TenderStatusRequest-2.3.xsdSummary reportmod/summary/reports/UBL-TenderStatusRequest-2.3.htmlTender Withdrawal SchemaDescription: A document whereby an Economic Operator (the tenderer) makes a Tender Withdrawal to
a Contracting Authority Processes involved
Pre-award
Submitter roleTenderer (Economic Operator)Receiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-TenderWithdrawal-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TenderWithdrawal-2.3.xsdSummary reportmod/summary/reports/UBL-TenderWithdrawal-2.3.htmlTenderer Qualification SchemaDescription: A document declaring the qualifications of a tenderer.Processes involved
Pre-award
Submitter roleTendererReceiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-TendererQualification-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TendererQualification-2.3.xsdSummary reportmod/summary/reports/UBL-TendererQualification-2.3.htmlTenderer Qualification Response SchemaDescription: A document issued by a procurement organization to notify an economic operator
whether it has been admitted to or excluded from the tendering process.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-TendererQualificationResponse-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TendererQualificationResponse-2.3.xsdSummary reportmod/summary/reports/UBL-TendererQualificationResponse-2.3.htmlTrade Item Location Profile SchemaDescription: A document specifying trade item attributes relating to replenishment
policies.Processes involved
Collaborative Planning, Forecasting, and Replenishment
Submitter roleBuyer, SellerReceiver roleBuyer, SellerNormative schemaxsd/maindoc/UBL-TradeItemLocationProfile-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TradeItemLocationProfile-2.3.xsdSummary reportmod/summary/reports/UBL-TradeItemLocationProfile-2.3.htmlUBL 2.1 example instancexml/UBL-TradeItemLocationProfile-2.1-Example.xmlTransit Customs Declaration SchemaDescription: A document used to declare goods for transitProcesses involved
Transit Customs Declaration
Submitter roleTransit Customs PartyReceiver roleCustoms PartyNormative schemaxsd/maindoc/UBL-TransitCustomsDeclaration-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransitCustomsDeclaration-2.3.xsdSummary reportmod/summary/reports/UBL-TransitCustomsDeclaration-2.3.htmlUBL 2.3 example instancexml/UBL-TransitCustomsDeclaration-2.3-Example.xmlTransport Execution Plan SchemaDescription: A document used in the negotiation of a transport service between a transport user
and a transport service provider.Processes involved
Intermodal Freight Management
Submitter roleTransport Service Provider, Transport UserReceiver roleTransport User, Transport Service ProviderNormative schemaxsd/maindoc/UBL-TransportExecutionPlan-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportExecutionPlan-2.3.xsdSummary reportmod/summary/reports/UBL-TransportExecutionPlan-2.3.htmlUBL 2.1 example instancexml/UBL-TransportExecutionPlan-2.1-Example.xmlTransport Execution Plan Request SchemaDescription: A document sent by a transport user to request a transport service from a transport
service provider.Processes involved
Intermodal Freight Management
Submitter roleTransport UserReceiver roleTransport Service ProviderNormative schemaxsd/maindoc/UBL-TransportExecutionPlanRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportExecutionPlanRequest-2.3.xsdSummary reportmod/summary/reports/UBL-TransportExecutionPlanRequest-2.3.htmlUBL 2.1 example instancexml/UBL-TransportExecutionPlanRequest-2.1-Example.xmlTransport Progress Status SchemaDescription: A document sent from a transportation network manager to a transport service
provider giving the status of the whereabouts and schedule of the transport means involved in
a transport service.Processes involved
Intermodal Freight Management
Submitter roleTransportation Network ManagerReceiver roleTransport Service ProviderNormative schemaxsd/maindoc/UBL-TransportProgressStatus-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportProgressStatus-2.3.xsdSummary reportmod/summary/reports/UBL-TransportProgressStatus-2.3.htmlUBL 2.1 example instancexml/UBL-TransportProgressStatus-2.1-Example.xmlTransport Progress Status Request SchemaDescription: A document sent from a transport service provider to a transportation network
manager requesting a Transport Progress Status.Processes involved
Intermodal Freight Management
Submitter roleTransport Service ProviderReceiver roleTransportation Network ManagerNormative schemaxsd/maindoc/UBL-TransportProgressStatusRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportProgressStatusRequest-2.3.xsdSummary reportmod/summary/reports/UBL-TransportProgressStatusRequest-2.3.htmlUBL 2.1 example instancexml/UBL-TransportProgressStatusRequest-2.1-Example.xmlTransport Service Description SchemaDescription: A document sent by a transport service provider to announce the availability of a
transport service.Processes involved
Intermodal Freight Management
Submitter roleTransport Service ProviderReceiver roleTransport UserNormative schemaxsd/maindoc/UBL-TransportServiceDescription-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportServiceDescription-2.3.xsdSummary reportmod/summary/reports/UBL-TransportServiceDescription-2.3.htmlUBL 2.1 example instancexml/UBL-TransportServiceDescription-2.1-Example.xmlTransport Service Description Request SchemaDescription: A document requesting a Transport Service Description, sent from a
party with a transport demand (transport user) to a party providing transport services
(transport service provider).Processes involved
Intermodal Freight Management
Submitter roleTransport UserReceiver roleTransport Service ProviderNormative schemaxsd/maindoc/UBL-TransportServiceDescriptionRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportServiceDescriptionRequest-2.3.xsdSummary reportmod/summary/reports/UBL-TransportServiceDescriptionRequest-2.3.htmlUBL 2.1 example instancexml/UBL-TransportServiceDescriptionRequest-2.1-Example.xmlTransportation Status SchemaDescription: A document to circulate reports of transportation status or changes in status
(events) among a group of participants.Processes involved
Freight Status Reporting
Submitter roleTransport Service ProviderReceiver roleTransport UserNormative schemaxsd/maindoc/UBL-TransportationStatus-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportationStatus-2.3.xsdSummary reportmod/summary/reports/UBL-TransportationStatus-2.3.htmlUBL 2.1 example instancexml/UBL-TransportationStatus-2.1-Example.xmlTransportation Status Request SchemaDescription: A document requesting a Transportation Status report.Processes involved
Freight Status Reporting
Submitter roleTransport UserReceiver roleTransport Service ProviderNormative schemaxsd/maindoc/UBL-TransportationStatusRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-TransportationStatusRequest-2.3.xsdSummary reportmod/summary/reports/UBL-TransportationStatusRequest-2.3.htmlUBL 2.1 example instancexml/UBL-TransportationStatusRequest-2.1-Example.xmlUnawarded Notification SchemaDescription: A document communicating to a tenderer that the contract has been awarded to
different tenderer.Processes involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTendererNormative schemaxsd/maindoc/UBL-UnawardedNotification-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-UnawardedNotification-2.3.xsdSummary reportmod/summary/reports/UBL-UnawardedNotification-2.3.htmlUnsubscribe From Procedure Request SchemaDescription: A document whereby an Economic Operator (the tenderer) wants to Unsubscribe From
Procedure and sends it to Contracting Authority Processes involved
Pre-award
Submitter roleTenderer (Economic Operator)Receiver roleContracting AuthorityNormative schemaxsd/maindoc/UBL-UnsubscribeFromProcedureRequest-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-UnsubscribeFromProcedureRequest-2.3.xsdSummary reportmod/summary/reports/UBL-UnsubscribeFromProcedureRequest-2.3.htmlUnsubscribe From Procedure Response SchemaDescription: A document whereby a Contracting Authority accepts receiving an Unsubscribe From
Procedure from an Economic Operator (the tenderer) and sends a confirmationProcesses involved
Pre-award
Submitter roleContracting AuthorityReceiver roleTenderer (Economic Operator)Normative schemaxsd/maindoc/UBL-UnsubscribeFromProcedureResponse-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-UnsubscribeFromProcedureResponse-2.3.xsdSummary reportmod/summary/reports/UBL-UnsubscribeFromProcedureResponse-2.3.htmlUtility Statement SchemaDescription: A supplement to an Invoice or Credit Note, containing
information on the consumption of services provided by utility suppliers to private and public
customers, including electricity, gas, water, and telephone services.Processes involved
Utility Billing
Submitter roleSupplier Accounting PartyReceiver roleCustomer Accounting PartyNormative schemaxsd/maindoc/UBL-UtilityStatement-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-UtilityStatement-2.3.xsdSummary reportmod/summary/reports/UBL-UtilityStatement-2.3.htmlWaybill SchemaDescription: A transport document describing a shipment. It is issued by the party who
undertakes to provide transportation services, or undertakes to arrange for their provision,
to the party who gives instructions for the transportation services (shipper, consignor,
etc.). It states the instructions for the beneficiary and may contain the details of the
transportation, charges, and terms and conditions under which the transportation service is
provided. See Waybill and compare with Bill of Lading.Processes involved
Transport
Submitter roleFreight Forwarder, CarrierReceiver roleConsignor (or Consignee), Freight ForwarderNormative schemaxsd/maindoc/UBL-Waybill-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-Waybill-2.3.xsdSummary reportmod/summary/reports/UBL-Waybill-2.3.htmlUBL 2.0 example instancexml/UBL-Waybill-2.0-Example-International.xmlWeight Statement SchemaDescription: A document used to report weight or verified mass measurements in the transport chain. Processes involved
Transport
Submitter roleSenderReceiver roleReceiverNormative schemaxsd/maindoc/UBL-WeightStatement-2.3.xsdRuntime schemaxsdrt/maindoc/UBL-WeightStatement-2.3.xsdSummary reportmod/summary/reports/UBL-WeightStatement-2.3.htmlUBL 2.2 example instancexml/UBL-WeightStatement-2.2-Example.xmlUBL 2.3 Common SchemasUBL 2.3 Common Schemas IntroductionThe xsd/common directory contains schemas referenced by the document schemas in xsd/maindoc. Elements defined in the common schemas constitute a library of reusable business data components from which the UBL document schemas are (and customized
document types may be) assembled. For a discussion of the way schemas are assembled, see .The name of each schema file together with a brief description of its contents is given below.Reusable BIE Schemas
CommonBasicComponents
xsd/common/UBL-CommonBasicComponents-2.3.xsdThe CommonBasicComponents 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, corresponding to individual data fields in traditional printed business forms.
CommonAggregateComponents
xsd/common/UBL-CommonAggregateComponents-2.3.xsdThe CommonAggregateComponents 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.For a discussion of the terms Basic Business Information Entity and Aggregate Business Information Entity, see .
Reusable Data Type Schemas
CCTS_CCT_SchemaModule
xsd/common/BDNDR-CCTS_CCT_SchemaModule-1.1.xsdThis schema provides Core Component Types as defined by . These types are used to construct higher-level data types in a standardized and consistent manner. This schema is defined by UN/CEFACT and should not be modified. It is imported by the UBL Unqualified
Data Type Schema, and its types are the basis upon which UBL’s unqualified data types are defined.
UnqualifiedDataTypes
xsd/common/BDNDR-UnqualifiedDataTypes-1.1.xsdThis schema defines Unqualified Data Types for BBIE definition. These types are derived from the Core Component Types in CCTS_CCT_SchemaModule. Where an unqualified type is not based solely on an XSD data type, all CCTS supplementary components are made available
in the UBL UDT from the CCTS CCT.
QualifiedDataTypes
xsd/common/UBL-QualifiedDataTypes-2.3.xsd permits the definition of Qualified Datatypes as derivations from CCTS-specified Unqualified Datatypes. In UBL 2.3, all data type qualifications are expressed in the file cva/UBL-DefaultDTQ-2.3.cva. The UBL-QualifiedDataTypes-2.3.xsd file in the UBL 2.3 release has declarations for each qualified type being only an unmodified restriction of the base unqualified data type, thus adding no constraints. The Common Basic Components type declarations point to the XSD
qualified types where the BBIEs are qualified in the CCTS model, but all BBIEs are effectively unqualified.See for information regarding UBL 2.3 data type derivation.
Extension Content SchemasUBL extensions enable the validation of user-defined additions to the standard schemas, which are sometimes needed to satisfy legal requirements and can perform other useful functions as well. For further information regarding the UBL extension mechanism, see .
CommonExtensionComponents
xsd/common/UBL-CommonExtensionComponents-2.3.xsdThe CommonExtensionComponents schema defines the extension scaffolding used in all UBL document types, providing metadata regarding the use of an extension embedded in a UBL document instance (see ).
ExtensionContentDatatype
xsd/common/UBL-ExtensionContentDataType-2.3.xsdThe ExtensionContentDataType schema specifies the actual structural constraints of the extension element containing the foreign non-UBL content. By default, the version of this schema provided in the UBL 2.3 distribution imports the UBL Signature
Extension module and namespace (see ). This both enables support by default for digital signatures and serves as an illustration of the way extensions are defined in UBL.This is the only schema intended to be modified by a user when it is necessary to support the constraints of additional user-defined extension structures. This is accomplished by adding other schema import directives, as is already done for the signature extension and that
extension’s use of XAdES. Without adding additional directives, the user’s constructs found under the extension point will not be validated. No changes are required to the complex type declaration for ExtensionContentType. The original declaration is considered the normative declaration but may be modified by users to accommodate restrictions they impose on the presence of extensions. To promote
interoperability, imposing such restrictions on the type declaration is not recommended.
Signature Extension SchemasUBL 2.3 schemas are supplied with a predefined standard extension that supports digital signatures; see and for further information regarding the UBL extension supporting
digital signatures such as XAdES.
CommonSignatureComponents
xsd/common/UBL-CommonSignatureComponents-2.3.xsdThe CommonSignatureComponents schema defines the scaffolding structures containing the IETF/W3C Digital Signature information XML elements related to either the entire document or particular signature business objects found within the document.
SignatureAggregateComponents
xsd/common/UBL-SignatureAggregateComponents-2.3.xsdThe SignatureAggregateComponents schema defines those Aggregate Business Information Entities (ABIEs) that are used for signature constructs not defined in the common library.
SignatureBasicComponents
xsd/common/UBL-SignatureBasicComponents-2.3.xsdThe SignatureBasicComponents schema defines those Basic Business Information Entities (BBIEs) that are used for signature constructs not defined in the common library.For a discussion of the terms Basic Business Information Entity and Aggregate Business Information Entity, see .
xmldsig-core-schema
xsd/common/UBL-xmldsig1-schema-2.3.xsdThis is a copy of the IETF/W3C Digital Signature core schema file, modified only to include a header and to import the renamed other digital signature schema fragments.
xmldsig-core-schema
xsd/common/UBL-xmldsig11-schema-2.3.xsdThis is a copy of the IETF/W3C Digital Signature core schema file, modified only to include a header.
xmldsig-core-schema
xsd/common/UBL-xmldsig-core-schema-2.3.xsdThis is a copy of the IETF/W3C Digital Signature core schema file, modified only to include a header and to remove the unnecessary PUBLIC and SYSTEM identifiers from the
DOCTYPE.
XAdES01903v132-201601
xsd/common/UBL-XAdES01903v132-201601-2.3.xsdThis is a copy of the XAdES v1.3.2 schema file, modified only to change the importing URI for the XML digital signature core schema file.The presence of this schema file does not oblige the use of XAdES. It is provided only as a convenience for those users who choose to include an XAdES extension inside of a digital signature.
XAdES01903v141-201601
xsd/common/UBL-XAdES01903v141-201601-2.3.xsdThis is a copy of the XAdES v1.4.1 schema file, modified only to change the importing URI for the XAdES v1.3.2 and the XML digital signature core schema files.The presence of this schema file does not oblige the use of XAdES. It is provided only as a convenience for those users who choose to include an XAdES extension inside of a digital signature.
Schema DependenciesThe following diagram details the dependencies among the schema modules making up a UBL 2.3 document schema.The UBL schemas define in ExtensionContentDataType the content of each extension to be a single element in any namespace. The schemas are delivered supporting the UBL standardized extension for digital signatures (namespaces with prefixes
sig:, sac: and sbc:, though the prefix values are not mandatory) by importation. For more information regarding the signature extension, see .As shown at the bottom and right in this diagram, a set of XSD schemas supporting a different user-customized extension can be engaged by replacing the delivered ExtensionContentDataType schema fragment with one also importing the required custom schema apex
fragment that defines the custom content (depicted using namespaces with example prefixes xxx:, xac: and xbc:).The namespaces shown in the shaded boxes (with prefixes qdt:, udt:, ccts-cct: and ccts:) exist for the management of the schema components only and have no utility in UBL XML document instances. Declaring unused
namespaces in an XML instance is superfluous and does not impact on conformance, but having them present may be confusing or misleading to the reader.The relationship of the UBL schemas to the UBL data model is illustrated in .Extension Methodology and ValidationExtension Methodology OverviewThere exist many established XML vocabularies expressing useful semantics for information exchange. The W3C digital signature vocabulary is but one example of such a vocabulary that has its own governance, life-cycle and publication schedule. It is futile to attempt to mimic all of an
established vocabulary’s constructs as new UBL constructs and keep up with changes made in their life cycle. Moreover, it is untenable to ask users to re-frame all of the content of an established vocabulary into any such new UBL constructs.Also, user communities may have the need to exchange information that is found neither in the UBL schemas nor in an established XML vocabulary. A colloquial XML vocabulary can be designed within which this information is expressed. Should the user community wish to promote the
inclusion of their additional semantics into the UBL specification, the UBL Maintenance Governance Procedures outlines how one would use the extension point and submit proposals for enhancements.The UBL extension scaffolding allows the inclusion of multiple extensions in any UBL instance, be they structured by established or colloquial XML vocabularies.Extension ExpressionEvery UBL ABIE is allowed to contain extension content using the element <ext:UBLExtensions> in the extension namespace
urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2 (there are no constraints on the namespace prefix, only the namespace URI). This schema-defined element shall be the first child element of
the ABIE element, appearing before every BIE child of the ABIE. It shall contain one or more <ext:UBLExtension> element children.Each <ext:UBLExtension> element contains the metadata and content of a single extension. All extension metadata is optional, and the extension content is mandatory. The extension content element contains as its only child the apex element, in a namespace other
than the UBL extension namespace, of an arbitrary XML structure.
UBL Extension Metadata And ContentElement nameCard.TypeDescriptioncbc:ID0..1IdentifierAn identifier for the Extension assigned by the creator of the extension.cbc:Name0..1NameAn identifier for the Extension assigned by the creator of the extension.ext:ExtensionAgencyID0..1IdentifierAn agency that maintains one or more Extensions.ext:ExtensionAgencyName0..1NameThe name of the agency that maintains the Extension.ext:ExtensionVersionID0..1IdentifierThe version of the Extension.ext:ExtensionAgencyURI0..1IdentifierA URI for the Agency that maintains the Extension.ext:ExtensionURI0..1IdentifierA URI for the Extension.ext:ExtensionReasonCode0..1CodeA code for reason the Extension is being included.ext:ExtensionReason0..1TextA description of the reason for the Extension.ext:ExtensionContent1ElementThe definition of the extension content.
An excerpt of the example instance xml/MyTransportationStatus.xml that includes a single extension without extension metadata is as follows:<TransportationStatus
xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2"
xmlns="urn:oasis:names:specification:ubl:schema:xsd:TransportationStatus-2">
<!--this document needs additional information not defined by the UBL TC-->
<ext:UBLExtensions>
<ext:UBLExtension>
<ext:ExtensionContent>
<mec:Additional xmlns:mec="urn:X-MyCompany:Extension"
xmlns:mac="urn:X-MyCompany:Aggregate"
xmlns:mbc="urn:X-MyCompany:Basic">
<mac:QualificationLevel>
<cbc:ID>L1</cbc:ID>
<cbc:Description>Level 1</cbc:Description>
<mbc:LevelPrerequisite>Level0</mbc:LevelPrerequisite>
</mac:QualificationLevel>
...
</mec:Additional>
</ext:ExtensionContent>
</ext:UBLExtension>
</ext:UBLExtensions>
<!--the remainder is stock UBL-->
<cbc:UBLVersionID>2.1</cbc:UBLVersionID>
<cbc:CustomizationID>urn:X-demo:TransportShipments</cbc:CustomizationID>
...
</TransportationStatus>Extension ValidationThe UBL Digital Signature extension described in is built into the UBL distribution and validates transparently. Users wishing to validate other extensions found in the instance simply revise the UBL-ExtensionContentDataType-2.3.xsd schema fragment. An <xsd:import> directive is added to incorporate the schema constraints of the apex of another extension to
be validated in the single pass of XSD validation. shows the replacement of the schema fragment with one in which user-defined extension modules with namespaces ext:, xxx:, xac:, and
xbc: augment the digital signature extension modules with namespaces ext:, sig:, sac:, sbc: and ds:.Due to limitations of W3C Schema validation semantics (this is not the case in RELAX NG , for example), the apex element of the extension in the instance being validated cannot be constrained solely to the apex element declared. W3C Schema’s lax
validation permits any element declared in any schema fragment to be the apex of an extension. Thus, an instance will pass when a known extension element not permitted by the user to be an apex element is in the place of an apex element. This is simply regarded by downstream processes as
an unknown extension and will likely be ignored.Notes For Extension CreatorsThe following points should be noted:Extension designers should follow the example by providing separate namespaces for apex element, aggregate constructs, and basic constructs if they wish the new items to be considered for inclusion in future UBL releases. This structures the new items for inclusion in the UBL
common library. See xml/MyTransportationStatus.xml for a document instance exemplifying the recommended treatment of namespaces in a colloquial XML vocabulary.Whenever possible, one should use existing UBL common library aggregate and basic constructs in extensions rather than inventing new items with the same semantics. However, a common library aggregate construct should only be used when the entire aggregate and all of its descendants
are applicable in the extension context without any changes. If any items need to be removed, then a new extension aggregate with a new local name should be used. If all the constructs in the common library aggregate are applicable but some items need to be added, then a new extension
aggregate with the same name should be created by adding the new constructs to a copy of the common library aggregate.The UBL Digital Signature extension described in has been modeled as an example to follow when designing and writing other custom extensions.Additional Document ConstraintsAdditional Document Constraints IntroductionIn addition to the UBL document constraints formally expressed by the schemas in , UBL mandates several other rules governing conforming UBL instances that cannot be expressed using W3C Schema. These additional UBL document rules, addressing XML
instance validation, character encoding, and empty elements, are specified below.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.See for the reference to an illustrative example of a script implementing checks of those of these tests that can be tested with Schematron .Additional document constraints do not apply to the arbitrary content of extensions expressed in a UBL document as described in .ValidationThe 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 actions are reflective of the purpose, intent, and
information content agreed to by both trading partners. Schemas provide the base mechanism for ensuring that instance documents do in fact support these requirements.
[IND1] All UBL instance documents SHALL validate to a corresponding schema.
UBL recommends a two-phase approach for validation of rules related to specific data content (such as to check of code list values). See for a description of this approach.Character EncodingXML supports a wide variety of character encodings. Processors SHALL 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 always to identify the character encoding being
employed.
[IND2] All UBL instance documents SHALL 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"?>
Empty ElementsUse 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—that the trading partner does not provide that data. In information exchange environments, different
trading partners may allow, require, or ban empty elements. UBL takes the position that empty elements do not provide the level of assurance necessary for business information exchanges and therefore are not to be used.
[IND5] UBL-conforming instance documents SHALL NOT contain an element devoid of content or containing null values.
An important implication of this rule is that every container UBL element shall contain at least one of its possible constituents even if all of its possible constituents are declared to be optional.To ensure that no attempt is made to circumvent rule IND5, UBL also prohibits attempting to convey meaning by omitting an element (i.e., an optional element may be omitted, but that omission cannot carry a specific meaning upon which an action is conditioned).
[IND6] The absence of a construct or data in a UBL instance document SHALL NOT carry meaning.
These constraints are consistent with the principle described in that the recipient is to receive all pertinent information manifest in the UBL document. Relying on the absence of a construct would require the recipient to know of the sender’s
intention with that construct being absent. For reliable communication this cannot be assumed.Natural Language Text ElementsNatural language text elements such as Note and Description appear throughout the UBL document model. They are of the same unstructured Text type as character data fields that are not intended for natural language prose, such as Address Line.All natural language text elements in UBL are repeatable within some container; for example, all Note elements are repeatable as adjacent siblings under a common parent. Despite appearances, these multiple text elements are not intended for the representation of separate paragraphs or
divisions within a single parent text; rather, each Note element (for example) contains the entire text of the note in one of the languages in which the note is provided. In other words, UBL allows 0..n Note or Description elements in order to present the same note or description in 0..n
languages, not to reflect structures such as paragraphs internal to a text in a single language. Since UBL text elements are intended for unstructured sequences of character data, more complex texts should be located in external documents and associated with the UBL message using document
references.UBL enforces this restriction with the following two rules:
[IND7] Where two or more sibling “Text. Type” elements of the same name exist in a document, no two can have the same “languageID” attribute value.
[IND8] Where two or more sibling “Text. Type” elements of the same name exist in a document, no two can omit the “languageID” attribute.
Empty AttributesAttributes in UBL are used exclusively for supplemental components of the data types of basic business information entities. An empty attribute conveys no information but may be the source of confusion for users.
[IND9] UBL-conforming instance documents SHALL NOT contain an attribute devoid of content or containing null values.
Semantic definitionsThe UBL Technical Committee has ascribed a definition to each of the business objects in UBL. These definitions provide important semantic context for the interpretation of the content. These definitions are found in the normative XSD Schemas. They are also transcribed into the XML model
ODS spreadsheet, XLS spreadsheet and the HTML document reports.To facilitate interoperability, implementations SHOULD follow these definitions to ensure the successful interchange of the business information.UBL Digital SignaturesUBL Digital Signatures IntroductionThis section provides the context for the use of UBL digital signatures and then defines profiles for digital signatures in UBL and a specific UBL extension that implements one specific kind of digital signature.There are certain circumstances in which it becomes necessary to digitally sign UBL documents. This can be the case when creating tenders or invoices. For example, in some countries digitally signing electronic invoices is required by law.UBL (without extension) has a data structure (known as Signature) for defining digital signatures and a number of elements for using such signatures in a document. To integrate UBL into the larger standards environment, this section associates the IETF/W3C XML Digital Signature
specification (a general framework for digitally signing XML documents) with the signature elements provided by UBL. These include specific provisions to use extensions supporting Digital Signatures (ETSI EN 319 132-1), when UBL
digitally-signed documents are necessary to satisfy additional legal and/or technical requirements. One important benefit of XAdES is that it allows the addition of information and timestamps that extend the validity of a signature beyond the expiration or revocation of the electronic certificates involved in signature verification or the obsolescence of the underlying cryptographic
keys and algorithms.XAdES extends XMLDSig also aiming to support advanced and qualified electronic signatures or seals as specified in the European regulation and other similar legal frameworks.Use of XAdES and the concept of Advanced Electronic Signature or Seal is not limited to Europe, as it is being adopted by many countries outside the EU, and, is the basis for the international standard ISO 14533-2:2012 .Any aspect beyond the specification of the use of digital signatures in UBL documents is not in scope of UBL. Therefore, procedures for creation and validation of digital signatures, management of signature keys, assessment of the suitability and reliability of cryptographic keys and
algorithms are out of UBL scope.The two digital signature profiles provided in UBL represent two approaches to signing UBL documents: enveloped and detached. Each of these approaches can use either XMLDSig alone or may also include XAdES features.XML Digital SignaturesXML Digital Signatures OverviewDigital signatures, when appropriate rules and functions are used, can support the following properties for a document:Integrity: the document has not been modified since it was signed.Authenticity: the identity of the party creating the signature that applies to the document is certified.Non-repudiation (content commitment): the document signer cannot deny its involvement in creating and/or approving the document (depending on the context and signer/seal creator role).Anteriority: associating a time-stamp to the signature, a proof that the signature (and therefore the signed document) existed before a certain point in time.XMLDSig defines XML Signature processing rules and syntax to provide integrity and message authentication and/or signer authentication services for data of any type, whether located within the XML that includes the signature or elsewhere. specifies a standard
format for time-stamping that can be used with XMLDSig and XAdES.That XAdES is completely embedded in XMLDSig ensures that the UBL profiles for XMLDSig are sufficient to support XAdES. These profiles can also support other existing or future extensions of XMLDSig that are completely embedded in XMLDSig syntax. These other possible UBL digital
signature profiles may or may not use the XAdES extensions to XMLDSig.Compliance of implementations of electronic signatures and seals, based on digital signature technologies, to a specific context may depend on local regulations in place and specific provisions set by the authority issuing the certificates supporting the electronic signature or seal.
XAdES is designed to help in fulfilling legal requirements, but any aspect beyond specification of digital signature formats are out of scope of UBL. Users are advised to examine the specific policies of the authority that issued the certificate and regulations applicable to their specific
context of use.The UBL digital signature implementation provides the following properties:A signed UBL document will be processed correctly by compliant UBL software (including UBL software that is not XMLDSig/XAdES aware) and by compliant XMLDSig/XAdES validation software (including software that is not UBL aware).No change is required for UBL or XMLDSig/XAdES syntaxes.The extension mechanism specified here supports any XMLDSig/XAdES form, leaving to the implementer the choice of the most appropriate one according to the specific legal framework or application context; support for signature profiles specified in XAdES is, however, recommended to
improve interoperability (see ).XML Signature TypesAn XML signature is a XMLDSig <ds:Signature> element and it may be (non-exclusively) described (per XMLDSig and XAdES) as detached, enveloping, or enveloped.Detached. The signature applies to content that is external to the <ds:Signature> element and can be identified via a URI or transform. Consequently, the signature is “detached” from the content it signs. This definition typically
applies to separate data objects, but it also includes the case where the <ds:Signature> and signed data object are sibling elements residing within the same XML document. Enveloping. The signature applies to content found within a <ds:Object> element of the signature itself. The <ds:Object> (or its content) is identified via a <ds:Reference> (using a URI
fragment identifier or transform).Enveloped. The signature applies to the XML content that contains <ds:Signature> as an element. Implementations of enveloped signature(s) need to take care not to include the signature in the calculation of the signature
value.UBL defines two profiles for signing a UBL document: enveloped and detached.XAdESXAdES builds on XMLDSig by the incorporation of signed and unsigned qualifying properties (for which XAdES provides XML Schema definitions) that address some additional requirement, such as the long term validity of digital signatures, in a number of use cases.XAdES clause 6 defines four levels of baseline signatures, meant to provide the basic features necessary for a wide range of use cases and applicable to a wide range of communities aiming to achieve a high degree of digital signature interoperability.The XAdES baseline signature levels address incremental requirements to maintain the validity of the signatures over the long term, and to encompass their life cycle. This is done in a way that a certain level always addresses all of the requirements addressed at levels that are below
it, each level requiring the precedence of certain XAdES qualifying properties.More specifically:XAdES-B-B level provides requirements for the incorporation of signed and unsigned qualifying properties at signature generation;XAdES-B-T level provides requirements for the generation and inclusion, for an existing signature, of a trusted token proving that the signature (and, consequently, the signed document) existed at a certain date and time;XAdES-B-LT level provides requirements for the incorporation of all the material required for validating the signature, aiming to tackle the long-term availability of the validation material;XAdES-B-LTA level provides requirements for the incorporation of electronic time-stamps that allow validation of the signature long after its generation, aiming to tackle the long-term availability and integrity of the validation material.A conforming XAdES signature generation and verification implementation SHOULD support at least XAdES-B-B.Requirements for Digital Signatures in UBLThe main requirements to be addressed when choosing a specific signature profile can be divided into the following categories:Legal requirements. In some countries a digital signature is required on electronic invoices. It can also be compulsory in electronic procurement, especially in a cross-border context, to have a digital signature on the key document exchanged, e.g., a
response to a request for tender. Another important legal requirement is long-term document preservation, for a storage period that in general is specific to each country and can span many years.Business requirements. A digital signature can reduce the risks associated with a business transaction (e.g., content commitment of a commercial order, proof-of-origin and integrity of an invoice), and its use can be provided for in the interchange
agreement between parties. The choice of the signature format and its application is a key factor in achieving interoperability.Process requirements.The presence of the digital signature SHOULD NOT add any specific constraints on UBL document content processing. If the signed document remains a valid UBL document, the signature can be verified at any stage of the process: it
SHOULD be possible to validate a signed document at any time “as is” by UBL and XAdES verifiers.Archiving of UBL documents also can be an important issue to consider, as document preservation has specific requirements. See, for example, and .Profiles for UBL Digital SignaturesSignature Profile IntroductionUBL specifies two profiles for use in digitally signing UBL documents:Enveloped Signature Profile: One or more signatures are added to the UBL document inside a single identifiable and dedicated UBL extension. Other UBL extensions MAY be present provided they have different identifiers so that they can be distinguished
from the one that contains the document signature(s). This profile is defined such that UBL content processing can be separated from electronic signature processing, both on the issuing side and on the receiving side, and specific applications can be devoted to each function. The UBL
application does not need to be electronic signature aware, and the electronic signature application does not need to be involved in the management of the UBL syntax, allowing to reuse existing applications. A signature business object in the UBL document may reference a particular
electronic signature in the extension.Detached Signature Profile: The signature is outside the UBL document content in another information resource. Some mechanism has to be defined by the implementer to send or make available the signature to the recipient. This method of signing may be
identified in the UBL document.The two profiles for adding one or more digital signatures to a UBL document are based on XMLDSig. These profiles and their associated methods decouple the UBL document to be signed from any specificity in the digital signature standard adopted within XMLDSig. The XAdES standard is an
example of a standard use of XMLDSig. UBL users may use any standard built on XMLDSig or simply use XMLDSig as it stands without any extensions.Managing XML signatures inside of a UBL document is described in . Managing XML signatures outside of a UBL document is described in .The main advantage of the enveloped profile is that the signature(s) are embedded in the UBL document (which syntactically remains a valid UBL document). This means that the transport of the signatures is guaranteed by the UBL document delivery infrastructure, but the generation of the
UBL extension that contains the signature needs to be implemented.The detached signature profile has a simpler preparation phase and signature procedure, but specific means to send or make available the signature(s) to the recipient have to be implemented. A standard container like can be used to associate the UBL document
with detached electronic signature(s) that apply to it. The simple container (ASiC-S) can be created later than signature generation in such a way that it contains a UBL document and one or more detached signatures that apply to it.XMLDSig and XAdES signatures can be created and verified using signature signing and verifying protocol.The references to and standards have been updated from UBL 2.2 to UBL 2.3. Refer to for the most significant differences between XAdES and ASiC ENs and the formerly referenced TSsEnveloped XML Signatures in UBL DocumentsEnveloped Signature IntroductionThe enveloped signature profile supports one or more signatures to be applied to a UBL document and embedded in the UBL document itself inside a dedicated extension. This profile can be used with all UBL documents under their respective <ext:UBLExtensions>
extension points. UBL syntax implementing the enveloped profile, together with examples of its use, are provided in .The user MAY choose to indicate in a <cac:Signature> element that the signature details are found in the signature extension. The URI urn:oasis:names:specification:ubl:dsig:enveloped is reserved as a value for
<cbc:SignatureMethod> to signal this. The URI urn:oasis:names:specification:ubl:dsig:enveloped:xades MAY be used as a value for <cbc:SignatureMethod> to signal when XAdES is
in use. Additionally, the user MAY include a <cbc:ID> child of <cac:Signature> for referencing purposes from the enveloped signature. The identifier used can be any value, but for convenience the URI of a URN beginning with
urn:oasis:names:specification:ubl:signature:, ending with the local name of the parent of the signature business object, and optionally followed with a colon and number, as in the
urn:oasis:names:specification:ubl:signature:IssuerEndorsement example, is reserved for this purpose for UBL users. As with all identifiers, the identifier SHOULD exist and SHOULD be unique across all identifier values. An
example is as follows: <cac:Signature>
<cbc:ID>urn:oasis:names:specification:ubl:signature:Invoice</cbc:ID>
<cbc:SignatureMethod
>urn:oasis:names:specification:ubl:dsig:enveloped</cbc:SignatureMethod>
<cac:SignatoryParty>
<cac:PartyIdentification>
<cbc:ID>MyParty</cbc:ID>
</cac:PartyIdentification>
</cac:SignatoryParty>
</cac:Signature>
See for a sample UBL Invoice that references an enveloped digital signature.Enveloped Signature Syntax and TransformationTwo different syntaxes are used in UBL enveloped signatures: UBL-specified scaffolding under the extension point used to contain the signature information and IETF/W3C-specified information for each digital signature. A transformation element is also present to prevent a signature from being invalidated by the subsequent addition of another signature. These features are described in detail in and . Detached XML Signatures for UBL DocumentsDetached Signature IntroductionThis profile supports the application to a UBL document of one or more signatures located outside of the document itself in some other resource.It is important to note that externally signing a UBL document with a detached signature imposes no requirements on the UBL document itself. Such a signature, in any kind of signature container, can digitally sign the content of a UBL document regardless of whether this is reflected
in the document.Before a detached signature conforming IETF/W3C XML digital signature is generated, the user MAY choose to signal in their UBL document that it is so signed. The URI value urn:oasis:names:specification:ubl:dsig:detached is
reserved to indicate that the detached signature is an IETF/W3C XML digital signature. The URI urn:oasis:names:specification:ubl:dsig:detached:xades MAY be used as a value to signal when XAdES is in use. The value is
used in the <cbc:SignatureMethod> child of <cac:Signature>.If the location of the digital signature is known, the user MAY choose to indicate the location in a <cbc:URI> child element of a <cac:ExternalReference> child element of a <cac:DigitalSignatureAttachment>
element.Following is a complete example of a <cac:Signature> business object that might be found in a UBL instance: <cac:Signature>
<cbc:ID>urn:oasis:names:specification:ubl:signature:Invoice</cbc:ID>
<cbc:SignatureMethod
>urn:oasis:names:specification:ubl:dsig:detached</cbc:SignatureMethod>
<cac:SignatoryParty>
<cac:PartyIdentification>
<cbc:ID>MyParty</cbc:ID>
</cac:PartyIdentification>
</cac:SignatoryParty>
<cac:DigitalSignatureAttachment>
<cac:ExternalReference>
<cbc:URI>sigFile.xml</cbc:URI>
</cac:ExternalReference>
</cac:DigitalSignatureAttachment>
</cac:Signature>
A document with multiple detached signatures is simply a document that is co-signed. By the appropriate use of the <ds:Reference> element pointing to the UBL document from a detached signature file, all such signatures are signing the content of the document
but not each other. A countersigning document signature, on the other hand, signs signatures already created for and external to or present in the document at the time it is countersigned. A digital countersignature
<ds:Signature>, which may be located internal to the UBL document or in an external file, includes additional <ds:Reference> elements, each pointing either to the <ds:Signature> element or
<ds:SignatureValue> element child of the signature being signed. In the first case, where the signature is detached, the <ds:Reference> element points to the external file for that signature; in the second case, where the signature is
enveloped, the <ds:Reference> element points to the Id= value of either the <ds:Signature> or <ds:SignatureValue> element for that signature.XAdES supports an alternative countersignature approach where a <ds:Signature> element pointing to the countersigned signature’s <ds:SignatureValue> is embedded in the <ds:Object> of the countersigning
signature. The inclusion of an alternative method in this specification does not prohibit this approach.See for a sample UBL Invoice that references a detached digital signature.Digital Signature Transformation (Detached Signatures)The content to be signed is addressed in the URI= attribute of <ds:Reference>. For example:<ds:Reference URI="myInvoice.xml">An option when using detached digital signatures is to express in XPath that address that qualifies all nodes in the referenced content to be included in the calculation of the digital signature hash. For a signature calculated for a document to remain valid, none of the signed
information can change, nor can any information be added or removed from that portion of the document included in the hash calculation.Consider the need to create a detached signature for a UBL file in which there already exists an enveloped signature. The following transformation element in a digital signature flexibly prevents the signature being invalidated by the subsequent addition of any signatures using the
enveloped profile within the extension of the document being signed: <Transform
Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
<XPath xmlns:sig=
"urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2">
count(ancestor-or-self::sig:UBLDocumentSignatures)=0
</XPath>
</Transform>
A non-final transformation algorithm used in the detached signature signs all content outside of any enveloped signatures in the UBL document. When the UBL document does not already have an enveloped signature, one cannot be added without invalidating the detached signature. In
effect, the entire document has been signed and cannot change, but the addition of the scaffolding for a signature constitutes a change. However, when the UBL document already has an enveloped signature, other signatures can be added without invalidating the detached signature, because
the scaffolding doesn’t change when other signatures are added within the existing scaffolding; the non-final transformation algorithm does not include the signatures found in the existing scaffolding. When there is no preexisting enveloped signature, the entire document SHALL be signed
in the detached signature.To sign only a portion of a UBL document, an appropriate address SHOULD be used because UBL business object elements do not have attributes of type ID. This requires XPointer awareness on the part of the digital signature tools being used.UBL Extension for Enveloped XML Digital SignaturesUBL Extension for Enveloped XML Digital Signatures IntroductionUBL extensions enable user-defined additions to the standard schemas. The UBL schemas in this distribution are provided with a predefined standard extension for enveloped signatures that supports IETF/W3C Digital Signature profiles. These also include advanced IETF/W3C XML digital
signatures conforming to XAdES.This extension also serves as a case study for the creation of user-defined UBL extensions; see . Further information on the UBL extension mechanism can be found in .UBL’s implementation of XML digital signatures puts all the signatures relating to a document in a single extension, which is engaged in validation by the UBL-ExtensionContentDataType-2.3.xsd schema module.Digital Signature NamespacesAs is true for the UBL document schemas and common library, the UBL digital signature extension is modeled with three namespaces: one for the apex element (a parallel to the document schema), one for new aggregate constructs (a parallel to the common aggregate schema), and one for new
basic constructs (a parallel to the common basic schema). See .The urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2 namespace is used for the apex element, the
urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2 namespace is used for new aggregate elements, and the
urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2 namespace is used for new basic elements. The IETF/W3C digital signature XMLDSig standard namespace
http://www.w3.org/2000/09/xmldsig# is also used in this extension. These namespaces are bound to the sig:, sac:, sbc: and ds: prefixes respectively, but any prefix or even the default namespace
can be used for any of these in an XML instance.Schema fragments for the two XAdES namespaces http://uri.etsi.org/01903/v1.3.2# and http://uri.etsi.org/01903/v1.4.1# are included in UBL for the convenience of users of the XAdES specification. There is no obligation to use the XAdES extension in
the IETF/W3C digital signature. The appropriate XSD fragments are imported into the overall schema structure from the extension content data type schema fragment. Changing UBL to support a future version of the XAdES schema fragments involves only changing the import statements in the
extension content data type schema fragment. The table below lists the namespaces used for UBL digital signatures. The prefixes on the left are only documentary conventions; their choice is not constrained by XML.
Digital Signature IdentificationThis UBL extension is distinguished from other extensions and identified using the URI urn:oasis:names:specification:ubl:dsig:enveloped in the <ext:ExtensionURI> element.In addition to Enveloped signatures, also provides methods to be used with Detached signatures (i.e., digital signatures that stand outside the document being signed). Detached signatures constitute an independent
technique without associated UBL artefacts, but an example instance showing detached signatures is included in this package; see .Digital Signature ValidationThe UBL-ExtensionContentDataType-2.3.xsd module links UBL validation to all needed extensions by importing the apex schema fragment of each extension vocabulary. The distribution version of this module supports IETF/W3C XML digital signatures by declaring that the
<ext:ExtensionContent> element can contain elements from the UBL Digital Signature extension namespace. Accordingly, a single <sig:UBLDocumentSignatures> element is used as the apex of all the document’s electronic signatures.The <ext:ExtensionContent> element alternatively allows any other namespace apex element in order to allow other foreign extensions in the same document.Digital Signature StructureDigital Signature Structure IntroductionThe signature extension structure exists to contain one or more IETF/W3C standard digital signature constructs. The UBL scaffolding for this extension starts with a <ext:UBLExtension> element with two children: <ext:ExtensionURI> (for
extension distinction and identification) and <ext:ExtensionContent> (for containing the extension information, in this case the actual signatures and supporting information).The signature extension Business Information Entities for UBL are contained in a single spreadsheet, provided here in two different formats (see for details regarding the spreadsheet columns):
One or more signature extensions in a given document may each contain one or more sets of signature information. The following instructions guide the proper use of this particular extension.Digital Signature Extension MetadataThe standard scaffolding for a given signature extension begins with the <ext:UBLExtension> element. The extension’s role as a UBL signature extension is indicated with a child <ext:ExtensionURI> element with the
urn:oasis:names:specification:ubl:dsig:enveloped value. The urn:oasis:names:specification:ubl:dsig:enveloped:xades value MAY be used to indicate the use of
XAdES in the extension. Other extension metadata elements defined in UBL are allowed to be included for the convenience of users without changing the meaning or use of the extension.<ext:UBLExtension>
<ext:ExtensionURI
>urn:oasis:names:specification:ubl:dsig:enveloped</ext:ExtensionURI>
<ext:ExtensionContent>
The Extension IdentifierAll uses of the optional <cbc:ID> metadata SHOULD be unique so that each extension can be uniquely identified. The identifier used can be any value. URNs beginning with
urn:oasis:names:specification:ubl:extension: and ending with a number value are reserved for this purpose for the convenience of UBL users. The value
urn:oasis:names:specification:ubl:extension:3 is an example of such a URN. As with all identifiers, each SHOULD be unique across all identifier values in a given UBL instance.Digital Signature ApexThe mandatory <ext:ExtensionContent> element contains the UBL signature scaffolding. The apex element of the UBL signature information is <sig:UBLDocumentSignatures>. Digital Signature InformationEach <sac:SignatureInformation> aggregate is used to contain the information related to a single IETF/W3C digital signature. Every signature added to the extension is isolated under a separate <sac:SignatureInformation> aggregate element
containing the signature and its supporting information. As many of these aggregates can be in the extension as is needed, each one containing the information for a single digital extension. <ext:ExtensionContent>
<sig:UBLDocumentSignatures>
<sac:SignatureInformation>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
Note that three namespaces are used for signature information, in parallel with UBL’s use of a document namespace, an aggregate namespace, and a basic namespace. The apex element is in the
urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2 namespace, a parallel to a UBL document namespace. Signature-related aggregate entities are in the
urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2 namespace. Signature-related basic entities are in the
urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2 namespace. Accordingly, there are three W3C Schema fragments in the distribution accommodating these three namespaces.Digital Signature IdentifierAn aggregate MAY be identified for referencing purposes using the common library <cbc:ID> element. Such an identifier may be useful in workflow scenarios where a particular signature needs to be identified external to the document, but its use is not obligatory.
The identifier used can be any value. URNs beginning with urn:oasis:names:specification:ubl:signature: and ending with a number value are reserved for this purpose for the convenience of UBL users. The value
urn:oasis:names:specification:ubl:signature:3 is an example of such a URN. As with all identifiers, each SHOULD be unique across all identifier values in a given UBL instance.Digital Signature ReferenceAn aggregate MAY make reference to an existing <cac:Signature> business object in the same UBL document, but this is not obligatory. When needed, the <sbc:ReferencedSignatureID> basic element is used to point to the
<cbc:ID> identifier value of the referenced <cac:Signature>. The identifier used can be any value. URNs beginning with urn:oasis:names:specification:ubl:signature: and ending with
the local name of the parent of the signature business object, optionally followed with a colon and number, are reserved for this purpose for the convenience of UBL users. An example of such a URN is
urn:oasis:names:specification:ubl:signature:IssuerEndorsement. As with all identifier references, the referenced identifier SHOULD exist and SHOULD be unique across all such identifier values in a given UBL instance.See for rules regarding common library UBL signature elements in the unextended portion of UBL documents that are being referenced by this element, together with an example of their use.Digital Signature ContentA single <ds:Signature> element is a child of the aggregate. It MAY be absent from the document, thus supporting workflow scenarios where the element is added by a subsequent process after the UBL scaffolding is added by an earlier process. However, the
signature information is semantically incomplete without the IETF/W3C-defined element. To support signatures countersigning this signature, this element shall use the Id= attribute with a value unique among other attributes of schema type ID in the
instance.Example Digital Signature SkeletonThe following is a skeleton example of a single signature:<ext:ExtensionContent>
<sig:UBLDocumentSignatures
xmlns:sig=
"urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2"
xmlns:sac=
"urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2"
xmlns:sbc=
"urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2">
<sac:SignatureInformation>
<cbc:ID>urn:oasis:names:specification:ubl:signature:1</cbc:ID>
<sbc:ReferencedSignatureID
>urn:oasis:names:specification:ubl:signature:Invoice
</sbc:ReferencedSignatureID>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Id=...>
<ds:SignedInfo>
...
<ds:Reference URI=...>
...
<ds:Transform>
...
</ds:Transform>
...
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
...
</ds:SignatureValue>
<ds:KeyInfo>
...
</ds:KeyInfo>
<ds:Object>
...
</ds:Object>
</ds:Signature>
</sac:SignatureInformation>
</sig:UBLDocumentSignatures>
</ext:ExtensionContent>
The XAdES specification contains all qualifying XAdES information in a single <ds:Object> element located as shown above. The UBL distribution includes and engages XAdES schema fragments with versions 1.3.2 and 1.4.1 for the convenience of users who choose to
use these versions of XAdES. Users of the UBL signature extension are not obliged to use any XAdES extensions.TransformationThe content to be signed is indicated in the URI= attribute of <ds:Reference>. Using the empty string indicates that the entire document (i.e. the enveloping UBL instance) is what is being signed:<ds:Reference URI="">
A requirement when using digital signatures is to express in XPath that address that qualifies all nodes in the referenced content to be included in the calculation of the digital signature hash. For a signature added to a document to remain valid, none of the information can change,
nor can any information be added or removed from that portion of the document included in the hash calculation.One of two such transformation expressions SHOULD be used in the UBL signature extension; users SHOULD choose the appropriate one to meet the objectives of adding the signature to the document. Adding non-signature information to the UBL document will invalidate all signatures already
in the extension. The choice to make is whether to support additional signatures after adding the signature with the transformation expression.The following transformation element in a digital signature flexibly prevents the signature from being invalidated by the subsequent addition of other signatures within the extension: <Transform
Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
<XPath xmlns:sig=
"urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2">
count(ancestor-or-self::sig:UBLDocumentSignatures |
here()/ancestor::sig:UBLDocumentSignatures[1]) >
count(ancestor-or-self::sig:UBLDocumentSignatures)
</XPath>
</Transform>
The following transformation element in a digital signature is inflexible and thus would be considered a “final” signature to be added to the document. Such a signature will be invalidated by the subsequent addition of other signatures to the document: <Transform
Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116">
<XPath xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
count(ancestor-or-self::ds:Signature |
here()/ancestor::ds:Signature[1]) >
count(ancestor-or-self::ds:Signature)
</XPath>
</Transform>
Multiple separate items of extra-document content (e.g., attachments) or embedded W3C signature content can be included in the same signature by using sibling <ds:Reference> elements with other URI= attribute values. For example, to countersign
another signature in the same UBL document, make a local reference to that signature’s unique identifier, as in:<ds:Reference URI="#{Id attribute of ds:Signature}">To digitally sign only a portion of standard UBL content and not the entire document of UBL content, one uses an appropriate XPointer address for URI=. This requires XPointer awareness on the part of the digital signature tools being used.Digital Signature ExamplesThe xml/UBL-Invoice-2.0-Enveloped.xml sample document illustrates the embedding of three extensions in a single document, one of which is a bona fide verifiable enveloped signature extension. A <cac:Signature> element makes reference to the embedded signature.The xml/UBL-Invoice-2.0-Detached.xml sample document illustrates the placement of a detached digital signature outside of the UBL file. A <cac:Signature> element makes reference to the external signature.The xml/UBL-Invoice-2.0-Detached-Signature.xml instance is an example of a bona fide verifiable digital signature of the xml/UBL-Invoice-2.0-Detached.xml instance.ConformanceDocument and Schema ConformanceThe UBL 2.3 XSD schemas are the only normative representations of the UBL 2.3 document types and library components for the purposes of XML document validation and conformance.An XML document is considered conforming to UBL 2.3 when all are true that:there are no violations of the XSD validation schema constraints when using one of the normative document schemas listed in , there are no violations of the XSD or other constraints on extension scaffolding and metadata described in , andthere are no content violations of the constraints listed in .Additional explanatory information regarding conformance as applied to UBL documents and schemas and their subsets, and the distinction between UBL conformance and UBL compatibility, is described in detail in the UBL 2 Guidelines for Customization. That document has no bearing or impact on the clauses of this subsection.Digital Signature Extension ConformanceBasic Digital Signature Extension ConformanceClaiming syntax conformance to the enveloped signature profile of UBL 2.3 requires the following:a schema-valid UBL extension in which the UBL Signature apex element is the apex of the extension;the <ext:Extension> element is present in the UBL extension and has either urn:oasis:names:specification:ubl:dsig:enveloped or
urn:oasis:names:specification:ubl:dsig:enveloped:xades as its value;the value in all uses of <sbc:ReferencedSignatureID>, when present, correlates to a corresponding <cbc:ID> element of a <cac:Signature> element in the same instance; andthe <cbc:SignatureMethod> element, when present, of signature business objects whose signatures are in the UBL extension has either urn:oasis:names:specification:ubl:dsig:enveloped or
urn:oasis:names:specification:ubl:dsig:enveloped:xades as its value.Claiming processing conformance to the enveloped profile of UBL 2.3 requires the conforming processing of all contained <ds:Signature> elements per .Claiming syntax conformance to the detached profile of this specification requires that the <cbc:SignatureMethod> element, when present, of signature business objects whose signatures are outside of the UBL document has either
urn:oasis:names:specification:ubl:dsig:detached or urn:oasis:names:specification:ubl:dsig:detached:xades as its value.XAdES Digital Signature Extension ConformanceWhen conformance to XAdES in a UBL extension is chosen, UBL 2.3 requires the valid expression and processing of the XAdES syntax found in an XMLDSig per .Release NotesAvailabilityOnline and downloadable versions of the latest OASIS release of this package are available from:Online and downloadable versions of the latest ISO/IEC release of this package are available from:Package StructureThe UBL 2.3 specification is published as a zip archive in the release directory. Unzipping this archive creates a directory named os-UBL-2.3 containing a master DocBook XML file (UBL-2.3.xml), a generated hypertext version of this file (UBL-2.3.html), a generated PDF version of
this file (UBL-2.3.pdf), and a number of subdirectories. The files in these subdirectories, linked to from UBL-2.3.xml, UBL-2.3.html, and UBL-2.3.pdf, contain the various normative and informational pieces of the 2.3 release. A description of each subdirectory is given below. Note that while
the UBL-2.3.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
cl/
Code list specification files; see
cva/
Artefacts expressing data type qualifications; see in and in
db/
DocBook stylesheets for viewing UBL-2.3.xml
mod/
Spreadsheets and HTML renderings of the UBL data models; see
val/
Test harness for demonstrating UBL 2.3 two-phase validation; see
xml/
Sample UBL 2.3 instances; see
xsd/
XSD schemas; see
xsdrt/
“Runtime” XSD schemas; see
SupportUBL is a volunteer project of the international business community. Inquiries regarding UBL may be posted to the unmoderated public UBL-Dev list, archives for which are located at:
https://lists.oasis-open.org/archives/ubl-dev/
Subscriptions to UBL-Dev can be made through the OASIS list manager at:
https://www.oasis-open.org/mlmanage/index.php
OASIS provides an official community gathering place and information resource for UBL at:
http://ubl.xml.org/
The Wikipedia article for UBL has numerous related links:
UBL CustomizationUBL provides a vocabulary that, for many user communities, can be used “as is”. However, it is recognized that some user communities need to address use cases whose requirements are not met by the UBL off-the-shelf solution. A separate OASIS Committee Specification known as
the UBL 2 Guidelines for Customization has been published to aid such users in developing custom solutions based on UBL.The goal of UBL customization is to maintain a common understanding of the meaning of information being exchanged between specific implementations. The factors governing when to customize may be business-driven, technically driven, or both. The decision should be based on real-world
needs balanced against perceived economic benefits.Upgrading from UBL 2.0, UBL 2.1, or UBL 2.2 to UBL 2.3For current UBL implementers, the most important thing to know about UBL 2.3 is that it is completely backward-compatible with earlier versions of UBL 2. In other words, any document that validates against a UBL 2 schema released before UBL 2.3 will validate against the UBL 2.3 version
of that schema.Nonetheless, it would be unwise to simply overlay this UBL 2.3 release onto an existing installation, and the possible differences among existing installations are too large to allow a specific set of instructions to be provided for making the transition.The brief history of UBL document types in the next section puts the new capabilities into context and may help users of existing UBL implementations decide whether to upgrade to 2.3.New 2.3 users, on the other hand, can simply install 2.3 and rest assured that their software will interoperate with UBL documents generated by existing conforming UBL 2.0 installations. For more on the concept of conformance, see and .Known errors in UBL 2.3During deployment the presence of errors in the UBL normative components comes to the attention of the UBL Technical Committee. Some of these cannot be repaired without breaking backwards compatibility to previous versions of UBL. Accordingly, they are obliged to remain in UBL untouched
to avoid ambiguity and to avoid problems with backwards compatibility.The list of known errors that are not being changed is as follows:the spelling of the BBIE named PartecipationPercent in the ABIE named ShareholderParty is incorrectthe spelling of the BBIE named FirstShipmentAvailibilityDate in the ABIE named PromotionalEvent is incorrectthe spelling of the BBIE named OccurenceLocation in the ABIE named Event is incorrectat this time there are no ASBIEs associating the common library ABIE with the DEN “Performance Data Line. Details”the cardinality of the BBIE named ElectronicPaymentUsageIndicator in the ABIE named PostAwardProcess is incorrectly specified as “0..n” instead of “0..1”Revision HistoryThe Business and Regulatory Impact of UBL Major and Minor RevisionsTo protect UBL stakeholders and users, a very rigid and consistent interpretation of major and minor revisions has been chosen for the evolution of the UBL data model and the validation artefacts. This impacts the way one uses UBL and plans for the future use of UBL from both business
and regulatory perspectives.Since its first release as an OASIS Standard in 2004, UBL has experienced one major and, now, three minor version upgrades. The impact on users is intended to be felt only with a major UBL revision. Minor UBL revisions are engineered not to have an impact on an existing user of
UBL.A major revision is considered only when the UBL committee has assessed that the changes needed to meet stakeholder requirements justify changes in the way business objects and documents are expressed. There has been only one major revision, that being from UBL 1.0 to UBL 2.0, and this
was made to accommodate requirements described in .UBL documents are structured instances of arranged information. A given document shall not violate sets of abstract document constraints that govern its content, chosen by the UBL committee and expressed in the UBL data model. The abstract model is reified in concrete form as sets of
constraint expressions. These constraint expressions take two forms: mandatory document schemas in XSD and optional code list associations in CVA. When UBL is published, these concrete constraint expressions are made available in a form computers use to validate that an XML document is, in
fact, a properly formed and valued UBL document. The computer can then act on the values found inside of the UBL document in order to satisfy business objectives.Accordingly, after the release of UBL 1.0, users created UBL 1.0 documents that conformed to the UBL 1.0 document constraints expressed in the UBL 1.0 document model.The impact of the major revision from UBL 1.0 to UBL 2.0 is that UBL 1.0 documents violate the constraints of the UBL 2.0 document model. A system designed for UBL 2.0 is unable to ingest a UBL 1.0 document precisely because the validation of the UBL 2.0 document constraints will fail
and the UBL 1.0 document is not recognized as a valid instance of the UBL 2.0 document model.There is no impact of minor revisions in UBL for existing UBL documents for a major revision. The committee goes to great lengths to ensure that the document constraints for every minor revision of UBL will not be violated by any UBL document created by a previous minor revision. Of
course this cannot work in the other direction. That is, a document of a new minor revision may very well violate the constraints of an earlier revision due to the introduction of new business objects.From a business perspective, this approach removes any need to redress older UBL documents to prevent constraint violations in newer UBL systems. Documents of older minor revisions are automatically, without making any changes, considered valid documents of newer minor revisions. In a
network of heterogeneous systems, it is not necessary to upgrade every installation at the same time in order to preserve interoperability. A new system can ingest a UBL document created by an old system without that old document violating the new document constraints.From a regulatory perspective, this approach allows a jurisdiction to mandate constraints on any minor revision of UBL and those constraints will apply equally to all subsequent minor revisions. There is no need to update any regulation for a given version of UBL just because the
committee development of UBL continues to add new features in new minor revisions for users outside of the jurisdiction. Until a new feature is available of interest to the jurisdiction, there is no need to move away from a chosen minor revision.This guarantee of backward compatibility of old UBL documents to new and future UBL models protects all stakeholders investing in the use of this specification.The remainder of this appendix provides more details regarding the past evolution of UBL.Initial Release: UBL 1.0Though apparently limited in scope, the eight document types provided in UBL 1.0 (2004) are applicable to a very large number of real-world use cases and have been widely deployed. These original 1.0 document types, later updated in UBL 2.0 and continued here in minor revisions, are
Order, Order Response, Order Response Simple, Order Change, Order Cancellation, Despatch Advice, Receipt Advice, and Invoice. The figure below shows the original assumed process context for this most basic
set of UBL document types. The scope of the process corresponds roughly to that of the UBL 2 Order, Fulfilment, and Traditional Billing processes described in the text (see , , and ).Because versions of UBL beginning with 2.0 do not maintain backward compatibility with UBL 1.0 document instances (that is, UBL 1.0 document instances will not validate against schemas from UBL 2.0 and later), use of UBL 1.0 in new installations is deprecated. Suitably revised versions
of the original eight document types continue all the business functionality of UBL 1.0 in later versions.Major Revision: UBL 2.0Adoption of UBL 1.0 following ratification as an OASIS standard in November 2004 resulted in major inputs of new business 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 resulted in greatly expanded pre-order and post-invoice capabilities together with the addition of several transport-related document types, bringing the total number of document types in UBL 2.0 to
31.The new release also featured changes in UBL’s use of XML schema methodology—most importantly, the adoption of global scoping for all element types—breaking backward compatibility with UBL 1.0 instances and therefore necessitating designation as a major revision,
signified by incrementing the version number from 1.0 to 2.0 rather than 1.1. The original eight UBL 1.0 document types were revised to reflect these changes.UBL 2.0 achieved OASIS Standardization in December 2006, and the package was updated and corrected in May 2008.The 23 document types added in UBL 2.0 can be summarized as follows:
Added UBL 2.0 document types for fulfilment:
Bill Of Lading, Certificate Of Origin, Forwarding Instructions, Packing List, Transportation Status, Waybill
Minor Revision: UBL 2.1Because it preserves backward compatibility with UBL 2.0, UBL 2.1 is technically a minor release, not a major one. However, it did add 34 new document types, bringing the total number of UBL business documents to 65.
Added UBL 2.1 document types for eTendering:
Awarded Notification, Call For Tenders, Contract Award Notice, Contract Notice, Guarantee Certificate, Tender, Tender Receipt, Tenderer Qualification, Tenderer Qualification Response, Unawarded Notification
Added UBL 2.1 document types for Collaborative planning, forecasting, and replenishment:
Exception Criteria, Exception Notification, Forecast, Forecast Revision, Item Information Request, Prior Information Notice, Trade Item Location Profile
Added UBL 2.1 document types for fulfilment:
Fulfilment Cancellation
Added UBL 2.1 document types for Intermodal Freight Management:
Goods Item Itinerary, Transport Execution Plan, Transport Execution Plan Request, Transport Progress Status, Transport Progress Status Request, Transport Service Description, Transport Service Description Request, Transportation Status, Transportation Status Request
Added UBL 2.1 document type for Utility billing:
Utility Statement
The extension was added in UBL 2.1. This extension works as is also with UBL 2.0.Details of the changes from UBL 2.0 to UBL 2.1 are found at Minor Revision: UBL 2.2Because it preserves backward compatibility with UBL 2.1 and UBL 2.0, UBL 2.2 is technically a minor release, not a major one. However, it did add 16 new document types, bringing the total number of UBL business documents to 81.
Added UBL 2.2 document types for eTendering:
Enquiry, Enquiry Response, Expression Of Interest Request, Expression Of Interest
Response, Qualification Application Request, Qualification Application Response, Tender Contract,
Tender Status, Tender Status Request, Tender Withdrawal, Unsubscribe From
Procedure Request, Unsubscribe From Procedure Response
Added UBL 2.2 document type for transportation:
Weight Statement
Added UBL 2.2 document types for business directories and agreements:
Business Card, Digital Agreement, Digital Capability
Minor Revision: UBL 2.3New Document Types in UBL 2.3Because it preserves backward compatibility with UBL 2.2, UBL 2.1, and UBL 2.0, UBL 2.3 is technically a minor release, not a major one. However, it does add ten new document types, bringing the total number of UBL business documents to 91.
Added UBL 2.3 document types for transportation:
Common Transportation Report, Export Customs Declaration, Goods Certificate, Goods Item Passport, Import Customs Declaration, Manifest, Proof Of Reexportation,
Proof Of Reexportation Reminder, Proof Of Reexportation Request, Transit Customs Declaration
Schema changes from UBL 2.2 to UBL 2.3Schema Changes IntroductionThe following two tables show the differences between the XML elements in UBL 2.2 and those in UBL 2.3.All changes in 2.3 schemas are backward-compatible with valid UBL 2.2, UBL 2.1, and UBL 2.0 instances. Changes include the addition of new elements and attributes; changes in cardinality from 1 to 0..1 (i.e., making a formerly required element optional); changes in cardinality from 1
to 1..n or from 0..1 to 0..n (i.e., allowing an unlimited number of occurrences instead of just one); and corrections to Dictionary Entry Names (DENs).Changes to Library Elements, UBL 2.2 to UBL 2.3A number of changes related to pre-award semantic components further the support of notification documents:a richer set of structured information elements such as “prize” and “concession revenue” elements, andmaking documents fitter for purpose to support more scenarios by relaxing some cardinalities, for example:Tendering Criterion Property is no longer mandatory to allow for the case when a Tendering Criterion is composed of sub criteria, in which case the master criterion has no property itself), andadding ASBIEs ( e.g. “Additional Notice Language” to support multiple official languages), in particular to support the eForms implementing regulation (Commission Implementing Regulation (EU) 2019/1780).The following table sums up the differences between the XML elements in the UBL 2.2 Common Library and those in the UBL 2.3 Common Library.
Summary changes to Library Elements Universal Business Language UBL 2.3 OS to 2.2Aggregate BIEBasic or Association BIEChanges for UBLAddressDescriptionAddedAttestationAddedAttestationLineAddedAuthorizationAddedAwardingCriterionNameAddedAwardingTermsPrizeAddedBallastWaterSummaryAddedBallastWaterTransactionAddedCardAccountRoleCodeAddedCertificateCertificateTypeCodeChanged cardinality from 1 to 0..1CertificateTypeChanged cardinality from 1 to 0..nIssuerPartyChanged cardinality from 1 to 0..1ConsignmentOfficeOfEntryLocationAddedOfficeOfSubSequentiallyEntryLocationAddedOfficeOfExitLocationAddedOfficeOfDepartureLocationAddedOfficeOfDestinationLocationAddedOfficeOfImportLocationAddedOfficeOfExportLocationAddedDocumentReferenceAddedConsumptionLineTaxInclusiveLineExtensionAmountAddedContactJobTitleAddedDepartmentAddedContractModificationReasonCodeAddedModificationReasonDescriptionAddedContractingActivityActivityTypeChanged cardinality from 0..1 to 0..nContractingPartyContractingRepresentationTypeAddedContractingPartyTypePartyTypeChanged cardinality from 0..1 to 0..nContractingRepresentationTypeAddedCreditNoteLineTaxInclusiveLineExtensionAmountAddedCrewPersonEffectAddedCriterionItemAddedCustomsDeclarationValidityPeriodAddedApplicableTerritoryAddressAddedShipmentAddedCustomsExitOfficeLocationAddedConsignorPartyAddedConsigneePartyAddedFreightForwarderPartyAddedCustomsPartyAddedPreviousCustomsDeclarationAddedAdditionalDocumentReferenceAddedDebitNoteLineTaxInclusiveLineExtensionAmountAddedDespatchLineSubDespatchLineAddedDocumentDistributionIDAddedDistributionTypeCodeAddedDistributionTypeAddedPrintQualifierChanged cardinality from 1 to 0..1CopyIndicatorAddedCommunicationAddedDocumentReferenceDocumentTypeChanged cardinality from 0..1 to 0..nReferencedDocumentInternalAddressAddedFeeAddedFrameworkAgreementEstimatedMaximumValueAmountAddedMaximumValueAmountAddedGoodsItemCustomsProcedureCodeAddedOrderLineReferenceAddedGoodsItemPassportCounterfoilAddedGoodsProcessingAddedHazardousGoodsTransitTransitDescriptionAddedHazardousItemUNPackingGroupCodeAddedUNPackingGroupAddedTunnelRestrictionCodeAddedMaritimePollutantCodeAddedPositionOnBoardStowageAddedISPSRequirementsAddedInvoiceLineTaxInclusiveLineExtensionAmountAddedItemIdentificationIssuerScopeIDAddedItemPropertyStandardPropertyIdentificationAddedSubItemPropertyAddedLineItemTaxInclusiveLineExtensionAmountAddedLocationStorageAddedLotDistributionLotsGroupAddedLotsGroupAddedMaritimeHealthDeclarationAddedMaritimeTransportMMSIRegistrationIDAddedSegregatedBallastMeasureAddedShipConfigurationCodeAddedINFShipClassCodeAddedAntennaLocusAddedVesselDynamicsAddedMaritimeWasteAddedPackagePackagingTypeAddedPartyPartyAuthorizationAddedPartyLegalEntityCompanyLegalFormChanged cardinality from 0..1 to 0..nPaymentMeansChargeBearerCodeAddedServiceLevelCodeAddedCardAccountChanged cardinality from 0..1 to 0..nRemittanceDocumentDistributionAddedPersonBirthplaceLocationAddedPersonnelHealthIncidentAddedPortCallAddedPortCallPurposeAddedPortCallRecordAddedPriceAlternativeCurrencyPriceAddedPrizeAddedProcurementAdditionalTypeAddedProcurementProjectSMESuitableIndicatorAddedProcurementAdditionalTypeAddedProcurementProjectLotLegalDocumentReferenceAddedTechnicalDocumentReferenceAddedRequiredDocumentReferenceAddedProvidedDocumentReferenceAddedAdditionalDocumentReferenceAddedTenderingProcessAddedPropertyIdentificationAddedQuotationLineTaxInclusiveLineExtensionAmountAddedRegulationNameChanged cardinality from 1 to 1..nRequestedTenderTotalEstimatedOverallFrameworkContractsAmountAddedSanitaryMeasureAddedSecurityClearanceTermAddedSecurityMeasureAddedShipRequirementAddedShipStoreArticleAddedShipToShipActivityRecordAddedShipmentIDChanged cardinality from 1 to 0..1ShipmentStageShipmentStageTypeCodeAddedShipmentStageTypeAddedCabotageIndicatorAddedHazardousRiskIndicatorAddedDestinationPortCallAddedShipStoreArticleAddedCrewPersonEffectAddedMaritimeWasteAddedBallastWaterSummaryAddedISPSRequirementsAddedMaritimeHealthDeclarationAddedSignatureReasonCodeAddedStatusSubStatusAddedStorageAddedTaxTotalCalculationSequenceNumericAddedTelecommunicationsSupplyLineTaxInclusiveLineExtensionAmountAddedTemperatureAttributeIDChanged cardinality from 1 to 0..1MeasureChanged cardinality from 1 to 0..1MeasureCodeAddedTenderLineTaxInclusiveLineExtensionAmountAddedTenderRequirementNameChanged cardinality from 1 to 1..nTenderedProjectAdditionalFeeAddedProcurementProjectLotChanged cardinality from 0..1 to 0..nTendererQualificationRequestCompanyLegalFormChanged cardinality from 0..1 to 0..nTenderingCriterionNameChanged cardinality from 0..1 to 0..nProcurementProjectLotReferenceAddedCommodityClassificationAddedTenderingCriterionPropertyGroupChanged cardinality from 1..n to 0..nTenderingCriterionPropertyExpectedIndicatorAddedExpectedURIAddedMaximumQuantityAddedMinimumQuantityAddedTenderingCriterionResponseProcurementProjectLotReferenceAddedCommodityClassificationAddedTenderingProcessTerminatedIndicatorAddedParticipationInvitationPeriodAddedAdditionalInformationRequestPeriodAddedTenderingTermsVariantConstraintCodeAddedRequiredCurriculaCodeAddedRecurringProcurementDescriptionAddedMultipleTendersCodeAddedProcurementLegislationDocumentReferenceChanged cardinality from 0..1 to 0..nFiscalLegislationDocumentReferenceChanged cardinality from 0..1 to 0..nEnvironmentalLegislationDocumentReferenceChanged cardinality from 0..1 to 0..nEmploymentLegislationDocumentReferenceChanged cardinality from 0..1 to 0..nCallForTendersDocumentReferenceChanged cardinality from 0..1 to 0..nQualificationRequestRecipientPartyAddedSecurityClearanceTermAddedVesselDynamicsAddedWHOAffectedAreaVisitAdded
Changes to Document Elements, UBL 2.2 to UBL 2.3The following table sums up the differences between the XML elements in the UBL 2.2 document schemas and those in the UBL 2.3 document schemas.
Summary changes to Document Elements Universal Business Language UBL 2.3 OS to 2.2Aggregate BIEBasic or Association BIEChanges for UBLCommonTransportationReportAddedContractAwardNoticeVersionIDAddedPreviousVersionIDAddedRequestedPublicationDateAddedNoticeTypeCodeAddedAdditionalNoticeLanguageAddedContractNoticeVersionIDAddedPreviousVersionIDAddedAdditionalNoticeLanguageAddedCreditNoteAccountingCustomerPartyChanged cardinality from 1 to 0..1DebitNoteAccountingCustomerPartyChanged cardinality from 1 to 0..1ExportCustomsDeclarationAddedFulfilmentCancellationBuyerCustomerPartyChanged cardinality from 1 to 0..1SellerSupplierPartyChanged cardinality from 1 to 0..1GoodsCertificateAddedGoodsItemPassportAddedImportCustomsDeclarationAddedInvoiceAccountingCustomerPartyChanged cardinality from 1 to 0..1ManifestAddedPriorInformationNoticeVersionIDAddedPreviousVersionIDAddedRequestedPublicationDateAddedRegulatoryDomainAddedAdditionalNoticeLanguageAddedProofOfReexportationAddedProofOfReexportationReminderAddedProofOfReexportationRequestAddedTransitCustomsDeclarationAdded
Editorial changes from UBL 2.2 to UBL 2.3As this is a very lengthy specification, this guidance to the reader reflects where UBL 2.3 has not changed substantially or substantively from UBL 2.2. Editorial changes that are related to grammar, spelling, and turn of phrase are not enumerated. is unchanged from UBL 2.2. has been augmented with the new transportation documents. No subject areas from UBL 2.2 have been removed from this section. has been augmented with a number of new document types and references to example instances. The new UBL 2.3 availability of an extension point at the start of every ABIE, not only the top-level document ABIE, is described in . is unchanged from UBL 2.2 except for the correction of the incorrectly labeled [IND9] in . has been updated with a new narrative outlining the latest version of using XAdES with XMLDSig. is unchanged from UBL 2.2 with the exception of clarifying the need to conform to documented other constraints for the extension scaffolding and content. is unchanged with the exception of adding UBL 2.3 to the section on upgrading, and enumerating the known errors in the document models. adds details of the changes from UBL 2.2 to UBL 2.3. The first subsection has been entirely rewritten from UBL 2.2 to assist in the understanding of the impact of
major and minor revisions. is changed from UBL 2.2 to include revisions to a diagram and a summary of the use of the spreadsheet columns. is unchanged from UBL 2.2. is changed from UBL 2.2 to revise the list of code lists and to include an illustrative example of a Schematron script for the UBL additional document constraints. includes a revised list of example instances. is unchanged other than referring to UBL 2.3 instead of UBL 2.2. is unchanged. is changed to reflect the active membership of the technical committee during the development of UBL 2.3.The UBL 2.3 Data ModelThe Use of the OASIS Business Document Naming and Design RulesAs described in the OASIS UBL Naming and Design Rules application of the OASIS Business Document Naming and Design Rules , the UBL data model design follows the principles of the UN/CEFACT Core Components Technical Specification . The UBL data model is based on a library of reusable information items known as Business Information Entities (BIEs). Each business document defined by UBL is created by assembling items appropriate to that document type from the UBL BIE library. Further detail regarding
BIEs is provided in .Historically, both the UBL common library of reusable components and the assembly models for the individual UBL documents have been published as separate spreadsheets using a format specifically developed for UBL business information modeling (this format is discussed further below).
Beginning with UBL 2.3, all of these models are published as separate worksheets in a single spreadsheet. This spreadsheet is provided in both Open Document and Microsoft Excel formats in mod/ subdirectory (see for details regarding the spreadsheet columns):
mod/UBL-Entities-2.3.odsmod/UBL-Entities-2.3.xls
A machine-processable XML version of the spreadsheet contents for the entire UBL data model is provided in OASIS genericode format:
mod/UBL-Entities-2.3.gc
Similar files for the UBL standardized signature extension also are in mod/ subdirectory:
For links to the individual HTML reports for each of the document types, see the schema tables in . These reports elide all of the library components that are not used by each document type and are far shorter than the “all documents”
report.For notes on the use of the HTML reports, see
mod/summary/readme-Reports.html
Business Information EntitiesIn the language of , UBL Business Information Items (BIEs) include BBIEs (“basic” individual pieces of information), ABIEs (aggregations of other BIEs), and ASBIEs (“associations” to ABIEs). Fuller explanations of these terms in the context
of the CCTS framework will be found in the CCTS specification. For purposes of understanding UBL as a set of XML schemas, however, it may be useful to describe these terms employing concepts more familiar to XML users. Refer to for the details of how these concepts and their nuances are specified for UBL in the spreadsheet tools used by the committee.With the understanding that every XML document describes a logical tree of elements, the different kinds of Business Information Entities from which UBL documents are constructed may be described as follows:UBL BBIEs (Basic Business Information Entities) are the leaf nodes of every UBL document structure. These are ordinary data fields such as one would expect to find in any business form, and they are realized in the schemas as individual XML elements at the
bottom level of the document tree with simple content representing amounts, codes, quantities, and so on. All UBL BBIE elements (and only UBL BBIE elements) are members of the UBL common basic components namespace, conventionally denoted in UBL schemas by the cbc: prefix.
(Since all namespace prefixes in XML are assigned on a per-instance basis according to namespace declarations in the individual instance, prefixes such as cbc: may be replaced with arbitrarily different namespace prefixes in actual UBL documents.)UBL ASBIEs (Association Business Information Entities) are substructures of a UBL document. Children of ASBIEs may be BBIEs or other ASBIEs, never ABIEs. All UBL ASBIEs (and only UBL ASBIEs) are members as elements of the
UBL common aggregate components namespace, denoted in UBL schemas by the cac: prefix.UBL document ABIEs (Aggregate Business Information Entities) are the root nodes and top-level structures of UBL documents. Children of document ABIEs may be BBIEs or ASBIEs, never ABIEs. All UBL document ABIEs (and only UBL document ABIEs) are defined within
individual namespaces specific to each document as both elements and types.UBL library ABIEs (that is, all ABIEs except document ABIEs) have a structural shape but are not concrete document structures; rather, they are abstract structures or templates for ASBIEs, thus allowing the same structure to be reused in multiple roles.
Children of library ABIEs in the data structure can be BBIEs or ASBIEs, never ABIEs. All library ABIEs are realized as ASBIEs in order to actually exist as elements in the UBL document tree. All UBL library ABIEs (and only UBL library ABIEs) are realized as
types in the UBL cac: namespace.This naming scheme inherited from CCTS may prove problematic for some UBL users. In particular, the CCTS terms “Association Business Information Entity” and “Aggregate Business Information Entity” do not well describe these two concepts as they are realized in
XML. The problem word here is “association”, which correctly describes this relationship within a UML (Unified Modeling Language) framework but is perhaps better thought of in the UBL context as meaning that a particular ASBIE is “associated with” an abstract ABIE
structure. For our purposes, it would have been better if ASBIEs had instead been called “Aggregate Business Information Entities” and ABIEs had instead been called “Structural Templates”. It may prove easiest for the UBL user to regard the terms ASBIE and ABIE as
opaque labels and to ignore the historical expansions of these acronyms.It can be seen from the above that the XML implementations of ASBIEs and library ABIEs share the same cac: namespace. In the schemas, library ABIEs are all implemented as XML types, and ASBIEs are all implemented as XML elements. This is simply a reflection of their
different roles—library ABIEs as abstract classes or structural templates (realized as XML types) and ASBIEs as concrete instantiations (realized as XML elements derived from those types).While the distinction between ABIEs/classes/types on the one hand and ASBIEs/instantiations/elements on the other is clear enough, it should be noted that in some cases an ASBIE does not qualify the name of the ABIE from which it is derived. In effect, they have the same name. Some
library ABIEs are used only in the form of an ASBIE having the same name; for example, AddressLine is a library ABIE that is only used in the form of an ASBIE named AddressLine. Some library ABIEs are realized in some places as ASBIEs with the same name
(where it is felt that the unqualified name is sufficient) and elsewhere as ASBIEs with a name that is further qualified; for example, the library ABIE Address has numerous ASBIE realizations with qualified names like LocationAddress,
ApplicableAddress, DespatchAddress, and so on, but it’s also seen as an ASBIE simply named Address that’s included in the library ABIEs FinancialInstitution, Branch,
Location, and ConsumptionPoint. Some library ABIEs are never actually implemented as ASBIEs with the same name; for example, only one ASBIE is associated with the library ABIE ActivityDataLine, and it has the qualified name
SupplyChainActivityDataLine.The UBL Common Aggregate Component schema declares an identically named element or potential ASBIE for every library ABIE regardless of whether that element is used in a UBL document schema to represent an ASBIE (these are among the long list of global element declarations at the
beginning of the CAC module). ABIEs are implemented as one or more ASBIEs via XSD references to these elements farther down in the CAC schema module or in individual document schema modules, which all import the CAC module. For example, the global element AddressLine
declared in the CAC with the line <xsd:element name="AddressLine" type="AddressLineType"/>
is implemented as an ASBIE with the same name in the declaration of the Address ABIE as follows: <xsd:element ref="cac:AddressLine" minOccurs="0" maxOccurs="unbounded">
[...]
</xsd:element>
One consequence of this approach is that the list of global elements that begins the CAC module contains elements that are in fact never used under those names in UBL 2.3. For example, the element ActivityDataLine mentioned above is used by reference in creating the
ASBIE SupplyChainActivityDataLine, but it never appears in the form of an ASBIE named ActivityDataLine. Such unused ABIE names remain available in the global element declarations for customizers and designers of future additions to UBL.Refer to for more information regarding the granularity of CCTS information maintained in the UBL document models.Navigating the UBL Data ModelThe concepts described above can be illustrated by navigating the UBL data model to construct a trivial UBL Invoice instance.We will start with a wrapper copied from an example in the xml/ directory of the UBL distribution (xml/UBL-Invoice-2.1-Example.xml) that has the required XML namespace declarations for the Invoice and for the common library components (“cac” for the aggregate (ABIE and ASBIE) components and “cbc” for the basic (BBIE) components):<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
[...]
</Invoice>
Now we will fill out this shell of an instance, completing the part in the square brackets by traversing the data model.In addition to the aforementioned complete UBL data model spreadsheets and HTML rendering, when dealing with only a single document type there is an HTML rendition of that subset of the spreadsheet contents with only that content utilized by the one document type, such as for the
Invoice:
mod/summary/reports/UBL-Invoice-2.3.html
Line 2 of the Invoice model defines the document ABIE named Invoice. The Component Type column confirms that Invoice is an ABIE, as also indicated by the pink background in that row of the rendering.Everything after Invoice in the model ends up as part of the schema, and the order seen here is the order in which these components will appear in both the schema and any conforming instances of Invoice. The BBIE children of Invoice are given first (white background), and then all the ASBIE children of Invoice (green background).As shown in Cardinality column, most of these components are optional. The first required field is ID (line 7) and the second is IssueDate (line 10), so we can write, for example, <cbc:ID>123</cbc:ID>
<cbc:IssueDate>2011-09-22</cbc:IssueDate>
Next let’s add an optional InvoicePeriod (line 25). This is an ASBIE, implying that it has some kind of substructure, and it derives from the generic
ABIE called Period (this is the “Associated Object Class” referred to in a column of the same name). To find this structure, we look for the Period library ABIE in the model report or in the Common Library worksheet of the UBL model spreadsheet.Period will be found at line 1709 and seen to contain a number of possible BBIE children, all of them optional; and the ASBIE InvoicePeriod in Invoice therefore has this structure, too. From this one could conclude that instantiations of the Period structure (there are more than 50 of them in UBL) need not contain any of the seven optional BBIE elements specified after line 1709, and
indeed the corresponding declaration of the complex type PeriodType in the CAC schema (xsd/common/UBL-CommonAggregateComponents-2.3.xsd) shows that an empty InvoicePeriod element will pass XML validation; but UBL explicitly prohibits such structures (see ). In UBL, as a normative rule independent of schema constraints, every ASBIE shall have at least one child (BBIE or ASBIE) instantiated. In this case, therefore,
one or more of the seven possible BBIE children of InvoicePeriod will need to appear in a UBL Invoice document for it to be conforming to UBL in addition to the requirement that the document validate against the Invoice schema. If StartDate and EndDate (for exsample) are chosen for the content of InvoicePeriod, the corresponding section of the sample instance might then look like this: <cac:InvoicePeriod>
<cbc:StartDate>2011-08-01</cbc:StartDate>
<cbc:EndDate>2011-08-31</cbc:EndDate>
</cac:InvoicePeriod>
Next in order in the Invoice come two required pieces, the ASBIEs AccountingSupplierParty and AccountingCustomerParty. As shown in Associated Object Class column of the Invoice model, AccountingSupplierParty (line 36) derives from the SupplierParty ABIE and AccountingCustomerParty (line 37) derives from the CustomerParty ABIE. Checking in the Common Library, it is seen that both SupplierParty (line 2348 of the Common Library) and CustomerParty (line 640 of the Common Library) can contain an ASBIE named Party (as shown in lines 2352 and 644, respectively) and that each Party ASBIE is an instantiation of the Party ABIE (line 1597). Therefore both parties have the same structure (the BBIEs and ASBIEs following line 1597). Thus AccountingSupplierParty and AccountingCustomerParty share the information components common to parties in general and differ in the information specific to suppliers and customers. Parties commonly have a PartyName (line 1605) that derives (the Associated Object Class column) from the ABIE PartyName (line 1637), which is a wrapper for the BBIE Name (line 1638). A conforming piece of the document instance might therefore look like this: <cac:AccountingSupplierParty>
<cac:Party>
<cac:PartyName>
<cbc:Name>Custom Cotter Pins</cbc:Name>
</cac:PartyName>
</cac:Party>
</cac:AccountingSupplierParty>
<cac:AccountingCustomerParty>
<cac:Party>
<cac:PartyName>
<cbc:Name>North American Veeblefetzer</cbc:Name>
</cac:PartyName>
</cac:Party>
</cac:AccountingCustomerParty>
Returning to the Invoice model, it is seen that the Invoice needs to end with a LegalMonetaryTotal (line 54) and at least one InvoiceLine (line 55). Taking LegalMonetaryTotal first, it is found in the Common Library to be derived from MonetaryTotal (line 1518), which has a mandatory PayableAmount BBIE. A corresponding example instance fragment might be therefore be constructed as follows: <cac:LegalMonetaryTotal>
<cbc:PayableAmount currencyID="CAD">100.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
If the preceding explanation of Party is understood, there should be nothing problematic about the process of forming the example LegalMonetaryTotal element shown above except the currencyID attribute on PayableAmount, which does not appear explicitly in the model line for that BBIE (line 1527). This is because
UBL does not define the primitive data types upon which the model is built; instead it uses standard data type definitions from and . In the case of PayableAmount, the CCTS data type (the Data Type column) is “Amount. Type” (the space is part of the name), and that type is defined in itself (Table 8-1 of the CCTS 2.01 specification). There it will be seen that “Amount. Type” has two
supplementary “CCT Components” called “Amount. Currency. Identifier” and “Currency. Code List Version. Identifier”. In the XML realization of CCTS, supplementary components are expressed as attributes, and the CCTS names “Amount. Currency.
Identifier”and “Currency. Code List Version. Identifier” are transformed into the XML attribute names currencyID and currencyCodeListVersionID, respectively. All of these CCTS-based types and attributes are declared in the CCTS Core
Component Type schema module:
xsd/common/BDNDR-CCTS_CCT_SchemaModule-1.1.xsd
Note that this schema module comes from UN/CEFACT, not UBL; that it does not implement all of the supplementary components of core component types defined by ; and that all of the attributes it does declare are defined as optional. In UBL, however, the attributes
currencyID and mimeCode are required, not optional. In order to impose its own restrictions, therefore, and also to supply a full set of supplementary component attributes, UBL provides an Unqualified Data Types module that imports the CCTS module and
then overrides those definitions as needed:
xsd/common/BDNDR-UnqualifiedDataTypes-1.1.xsd
Further information about UBL data types can be found in . Note in particular , which includes a list of all the attributes associated with UBL unqualified data types. A reverse lookup of the
implied occurrence of each attribute in the data models is provided in this summary report:
In the example fragment above, currencyID has been used to label the amount in Canadian dollars (CAD). As explained in , the value CAD for this attribute is not specified in schemas to be
checked using XSD validation but will instead be found in separate OASIS genericode code list files in the gc/ directory of the UBL distribution, which are engaged through a separate XSLT-based process.Using the same methodology, a sample InvoiceLine can be constructed to complete the example as follows: <cac:InvoiceLine>
<cbc:ID>1</cbc:ID>
<cbc:LineExtensionAmount currencyID="CAD">100.00</cbc:LineExtensionAmount>
<cac:Item>
<cbc:Description>Cotter pin, MIL-SPEC</cbc:Description>
</cac:Item>
</cac:InvoiceLine>
The finished example can be found in
xml/UBL-Invoice-2.1-Example-Trivial.xml
The CCTS Specification of UBL Business Information EntitiesThe UBL Business Information Entities (BIEs) outlined in are specified in CCTS terms by the technical committee through the use of the office spreadsheets cited in .The column values for each BIE are governed by the OASIS Business Document Naming and Design Rules. A summary of these columns is provided here for reference, listed in order of columns A through V:A - Component Namethe label used to identify the BIE in the serialization markup (for XML this is the element name used in the start tag and the end tag surrounding the information)the value is algorithmically derived from other column values and so is never a data value entered by usersB - Subsetan unspecified value reserved for use by tools processing the CCTS model for arbitrary purposescertain publicly-available tools will use this column to interpret the cardinality of the BIE within a subset model of cherry-picked BIEs, where a cardinality of 0 indicates that the BIE is not found within the subsetthe value is specified by users of the UBL specification who are configuring a subset document modelC - Cardinalitythe constraint of how often the given BIE shall be or is allowed to be repeated when encountered in a UBL document1=mandatory, 0..1=optional, 1..n=mandatory and repeatable, 0..n=optional and repeatablethe value is specified by the UBL Technical CommitteeD - Definitiona prose description of the semantic represented by the use of this BIEthe value is specified by the UBL Technical CommitteeE - Alternative Business Termsexamples of common terms used that are synonymous with the name adopted for the BIEthe value is specified by the UBL Technical CommitteeF - Examplesexample values that might be found when this BIE is used in a documentthe value is specified by the UBL Technical CommitteeG - Dictionary Entry Namethe unambiguous name of this BIE using the ISO/IEC 11179 classification naming schemethis value can be used as a unique key for the BIE across the entire CCTS model for UBLthe value is algorithmically derived from other column values and so is never a data value entered by usersH - Object Class Qualifierthe component of the Dictionary Entry Name that distinguishes the object class from other like-named object classesthis value is always empty for all BIEs in UBL and remains in the spreadsheet solely for ISO/IEC 11179 completenessin UBL object classes are qualified by their use in context using the property term qualifier, not by their definitionthis value is not specified by anyone and should never be used in UBLthis column is not included in the HTML summary reportsI - Object Classthe identification of the aggregate BIE in which this BIE residesthe value is specified by the UBL Technical CommitteeJ - Property Term Qualifiera qualification of the property term to distinguish this property term from another like-named property term used within the aggregatethe value is an adjective; refer to the discussion that follows regarding the composition of a qualified property termthe value is specified by the UBL Technical CommitteeK - Property Term Possessive Nouna component of the property term that distinguishes using context this property term’s primary noun from another property term’s primary noun used within the aggregatethe value is a noun; refer to the discussion that follows regarding the composition of a qualified property termthe value is specified by the UBL Technical CommitteeL - Property Term Primary Nouna component of the property term that identifies the root meaning of the semantic concept typically being context freethe value is a noun; refer to the discussion that follows regarding the composition of a qualified property termthe value is specified by the UBL Technical CommitteeM - Property Termthe CCTS-defined single-valued property term composed of the two components specified in the OASIS NDR that make up this valuerefer to the discussion that follows regarding the composition of a qualified property termthe value is algorithmically derived from other column values and so is never a data value entered by usersN - Representation Termthe semantic-free identification of the format or structure of the BIE valueone does not have to know the property term or semantic concept or context of use to know the structure of the value of the BIE, as the representation term is sufficient to know how to constrain the BIE value in the document for BBIEs this is the data type identifier and is specified by the UBL Technical Committeefor ASBIEs this is the associated object class and is algorithmically derived from other column valuesO - Data Type Qualifiersemantically identifies a value constraint that, optionally, may be imposed by users on the value of a BBIEthe UBL Technical committee identifies candidate data type qualifiers but does not impose any value constraints by doing sousers of UBL may choose to impose value constraints in a deployment, and this semantic identifier guides them in the nature of the constraint to imposeusers of UBL may choose to impose value constraints on any value in a UBL document, not only those values qualified using this identifier as some semantic value constraintthe value is specified by the UBL Technical CommitteeP - Data Typeidentifies the lexical constraint on a BBIE value, that is, the character-level contents or structure of an atomic string value in the UBL documentthe value is algorithmically derived from other column values and so is never a data value entered by usersQ - Associated Object Class Qualifierthe component of the Dictionary Entry Name that distinguishes the associated object class from other like-named object classesthis value is always empty for all BIEs in UBL and remains in the spreadsheet solely for ISO/IEC 11179 completenessin UBL object classes are qualified by their use in context using the property term qualifier, not by their definitionthis value is not specified by anyone and should never be used in UBLthis column is not included in the HTML summary reportsR - Associated Object Classthe associated object class of an ASBIE identifying the object class that describes the structured value of this BIEthe value is specified by the UBL Technical CommitteeS - Component Typeidentifies the CCTS type of the BIEan ABIE is an aggregate BIE that defines an object classa BBIE is a basic BIE, defined by a data type, collected as the first children of an ABIE before all ASBIEsan ASBIE is an association BIE, defined by an ABIE, collected as the last children of an ABIE after all BBIEsthe value is specified by the UBL Technical CommitteeT - UN/TDED Codeindicates the semantic of the BIE through the use of an identifier used in the United Nations Trade Data Element Directory (ISO 7372)the value is specified by the UBL Technical CommitteeU - Current Versionindicates the version of UBL in which this BIE was introduced into the document modelthe value is specified by the UBL Technical CommitteeV - Editor’s notesa free-form text value of some information of record that may be useful to readers, users, or committee membersthe value is specified by the UBL Technical Committeethis column is not included in the HTML summary reportsAn ABIE is an object class and is named as a unqualified noun. It contains BBIE (basic) and ASBIE (association) business information entities, in that order, as child properties.The property term of an ASBIE is its representation term which, in turn, is also its associated object class that defines it. That is, the ASBIE is reified in the XML document as an instance of the ABIE object class to which it is associated. Accordingly, ASBIEs property terms as nouns,
that being the noun of the ABIE, though it may also be qualified in its context of use.The property term of a BBIE is modeled using a refinement of the CCTS concepts as described in the OASIS Business Document Naming and Design Rules. Unlike the monolithic ASBIE property term noun, in UBL the BBIE property term is built as a two-part combination noun, where one part is
optional:property term primary nounwhen the representation term is not text, the primary noun is the representation term of the BBIE under the presumption this is the basic semantic conceptwhen the representation term is text, the primary noun is the simplest basic semantic concept reflected in the text value of the BBIEproperty term possessive nounthe possessive noun leads the primary noun expanding on the primary noun to distinguish the semantic concept from other BBIEs based on the same semantic conceptthis cannot be an adjective and it shall be a noun along the lines of “the {primary noun} relates to the {possessive noun}” or using the possession concept “the {possessive noun}’s {primary noun}”the CCTS property term is simply the concatenation of the possessive noun and the primary nounAdditionally, the ASBIE or BBIE property term may be augmented by a property term qualifier as an adjective. This qualification may be needed or helpful to clarify the semantic role of the BIE, or it may be necessary in order to disambiguate other sibling BIEs of the parent ABIE:this cannot be a noun and it shall be an adjective along the lines of “the {property term} of qualified type {qualifier}”Consider the following excerpt from the “Address. Details” ABIE where these property term concepts are illustrated:Property Term QualifierProperty Term Possessive NounProperty Term Primary NounProperty TermRep. TermStreetNameStreet NameNameAdditionalStreetNameStreet NameNameBlockNameBlock NameNameBuildingNameBuilding NameNameBuildingNumberBuilding NumberTextInhouseMailMailTextDepartmentDepartmentTextMarkAttentionMark AttentionTextMarkCareMark CareTextPlotIdentificationPlot IdentificationTextCity SubdivisionNameCity Subdivision NameNameCityNameCity NameNamePostalZoneZoneTextCountrySubentityCountry SubentityTextCountry SubentityCodeCountry Subentity CodeCodeRegionRegionTextDistrictDistrictTextTimezoneOffsetTimezone OffsetTextRoomRoomTextthe words in the qualifier column all are adjectives, and the words n the property term columns all are nounsthere are many examples of the information being captured in a BBIE as the name of a given semantic concept: and so uses the representation term of “Name”:the street name, the block name, the building name, the city subdivision name, and the city namethe possessive noun clarifies the nature of the semantic concept, that is, the primary noun is of type possessive noun, thus using the possessive concept:“Street” identifies the street’s name, “Block” identifies the block’s name, “Building” identifies the building’s name, “City Subdivision” identifies the city subdivision’s name, and “City” identifies the city’s namethe property term qualifier is an adjective needed when the same property term semantic concept exists for more than one reason in the one ABIEfor example, the qualifier “Additional” distinguishes a supplemental street name that may exist in addition to the street name, thus, “Address. Additional_ Street Name. Name” is distinguished from “Address. Street Name. Name”, while, in fact, they both are street namesTwo other illustrations of the nuances of property term naming conventions are as follows:comparing CountrySubentity and CountrySubentityCode:the text-based value is expressed colloquially as “the country’s subentity” while the coded domain value is expressed as “the country subentity’s code”all of the words are nounscomparing Region, TimezoneOffset, and PostalZone:all are text values and so all the primary nouns are the base concepts of “region”, “offset”, and “zone”no modifiers are needed for the region as that is sufficient to describe the semantic concept found in the addressthe offset is related to the timezone as in “the timezone’s offset” (not “the offset is a timezone”, “timezone” is a noun)the zone is a postal zone as in “a zone of type postal” (not “the zone relates to the postal”, “postal” is an adjective))UBL Validation Artefact GenerationFollowing the relevant sections of the OASIS Business Document Naming and Design Rules, the normative UBL schemas and the non-normative OASIS Context/Value Association file are generated from the machine-processable XML of the CCTS model expressed in the spreadsheet
contents. From the CVA file and the genericode expressions of code list values, the data type qualifications XSLT stylesheet is generated.The following diagram shows the conceptual relationships between the UBL data model (CCTS and CVA) on the left and validation artefacts (schemas and XSLT) on the right. Compare .In the diagram section for the modeling artefacts, the UBL data model of business information entities is described using CCTS as detailed in . Each document ABIE is in its own namespace and makes references to the contained BBIEs and
ASBIEs to library ABIEs. The library ABIEs are defined by the contained BBIEs and ASBIEs to library ABIEs. The library ABIEs and ASBIEs are all in the aggregate namespace. The document and library BBIEs are all in the basic namespace. The business objects and document aggregates are reified
as validation artefacts in XSD, illustrated in each box as an XSD schema fragment associated with the namespace URI string indicated by the documentary namespace prefix.Also shown in the modeling artefacts are the semantic code list associations in CVA for the context/value constraints governed by lists of codes in genericode files. The CVA and genericode files are used to create the data type qualifications XSLT stylesheet validation artefact used for
the demonstrative second-pass validation process documented in .In the diagram section for the validation artefacts, the namespaces shown in the shaded boxes (with prefixes qdt:, udt:, ccts-cct: and ccts:) exist only for the management of the schema components and have no
utility in UBL XML document instances. Declaring unused namespaces in an XML instance is superfluous and does not impact on conformance, but having them present may be confusing or misleading to the reader.All namespace prefixes used in this specification and in the validation artefacts are arbitrarily chosen and used consistently for documentary purposes. There is no requirement to use these particular namespace prefix values in actual UBL documents. This is in contrast to the UBL
namespace URI strings that are normative and shall be used as required whatever arbitrary non-normative namespace prefixes are chosen by users.Data Type Qualifications in UBLAll UBL data types ultimately derive either from the UN/CEFACT Core Components Technical Specification Core Component Types (CCT) or from the W3C Schema specification itself; this derivation takes place in the UBL UDT module. The following
table lists the CCTS 2.01 Core Component Types.
CCTS Core Component TypesCCTS CCTDefinitionAmount. TypeA number of monetary units specified in a currency where the unit of currency is explicit or implied.Binary Object. TypeA set of finite-length sequences of binary octets.Code. TypeA character string (letters, figures or symbols) that for brevity and/or language independence may be used to represent or replace a definitive value or text of an Attribute together with relevant supplementary information.Date Time. TypeA particular point in the progression of time together with relevant supplementary information.Identifier. TypeA character string to identify and distinguish uniquely, one instance of an object in an identification scheme from all other objects in the same scheme together with relevant supplementary information.Indicator. TypeA list of two mutually exclusive Boolean values that express the only possible states of a Property.Measure. TypeA numeric value determined by measuring an object along with the specified unit of measure.Numeric. TypeNumeric information that is assigned or is determined by calculation, counting, or sequencing. It does not require a unit of quantity or unit of measure.Quantity. TypeA counted number of non-monetary units possibly including fractions.Text. TypeA character string (i.e. a finite set of characters) generally in the form of words of a language.
The UBL unqualified data types include the CCTS unqualified data types (named according to the UBL Naming and Design Rules) and a few others, as listed in the following table. Some of these (GraphicType, PictureType, SoundType,
VideoType, and ValueType) are defined for completeness but not actually used in UBL 2.3.The rightmost column of this table lists the UBL XML attributes that implement the CCTS supplementary components associated with each CCTS data type. It is important to be aware of these attributes, because they do not appear directly in the UBL data models but are logically implied by
data type inheritance and do appear in the UBL XML schemas in accordance with the UBL Naming and Design Rules. As indicated here, a few of the most significant of these supplementary CCTS components become required XML attributes in UBL and will be required in any instance of an element
derived from the corresponding type. See for an example of UBL attributes and a further discussion of this point. A reverse lookup of the implied occurrence of each attribute in the data models is provided in this summary report:
UBL Unqualified Data TypesUBL Unqualified Data TypeDefinitionAttributesAmountTypeA number of monetary units specified using a given unit of currency.currencyID (required)currencyCodeListVersionIDBinaryObjectTypeA set of finite-length sequences of binary octets.formatmimeCode (required)encodingCodecharacterSetCodeurifilenameGraphicTypeA diagram, graph, mathematical curve, or similar representation.not used in UBL 2.3PictureTypeA diagram, graph, mathematical curve, or similar representation.not used in UBL 2.3SoundTypeAn audio representation.not used in UBL 2.3VideoTypeA video representation.not used in UBL 2.3CodeTypeA character string (letters, figures, or symbols) that for brevity and/or language independence may be used to represent or replace a definitive value or text of an attribute, together with relevant supplementary information.listIDlistAgencyIDlistAgencyNamelistNamelistVersionIDnamelanguageIDlistURIlistSchemeURIDateTimeTypeA particular point in the progression of time, together with relevant supplementary information.format (not used in UBL 2.3)DateTypeOne calendar day according the Gregorian calendar.TimeTypeAn instance of time that occurs every day.IdentifierTypeA character string to identify and uniquely distinguish one instance of an object in an identification scheme from all other objects in the same scheme, together with relevant supplementary information.schemeIDschemeNameschemeAgencyIDschemeAgencyNameschemeVersionIDschemeDataURIschemeURIIndicatorTypeA list of two mutually exclusive Boolean values that express the only possible states of a property.formatMeasureTypeA numeric value determined by measuring an object using a specified unit of measure.unitCode (required)unitCodeListVersionIDNumericTypeNumeric information that is assigned or is determined by calculation, counting, or sequencing. It does not require a unit of quantity or unit of measure.formatValueTypeNumeric information that is assigned or is determined by calculation, counting, or sequencing. It does not require a unit of quantity or unit of measure.not used in UBL 2.3PercentTypeNumeric information that is assigned or is determined by calculation, counting, or sequencing and is expressed as a percentage. It does not require a unit of quantity or unit of measure.formatRateTypeA numeric expression of a rate that is assigned or is determined by calculation, counting, or sequencing. It does not require a unit of quantity or unit of measure.formatQuantityTypeA counted number of non-monetary units, possibly including a fractional part.unitCodeunitCodeListIDunitCodeListAgencyIDunitCodeListAgencyNameTextTypeA character string (i.e. a finite set of characters), generally in the form of words of a language.languageIDlanguageLocaleIDNameTypeA character string that constitutes the distinctive designation of a person, place, thing, or concept.languageIDlanguageLocaleID
Some UBL BBIEs have data type qualifications based on the unqualified UBL types. These qualified types are all code types, and their definitions are the mechanism whereby a specific set of values is associated with each code.UBL data type qualifications are expressed formally in an OASIS (Context/Value Association) file contained in the cva directory of the 2.3 distribution.
cva/UBL-DefaultDTQ-2.3.cva
The specification of the CVA mechanism and format is maintained by the OASIS Code List Representation Technical Committee.A human-readable version is provided in an accompanying HTML file, which also serves as primary documentation on the UBL codes defined as qualified data types.
cva/UBL-DefaultDTQ-2.3.html
The val directory contains the predefined CVA associations compiled into a runtime XSLT artefact used in the recommended two-phase validation process to perform a check of code list values. See for a description of
this process.
val/UBL-DefaultDTQ-2.3.xsl
The UBL revised approach to data type qualification contrasted to the UBL 2.0 approach is illustrated in the following diagram.In UBL 2.0, the schema library of common basic components (basic business information entities or BBIEs, (A) in the diagram) is based on a combination of the data types defined in the file of UBL 2.0 qualified data types (C)
and the unqualified data types defined in the UN/CEFACT Unqualified Data Type schema module Ver. 1.1 Rev A 16 Feb 2005(K). The UBL 2.0 data type qualifications XSLT stylesheet (D) was used in the two-pass validation process, offering limitations on values such as code lists hardwired in the UN/CEFACT UDT definition.In subsequent releases of UBL, the schema library of common basic components ((B) in the diagram) is based on a combination of the data types defined in the file of UBL qualified data types (E) and the data types defined in
a file of UBL unqualified data types (M). The latter inherits the data type definitions in the UN/CEFACT CCTS CCT schema module Ver. 1.1 050114(N). The UBL data type qualifications CVA file (F) controls the creation of the UBL XSLT stylesheet (G) used in the two-pass validation process, offering both limitations and extensions to values
such as code lists. While this XSLT file, UBL-2.x-DefaultDTQ.xsl, can, when modified, apply to data type qualifications in general (such as field length restrictions and value range restrictions), the version of this file included in the UBL release contains only code list
values linked to the metadata of the applicable code list.The two remaining boxes on the right in the diagram illustrate that users can add further data type qualifications if desired by preparing a custom CVA (H) and creating a custom XSLT file (J) to replace the default CVA and
XSLT stylesheet provided in the UBL distribution.Users intending to prepare a custom CVA should note that cva/UBL-DefaultDTQ-2.3.cva contains relative URIs that expect the UBL 2.0 code lists from the UBL 2.0 Update Package in a sibling directory named os-UBL-2.0, the UBL 2.1 code lists from the UBL 2.1 distribution in a sibling directory named os-UBL-2.1, and the UBL 2.2 code
lists from the UBL 2.2 distribution in a sibling directory named os-UBL-2.2. This is irrelevant to users of the pre-compiled val/UBL-DefaultDTQ-2.3.xsl file contained in the UBL package, but users wishing to create their own CVA file need first to install the code lists of prior releases of UBL 2.0. To properly install the update, first download and install the original UBL 2.0 release:
Complete installation instructions can be found in the each package. As indicated above, the os-UBL-2.0/, os-UBL-2.1/, and os-UBL-2.2/ directories thus created need to be siblings directories to the directory created by installing
the UBL 2.3 package.UBL 2.3 Code Lists and Two-phase ValidationCode Lists IntroductionCode 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 were enumerated directly in the UBL schemas. This allowed 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 made 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 introduced a two-phase validation model that has now been fully implemented in UBL 2.1 and beyond. In the first phase, the UBL instance is checked for structure
and vocabulary against a standard UBL schema using a generic schema validator (or custom-built software performing the same function). This is exactly the same procedure used for validation in UBL 1.0, except that the schemas do not contain hardwired code list values. Then in an added second
validation (or verification) phase, 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 code list values assumed by the UBL 2.3 specification are expressed
as data type qualifications in a file named UBL-2.3-DefaultDTQ.xsl located in the val directory, as described in more detail below. Publicly available tools were used to create the XSL file using the methodology described in the “Validation”
section of , the UBL Guidelines for Customization.Separating the checking of structure and vocabulary from the checking of code values 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 sub-trees within
UBL document instances. Another way to say this is that 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.Default Validation SetupTo facilitate the processing of UBL instances using the two-phase method, an “out-of-the-box” collection of open-source software that can be used to demonstrate default validation of UBL documents is included in the val directory of this release package.
The validation harness assumes a Linux or Windows 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 Xerxes schema parser. If necessary, download and install
the latest JRE from the following location before continuing:
http://www.java.com/en/download/manual.jsp
To demonstrate UBL default validation:Change to the val directory from within a command or shell prompt.From within that directory, enter the test commandtest.bat (Windows command prompt)orsh test.sh (Linux/OSX Terminal shell prompt)The output, which is explained in the next section, should resemble the output shown in the following transcript (the spacing has been manually adjusted to make the output easier to read).############################################################
Validating order-test-bad-syntax.xml
############################################################
============== Phase 1: XSD schema validation ==============
org.xml.sax.SAXParseException; systemId: order-test-bad-syntax.xml;
lineNumber: 50; columnNumber: 25; Element type "cbc:ChannelCodeLA"
must be followed by either attribute specifications, ">" or "/>".
at org.apache.xerces.parsers.AbstractSAXParser.parse(Unknown Source)
at org.apache.xerces.jaxp.SAXParserImpl$JAXPSAXParser.parse(Unknown Source)
at org.apache.xerces.jaxp.SAXParserImpl.parse(Unknown Source)
at javax.xml.parsers.SAXParser.parse(SAXParser.java:274)
at com.nwalsh.parsers.XJParser.xsdParse(Unknown Source)
at com.nwalsh.parsers.XJParser.parse(Unknown Source)
at com.nwalsh.parsers.XJParse.run(Unknown Source)
at com.nwalsh.parsers.XJParse.main(Unknown Source)
Exception in thread "main" java.lang.NullPointerException
at com.nwalsh.parsers.XJParser.printParseStats(Unknown Source)
at com.nwalsh.parsers.XJParse.run(Unknown Source)
at com.nwalsh.parsers.XJParse.main(Unknown Source)
Attempting well-formed, namespace-aware parse
Fatal error:order-test-bad-syntax.xml:50:25:Element type
"cbc:ChannelCodeLA" must be followed by either attribute
specifications, ">" or "/>".
############################################################
Validating order-test-bad-model.xml
############################################################
============== Phase 1: XSD schema validation ==============
Attempting well-formed, namespace-aware parse
Error:order-test-bad-model.xml:50: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:
CommonExtensionComponents-2":UBLExtensions,
"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.12) with 1 error and no warnings.
############################################################
Validating order-test-bad-code.xml
############################################################
============== Phase 1: XSD schema validation ==============
No schema validation errors.
============ Phase 2: XSLT code list validation ============
Value supplied 'LA' is unacceptable for constraints identified by
'Channel-2.0 Channel-2.1 Channel-2.2 Channel-2.3' in the context
'cbc:ChannelCode': /Order/cac:BuyerCustomerParty[1]/cac:Party[1]/
cac:Contact[1]/cac:OtherCommunication[1]/cbc:ChannelCode[1]
Processing terminated by xsl:message at line 151
############################################################
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.From any directory in the file system the invocations in the val directory will run two-phase validation on any UBL document against the UBL schemas by executing commands of the form:validate.bat<ubl-schema> <ubl-document>sh validate.sh<ubl-schema> <ubl-document>where <ubl-schema> is the path of the UBL schema for that document type (Order, Invoice, etc.) and <ubl-document> is the path of a document to be validated. 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. The invocation process returns non-zero for an error and zero for no error.One can run one-pass W3C schema validation without the code list check by executing commands of the form:w3cschema.bat<ubl-schema> <ubl-document>sh w3cschema.sh<ubl-schema> <ubl-document>Discussion of the Default Validation TestThe test output displayed above demonstrates the default validation process with four test files: a UBL Order containing invalid syntax (val/order-test-bad-syntax.xml); a UBL Order containing a bad (misspelled) element (val/order-test-bad-model.xml); a UBL Order that is schema-valid but contains an illegal code list value (val/order-test-bad-code.xml); and a valid UBL Order (val/order-test-good.xml);. The file val/test.bat (Windows) or val/test.sh (Linux) is used to run the script val/validate.bat or val/validate.sh against each of the test files.Looking at the last test results first, run using order-test-good.xml, this demonstrates both phases of the default validation process running normally. The exit status of the entire test is the exit of the last test which should be successful when being tested for
error.In each test’s first phase, a standard W3C Schema (XSD) validator, Xerxes, is invoked from val/w3cschema.bat (or val/w3cschema.sh) to validate the specified UBL document
(.xml) against the specified UBL 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 each test uses a standard XSLT 1.0 engine, Saxon, to verify that the values of various codes used in the UBL document to be tested (currency codes, packaging types, etc.) are valid in terms of the default UBL code list values specified in val/UBL-DefaultDTQ-2.3.xsl. Here the output line “No code list validation errors” from the validate script indicates that the Saxon run (invoked from val/xslt.bat or val/xslt.sh) finds no illegal code values in the document.The first test of the set shows what happens when the input document (order-test-bad-syntax.xml) contains an XML syntax error, in this case due to omission of the trailing “>” from the start tag of the element named cbc:ChannelCode. When
the Xerxes parser encounters bad syntax, 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.The second test of the set shows what happens when the input document (order-test-bad-model.xml) is syntactically well-formed but contains a structure or vocabulary error, in this case due to omission of the trailing “e” from the element named
cbc:ChannelCode resulting in the name cbc:ChannelCod which is not part of the UBL model. When the Xerxes parser encounters the unrecognized 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 test of the set, the input document order-test-bad-code.xml is syntactically well-formed according to XML, and structurally valid according to the Order schema, but it contains a misspelled 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 val/UBL-DefaultDTQ-2.3.xsl.To summarize, input documents are checked in the first validation phase for correctness of syntax, structure, and vocabulary, using the constraints expressed in the appropriate UBL schema. Then they are checked in the second phase for correctness of default code list values, using the
default constraints expressed in the XSLT file UBL-DefaultDTQ-2.3.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.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, or associate different versions of the same code list with different parts of the same UBL document
by substituting a custom process (be it XSLT or some other language or process) for the default UBL-DefaultDTQ-2.3.xsl provided in the UBL 2.3 distribution. This allows extensive code list management without the need to change the standard UBL 2.3 schemas. The top-level Schematron fragment cva/UBL-DefaultDTQ-2.3.sch defining the constraints to be expressed in XSLT pulls in two fragments tailored for UBL 2.3: cva/UBL-DefaultDTQ-2.3.pattern.sch with the code list constraints from cva/UBL-DefaultDTQ-2.3.cva , and cva/UBL-DocumentConstraints-2.3.pattern.sch with the subset of that can be tested using the technology.Schematron-based techniques for generating a custom XSLT file to take the place of UBL-DefaultDTQ-2.3.xsl are explained in and . See also for more about UBL data type
qualifications.Since XSLT is a very powerful general-purpose XML transformation tool, the same framework can be extended to perform fairly sophisticated business rule checking by manually coding additional logic into the XSLT file that drives the second validation phase. Such modification is beyond the
scope of the customization methodologies associated specifically with UBL, but a business analyst willing to perform XSLT programming can use this mechanism to offload a large proportion of input filtering from the back-end business application to a simpler input processing area. Additional
XSLT scripts can be added to extract logical sub-trees of incoming UBL documents for allocation to different downstream processes and to perform even more extensive front-end processing.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 file val/xjparse.jar (renamed from xjparse-2.0.1.jar) and the files in the “val/lib” directory are from the Xjparse 2.0.1 distribution at
http://xjparse.org
The file val/saxon.jar is from the Saxon 6.5.5 distribution at
The file val/UBL-DefaultDTQ-2.3.xsl was created from the file cva/UBL-DefaultDTQ-2.3.sch using the Schematron
implementation of CVA files for validation at
Code Lists Included in UBL 2.3Code List FormatThe code lists included in the UBL 2.3 distribution use an OASIS Standard XML format for code lists called . Each code list in the distribution is expressed as a genericode file. The code lists of UBL 2.0, UBL 2.1, UBL 2.2, and UBL 2.3 are incorporated into the
default validation framework. Documentation on the UBL code lists is contained in a generated report file:
cva/UBL-DefaultDTQ-2.3.html
The code list files in UBL 2.3 are divided into two subdirectories, cl/gc/default and cl/gc/special-purpose.cl/gc/defaultThe code lists in the cl/gc/default directory contain the default code values represented in UBL-DefaultDTQ-2.3.xsl. A second-phase code list check using an unmodified version of the test setup from this distribution as described above will verify
all occurrences of code values from these lists against the values specified in the cl/gc/default directory. These are the code lists expected to be used in most application contexts, but there is no obligation to use them. The genericode files with corresponding
“including deprecated” or “including deleted” files have been culled of deprecated or deleted values in order to be used in typical contexts. The files with entries no longer used are included for completeness.
UBL 2.3 Example Document InstancesThe xml directory of this distribution contains a number of sample UBL documents that can be used for testing purposes. The testsamples.bat batch file and the testsamples.sh script in the val directory of this
distribution can be used to demonstrate the validity of these examples in Windows and Linux operating environments. See for a general discussion of UBL validation methodology. For convenience, those examples that relate
specifically to a particular document type are linked from the description of that type in .
Alternative Representations of the UBL 2.3 SchemasUBL 2.3 continues the practice, adopted at the beginning of the UBL effort, of creating its normative XML specifications using W3C Schema (XSD) syntax. Alternative representations of the same content are technically non-normative, but can be generated directly from the XSD and, with the
exception of the UBL 2.3 digital signature extension (see ), are intended to implement the same document instance constraints. The ASN.1 schemas of prior releases of the UBL models are an example of the result of such an XSD
schema transformation.Regarding creating RELAX-NG expressions of the UBL document models, the free Trang tool found at is suitable for converting the UBL W3C Schema expressions into such expressions.It is also possible to create an alternative representation directly from the CCTS model of UBL. The JSON schemas of prior releases of the UBL models are an example of the result of such a CCTS transformation.Please see the https://docs.oasis-open.org/ubl web site for available or anticipated alternative representations of UBL 2.3 models in ASN.1, JSON, and possibly other technologies.The Open-edi reference model perspective of UBLISO/IEC 14662:2010 Information technology - Open-edi reference model has been developed primarily in order to provide standards required for the inter-working of organizations through interconnected information technology systems. Open-edi lowers barriers to
electronic data interchange by introducing standard business scenarios and the necessary services to support them. The Open-edi Reference Model identifies the required standards for Open-edi and provides a reference for those standards by defining the basic concepts used to develop them. depicts two views to describe the relevant aspects of business transactions: the Business Operational View (BOV);the Functional Service View (FSV).The BOV addresses the aspects of the semantics of business data in business transactions and associated data interchanges which apply to the business needs of Open-edi. The BOV-related standards are tools and rules by which users who understand the operating aspects of a business domain
may create scenarios. The FSV addresses the supporting services meeting the mechanistic needs of Open-edi, focusing on information technology aspects of functional capabilities, service interfaces, and protocols. Using the concepts of Open-edi, UBL provides a generic Open-edi Configuration that an Open-edi Community may customize with their own requirements to implement their own Open-edi Configuration. ISO/IEC 15944-20 Information technology - Business operational view - Linking business operational view to functional service view presents the relationships linking the BOV with the FSV. illustrates how the two normative deliverables of UBL, the semantic components and the XML schemas, align respectively with the BOV and FSV views of the Open-edi Reference Model. provides the configuration’s BOV with a suite of normative business objects and associated semantics from which the community selects the semantic components needed in an information bundle. An information bundle describes the semantics of the
recorded information to be exchanged between Open-edi Support Infrastructures servicing Decision Making Applications. The community’s configuration combines these information bundles with their identified scenarios and roles. and provides the configuration’s FSV with a set of corresponding normative XML schemas and document instance rules constraining the expression of the business objects in user data. One translates the
semantic component values into a transfer syntax from the information bundle specification as a set of recorded information. It is the UBL XML syntax for the sets of recorded information defined by the information bundles that is exchanged between Parties. provides the configuration’s FSV with a normative schema fragment suitable for including profiles of digital signatures in user data. The other aspects of the implemented BOV and implemented FSV of the community’s Open-edi Configuration are governed by influences outside of the scope of UBL. Those aspects guide the community in customizing UBL to suit their requirements, as outlined in . AcknowledgementsThe OASIS UBL Technical Committee thanks SyncroSoft for its contribution of oXygen licenses used in DocBook authoring of UBL documentation; Réalta Online Publishing Solutions for support in generating PDF and HTML documents from DocBook originals; and Crane Softwrights for the generation
of the summary reports.The following persons and companies participated as members of the OASIS UBL Technical Committee during the years of its development (2017–2021).Todd Albers, Federal Reserve Bank of MinneapolisOriol Bausa Peris, IndividualKenneth Bengtsson, IndividualErlend Klakegg Bergheim, Difi-Agency for Public Management and eGovernmentMartijn van den Boogaard, IndividualPeter Borresen, ClearView TradeJon Bosak, IndividualAndrea Caccia, IndividualRoberto Cisternino, IndividualGer Clancy, IBMKees Duvekot, RFS Holland Holding B.V.Martin Forsberg, Swedish Association of Local Authorities & RegionsCécile Guasch, IndividualPhilip Helger, IndividualG. Ken Holman, Crane Softwrights Ltd.Yves Jordan, Publications Office of the European UnionMatt Lewis, IndividualOle Madsen, Danish Business AuthorityAndre Mitchell, IndividualNatalie Muric, Publications Office of the European UnionLevine Naidoo, IBMOlli Pajari, IndividualEnric Staromiejski Torregrosa, everis, S.L.U.Matt Vickers, Xero