OASIS Committee Note

UBL Naming and Design Rules Version 3.1

Committee Note Draft 01

29 July 2020

This stage:
https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/cnd01/UBL-NDR-v3.1-cnd01.xml (Authoritative)
https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/cnd01/UBL-NDR-v3.1-cnd01.html
https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/cnd01/UBL-NDR-v3.1-cnd01.pdf
Previous stage:
N/A
Latest stage:
https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/UBL-NDR-v3.1.html
https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/UBL-NDR-v3.1.pdf
Technical Committee:
OASIS Universal Business Language TC
Chairs:
Kenneth Bengtsson (kbengtsson@efact.pe), Individual
G. Ken Holman (gkholman@CraneSoftwrights.com), Crane Softwrights Ltd.
Editor:
G. Ken Holman (gkholman@CraneSoftwrights.com), Crane Softwrights Ltd.
Related work:

This note is related to:

[BDNDR] Business Document Naming and Design Rules (BDNDR) Version 1.1. Edited by Kenneth Bengtsson, Erlend Klakegg Bergheim and G. Ken Holman. 29 July 2020. Committee Specification Draft 03. https://docs.oasis-open.org/ubl/Business-Document-NDR/v1.1/csd03/Business-Document-NDR-v1.1-csd03.html. Latest version: https://docs.oasis-open.org/ubl/Business-Document-NDR/v1.1/Business-Document-NDR-v1.1.html.

Universal Business Language Version 2.3. Edited by G. Ken Holman. 14 April 2020. Committee Specification Public Review Draft 03. https://docs.oasis-open.org/ubl/csprd03-UBL-2.3/UBL-2.3.html.

Abstract:

This committee note describes the application of the OASIS Business Document Naming and Design Rules (NDR) to the OASIS UBL 2.3 specification.

Status:

This document was last revised or approved by the OASIS Universal Business Language TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl#technical.

TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/ubl/.

See Appendix A, Release notes (Non-Normative) for more information regarding this release package.

Citation format:

When referencing this note the following citation format should be used:

[UBL-NDR] UBL Naming and Design Rules Version 3.1. 29 July 2020. OASIS Committee Note Draft 01. https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/cnd01/UBL-NDR-v3.1-cnd01.html. Latest version: https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/UBL-NDR-v3.1.html.


Notices

Copyright © OASIS Open 2001-2020. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the “OASIS IPR Policy”). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Table of Contents

1 Introduction
1.1 Introduction Overview
1.2 Terminology
1.2.1 Key words
1.2.2 Terms and Definitions
1.2.3 Symbols and Abbreviations
1.3 References
2 Context of use and application of these rules
3 Information modeling
3.1 Document ABIEs
3.2 ABIE Library
3.3 Extensions
4 Dictionary information
4.1 Dictionary information overview
4.2 Dictionary information values
4.3 Abbreviations
4.4 Dictionary information for BIEs
4.5 Structure of an ABIE
5 XML validation artefacts
5.1 XML validation artefacts overview
5.2 Namespaces
5.3 XSD import/include tree
5.4 Schema fragment annotations
5.5 Schema fragments and declarations
5.6 Extension schema fragments and declarations
5.7 Qualified data types schema fragment and declarations
5.8 Unqualified data types schema fragment and declarations
5.9 CCTS Core Component Types schema
5.10 XML attribute names
5.11 Data type qualifications

Appendixes

A Release notes (Non-Normative)
A.1 Availability
A.2 Status of this release
A.3 Package structure
B Acknowledgements (Non-Normative)
C Additional production processes
C.1 CCTS serialization
C.2 Reporting
C.2.1 HTML summary reports
C.2.2 Model check report

1 Introduction

1.1 Introduction Overview

These UBL Naming and Design Rules (NDR) describe the application of the OASIS Business Document Naming and Design Rules [BDNDR] by which the XML document user data syntax constraint mechanisms are created from the abstract definition of the UBL business object information bundles. This is illustrated in Figure 1, “Open-edi Application”, reproduced from OASIS Standard UBL 2.3 Figure H.2 with an annotation highlighting the relationship of the NDR applied to UBL. The original figure depicts the roles of the four normative sections of the UBL 2.3 specification. This figure adds the JSON serialization as an additional representation of user data.

Figure 1. Open-edi Application

[Open-edi Application]

This work product fulfills a commitment by the UBL Technical Committee to document the maintenance of the information bundles and the application of the Business Document NDR to produce the validation artefacts for UBL 2.3 [UBL-2.3] documents expressing user data. The UBL information bundles are described in the abstract using CCTS [CCTS]. The UBL XML user data document model validation artefacts are described using W3C XML Schema [XSD schema] and OASIS Context/value association [CVA] expressions.

This work also provides guidance when writing custom extensions for UBL document models and when writing custom documents using the UBL common library.

Note

The UBL 2.3 specification is backwards compatible with its predecessors UBL 2.0, UBL 2.1, and UBL 2.2. The earlier specifications were completed before the Business Document Naming and Design Rules were formalized. There may very well be in those specifications some isolated violations of these rules. Changing the specifications to remove these violations is not possible because of the commitment to maintain backward compatibility with established implementations of the published specifications. Such rule violations do not impact on the integrity of the specifications, as the naming and design rules represent a best practice promoted by the UBL Technical Committee.

Documentation conventions

The documentation convention followed in this committee note is that the major clauses are aligned to the major clauses and first subclauses of the cited Business Document Naming and Design Rules and use the same titles. In some cases it is necessary to instantiate a document section with no additional information in order to align the titles of subsequent sections.

1.2 Terminology

1.2.1 Key words

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC 2119]. Note that for reasons of style, these words are not capitalized in this document.

1.2.2 Terms and Definitions

Context/value Association

The association of value constraints imposed on information found in a particular document context.

Core Component Technical Specification

A methodology for creating a business vocabulary that can be expressed in one or more syntactic expressions, as defined in [CCTS].

document ABIE

The apex ABIE of an information bundle.

document element

The apex element of information in an XML document, as defined in [XML].

extension collection

The set of extension items found in an XML document, constrained by an extension schema, that supplements the base information that is constrained by the published document model.

extension item

A single instance of structured supplemental information and its associated metadata distinguishing it from other extension items.

extension point

The apex element of structured supplemental information described by its metadata.

information bundle

The formal description of the semantics of the recorded information to be exchanged, as defined in [ISO 14662].

naming and design rules

A set of rules governing the expression of information bundles using Core Component Technical Specification, and the creation of associated XML document model validation artefacts using Context/value Association and XSD schema.

object class

A set of ideas, abstractions, or things in the real world that are identified with explicit boundaries and meaning and whose properties and behavior follow the same rules [ISO 11179] (definition 3.3.22).

property

A characteristic common to all members of an object class [ISO 11179] (definition 3.3.29).

XSD schema

An XML document model definition conforming to the W3C XML Schema language [XSD1][XSD2].

The terms Core Component (CC), Basic Core Component (BCC), Aggregate Core Component (ACC), Association Core Component (ASCC), Business Information Entity (BIE), Basic Business Information Entity (BBIE), and Aggregate Business Information Entity (ABIE) are used in this specification with the meanings given in [CCTS].

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

1.2.3 Symbols and Abbreviations

ABIE

Aggregate Business Information Entity [CCTS]

ASBIE

Association Business Information Entity [CCTS]

BIE

Business Information Entity [CCTS]

BBIE

Basic Business Information Entity [CCTS]

CCTS

Core Component Technical Specification

CVA

Context/value Association

NDR

naming and design rules

TC

Technical Committee

XSD

W3C XML Schema Definition [XSD schema]

1.3 References

[BDNDR] Business Document Naming and Design Rules (BDNDR) Version 1.1. Edited by Kenneth Bengtsson, Erlend Klakegg Bergheim and G. Ken Holman. 29 July 2020. Committee Specification Draft 03. https://docs.oasis-open.org/ubl/Business-Document-NDR/v1.1/csd03/Business-Document-NDR-v1.1-csd03.html. Latest version: https://docs.oasis-open.org/ubl/Business-Document-NDR/v1.1/Business-Document-NDR-v1.1.html.

[CCTS] UN/CEFACT Core Component Technical Specification Version 2.01 https://www.oasis-open.org/committees/download.php/6232/CEFACT-CCTS-Version-2pt01.zip

[CVA] OASIS Context/value association using genericode 1.0. 15 April 2010. Committee Specification 01. http://docs.oasis-open.org/codelist/cs01-ContextValueAssociation-1.0/doc/context-value-association.html.

[genericode] OASIS Code List Representation (Genericode) Version 1.0. 28 December 2007. Committee Specification 01. http://docs.oasis-open.org/codelist/cs-genericode-1.0/doc/oasis-code-list-representation-genericode.html.

[ISO 11179] ISO/IEC 11179-1:2004 Information technology — Specification and standardization of data elements — Part 1: Framework for the specification and standardization of data elements http://standards.iso.org/ittf/PubliclyAvailableStandards/c035343_ISO_IEC_11179-1_2004(E).zip

[ISO 14662] ISO/IEC 14662:2004 Information technology — Open-edi reference model http://standards.iso.org/ittf/PubliclyAvailableStandards/

[RFC 2119] S. Bradner, , Key words for use in RFCs to Indicate Requirement Levels, BCP 14, RFC 2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.

[UBL-2.3] Universal Business Language Version 2.3. Edited by G. Ken Holman. 29 July 2020. Committee Specification Draft 03. https://docs.oasis-open.org/ubl/UBL-2.3.html.

[XML] Extensible Markup Language (XML) 1.0 (Fifth Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, F. Yergeau, Editors, W3C Recommendation, 26 November 2008, http://www.w3.org/TR/2008/REC-xml-20081126/. Latest version available at http://www.w3.org/TR/xml.

[xmldsig] XML-Signature Syntax and Processing Version 1.1, D. E. Eastlake, J. Reagle, D. Solo, F. Hirsch, M. Nyström, T. Roessler, K. Yiu, Editors, W3C Recommendation, 11 April 2013, http://www.w3.org/TR/2013/REC-xmldsig-core1-20130411/. Latest version available at http://www.w3.org/TR/xmldsig-core1.

[XPath 1.0] XML Path Language (XPath) Version 1.0, J. Clark, S. DeRose, Editors, W3C Recommendation, 16 November 1999, http://www.w3.org/TR/1999/REC-xpath-19991116/. Latest version available at http://www.w3.org/TR/xpath.

[XSD1] XML Schema Part 1: Structures Second Edition, H. S. Thompson, D. Beech, M. Maloney, N. Mendelsohn, Editors, W3C Recommendation, 28 October 2004, http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/. Latest version available at http://www.w3.org/TR/xmlschema-1.

[XSD2] XML Schema Part 2: Datatypes Second Edition, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 28 October 2004, http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. Latest version available at http://www.w3.org/TR/xmlschema-2.

2 Context of use and application of these rules

The UBL Technical Committee has established a suite of worksheets in an office spreadsheet in which all business object information is maintained, organized by the types of information bundle. Periodic snapshots of revisions to the spreadsheet are archived in the committee's document repository. Per the Business Document NDR, these information bundles are expressed in terms and concepts of the Core Component Technical Specification [CCTS].

Note

The UBL community site resources page http://ubl.xml.org/wiki/ubl-resources has links to the live copy of the spreadsheet being edited by the committee.

Also per the Business Document NDR, the user data validation artefacts for a document model are twofold: the document structural constraints (e.g. nesting and cardinality) of elements and attributes in XML documents [XML], and the data type qualifications (e.g. coded value domains, a.k.a. code lists). Document structural constraints are expressed using XSD schema semantics and syntax [XSD schema]. Data type qualifications are expressed using CVA associations [Context/value Association] of code list values [genericode] with XML document locations using XPath [XPath 1.0].

The processes engaged by the UBL TC to produce these artefacts are depicted in Figure 2, “UBL NDR process to create validation artefacts”. This diagram shows how the office spreadsheet worksheets are used to organize the CCTS information describing information bundles in a manner suitable for collaboration amongst members of the technical committee. This information is exported in an XML vocabulary using OASIS Open Document Format (ODF). This is then massaged using XSLT to produce a single serialization of the CCTS information in XML using the OASIS genericode vocabulary.

This genericode file is the master copy of all information bundle information and is used to create all of the artefacts. Using XSLT the process produces both an HTML summary of all of the models and a model checking report detailing problems with the CCTS information. These reporting artefacts are used by the collaborators to polish the CCTS information.

The genericode file is also used to create the validation artefacts, again using XSLT.

Figure 2. UBL NDR process to create validation artefacts

[UBL Process Diagram]

3 Information modeling

3.1 Document ABIEs

In UBL 2.3 no document-level ABIE is referenced by an ASBIE. This merely reflects user requirements to date and in a future revision of UBL there may be such references.

There are 86 document ABIEs representing information bundles in UBL 2.3. The class names for these ABIEs are as follows:

Table 1. UBL 2.3 Document ABIEs

  • ApplicationResponse

  • AttachedDocument

  • AwardedNotification

  • BillOfLading

  • BusinessCard

  • CallForTenders

  • Catalogue

  • CatalogueDeletion

  • CatalogueItemSpecificationUpdate

  • CataloguePricingUpdate

  • CatalogueRequest

  • CertificateOfOrigin

  • ContractAwardNotice

  • ContractNotice

  • CreditNote

  • DebitNote

  • DespatchAdvice

  • DigitalAgreement

  • DigitalCapability

  • DocumentStatus

  • DocumentStatusRequest

  • Enquiry

  • EnquiryResponse

  • ExceptionCriteria

  • ExceptionNotification

  • ExportCustomsDeclaration

  • ExpressionOfInterestRequest

  • ExpressionOfInterestResponse

  • Forecast

  • ForecastRevision

  • ForwardingInstructions

  • FreightInvoice

  • FulfilmentCancellation

  • GoodsCertificate

  • GoodsItemItinerary

  • GoodsItemPassport

  • GuaranteeCertificate

  • InstructionForReturns

  • InventoryReport

  • Invoice

  • ItemInformationRequest

  • Order

  • OrderCancellation

  • OrderChange

  • OrderResponse

  • OrderResponseSimple

  • PackingList

  • PriorInformationNotice

  • ProductActivity

  • ProofOfReexportation

  • ProofOfReexportationRequest

  • QualificationApplicationRequest

  • QualificationApplicationResponse

  • Quotation

  • ReceiptAdvice

  • Reminder

  • RemittanceAdvice

  • RequestForQuotation

  • RetailEvent

  • SelfBilledCreditNote

  • SelfBilledInvoice

  • Statement

  • StockAvailabilityReport

  • Tender

  • TenderContract

  • TenderReceipt

  • TenderStatus

  • TenderStatusRequest

  • TenderWithdrawal

  • TendererQualification

  • TendererQualificationResponse

  • TradeItemLocationProfile

  • TransportExecutionPlan

  • TransportExecutionPlanRequest

  • TransportProgressStatus

  • TransportProgressStatusRequest

  • TransportServiceDescription

  • TransportServiceDescriptionRequest

  • TransportationStatus

  • TransportationStatusRequest

  • UnawardedNotification

  • UnsubscribeFromProcedureRequest

  • UnsubscribeFromProcedureResponse

  • UtilityStatement

  • Waybill

  • WeightStatement


3.2 ABIE Library

In UBL 2.3 the common library contains 267 ABIEs for reference as ASBIEs in the document ABIEs, library ABIEs and extension ABIEs.

3.3 Extensions

Per the Business Document NDR every document and library ABIE has as its first child a reference to an optional extension point that can be used to add supplemental information not already defined by UBL to the document.

In the UBL 2.3 distribution there is one extension made available to be used, that being for digital signatures. The information in this extension is modeled primarily using CCTS but with an additional data item modeled by the W3C in [xmldsig]. The components described using CCTS are in a single collection of two ABIEs describing the signature extension ABIE and another ABIE for reference by the extension's ASBIEs.

4 Dictionary information

4.1 Dictionary information overview

The UBL TC uses office spreadsheet worksheets as the collaborative tool to maintain the CCTS model of the UBL documents, the common library and the signature extension. A worksheet row is used for each component. A worksheet column is used for each mandatory and optional CCTS facet. In the UBL distribution this information is split into individual spreadsheets as follows.

The 65 document ABIEs are described using individual spreadsheets that are all found here:

The common library ABIEs are in a single spreadsheet and the signature extension ABIEs are in a single spreadsheet that are both found here:

4.2 Dictionary information values

UBL imposes an additional constraint on the values of recorded CCTS information that all characters used be ASCII characters. This prohibits accented letters, exotic symbols, and stylized punctuation such as "smart quotes". The rationale for this is that the resulting character sequences are then not subject to character encoding vagaries that may not be properly handled by downstream processing applications.

4.3 Abbreviations

UBL abbreviates the following name value words when used in a component's name:

  • "Identifier" is abbreviated as "ID"

UBL considers the following name value words equivalent when used in a component's name:

  • the property term "UUID" is equivalent to the representation term "Identifier"

  • the property term primary noun "URI" is equivalent to the representation term "Identifier"

UBL allows the use of the following abbreviations in name values and in a component's name:

  • CV2 is allowed for "Card Verification Value"

  • UBL is allowed for "Universal Business Language"

  • UNDG is allowed for "United Nations Dangerous Goods"

  • URI is allowed for "Uniform Resource Identifier"

  • UUID is allowed for "Universally Unique Identifier"

  • XPath is allowed for "XML Path Language"

4.4 Dictionary information for BIEs

The CCTS information "Name" value for a BIE definition is labeled "UBL Name" in the UBL spreadsheets.

In addition to the CCTS columns indicated as having to be maintained by these NDR, the UBL spreadsheets contain the following columns of additional information used and recorded during analysis, all of which are optional:

  • Examples

  • UN/TDED Code

  • Current Version

  • Analyst Notes

  • CCL Dictionary Entry Name

  • Context: Business Process

  • Context: Region (Geopolitical)

  • Context: Official Constraints

  • Context: Product

  • Context: Industry

  • Context Role

  • Context: Supporting Role

  • Context: System Constraint

  • Editor's Notes

  • Changes from Previous Version

Object classes are never qualified in UBL. Accordingly, the "Object Class Qualifier" and "Associated Object Class Qualifier" columns are present but always empty in instances of the spreadsheets.

Every Document ABIE contains as its first four BBIE children, in order and all with property Term Primary Noun "Identifier" and Representation Term "Identifier", items with the following Property Term Possessive Nouns and cardinality "0..1":

  • UBL Version

  • Customization

  • Profile

  • Profile Execution

Every Document ABIE contains a Signature ASBIE with cardinality "0..n" to the Signature ABIE.

4.5 Structure of an ABIE

These NDR to not vary from the Business Document NDR in this regard. This section of the documentation exists to maintain alignment of sections.

5 XML validation artefacts

5.1 XML validation artefacts overview

While the information bundles are described using CCTS principles, it is the document models that govern the structure of documents expressing in a machine-readable format the information described by the bundles. These NDR provide for expressing the model of an information bundle using validation artefacts that describe constraints on the structure and content of documents. Validation processes report violations of these model constraints found in a document.

There are two types of validation artefacts. W3C XSD schemas are used to validate the structure of elements and the structure of data content. OASIS CVA expressions and OASIS genericode files are used to validate the values of data content.

The UBL distribution organizes the documented XSD schemas (with BIE XSD annotations) under the xsd/ subdirectory and the runtime XSD schemas (without BIE XSD annotations) under the xsdrt/ subdirectory:

The CVA file and formatted report are distributed in the cva/ subdirectory:

The genericode files referenced by the CVA file are distributed in the gc/ subdirectories of each of the UBL 2.2, UBL 2.1, and UBL 2.0 distributions:

The UBL CVA and genericode files are compiled into an XSLT stylesheet expression for runtime testing against XML instances that have been validated using the UBL XSD schemas. This stylesheet is named UBL-DefaultDTQ-2.3.xsl and is distributed in the val/ subdirectory:

5.2 Namespaces

The following namespace URI strings are associated with the indicated documentary namespace prefixes:

Table 2. UBL Namespaces

(no prefix)Document ABIE namespaces use the component name of the ABIE XXXXXXXX as follows:

urn:oasis:names:specification:ubl:schema:xsd:XXXXXXXX-2

cbcurn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2
cacurn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2
exturn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2
sigurn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2
sacurn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2
sbcurn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2
qdturn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2
udturn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2
ccts-ccturn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2
cctsurn:un:unece:uncefact:documentation:2

5.3 XSD import/include tree

Figure 3, “UBL import/include hierarchy of XSD schema expressions” depicts the UBL implementation of the import and include directives described in the naming and design rules.

Figure 3. UBL import/include hierarchy of XSD schema expressions

[XSD Schema Structure]

5.4 Schema fragment annotations

The documented XSD schemas include CCTS information in annotations of the Library and Document ABIE complex types (not of the element declarations). Only those values found in the columns referenced in Section 4.4, “Dictionary information for BIEs” are included. An example of each of an ABIE, BBIE and ASBIE is as follows:

<xsd:complexType name="WinningPartyType">
  <xsd:annotation>
     <xsd:documentation>
        <ccts:Component>
           <ccts:ComponentType>ABIE</ccts:ComponentType>
           <ccts:DictionaryEntryName>Winning Party. 
           Details</ccts:DictionaryEntryName>
           <ccts:Definition>A party that is identified as the awarded by
           a tender result.</ccts:Definition>
           <ccts:ObjectClass>Winning Party</ccts:ObjectClass>
        </ccts:Component>
     </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
     <xsd:element ref="cbc:Rank" minOccurs="0" maxOccurs="1">
        <xsd:annotation>
           <xsd:documentation>
              <ccts:Component>
                 <ccts:ComponentType>BBIE</ccts:ComponentType>
                 <ccts:DictionaryEntryName>Winning Party. Rank.
                 Text</ccts:DictionaryEntryName>
                 <ccts:Definition>Indicates the rank obtained in the
                 award.</ccts:Definition>
                 <ccts:Cardinality>0..1</ccts:Cardinality>
                 <ccts:ObjectClass>Winning Party</ccts:ObjectClass>
                 <ccts:PropertyTerm>Rank</ccts:PropertyTerm>
                 <ccts:RepresentationTerm>Text</ccts:RepresentationTerm>
                 <ccts:DataType>Text. Type</ccts:DataType>
              </ccts:Component>
           </xsd:documentation>
        </xsd:annotation>
     </xsd:element>
     <xsd:element ref="cac:Party" minOccurs="1" maxOccurs="1">
        <xsd:annotation>
           <xsd:documentation>
              <ccts:Component>
                 <ccts:ComponentType>ASBIE</ccts:ComponentType>
                 <ccts:DictionaryEntryName>Winning Party.
                 Party</ccts:DictionaryEntryName>
                 <ccts:Definition>Information about an organization,
                 sub-organization, or individual fulfilling a role in a
                 business process.</ccts:Definition>
                 <ccts:Cardinality>1</ccts:Cardinality>
                 <ccts:ObjectClass>Winning Party</ccts:ObjectClass>
                 <ccts:PropertyTerm>Party</ccts:PropertyTerm>
                 <ccts:AssociatedObjectClass>Party</ccts:Associated
ObjectClass>
                 <ccts:RepresentationTerm>Party</ccts:RepresentationTerm>
              </ccts:Component>
           </xsd:documentation>
        </xsd:annotation>
     </xsd:element>
  </xsd:sequence>
</xsd:complexType>

Every schema fragment generated for UBL 2.3 includes an XML comment at both the beginning of the document and the end of the document. These comments are present in both the documented schemas and the runtime schemas.

The comment at the beginning of every schema fragment includes identification information and revision metadata, as in this example from the common aggregate components fragment:

<!--
  Library:           OASIS Universal Business Language (UBL) 2.3 OS
                     http://docs.oasis-open.org/ubl/os-UBL-2.3/
  Release Date:      14 April 2020
  Module:            xsd/common/UBL-CommonAggregateComponents-2.3.xsd
  Generated on:      2020-04-03 17:20z
  Copyright (c) OASIS Open 2020. All Rights Reserved.
-->

The comment at the end of the document is a detailed copyright notice as follows:

<!-- ===== Copyright Notice ===== --><!--
  OASIS takes no position regarding the validity or scope of any 
  intellectual property or other rights that might be claimed to pertain 
  to the implementation or use of the technology described in this 
  document or the extent to which any license under such rights 
  might or might not be available; neither does it represent that it has 
  made any effort to identify any such rights. Information on OASIS's 
  procedures with respect to rights in OASIS specifications can be 
  found at the OASIS website. Copies of claims of rights made 
  available for publication and any assurances of licenses to be made 
  available, or the result of an attempt made to obtain a general 
  license or permission for the use of such proprietary rights by 
  implementors or users of this specification, can be obtained from 
  the OASIS Executive Director.

  OASIS invites any interested party to bring to its attention any 
  copyrights, patents or patent applications, or other proprietary 
  rights which may cover technology that may be required to 
  implement this specification. Please address the information to the 
  OASIS Executive Director.
  
  This document and translations of it may be copied and furnished to 
  others, and derivative works that comment on or otherwise explain 
  it or assist in its implementation may be prepared, copied, 
  published and distributed, in whole or in part, without restriction of 
  any kind, provided that the above copyright notice and this 
  paragraph are included on all such copies and derivative works. 
  However, this document itself may not be modified in any way, 
  such as by removing the copyright notice or references to OASIS, 
  except as needed for the purpose of developing OASIS 
  specifications, in which case the procedures for copyrights defined 
  in the OASIS Intellectual Property Rights document must be 
  followed, or as required to translate it into languages other than 
  English. 

  The limited permissions granted above are perpetual and will not be 
  revoked by OASIS or its successors or assigns. 

  This document and the information contained herein is provided on 
  an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, 
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 
  WARRANTY THAT THE USE OF THE INFORMATION HEREIN 
  WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 
  WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 
  PARTICULAR PURPOSE.    
-->

Throughout the fragments are short XML comments delineating sections with declarations for different purposes.

The built-in version annotation of the schema document element is used to reflect the version of the UBL release. For example, this is used for every schema fragment in the UBL 2.3 release:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" version="2.3" ...

5.5 Schema fragments and declarations

The UBL common ABIE library schema fragment is named UBL-CommonAggregateComponents-2.3.xsd in UBL 2.3.

Each UBL document ABIE schema fragment is named UBL-XXXXX-2.3.xsd in UBL 2.3, where XXXXX is the component name of the document ABIE.

There is only one addition in the UBL implementation of declarations as in the naming and design rules. The element declaration in a document ABIE includes an annotation as follows:

<xsd:annotation>
   <xsd:documentation>This element MUST be conveyed as the root element 
in any instance document based on this Schema expression</xsd:documentation>
</xsd:annotation>

The UBL common BBIE library schema fragment is named UBL-CommonBasicComponents-2.3.xsd in UBL 2.3.

There are no differences in the UBL implementation of declarations as in the naming and design rules.

5.6 Extension schema fragments and declarations

The UBL common extension library schema fragment is named UBL-CommonExtensionComponents-2.3.xsd in UBL 2.3.

The UBL extension collection element is named "UBLExtensions" and its type is named "UBLExtensionsType". It is comprised of one or more UBL extension elements.

The UBL extension element is named "UBLExtension" and its type is named " UBLExtensionType". It is comprised of the following elements, in order, each with a type named by the element name suffixed with "Type", each with a cardinality of 0..1, and those declared in the module are declared with the given unqualified data type:

  • cbc:ID (from the common library)

    • An identifier for the Extension assigned by the creator of the extension.

  • cbc:Name (from the common library)

    • A name for the Extension assigned by the creator of the extension.

  • ExtensionAgencyID (of unqualified data type "Identifier. Type")

    • An agency that maintains one or more Extensions.

  • ExtensionAgencyName (of unqualified data type "Text. Type")

    • The name of the agency that maintains the Extension.

  • ExtensionVersionID (of unqualified data type "Identifier. Type")

    • The version of the Extension.

  • ExtensionAgencyURI (of unqualified data type "Identifier. Type")

    • A URI for the Agency that maintains the Extension.

  • ExtensionURI (of unqualified data type "Identifier. Type")

    • A URI for the Extension.

  • ExtensionReasonCode (of unqualified data type "Code. Type")

    • A code for reason the Extension is being included.

  • ExtensionReason (of unqualified data type "Text. Type")

    • A description of the reason for the Extension.

  • ExtensionContent (this type is declared in an included extension content data type schema fragment)

    • The definition of the extension content.

The UBL implementation of the extension content data type schema fragment imposes "lax" processing on a single, mandatory element of type xsd:any. The schema fragment imports the UBL common digital signature extension in order to impose that extension's schema constraints when the signature extension element is used.

The UBL common digital signature extension schema fragment is named UBL-CommonSignatureComponents-2.3.xsd in UBL 2.3.

5.7 Qualified data types schema fragment and declarations

The UBL qualified data type schema fragment is named UBL-QualifiedDataTypes-2.3.xsd in UBL 2.3.

The UBL implementation of qualified data types is pass-through. There are no data type qualifications expressed in XSD semantics. Data type qualifications are validated solely through the expression of code list constraints using CVA expressions and genericode code list expressions.

5.8 Unqualified data types schema fragment and declarations

The UBL unqualified data type schema fragment in UBL 2.3 is the BDNDR 1.1 fragment named BDNDR-UnqualifiedDataTypes-1.1.xsd.

5.9 CCTS Core Component Types schema

The UBL CCTS Core Component Types schema fragment in UBL 2.3 is the BDNDR 1.1 fragment named BDNDR-CCTS_CCT_SchemaModule-1.1.xsd.

5.10 XML attribute names

These NDR do not vary from the Business Document NDR in this regard. This section of the documentation exists to maintain alignment of subsequent sections.

5.11 Data type qualifications

The data type qualifications in UBL 2.3 reference code lists whose name matches a name found in the Data Type Qualification information item of all BBIEs. These code lists are found in the following directories:

For completeness, the Binary Object. Mime. Code and Measure. Unit. Code lists, using the names "BinaryObjectMime" and "UnitOfMeasure" respectively, also are included from these directories:

Instance metadata is described for the supplementary components as follows:

<InstanceMetadataSets>
<Annotation>
  <Description>
    <x:p>
      A supplementary component is a piece of metadata describing a
      property of the list of values in which a particular value is
      found.  For example, each code list of currency values has a
      version and when a currency value is specified in a UBL document
      it may be important to specify which version of the currency 
      code list that value is found.  By knowing the list from which a
      value is found, the semantics representated by that value are
      unambiguous.
    </x:p>
    <x:p>
      These sets of supplementary components describe where instance-level
      metadata is found that contains values of list-level metadata from
      genericode files.  Each set is identified in a context using that
      set's unique <x:samp>xml:id=</x:samp> attribute.
    </x:p>
    <x:p>
      Each component pairs an XPath address of the supplementary component
      (specified in <x:samp>address=</x:samp>) relative to the item with
      the code list value in the UBL document, with the XPath address of
      the corresponding list-level metadata item in the genericode file
      (specified in <x:samp>identification=</x:samp>) relative to the
      <x:samp>&lt;Identification></x:samp> element in the code
      list file.
    </x:p>
    <x:p>
      All supplementary components in UBL are defined by the UN/CEFACT Core
      Component Technical Specification (CCTS) Version 2.01 dated
      15 November 2003
      <x:a href="http://www.unece.org/cefact/ebxml/CCTS_V2-01_Final.pdf">
    <x:samp>http://www.unece.org/cefact/ebxml/CCTS_V2-01_Final.
               pdf</x:samp>.</x:a>
      Table 8-2 "Approved Core Component Type Content
      and Supplementary Components" lists the various supplementary
      components available.  The UN/CEFACT 
      UnqualifiedDataTypeSchemaModule-2.0.xsd schema fragment specifies
      the names of the attributes for supplementary components.
    </x:p>
  </Description>
</Annotation>
<InstanceMetadataSet xml:id="cctsV2.01-amount">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Amount. Type</x:samp> supplementary component.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="../@currencyCodeListVersionID"
                    identification="Version"/>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-binary">
  <Annotation>
    <Description>
      <x:p>
        There are no supplementary components for the
        <x:samp>Binary Object. Type</x:samp>.
      </x:p>
    </Description>
  </Annotation>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-code">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Code. Type</x:samp> supplementary components.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="@listName"
                    identification="LongName[not(@Identifier='listID')]"/>
  <InstanceMetadata address="@listID"
                    identification="LongName[@Identifier='listID']"/>
  <InstanceMetadata address="@listVersionID"
                    identification="Version"/>
  <InstanceMetadata address="@listSchemeURI"
                    identification="CanonicalUri"/>
  <InstanceMetadata address="@listURI"
                    identification="LocationUri"/>
  <InstanceMetadata address="@listAgencyName"
                    identification="Agency/LongName"/>
  <InstanceMetadata address="@listAgencyID"
                    identification="Agency/Identifier"/>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-identifier">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Identifier. Type</x:samp> supplementary components.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="@schemeName"
                    identification="LongName[not(@Identifier='listID')]"/>
  <InstanceMetadata address="@schemeID"
                    identification="LongName[@Identifier='listID']"/>
  <InstanceMetadata address="@schemeVersionID"
                    identification="Version"/>
  <InstanceMetadata address="@schemeURI"
                    identification="CanonicalUri"/>
  <InstanceMetadata address="@schemeDataURI"
                    identification="LocationUri"/>
  <InstanceMetadata address="@schemeAgencyName"
                    identification="Agency/LongName"/>
  <InstanceMetadata address="@schemeAgencyID"
                    identification="Agency/Identifier"/>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-measure">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Measure. Type</x:samp> supplementary component.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="../@unitCodeListVersionID"
                    identification="Version"/>
</InstanceMetadataSet>
<InstanceMetadataSet xml:id="cctsV2.01-quantity">
  <Annotation>
    <Description>
      <x:p>
        The <x:samp>Quantity. Type</x:samp> supplementary components.
      </x:p>
    </Description>
  </Annotation>
  <InstanceMetadata address="../@unitCodeListID"
                    identification="LongName[@Identifier='listID']"/>
  <InstanceMetadata address="../@unitCodeListAgencyName"
                    identification="Agency/LongName"/>
  <InstanceMetadata address="../@unitCodeListAgencyID"
                    identification="Agency/Identifier"/>
</InstanceMetadataSet>
</InstanceMetadataSets>

The following contexts are described for attributes:

  • every currencyID attribute is a context for the currency code lists

  • every mimeCode attribute is a context for the binary object mime code lists

  • every unitCode attribute of those BBIEs with a Data Type value of "Measure" is a context for the unit of measure code lists

  • every unitCode attribute of those BBIEs with a Data Type value of "Quantity" is a context for the unit of measure code lists

The following contexts are described for elements:

  • every element of those BBIEs with a Qualified Data Type value is a context for a code list with the same name as the value

Appendix A Release notes (Non-Normative)

A.1 Availability

Online and downloadable versions of this release are available from the locations specified at the top of this document.

A.2 Status of this release

Release of this package marks the completion of this committee note.

The UBL Technical Committee welcomes input from the user community regarding this note. See Status at the beginning of this document for procedures to be used in submitting comments to the Committee. Note that in accordance with OASIS policies regarding intellectual property, the UBL TC cannot accept input from persons outside the UBL TC (including OASIS members) unless it is submitted via the comment list.

A.3 Package structure

This Committee Note Draft 01 is published as a zip archive in the https://docs.oasis-open.org/ubl/UBL-NDR/v3.1/cnd01/ directory. Unzipping this archive creates a directory tree containing a number of files and subdirectories. Note that while the two XML files comprise the revisable version of this specification, this revisable XML may not be directly viewable in all currently available web browsers.

The base directory has the following files:

UBL-NDR-v3.1-cnd01.xml

The revisable form of the document.

UBL-NDR-v3.1-cnd01.html

An HTML rendering of the document.

UBL-NDR-v3.1-cnd01.pdf

A PDF rendering of the document.

These are the subdirectories in the package:

art

Diagrams and illustrations used in this specification

db

DocBook stylesheets for viewing in HTML the XML of this work product

Appendix B Acknowledgements (Non-Normative)

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Todd Albers, Federal Reserve Bank of Minneapolis
Rui Barros, Individual
Oriol Bausa Peris, Individual
Kenneth Bengtsson, Individual
Erlend Klakegg Bergheim, Norwegian Digitalisation Agency
Peter Borresen, ClearView Trade
Andrea Caccia, Individual
Ger Clancy, IBM
Kees Duvekot, RFS Holland Holding B.V.
Martin Forsberg, Swedish Association of Local Authorities & Regions
Cecile Guasch, Individual
Philip Helger, Individual
Ken Holman, Crane Softwrights Ltd.
Yves Jordan, Publications Office of the European Union
Kari Korpela, Individual
Ole Madsen, Danish Business Authority
Natalie Muric, Publications Office of the European Union
Levine Naidoo, IBM
Enric Torregrosa, everis, S.L.U.
Matt Vickers, Xero

Appendix C Additional production processes

C.1 CCTS serialization

The UBL distribution includes the following serializations of CCTS information expressed using the OASIS genericode XML vocabulary:

http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/

  • UBL-Entities-2.1.gc - all document ABIEs and common library ABIEs

  • UBL-Signature-Entities-2.1.gc - all signature extension ABIEs

Note

The rationale is that while OASIS genericode was designed for use with code lists, it is a suitable XML serialization of any sparsely-populated tabular construct. The table of CCTS information in a model is sparsely-populated with numerous undefined cells.

In addition to a column for each piece of CCTS information saved for each BIE, there is a column named "ModelName" populated by every row. The value in this column indicates the model in which the BIE is defined. The values include "UBL-CommonLibrary-2.1" for all BIEs defined in the common library, and "UBL-XXXX-2.1" where "XXXX" is the component name of the ABIE for the object class (e.g. "FreightInvoice") for the document ABIE and its child BIEs.

The key column in the genericode serialization is declared to be the "DictionaryEntryName" column.

The genericode specification imposes no order on the values in a row. In UBL 2.1 the order happens to correspond to the order of column declarations.

An example serialization of all three kinds of BIE is as follows for the common library ABIE "Winning Party", one of 8 ABIEs in UBL 2.1 that have a single BBIE and a single ASBIE (note that commented numbers indicate the row number from the spreadsheet; this supplemental information is not required to be included but exists as a convenient reference):

<Row><!--2709-->
   <Value ColumnRef="ModelName">
      <SimpleValue>UBL-CommonLibrary-2.3</SimpleValue>
   </Value>
   <Value ColumnRef="ComponentName">
      <SimpleValue>WinningParty</SimpleValue>
   </Value>
   <Value ColumnRef="Definition">
      <SimpleValue>A party that is identified as the 
awarded by a tender result.</SimpleValue>
   </Value>
   <Value ColumnRef="DictionaryEntryName">
      <SimpleValue>Winning Party. Details</SimpleValue>
   </Value>
   <Value ColumnRef="ObjectClass">
      <SimpleValue>Winning Party</SimpleValue>
   </Value>
   <Value ColumnRef="ComponentType">
      <SimpleValue>ABIE</SimpleValue>
   </Value>
   <Value ColumnRef="CurrentVersion">
      <SimpleValue>2.1</SimpleValue>
   </Value>
</Row>
<Row><!--2710-->
   <Value ColumnRef="ModelName">
      <SimpleValue>UBL-CommonLibrary-2.3</SimpleValue>
   </Value>
   <Value ColumnRef="ComponentName">
      <SimpleValue>Rank</SimpleValue>
   </Value>
   <Value ColumnRef="Cardinality">
      <SimpleValue>0..1</SimpleValue>
   </Value>
   <Value ColumnRef="Definition">
      <SimpleValue>Indicates the rank obtained in the award.</SimpleValue>
   </Value>
   <Value ColumnRef="DictionaryEntryName">
      <SimpleValue>Winning Party. Rank. Text</SimpleValue>
   </Value>
   <Value ColumnRef="ObjectClass">
      <SimpleValue>Winning Party</SimpleValue>
   </Value>
   <Value ColumnRef="PropertyTermPrimaryNoun">
      <SimpleValue>Rank</SimpleValue>
   </Value>
   <Value ColumnRef="PropertyTerm">
      <SimpleValue>Rank</SimpleValue>
   </Value>
   <Value ColumnRef="RepresentationTerm">
      <SimpleValue>Text</SimpleValue>
   </Value>
   <Value ColumnRef="DataType">
      <SimpleValue>Text. Type</SimpleValue>
   </Value>
   <Value ColumnRef="ComponentType">
      <SimpleValue>BBIE</SimpleValue>
   </Value>
   <Value ColumnRef="CurrentVersion">
      <SimpleValue>2.1</SimpleValue>
   </Value>
</Row>
<Row><!--2711-->
   <Value ColumnRef="ModelName">
      <SimpleValue>UBL-CommonLibrary-2.3</SimpleValue>
   </Value>
   <Value ColumnRef="ComponentName">
      <SimpleValue>Party</SimpleValue>
   </Value>
   <Value ColumnRef="Cardinality">
      <SimpleValue>1</SimpleValue>
   </Value>
   <Value ColumnRef="Definition">
      <SimpleValue>Information about an organization,
sub-organization, or individual fulfilling a role in
a business process.</SimpleValue>
   </Value>
   <Value ColumnRef="DictionaryEntryName">
      <SimpleValue>Winning Party. Party</SimpleValue>
   </Value>
   <Value ColumnRef="ObjectClass">
      <SimpleValue>Winning Party</SimpleValue>
   </Value>
   <Value ColumnRef="PropertyTerm">
      <SimpleValue>Party</SimpleValue>
   </Value>
   <Value ColumnRef="RepresentationTerm">
      <SimpleValue>Party</SimpleValue>
   </Value>
   <Value ColumnRef="AssociatedObjectClass">
      <SimpleValue>Party</SimpleValue>
   </Value>
   <Value ColumnRef="ComponentType">
      <SimpleValue>ASBIE</SimpleValue>
   </Value>
   <Value ColumnRef="CurrentVersion">
      <SimpleValue>2.1</SimpleValue>
   </Value>
</Row>

C.2 Reporting

C.2.1 HTML summary reports

The UBL distribution includes a number of HTML summary files reporting filtered content from the CCTS information. These files are found in the directory:

http://docs.oasis-open.org/ubl/os-UBL-2.3/mod/summary/

  • readme-Reports.html - report descriptions and usage, legend information, and a summary of links to all of the HTML summary files

  • http://docs.oasis-open.org/ubl/os-UBL-2.3/mod/summary/reports/ - the subdirectory with all of the reports

    • All-UBL-2.3-Documents.html - an unfiltered report of the entire CCTS information content

    • UBL-XXXX-2.3.html - a filtered report for the document type "XXXX" as the component name of the ABIE of the object class of the Document ABIE (e.g. OrderResponseSimple) in which all common library CCTS information not found to be used somewhere in the document type is not included

C.2.2 Model check report

Not included in the UBL distribution is a textual report the UBL TC utilizes as a "model check" that has analyzed the CCTS information reporting any violations of these Naming and Design Rules or any anomalies that may inadvertently interfere with the production of the validation artefacts. An example of such inadvertent interference is the use of a double-hyphen "--" in any description field. Such a sequence interferes with generating XML-based artefacts where some content might be, or later want to be, placed in an XML comment. Participants can be warned to revise field values so as not to include this or other sensitive character sequences.

UBL-NDR-v3.1-cnd01
Non-standards Track

Copyright © OASIS Open 2020. All Rights Reserved.
29 July 2020