]>
&name; &version; Universal Business Language (UBL) 2.0 Naming and Design Rules &this-loc;/&name;.html &this-loc;/&name;.pdf &this-loc;/&name;.xml &previous-loc;.doc &previous-loc;.htm &previous-loc;.pdf &latest-loc;/UBL-2.0-NDR.html &latest-loc;/UBL-2.0-NDR.pdf &latest-loc;/UBL-2.0-NDR.xml OASIS Universal Business Language (UBL) TC Mike Grimley US Navy
MJGrimley@acm.org
 Mavis Cournane Cognitran Limited
mavis.Cournane@cognitran.com
 Jon Bosak Pinax
bosak@pinax.com
 Tim McGrath Document Engineering       Services
tim.mcgrath@documentengineeringservices.com
 Abstract This specification documents the naming and design rules and guidelines for the construction of XML components for the UBL vocabulary. 6 November 2009 Status This document was last revised or approved by the UBL TC on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule. Technical Committee members should send comments on this specification to the Technical Committee's email list. Others should send comments to the Technical Committee by using the "Send A Comment" button on the Technical Committee's web page at . For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (). The non-normative errata page (if any) for this specification is located at . Notices Copyright © OASIS® Open 2001-2009. All Rights Reserved. All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so. OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims. The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.
Introduction XML is often described as the lingua franca of e-commerce. The implication is that by standardizing on XML, enterprises will be able to trade with anyone, any time, without the need for the costly custom integration work that has been necessary in the past. But this vision of XML-based "plug-and-play" commerce is overly simplistic. Of course XML can be used to create electronic catalogs, purchase orders, invoices, shipping notices, and the other documents needed to conduct business. But XML by itself doesn't guarantee that these documents can be understood by any business other than the one that creates them. XML is only the foundation on which additional standards can be defined to achieve the goal of true interoperability. The Universal Business Language (UBL) initiative is the next step in achieving this goal. The task of creating a universal XML business language is a challenging one. Most large enterprises have already invested significant time and money in an e-business infrastructure and are reluctant to change the way they conduct electronic business. Furthermore, every company has different requirements for the information exchanged in a specific business process, such as procurement or supply-chain optimization. A standard business language must strike a difficult balance, adapting to the specific needs of a given company while remaining general enough to let different companies in different industries communicate with each other. The UBL effort addresses this problem by building on the work of the electronic business XML (ebXML) initiative. UBL is organized as an OASIS Technical Committee to guarantee a rigorous, open process for the standardization of the XML business language. The development of UBL within OASIS also helps ensure a fit with other essential ebXML specifications. This specification documents the rules and guidelines for the naming and design of XML components for the UBL library. It contains only rules that have been agreed on by the OASIS UBL Technical Committee. Consumers of the Naming and Design Rules Specification should consult previous UBL position papers that are available at . These provide a useful background to the development of the current rule set. Audiences This document has several primary and secondary targets that together constitute its intended audience. Our primary target audience is the members of the UBL Technical Committee. Specifically, the UBL Technical Committee uses the rules in this document to create normative form schemas for business transactions. Other XML schema developers may find the rules contained herein sufficiently useful to merit consideration for adoption as, or infusion into, their own approaches to XML schema development. Scope This specification conveys a normative set of XML schema design rules and naming conventions for the creation of UBL schemas for business documents being exchanged between two parties using XML constructs defined in accordance with the ebXML Core Components Technical Specification. Guiding Principles The UBL NDR primary objectives are to provide the UBL TC with a set of unambiguous, consistent rules for the development of extensible, reusable UBL schemas.
Terminology and Notation 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 Internet Engineering Task Force (IETF) Request for Comments (RFC) 2119. Non-capitalized forms of these words are used in the regular English sense. Definition A formal definition of a term. Definitions are normative. Example An example of a definition or a rule. Examples are informative. Note Explanatory information. Notes are informative. RRRn Identifier of a rule to which an XML schema must comply in order to be UBL conformant. The value RRR is a prefix to categorize the type of rule where the value of RRR is as defined in , and n (1..n) is the sequential number of the rule within its category. To ensure continuity across versions of the specification, rule numbers that are deleted in future versions will not be re-issued, and any new rules will be assigned the next higher number — regardless of location in the text. Only rules and definitions are normative; all other text is explanatory. Rule Prefix Value Rule Prefix Value ATD Attribute Declaration CDL Code List CTD ComplexType Definition CTN ComplexType Naming Rules DOC Documentation ELD Element Declaration ELN Element Naming GNR General Naming GTD General Type Definition GXS General XML Schema IND Instance Document MDC Modeling Constraints NMC Naming Constraints NMS Namespace RED Root Element Declaration SSM Schema Structure Modularity VER Versioning
The term "XSD" is used throughout this document to refer to Parts 1 and 2 of the W3C XML Schema Definition Language (XSD) Recommendation.
Normative References [CCTS] ISO 15000-5 ebXML Core Components Technical Specification. [ISONaming] ISO/IEC 11179, Final committee draft, Parts 1-6. [RFC 2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, , IETF RFC 2119, March 1997. [XML] Extensible Markup Language (XML) 1.0 (Second Edition), W3C Recommendation, October 6, 2000. [XSD] XML Schema, W3C Recommendations Parts 0, 1, and 2, 2 May 2001.
Non-normative References [SchCust] Guidelines for the Customization of UBL v1.0 Schemas, , an informative annex to the UBL 1.0 Standard.
Relationship to ebXML Core Components UBL employs the methodology and model described in ISO TS 15000-5:2005 -- ebXML Core Components Technical Specification, Version 2.01 [CCTS] to build the UBL Component Library. CCTS defines a new paradigm in the design and implementation of reusable, syntactically neutral information building blocks. Syntax-neutral Core Components are intended to form the basis of business information standardization efforts and to be realized in syntactically specific instantiations such as ANSI ASC X12, UN/EDIFACT, and various XML representations such as UBL. Context-neutral and context-specific building blocks are the essence of the Core Components specification. The context-neutral components are called Core Components. A Core Component is defined in CCTS as "a building block for the creation of a semantically correct and meaningful information exchange package. It contains only the information pieces necessary to describe a specific concept". Figure 1 illustrates the various pieces of the overall Core Components metamodel. The context-specific components are called Business Information Entities (BIEs). A BIE is defined in CCTS as "a piece of business data or a group of pieces of business data with a unique Business Semantic definition". Figure 2 illustrates the various pieces of the overall BIE metamodel and its relationship to the Core Components metamodel. As shown here, there are different types of Core Components and BIEs, each of which has specific relationships to the other components and entities. The context-neutral Core Components establish the formal relationship between the various context-specific BIEs.
Core Components and Datatypes Metamodel
Business Information Entities Basic Definition Model
Mapping Business Information Entities to XSD UBL consists of a library of CCTS BIEs, each of which is mapped to an XSD construct (See Figure 3).
UBL Document Metamodel
A BIE can be a CCTS Aggregate Business Information Entity (ABIE), a CCTS Basic Business Information Entity (BBIE), or a CCTS Association Business Information Entity (ASBIE). In understanding the logic of the UBL binding of BIEs to XSD expressions, it is important to understand the basic constructs of the BIEs and their relationships as shown in Figure 2. The ABIEs are treated as objects and are defined as xsd:complexTypes. The BBIEs are treated as properties of the ABIE and are found in the content model of the ABIE as a referenced xsd:element. The BBIEs are based on reusable CCTS Basic Business Information Entity Properties (BBIE Properties), which are defined as xsd:complexTypes. A BBIE Property represents an intrinsic property of an ABIE. BBIE Properties are linked to a data type. UBL uses two kinds of data types — unqualified datatypes, which are provided by the UN/CEFACT Unqualified Data Type (UDT) schema module, and Qualified Data Types, which are defined by UBL. UBL's use of the UN/CEFACT UDT schema module is primarily confined to its importation. It must not be assumed that UBL's adoption of the UDT schema module extends to any of the UN/CEFACT rules relating to use of the UDT. The CCTS Unqualified Data Types correspond to CCTS Representation Terms. The UBL Qualified Data Types are derived from CCTS Unqualified Data Types with restrictions to the allowed values or ranges of the corresponding CCTS Content Component or CCTS Supplementary Component (see CCTS for explanations of these terms). CCTS defines an approved set of primary and secondary representation terms. However, these representation terms are simply naming conventions to identify the data type of an object, not actual constructs. A CCTS data type defines the set of values that can be used for a particular Basic Core Component Property or Basic Business Information Entity Property data type. The CCTS data types can be either unqualified (no restrictions applied) or qualified through the application of restrictions. These data types form the basis for the various XSD simple and complex types defined in the UBL schemas. CCTS supports data types that are qualified, i.e., it enables users to define their own data types for their syntax-neutral constructs. Thus, CCTS data types allow UBL to identify restrictions for elements when restrictions to the corresponding CCTS Content Component or CCTS Supplementary Component are required. There are two kinds of BIE Properties — Basic and Association. A CCTS Association BIE Property (ASBIE Property) represents an extrinsic property — in other words, an association from one ABIE instance to another ABIE instance. It is the ASBIE Property that expresses the relationship between ABIEs. Due to their unique extrinsic association role, ASBIEs are not defined as xsd:complexTypes; rather, they are either declared as elements that are then bound to the xsd:complexType of the associated ABIE, or they are reclassified as ABIEs. BBIEs define the intrinsic structure of an ABIE. These BBIEs are the "leaf" types in the system in that they contain no other BIEs. A BBIE must have a CCTS Core Component Type. All CCTS Core Component Types are low-level types such as Identifiers and Dates. A CCTS Core Component Type describes these low-level types for use by CCTS Core Components, and (in parallel) a CCTS data type, corresponding to that CCTS Core Component Type, describes these low-level types for use by BBIEs. Every CCTS Core Component Type has a single CCTS Content Component and one or more CCTS Supplementary Components. A CCTS Content Component is of some Primitive Type. All CCTS Core Component Types and their corresponding content and supplementary components are predefined in CCTS. UBL has developed an XSD schema module that declares each of the predefined CCTS Core Component Types as an xsd:complexType or xsd:simpleType and declares each CCTS Supplementary Component as an xsd:attribute or uses the predefined facets of the built-in XSD datatypes for those that are used as the base expression for an xsd:simpleType.
General XML Constructs This chapter defines UBL rules related to general XML constructs, including overall schema structure, naming and modeling constraints, reusability, namespaces, versioning, modularity, and documentation.
Overall Schema Structure A key aspect of developing standards is to ensure consistency in their implementation. Therefore, it is essential to provide a mechanism that will guarantee that each occurrence of a UBL conformant schema will have the same look and feel.
[GXS1] Except in the case of extension, where the "UBL Extensions" element is used, UBL schemas SHOULD conform to the following physical layout as applicable: See Figure 4.
Physical layout
As shown above, a UBL schema should contain a comment block at the top of the schema that functions as a "schema header".
Element Declarations within Document Schemas A document schema is a schema within a specific namespace that conveys the business document functionality of that namespace. The document schema declares a target namespace and is likely to include (xsd:include) internal schema modules or import (xsd:import) external schema modules. Each namespace will have one, and only one, major version of a document schema as well as any related minor versions. In order to facilitate the management and reuse of UBL constructs, all global elements, excluding the root element of the document schema, must be declared in either the Common Aggregate Components (CAC) or Common Basic Components (CBC) schema modules and referenced from within the document schema.
Root Element Only a single global element is declared inside a UBL document schema. The single global element is the root element of every conforming instance.
[RED2] The root element MUST be the only global element declared in the document schema.
Naming and Modeling Constraints UBL has the following naming and modeling constraints.
Naming Constraints A primary aspect of the UBL library documentation is its spreadsheet models. The entries in these spreadsheet models fully define the constructs available for use in UBL business documents. The spreadsheet entries contain fully conformant CCTS Dictionary Entry Names (DENs) as well as truncated UBL XML element names developed in conformance with the rules in Section 4. The XML element name is the short form of the DEN. The rules for element naming differ from the rules for DEN naming.
[NMC1] Each Dictionary Entry Name MUST define one and only one fully qualified path (FQP) for an element or attribute.
The FQP anchors the use of the element or attribute to a particular location in a business message. Any semantic dependencies that the element or attribute has on other elements and attributes within the UBL library that are not otherwise enforced or made explicit in its structural definition can be found in its prose definition.
Modeling Constraints Modeling constraints are limited to those necessary to ensure consistency in development of the UBL library.
Defining Classes UBL is based on instantiating ebXML CCTS BIEs. UBL models and the XML expressions of those models are class driven. Specifically, the UBL library defines classes for each CCTS ABIE and the UBL schemas instantiate those classes. The properties of those classes consist of CCTS BBIEs and ASBIEs.
Core Component Types Each BBIE is associated with one of an approved set of CCTS Core Component Types.
[MDC1] UBL libraries and schemas MUST only use CCTS Core Component Types, except in the case of extension, where the UBLExtensions element is used.
XML Mixed Content UBL documents are designed to effect data-centric electronic commerce transactions. Including XML mixed content in business documents is undesirable because business transactions are based on exchange of discrete pieces of data. The white space aspects of XML mixed content make processing unnecessarily difficult and add a layer of complexity not desirable in business exchanges.
[MDC2] XML mixed content MUST NOT be used except where contained in an xsd:documentation element.
Sequencing In the UBL model, the prescribed order for the contents of an ABIE is that ASBIEs follow BBIEs. However, this is, strictly speaking, a rule of the modeling methodology rather than an NDR. The NDR in this case is that the sequential order of entities in the model must be preserved.
[MDC0] The sequence of the business information entities that is expressed in the UBL model MUST be preserved in the schema.
Reusability Scheme To promote effective management of the UBL library, all element declarations are unique. Consequently, UBL elements are declared globally.
Reusable Elements UBL elements are global and qualified. Hence in the example below, the Address element is directly reusable as a modular component. <programlisting><xsd:element name="Party" type="PartyType"/> <xsd:complexType name="PartyType"> <xsd:annotation> <!-- Documentation goes here --> </xsd:annotation> <xsd:sequence> <xsd:element ref="cbc:MarkCareIndicator" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="cbc:MarkAttentionIndicator" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="PartyIdentification" minOccurs="0" maxOccurs="unbounded"> ... </xsd:element> <xsd:element ref="PartyName" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="Address" minOccurs="0" maxOccurs="1"> ... </xsd:element> ... </xsd:sequence> </xsd:complexType> <xsd:element name="Address" type="AddressType"/> <xsd:complexType name="AddressType"> ... <xsd:sequence> <xsd:element ref="cbc:CityName" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="cbc:PostalZone" minOccurs="0" maxOccurs="1"> ... </xsd:element> ... </xsd:sequence> </xsd:complexType></programlisting> </example> <para id="para-1.5.6.3.4">Software written to work with UBL's standard library should work with new assemblies of the same components, since global elements will remain consistent and unchanged. The globally declared <Address> element is fully reusable without regard to the reusability of types and provides a solid mechanism for ensuring that extensions to the UBL core library will provide consistency and semantic clarity regardless of their placement within a particular type.</para> <blockquote role="Rule" id="rule-ELD2"> <para id="para-1.5.6.3.5.1">[<emphasis role="rule-prefix">ELD2</emphasis>] All element declarations MUST be global.</para> </blockquote> </section> </section> <section id="section-3.4"> <title>Extension Scheme Some organizations are required by law to send additional information not covered by the UBL document structure, thus requiring an extension to the UBL message. The xsd:any construct is seen as the most efficient way to implement this requirement. In general, UBL restricts the use of xsd:any because this feature permits the introduction of unknown elements into an XML instance. However, limiting its use to a single, predefined element mitigates this risk. For meaningful validation of UBL document instances, the value of the xsd:processContents attribute of the element must be set to "skip", thereby removing the potential for errors in the validation layer. Extension imposes cardinality constraints. The following rules apply in the order below.
[ELD12] The UBL Extensions element MUST be declared as the first child of the document element with xsd:minOccurs="0".
[ELD13] The UBLProfileID element MUST be declared immediately following the UBL Extensions element with xsd:minOccurs="0".
[ELD14] The UBLSubsetID element MUST be declared immediately following the UBLProfileID element with xsd:minOccurs="0".
Namespace Scheme The concept of XML namespaces is defined in the W3C XML namespaces technical specification. The use of XML namespace is specified in the W3C XML Schema (XSD) Recommendation. A namespace is declared in the root element of a schema using a namespace identifier. Namespace declarations can also identify an associated prefix "shorthand identifier" that allows for compression of the namespace name. For each UBL namespace, a normative token is defined as its prefix. These tokens (currently udt, qdt, cac, cbc, ext) are defined in Section 3.7.
Declaring Namespaces Neither XML 1.0 nor XSD requires the use of namespaces. However, the use of namespaces is essential to managing the complex UBL library. UBL uses UBL-defined schemas (created by the UBL TC) and UBL-used schemas (created by external activities), and both require a consistent approach to namespace declarations.
[NMS1] Every UBL-defined or -used schema module, except internal schema modules, MUST declare a namespace using the xsd:targetNamespace attribute.
Each UBL schema module consists of a logical grouping of lower level artefacts that can be used in a variety of UBL schemas. These schema modules are grouped into a schema set. Each schema set is assigned a namespace that identifies that group of schema modules. As constructs are changed, new versions are to be created. The schema set is the versioned entity; all schema modules within that package are of the same version, and each major version has a unique namespace. Schema set A collection of schemas that constitute a specific UBL namespace. Schema validation ensures that an instance conforms to its declared schema. In keeping with Rule NMS1, each UBL schema module is part of a versioned namespace.
[NMS2] Every UBL-defined or -used major version schema set MUST have its own unique namespace.
UBL's extension methodology encourages a wide variety in the number of schema modules that are created as derivations from UBL schema modules. Customized schemas should not be confused with those developed by UBL.
[NMS3] UBL namespaces MUST only contain UBL developed schema modules.
Namespace Uniform Resource Identifiers A UBL namespace name must be a URI that conforms to RFC 2396. UBL has adopted the Uniform Resource Name (URN) scheme as the standard for URIs for UBL namespaces, in conformance with IETF's RFC 3121. Rule NMS2 requires separate namespaces for each UBL major version schema set. In accordance with OASIS procedures, the UBL namespace rules differentiate between committee draft and OASIS Standard status. For each schema holding draft status, a UBL namespace must be declared and named.
[NMS4] The namespace names for UBL schemas holding committee draft status MUST be of the form urn:oasis:names:tc:ubl:schema:<subtype>:<document-id>
The format for document-id is found in Section 3.6. For each UBL schema holding OASIS Committee Specification or Standard status, a UBL namespace must be declared and named using the same notation, but with the value "specification" replacing the value "tc".
[NMS5] The namespace names for UBL schemas holding OASIS Standard status MUST be of the form urn:oasis:names:specification:ubl:schema:<subtype>:<document-id>
Schema Location UBL schemas use a URN namespace scheme. In contrast, schema locations are defined as a Uniform Resource Locator (URL). UBL schemas must be available both at design time and run time. Therefore, the UBL schema locations will differ from the UBL namespace declarations. UBL uses an OASIS URL for hosting retrievable copies of UBL schemas.
Persistence UBL namespaces use URNs to provide name persistence. UBL namespaces must never change once they have been declared. Conversely, changes to a schema may result in a new namespace declaration. Thus, a published schema version and its namespace association will always be inviolate.
[NMS6] UBL published namespaces MUST never be changed.
Versioning Scheme UBL distinguishes between major versions and minor versions. Major versions are not backwards compatible. Minor versions do not break backwards compatibility. In other words, a document instance that validates against version 1 of the schema must also validate against version 1.1 of the schema, where version 1.1 is a minor version change based on version 1. However, the same document instances would not necessarily be valid against version 2 of the schema, where version 2 is a major version change. Versioning information is indicated both in the namespace URI and in the version attribute of the schema module. However, this information is represented somewhat differently in these two locations.
Versioning Information in the Namespace URI UBL namespaces conform to the OASIS namespace rules defined in RFC 3121. All UBL namespace URIs have the form: urn:oasis:names:specification:ubl:schema:xsd:<modulename>-<major>where <modulename> is the name of the schema module and <major> is a positive integer representing the major version. The field containing <modulename>-<major> is called the document-id.
[VER2] Every UBL schema module major version MUST have an RFC 3121 document-id of the form <modulename>-<major>
[VER6] Every UBL schema module major version number MUST be a sequentially assigned integer greater than zero.
The value of <major> is "1" for the first release of a namespace. For example, the namespace URI for the first major release of the Invoice domain has the form: urn:oasis:names:specification:ubl:schema:xsd:Invoice-1 Subsequent major releases increment the value by 1. For example, the second major release of the Invoice domain has the URI urn:oasis:names:specification:ubl:schema:xsd:Invoice-2 The rule for minor version releases is as follows:
[VER4] Every minor version release of a UBL schema module MUST have a document-id of the form <modulename>-<major>
For example, the fifth minor version of the release based on the second major release mentioned above will have the URI urn:oasis:names:specification:ubl:schema:xsd:Invoice-2As can be seen, both the rule and the example for the minor version releases is exactly the same as that for the major version. There is even a rule stating this directly.
[VER5] For UBL minor version changes, the namespace name MUST not change.
However, minor versioning is handled differently in the xsd:schema element.
Versioning representation in the xsd:schema element UBL uses the version attribute in the xsd:schema element to convey minor version releases of the schema module.
[VER12] Every major version release of a UBL schema module MUST capture its version number in the xsd:version attribute of the xsd:schema element in the form <major>.0
[VER14] Every minor version release of a UBL schema module MUST capture its version information in the xsd:version attribute in the form <major>.<non-zero>
[VER7] Every UBL schema module minor version number MUST be a sequentially assigned, non-negative integer.
Instance Versioning UBL version information can also be captured in instances of UBL document schemas via the ubl:UBLVersionID element.
[VER15] Every UBL document schema MUST declare an optional element named UBLVersionID immediately following the optional UBL Extensions element.
Modularity Strategy There are many possible mappings of XML schema constructs to namespaces and to files. In addition to the logical taming of complexity that namespaces provide, dividing the physical realization of schemas into multiple schema modules provides a mechanism whereby reusable components can be imported as needed without the need to import complete schemas.
[SSM1] UBL schema expressions MAY be split into multiple schema modules.
Schema module A schema document containing type definitions and element declarations intended to be reused in multiple schemas.
UBL Modularity Model UBL relies extensively on modularity in schema design. There is no single UBL root schema. Rather, there are a number of UBL document schemas used to perform different business functions. UBL is structured so that users can reuse individual document schemas without having to import the entire UBL document schema library. A document schema can import individual modules without having to import all UBL schema modules. Each document schema defines its own dependencies. The UBL schema modularity approach reflects logical associations that exist between document and internal schema modules,and it ensures that individual modules can be reused to the maximum extent possible. If the contents of a namespace are small enough then they can be completely specified within a single document. Document and internal schema modules are shown in Figure 5.
UBL Schema Modularity Model
Figure 5 shows the one-to-one correspondence between document schemas and namespaces. It also shows the one-to-one correspondence between files and schema modules. As shown here, there are two types of schemas in the UBL library — document schemas and schema modules. Both types of schemas are conformant with XSD. Each document schema occupies its own namespace and may include zero or more internal modules. The namespace for a document schema includes any of its internal modules. Schema modules that are not internal to a document occupy a different namespace, as in the qdt, cbc, and cac schema modules.
Schema Modules
Another way to visualize the structure is by example. Figure 6 depicts instances of the various schema modules from the previous diagram. Figure 7 shows how the Order and Invoice document schemas import the CommonAggregateComponents and CommonBasicComponents external schema modules. It also shows how the Order document schema may include internal schema modules — modules local to that namespace. The clear boxes show how the various schema modules are grouped into namespaces. Any UBL schema module, be it a document schema or an internal module, may import other document schemas from other namespaces.
Order and Invoice Schema Import of Common Component Schema Modules
If two namespaces are mutually dependent, then importing one will cause the other to be imported as well. For this reason there must not exist circular dependencies between UBL schema modules. By extension, there must notexist circular dependencies between namespaces. A namespace A dependent upon type definitions or element declarations defined in another namespace B must import B's document schema.
[SSM2] A schema in one UBL namespace that is dependent upon type definitions or element declarations in another schema namespace MUST only import that schema.
An additional rule is necessary to address potentially circular dependencies as well — schema A must not import internal schema modules of schema B.
[SSM3] A schema in one UBL namespace that is dependent upon type definitions or element declarations defined in another schema namespace MUST NOT import the internal schema modules of that schema.
Internal and External Schema Modules As illustrated in figures 5 and 6, UBL schema modules are either internal or external.
Internal Schema Modules UBL internal schema modules do not declare a target namespace, but instead reside in the namespace of their parent schema. All internal schema modules are accessed using xsd:include.
[SSM6] All UBL internal schema modules MUST be in the same namespace as their corresponding document schema.
UBL internal schema modules must have semantically meaningful names. Internal schema module names identify the parent schema module, the internal schema module function, and the schema module itself.
[SSM7] Each UBL internal schema module MUST be named <ParentSchemaModuleName><InternalSchemaModuleFunction>
Example: ExtensionContentDatatype
External Schema Modules External schema modules are used to group complex types and global elements that are used in multiple document schemas.
[SSM8] UBL schema modules MAY be created for reusable components.
UBL external schema modules organize the reusable components into logical groupings. At a minimum, UBL defines the following external schema modules: UBL CommonAggregateComponents UBL CommonBasicComponents UBL Qualified Datatypes In addition, UBL 2.0 uses the following schema modules provided by UN/CEFACT. CCTS Core Component Types CCTS Unqualified Datatypes Multiple UN/CEFACT Code Lists Furthermore, where extensions are used, an extension schema module must be provided. This schema module must be named: CommonExtensionComponents
[SSM21] The UBL extension schema module MUST be identified as CommonExtensionComponents in the document name within the schema header.
To ensure consistency in expressing the CommonExtensionComponents schema module, a namespace prefix that will be used in all UBL schemas must be defined.
[NMS18] The CommonExtensionComponents schema module namespace MUST be represented by the namespace prefix "ext" when referenced in other schemas.
UBL Common Aggregate Components Schema Module The UBL library contains a wide variety of CCTS ABIEs, each defined as an xsd:complexType. Although some of these complex types may be used in only one UBL schema, many will be reused in multiple UBL schema modules. For ease of reuse, all the ABIE xsd:complexType definitions used in more than one UBL schema module are grouped into a single schema module of their own.
[SSM9] A schema module defining all UBL Common Aggregate Components MUST be created.
[SSM10] The UBL Common Aggregate Components schema module MUST be identified as CommonAggregateComponents in the document name within the schema header.
[NMS7] The UBL Common Aggregate Components schema module MUST reside in its own namespace.
[NMS8] The UBL Common Aggregate Components schema module namespace MUST be represented by the namespace prefix "cac" when referenced in other schemas.
UBL CommonBasicComponents Schema Module The UBL library contains a wide variety of CCTS BBIEs based on CCTS BBIE Properties. BBIE Properties are reusable in multiple BBIEs, and each is defined as an xsd:complexType. Although some of these complex types may be used in only one UBL schema, many will be reused in multiple UBL schema modules. For ease of reuse, all the BBIE Property xsd:complexType definitions used in more than one UBL schema module are grouped into a single schema module of their own.
[SSM11] A schema module defining all UBL Common Basic Components MUST be created.
[SSM12] The UBL Common Basic Components schema module MUST be identified as CommonBasicComponents in the document name within the schema header.
[NMS9] The UBL Common Basic Components schema module MUST reside in its own namespace.
[NMS10] The UBL Common Basic Components schema module namespace MUST be represented by the namespace prefix "cbc" when referenced in other schemas.
CCTS CoreComponentType Schema Module CCTS defines an authorized set of Core Component Types that convey content and supplementary information related to exchanged data. As the basis for all higher level CCTS models, these Core Component Types are reusable in every UBL schema. The complex type definitions for all CCTS Core Component Types are collected in the Core Component Type schema module published by UN/CEFACT.
CCTS Qualified and Unqualified Datatypes CCTS defines a set of primary and secondary Representation Terms that describe the form of every CCTS BIE. These Representation Terms are instantiated in the form of data types that are reusable in every UBL schema. Each CCTS Datatype defines the set of values that can be used for its associated CCTS BBIE Property. These datatypes may be unqualified or qualified, that is to say, unrestricted or restricted. We refer to these two categories as CCTS Unqualified Datatypes and UBL Qualified Datatypes.
CCTS Unqualified Datatypes Schema Module UBL 2.0 uses the UN/CEFACT Unqualified Data Type schema module, including the code list schema modules that it imports. When the CCTS Unqualified Datatypes schema module is referenced, the "udt" namespace prefix must be used.
[NMS17] The CCTS Unqualified Datatypes schema module namespace MUST be represented by the prefix "udt" when referenced in other schemas.
Note: It is the intention of the UBL TC to move the UN/CEFACT code lists out of the UDT module and into the set of other UBL code lists in versions of UBL following 2.0. See Section 6.
UBL Qualified Datatypes Schema Module UBL Qualified Datatypes are defined by specifying restrictions on CCTS Unqualified Datatypes. All the UBL Qualified Datatype definitions are collected in a single schema module named QualifiedDatatypes that imports the CCTS UnqualifiedDatatypes module.
[SSM18] A schema module defining all UBL Qualified Datatypes MUST be created.
[SSM19] The UBL Qualified Datatypes schema module MUST be identified as QualifiedDatatypes in the document name in the schema header.
[SSM20] The UBL Qualified Datatypes schema module MUST import the CCTS Unqualified Datatypes schema module.
[NMS15] The UBL Qualified Datatypes schema module MUST reside in its own namespace.
To ensure consistency in expressing the UBL Qualified Datatypes schema module, a namespace prefix that will be used in all UBL schemas must be defined.
[NMS16] The UBL Qualified Datatypes schema module namespace MUST be represented by the namespace prefix "qdt" when referenced in other schemas.
Annotation and Documentation Requirements Annotation is an essential tool in understanding and reusing a schema. UBL, as an implementation of CCTS, requires an extensive amount of annotation to provide all necessary metadata required by the CCTS specification.
Schema Annotation The annotation needed to satisfy CCTS requirements considerably increases the size of the UBL schemas, with undesirable performance impacts. To address this issue, a cut-down alternative has been developed for each UBL schema. A normative, fully annotated schema is provided to facilitate greater understanding of the schema module and its components and to meet the CCTS metadata requirements. A non-normative schema devoid of annotation is provided that can be used at run-time if required to meet processor resource constraints.
[GXS2] UBL MUST provide two schemas for each transaction. One normative schema shall be fully annotated. One non-normative schema shall be a run-time schema devoid of documentation.
Embedded Documentation UBL spreadsheets contain all necessary information to produce fully annotated schemas, including information about each UBL BBIE. UBL annotations consist of information currently required by Section 7 of the CCTS and supplemented by metadata from the UBL spreadsheet models. The absence of an optional annotation from the structured set of annotations in a documentation element implies the use of the default value. For example, there are several annotations relating to context, such as CCTS Business Context and CCTS Industry Context; their absence implies that their value is "all contexts". The following rules describe the documentation requirements for each UBL Qualified Datatype and UBL Unqualified Datatype definition. None of these documentation rules apply in the case of extension where the UBL Extensions element is used.
[DOC1] The xsd:documentation element for every data type MUST contain a set of annotations in the following order (as defined in CCTS Section 7): DictionaryEntryName (mandatory) Version (mandatory) Definition (mandatory) RepresentationTerm (mandatory) QualifierTerm(s) (mandatory, where used) UniqueIdentifier (mandatory) Usage Rule(s) (optional) Content Component Restriction (optional)
[DOC2] A datatype definition MAY contain one or more Content Component Restrictions to provide additional information on the relationship between the datatype and its corresponding Core Component Type. If used, the Content Component Restrictions MUST contain a set of annotations in the following order: RestrictionType (mandatory): Defines the type of format restriction that applies to the Content Component. RestrictionValue (mandatory): The actual value of the format restriction that applies to the Content Component. ExpressionType (optional): Defines the type of the regular expression of the restriction value.
[DOC3] A datatype definition MAY contain one or more Supplementary Component Restrictions to provide additional information on the relationship between the datatype and its corresponding Core Component Type. If used, the Supplementary Component Restrictions MUST contain a set of annotations in the following order: SupplementaryComponentName (mandatory): Identifies the Supplementary Component to which the restriction applies. RestrictionValue (mandatory, repetitive): The actual value(s) that is (are) valid for the Supplementary Component.
The following rule describes the documentation requirements for each Basic Business Information Entity definition.
[DOC4] The xsd:documentation element for every BBIE MUST contain a set of annotations in the following order: ComponentType (mandatory): The type of component to which the object belongs. For BBIEs this MUST be "BBIE". DictionaryEntryName (mandatory): The official name of a BBIE. Version (optional): An indication of the evolution over time of the BBIE Entity. Definition (mandatory): The meaning of a BBIE. Cardinality (mandatory): Indicates whether the BBIE represents a not-applicable, optional, mandatory, or repetitive characteristic of the Aggregate Business Information Entity to which it belongs. ObjectClassQualifier (optional): The qualifier for the Object Class. ObjectClass (mandatory): The Object Class containing the BBIE. PropertyTermQualifier (optional): A word or words which help define and differentiate a BBIE. PropertyTerm (mandatory): Conveys the characteristic or Property of the Object Class. RepresentationTerm (mandatory): Describes the form in which the BBIE is represented. DataTypeQualifier (optional): A meaningful name that differentiates the data type of the BBIE from its underlying Core Component Type. DataType (mandatory): Defines the data type used for the BBIE. AlternativeBusinessTerms (optional): Any synonymous terms under which the BBIE is commonly known and used in the business. Examples (optional): Examples of possible values for the BBIE.
The following rule describes the documentation requirements for each CCTS Aggregate Business Information Entity definition.
[DOC5] The xsd:documentation element for every ABIE MUST contain a set of annotations in the following order: ComponentType (mandatory): The type of component to which the object belongs. For ABIEs this MUST be "ABIE". DictionaryEntryName (mandatory): The official name of the ABIE . Version (optional): An indication of the evolution over time of the ABIE. Definition (mandatory): The meaning of the ABIE. ObjectClassQualifier (optional): The qualifier for the Object Class. ObjectClass (mandatory): The Object Class represented by the ABIE. AlternativeBusinessTerms (optional): Any synonymous terms under which the ABIE is commonly known and used in the business.
The following rule describes the documentation requirements for each CCTS Association Business Information Entity definition.
[DOC6] The xsd:documentation element for every ASBIE element declaration MUST contain a set of annotations in the following order: ComponentType (mandatory): The type of component to which the object belongs. For ASBIEs this MUST be "ASBIE". DictionaryEntryName (mandatory): The official name of the ASBIE. Version (optional): An indication of the evolution over time of the ASBIE. Definition (mandatory): The meaning of the ASBIE. Cardinality (mandatory): Indicates whether the ASBIE represents an optional, mandatory, or repetitive assocation. ObjectClass (mandatory): The Object Class containing the ASBIE. PropertyTermQualifier (optional): A word or words which help define and identify the ASBIE. PropertyTerm (mandatory): Represents the ASBIE contained by the Association Business Information Entity. AssociatedObjectClassQualifier (optional): The Associated Object Class Qualifiers describe the "context" of the relationship with another ABIE. That is, it is the role the contained ABIE plays within its association with the containing ABIE. AssociatedObjectClass (mandatory): The Object Class at the other end of the association. It represents the ABIE contained by the ASBIE.
[DOC8] The xsd:documentation element for every Supplementary Component attribute declaration MUST contain a set of annotations in the following order: Name (mandatory): Name in the Registry of a Supplementary Component of a Core Component Type. Definition (mandatory): An explanation of the meaning of a Supplementary Component and its relevance for the related Core Component Type. Primitive type (mandatory): The PrimitiveType to be used for the representation of the value of a Supplementary Component. Possible Value(s) (optional): Possible values of Supplementary Components.
[DOC9] The xsd:documentation element for every Supplementary Component attribute declaration containing restrictions MUST include the following additional information appended to the information required by DOC8: Restriction Value(s) (mandatory): The actual value(s) that is (are) valid for the Supplementary Component.
Naming Rules The rules in this section make use of the following special concepts related to XML elements. Top-level element: An element that encloses a whole UBL business message. Note that UBL business messages might be carried by messaging transport protocols that themselves have higher-level XML structure. Thus, a UBL top-level element is not necessarily the root element of the XML document that carries it. Lower-level element: An element that appears inside a UBL business message. Lower-level elements consist of intermediate elements and leaf level elements. Intermediate element: An element not at the top level that is of a complex type, containing only other elements and possibly attributes, but no mixed content. Leaf element: An element containing only character data (though it may also have attributes). Note that, because of the XSD mechanisms involved, a leaf element that has attributes must be declared as having a complex type, but a leaf element with no attributes may be declared with either a simple type or a complex type.
General Naming Rules In keeping with CCTS, UBL uses English as its normative language.
[GNR1] UBL XML element and type names MUST be in the English language, using the primary English spellings provided in the Oxford English Dictionary.
CCTS adheres to ISO/IEC 11179. The UBL component library is also fully conformant to those rules. The UBL XSD instantiation of the UBL component library in some cases refines the CCTS naming rules to leverage the capabilities of XML and XSD. Specifically, truncation rules are applied to allow for reuse of element names across parent element environments and to maintain brevity and clarity. Following 11179, CCTS mandates three-part Dictionary Entry Names (DENs) for information items. As an implementation of CCTS, UBL assigns an official DEN to each item and then converts this to the name in UBL schemas using determinate transformation rules.
[GNR2] UBL XML element and type names MUST be consistently derived from CCTS conformant Dictionary Entry Names.
DENs contain spaces and characters not allowed by XML and therefore not appropriate for UBL XML component names.
[GNR3] UBL XML element and type names constructed from CCTS Dictionary Entry Names MUST NOT include periods, spaces, other separators, or characters not allowed by XSD.
Acronyms and abbreviations impair interoperability and therefore are to be avoided to the maximum extent practicable. Since some abbreviations will inevitably be necessary, UBL maintains a normative list of authorized acronyms and abbreviations. Creation and maintainance of this list belongs to content definition rather than Naming and Design, but for convenience, the list used for UBL 2.0 is provided in Appendix B.
[GNR4] UBL XML element names and simple and complex type names MUST NOT use acronyms, abbreviations, or other word truncations, except those in the list of exceptions maintained and published by the UBL TC.
The exception list is maintained and tightly controlled by UBL. Additions are made only when necessary. Once approved, an acronym or abbreviation must always be used to replace the term it stands for.
[GNR6] The acronyms and abbreviations listed in the UBL-approved list MUST always be used in place of the word or phrase they represent.
Generally speaking, the names for UBL XML constructs must always be singular. The only exception is where the concept itself is plural.
[GNR7] UBL XML element and type names MUST be in singular form unless the concept itself is plural.
Approved acronyms and abbreviations must be used consistently across documents.
[GNR10] Acronyms and abbreviations at the beginning of an attribute name MUST appear in all lower case. Acronyms and abbreviations elsewhere in an attribute name MUST appear in upper case.
[GNR11] Acronyms and abbreviations MUST appear in all upper case for all element and type names.
XML is case sensitive. Consistency in the use of case for a specific XML component (element, type, attribute) is essential to ensure that every occurrence of a component is treated as the same. Capitalization helps readability and consistency. The ebXML architecture document specifies a standard use of upper and lower camel case for expressing XML elements and attributes, respectively. Following this practice, UBL element and type names use UpperCamelCase (UCC), and attribute names use lowerCamelCase (LCC).
[GNR8] The UpperCamelCase (UCC) convention MUST be used for naming elements and types.
<itemizedlist mark="none" spacing="compact"> <listitem><para id="para-1.6.4.21.2">CurrencyBaseRate</para></listitem> <listitem><para id="para-1.6.4.21.3">CityNameType</para></listitem> </itemizedlist> </example> <blockquote role="Rule" id="rule-GNR9"> <para id="para-1.6.4.22.1">[<emphasis role="rule-prefix">GNR9</emphasis>] The lowerCamelCase (LCC) convention MUST be used for naming attributes.</para> </blockquote> <example id="example-4.1.3"> <title/> <itemizedlist mark="none" spacing="compact"> <listitem><para id="para-1.6.4.23.2">currencyID</para></listitem> <listitem><para id="para-1.6.4.23.3">unitCode</para></listitem> </itemizedlist> </example> </section> <section id="section-4.2"> <title>Type Naming Rules UBL specifies naming rules for complex types based on CCTS ABIEs, BBIEs, and BBIE Properties. The use of unique CCTS Dictionary Entry Names for these constructs disambiguates their meanings and prevents duplication.
Complex Type Names for CCTS Aggregate Business Information Entities (ABIEs) UBL xsd:complexType names for ABIEs are derived from their DENs by removing separators to follow general naming rules and appending the suffix "Type" to replace the word "Details".
[CTN1] A UBL xsd:complexType name based on a CCTS ABIE MUST be the CCTS Dictionary Entry Name with the separators removed and with the "Details" suffix replaced with "Type".
<informaltable> <tgroup cols="2"> <colspec colwidth="60*" colname="col1"/> <colspec colwidth="40*" colname="col2"/> <tbody> <row> <entry> <para id="para-1.6.5.4.4.2.1.3.1.1.1"> <emphasis role="bold">CCTS Aggregate Business Information Entity</emphasis> </para> </entry> <entry> <para id="para-1.6.5.4.4.2.1.3.1.2.1"> <emphasis role="bold">UBL xsd:complexType</emphasis> </para> </entry> </row> <row> <entry> <para id="para-1.6.5.4.4.2.1.3.2.1.1">Address. Details</para> </entry> <entry> <para id="para-1.6.5.4.4.2.1.3.2.2.1">AddressType</para> </entry> </row> <row> <entry> <para id="para-1.6.5.4.4.2.1.3.3.1.1">Financial Account. Details</para> </entry> <entry> <para id="para-1.6.5.4.4.2.1.3.3.2.1" >FinancialAccountType</para> </entry> </row> </tbody> </tgroup> </informaltable> </example> </section> <section id="section-4.2.2"> <title>Complex Type Names for CCTS Basic Business Information Entity (BBIE) Properties All BBIE Properties are reusable across multiple BBIEs. The CCTS does not specify, but implies, that BBIE Property names are the reusable property term and representation term of the family of BBIEs that are based on them. The UBL xsd:complexType names for BBIE Properties are derived from the shared Property and Representation terms portion of the DENs in which they appear by removing separators to follow general naming rules and appending the suffix "Type".
[CTN2] A UBL xsd:complexType name based on a CCTS BBIE Property MUST be the CCTS Dictionary Entry Name shared Property Term and its qualifiers and the Representation Term of the BBIE with the separators removed and with the "Type" suffix appended after the Representation Term.
<informaltable> <tgroup cols="2"> <colspec colwidth="60*" colname="col1"/> <colspec colwidth="40*" colname="col2"/> <tbody> <row> <entry> <para id="para-1.6.5.5.2.2.1.3.1.1.1"> <emphasis role="bold">CCTS Business Information Entity Property</emphasis> </para> </entry> <entry> <para id="para-1.6.5.5.2.2.1.3.1.2.1"> <emphasis role="bold">UBL xsd:complexType</emphasis> </para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.2.2.1.3.2.1.1">Declared Customs_ Value. Amount</para> </entry> <entry> <para id="para-1.6.5.5.2.2.1.3.2.2.1" >DeclaredCustomsValueAmountType</para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.2.2.1.3.3.1.1">Gross_ Weight. Measure</para> </entry> <entry> <para id="para-1.6.5.5.2.2.1.3.3.2.1" >GrossWeightMeasureType</para> </entry> </row> </tbody> </tgroup> </informaltable> </example> <blockquote role="Rule" id="rule-CTN6"> <para id="para-1.6.5.5.5.1">[<emphasis role="rule-prefix">CTN6</emphasis>] A UBL xsd:complexType name based on a CCTS BBIE Property and with a CCTS BBIE Representation Term of "Text" MUST have the word "Text" removed from the end of its name.</para> </blockquote> <example id="example-4.2.1.2"> <title/> <informaltable> <tgroup cols="2"> <colspec colwidth="60*" colname="col1"/> <colspec colwidth="40*" colname="col2"/> <tbody> <row> <entry> <para id="para-1.6.5.5.5.1.2"> <emphasis role="bold">CCTS Basic Business Information Entity</emphasis> </para> </entry> <entry> <para id="para-1.6.5.5.5.1.3"> <emphasis role="bold">UBL xsd:complexType</emphasis> </para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.5.1.4">Agency Name. Text</para> </entry> <entry> <para id="para-1.6.5.5.5.1.5">AgencyNameType</para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.5.1.6">Floor. Text</para> </entry> <entry> <para id="para-1.6.5.5.5.1.7">FloorType</para> </entry> </row> </tbody> </tgroup> </informaltable> </example> <blockquote role="Rule" id="rule-CTN7"> <para id="para-1.6.5.5.6.1">[<emphasis role="rule-prefix">CTN7</emphasis>] A UBL xsd:complexType name based on a CCTS BBIE Property and with a CCTS BBIE Representation Term of "Identifier" MUST replace "Identifier" with "ID" at the end of its name.</para> </blockquote> <example id="example-4.2.1.4"> <title/> <informaltable> <tgroup cols="2"> <colspec colwidth="60*" colname="col1"/> <colspec colwidth="40*" colname="col2"/> <tbody> <row> <entry> <para id="para-1.6.5.5.5.2.1"> <emphasis role="bold">CCTS Basic Business Information Entity</emphasis> </para> </entry> <entry> <para id="para-1.6.5.5.5.2.2"> <emphasis role="bold">UBL xsd:complexType</emphasis> </para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.5.2.3">Agency Identifier. Identifier</para> </entry> <entry> <para id="para-1.6.5.5.5.2.4">AgencyIDType</para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.5.2.5">Vessel Identifier. Identifier</para> </entry> <entry> <para id="para-1.6.5.5.5.2.6">VesselIDType</para> </entry> </row> </tbody> </tgroup> </informaltable> </example> <blockquote role="Rule" id="rule-CTN8"> <para id="para-1.6.5.5.7.1">[<emphasis role="rule-prefix">CTN8</emphasis>] A UBL xsd:complexType name based on a CCTS BBIE Property MUST remove all duplication of words that occurs as a result of duplicate Property Terms and Representation Terms.</para> </blockquote> <example id="example-4.2.1.5"> <title/> <informaltable> <tgroup cols="2"> <colspec colwidth="60*" colname="col1"/> <colspec colwidth="40*" colname="col2"/> <tbody> <row> <entry> <para id="para-1.6.5.5.5.3.1"> <emphasis role="bold">CCTS Basic Business Information Entity</emphasis> </para> </entry> <entry> <para id="para-1.6.5.5.5.3.2"> <emphasis role="bold">UBL xsd:complexType</emphasis> </para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.5.3.3"> Issue Date. Date</para> </entry> <entry> <para id="para-1.6.5.5.5.3.4">IssueDateType</para> </entry> </row> <row> <entry> <para id="para-1.6.5.5.5.3.5">Issue Time. Time</para> </entry> <entry> <para id="para-1.6.5.5.5.3.6">IssueTimeType</para> </entry> </row> </tbody> </tgroup> </informaltable> </example> </section> </section> <section id="section-4.3"> <title>Element Naming Rules As shown in Figure 3, UBL elements are created for each UBL ABIE, BBIE, and ASBIE.
Element Names for CCTS ABIEs (ABIEs)
[ELN1] A UBL global element name based on a CCTS ABIE MUST be the same as the name of the corresponding xsd:complexType to which it is bound, with the word "Type" removed.
For example, a UBL xsd:complexType name based on the ABIE Party. Details will be PartyType. The global element based on PartyType will be named Party. <programlisting><xsd:element name="Party" type="PartyType"/> <xsd:complexType name="PartyType"> <xsd:annotation> <!-- Documentation goes here --> </xsd:annotation> <xsd:sequence> <xsd:element ref="cbc:MarkCareIndicator" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="cbc:MarkAttentionIndicator" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="PartyIdentification" minOccurs="0" maxOccurs="unbounded"> ... </xsd:element> <xsd:element ref="PartyName" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="Address" minOccurs="0" maxOccurs="1"> ... </xsd:element> ... </xsd:sequence></programlisting> </example> </section> <section id="section-4.3.2"> <title>Element Names for CCTS BBIE Properties The same naming concept used for ABIEs applies to BBIE Properties.
[ELN2] A UBL global element name based on a CCTS BBIE Property MUST be the same as the name of the corresponding xsd:complexType to which it is bound, with the word "Type" removed.
<programlisting><!--===== Basic Business Information Entity Type Definitions =====--> <xsd:complexType name="ChargeIndicatorType"> ... </xsd:complexType> ... <!--===== Basic Business Information Entity Property Element Declarations =====--> <xsd:element name="ChargeIndicator" type="ChargeIndicatorType"/></programlisting> </example> </section> <section id="section-4.3.3"> <title>Element Names for CCTS ASBIEs An ASBIE is not a class like an ABIE or a BBIE Property that is reused as a BBIE. Rather, it is an association between two classes. Therefore, an element representing an ASBIE does not have its own unique xsd:complexType. Instead, when an element representing an ASBIE is declared, the element is bound to the xsd:complexType of its associated ABIE by referencing the ABIE's global element declaration.
[ELN3] A UBL global element name based on a CCTS ASBIE MUST be the CCTS ASBIE Dictionary Entry Name Property Term and its qualifiers and the Object Class Term and qualifiers of its associated CCTS ABIE. All CCTS Dictionary Entry Name separators MUST be removed.
<informaltable> <tgroup cols="3"> <colspec colwidth="33*" colname="col1"/> <colspec colwidth="33*" colname="col2"/> <colspec colwidth="34*" colname="col3"/> <tbody> <row> <entry> <para id="para-1.6.6.5.3.2.1"> <emphasis role="bold">CCTS ASBIE Property Term</emphasis> </para> </entry> <entry> <para id="para-1.6.6.5.3.2.2"> <emphasis role="bold">Associated ABIE Object Class</emphasis> </para> </entry> <entry> <para id="para-1.6.6.5.3.2.2.1"> <emphasis role="bold">Global Element Name</emphasis> </para> </entry> </row> <row> <entry> <para id="para-1.6.6.5.3.2.3">Buyer_Contact</para> </entry> <entry> <para id="para-1.6.6.5.3.2.3.1">Contact.Details</para> </entry> <entry> <para id="para-1.6.6.5.3.2.4">BuyerContact</para> </entry> </row> <row> <entry> <para id="para-1.6.6.5.3.2.5">Origin_Address</para> </entry> <entry> <para id="para-1.6.6.5.3.2.5.1">Address.Details</para> </entry> <entry> <para id="para-1.6.6.5.3.2.6">OriginAddress</para> </entry> </row> </tbody> </tgroup> </informaltable> </example> </section> </section> <section id="section-4.4"> <title>Attributes in UBL As a transaction-based XML exchange format, UBL significantly restricts the use of XML attributes. Attribute usage is relegated to supplementary components only; all "primary" business data appears exclusively in element content. Attributes are defined in the UN/CEFACT Unqualified Datatype schema module.
Declarations and Definitions In XSD, elements are defined in terms of complex or simple types, and attributes are defined in terms of simple types. The rules in this section govern the consistent structuring of these types and their documentation in the UBL Library.
Type Definitions
General Type Definitions Since UBL elements and types are intended to be reusable, all types must be named. This permits other types to establish elements that reference these types, and also supports the use of extensions for the purposes of versioning and customization.
[GTD1] All types MUST be named.
<programlisting><xsd:complexType name="QuantityType"> ... </xsd:complexType></programlisting> </example> <para id="para-1.7.3.2.5">UBL disallows the use of the type xsd:anyType, because this feature permits the introduction of potentially unknown types into an XML instance.</para> <blockquote role="Rule" id="rule-GTD2"> <para id="para-1.7.3.2.6.1">[<emphasis role="rule-prefix">GTD2</emphasis>] The predefined XML schema type xsd:anyType MUST NOT be used.</para> </blockquote> </section> <section id="section-5.1.2"> <title>Simple Types CCTS provides a set of constructs called Core Component Types (CCTs) for the modeling of basic data. These are represented in UBL with a library of complex types. Most "simple" data is represented as property sets defined according to the CCTs, made up of content components and supplementary components. In most cases, the supplementary components are expressed as XML attributes, the content component becomes element content, and the CCT is represented with an xsd:complexType. There are exceptions to this rule in those cases where all of a CCT's properties can be expressed without the use of attributes. In these cases, an xsd:simpleType is used. UBL does not define its own simple types. These are defined in the UN/CEFACT Unqualified Datatype schema module. UBL defines restrictions of these simple types in the UBL Qualified Datatype schema module.
Complex Types Since even simple datatypes are modeled as property sets in most cases, the XML expression of these models primarily employs xsd:complexType. To facilitate reuse, versioning, and customization, all complex types are named. In the UBL model, ABIEs are considered classes (objects) .
[CTD1] For every class identified in the UBL model, a named xsd:complexType MUST be defined.
<programlisting><xsd:complexType name="BuildingNameType"> </xsd:complexType></programlisting> </example> <para id="para-1.7.3.4.5"/> <para id="para-1.7.3.4.6">Every class identified in the UBL model consists of properties. These properties are either ASBIEs, when the property represents another class, or BBIEs.</para> <blockquote role="Rule" id="rule-CTD25"> <para id="para-1.7.3.4.7.1">[<emphasis role="rule-prefix">CTD25</emphasis>] For every CCTS BBIE Property identified in the UBL model, a named xsd:complexType MUST be defined.</para> </blockquote> <section id="section-5.1.3.1"> <title>Aggregate Business Information Entities (ABIEs) An ABIE encapsulates the relationship between a class (the ABIE) and its properties (those data items contained within the ABIE). UBL represents this relationship by defining an xsd:complexType for each ABIE with its properties represented as a sequence of references to global elements.
[CTD2] Every CCTS ABIE xsd:complexType definition content model MUST contain an xsd:sequence element containing the appropriate global element declarations.
<programlisting><xsd:complexType name="AddressType"> ... <xsd:sequence> <xsd:element ref="cbc:CityName" minOccurs="0" maxOccurs="1"> ... </xsd:element> <xsd:element ref="cbc:PostalZone" minOccurs="0" maxOccurs="1"> ... </xsd:element> ... </xsd:sequence> </xsd:complexType></programlisting> </example> </section> <section id="section-5.1.3.2"> <title>Basic Business Information Entities (BBIEs) In accordance with CCTS, all BBIEs have a primary or secondary Representation Term. Representation Terms are expressed in the UBL Model as Unqualified Datatypes bound to a Core Component Type that describes their structure. In addition to the Unqualified Datatypes defined in CCTS, UBL has defined a set of Qualified Datatypes that are derived from the CCTS Unqualified Datatypes. The following set of rules specifies the way these relationships are expressed in the UBL XML library. As discussed above, BBIE Properties are represented with complex types. Within these are xsd:simpleContent elements that extend the Datatypes.
[CTD3] Every CCTS BBIE Property xsd:complexType definition content model MUST contain an xsd:simpleContent element.
[CTD4] Every CCTS BBIE Property xsd:complexType content model xsd:simpleContent element MUST consist of an xsd:extension element.
[CTD5] Every CCTS BBIE Property xsd:complexType xsd:base attribute value MUST be the UN/CEFACT Unqualified Datatype or UBL Qualified Datatype as appropriate.
<programlisting><xsd:complexType name="StreetNameType"> <xsd:simpleContent> <xsd:extension base="udt:NameType"/> </xsd:simpleContent> </xsd:complexType></programlisting> </example> </section> <section id="section-5.1.3.3"> <title>Datatypes There is a one-to-one relationship between CCTS CoreComponentTypes and CCTS PrimaryRepresentationTerms. Additionally, there are several CCTS SecondaryRepresentationTerms that are semantic refinements of their parent CCTS PrimaryRepresentationTerms. There is a CCTS UnqualifiedDataType for each CCTS PrimaryRepresentationTerm or CCTS SecondaryRepresentationTerm. In the UBL XML Library, each CCTS UnqualifiedDatatype is expressed as complex or simple type that is of the type of its corresponding CCTS CoreComponentType. UBL uses the CCTS UnqualifiedDatatypes that are provided by the UN/CEFACT Unqualified Datatype (UDT) schema module.
Qualified Datatypes The data types defined in the Unqualified Datatype (UDT) schema module are intended to be suitable as the xsd:base types for some, but not all BBIEs. As business process modeling reveals the need for specialized data types, new qualified data types will need to be defined. These new CCTS Qualified Datatypes must each be based on a CCTS Unqualified Datatype and must represent a semantic or technical restriction of the CCTS Unqualified Datatype. Technical restrictions must be implemented as an xsd:restriction or as a new xsd:simpleType if the supplementary components of the Qualified Datatype map directly to the properties of a built-in XSD data type.
[CTD6] For every CCTS Qualified Datatype used in the UBL model, a named xsd:complexType or xsd:simpleType MUST be defined.
[CTD20] A CCTS Qualified DataType MUST be based on an CCTS Unqualified Datatype and add some semantic and/or technical restriction to the CCTS Unqualified Datatype.
[CTD21] The name of a UBL Qualified DataType MUST be the qualifier term followed by the name of its base CCTS Unqualified DataType with separators and spaces removed.
In accordance with rule GXS3, built-in XSD data types are used whenever possible.
[CTD22] Every Qualified Datatype based on an Unqualified Datatype xsd:complexType whose supplementary components map directly to the properties of an XSD built-in data type MUST be defined as an xsd:simpleType, MUST contain one xsd:restriction element, and MUST include an xsd:base attribute that defines the specific XSD built-in data type required for the content component.
[CTD23] Every CCTS Qualified Datatype based on a CCTS Unqualified Datatype xsd:complexType whose supplementary components do not map directly to the properties of an XSD built-in data type MUST be defined as an xsd:complexType, MUST contain one xsd:simpleContent element, MUST contain one xsd:restriction element, and MUST include the Unqualified Datatype as its xsd:base attribute.
[CTD24] Every CCTS Qualified Datatype based on a CCTS Unqualified Datatype xsd:simpleType MUST contain one xsd:restriction element MUST include the unqualified datatype as its xsd:base attribute.
Core Component Types UBL uses UN/CEFACT's Core Component Type schema module.
Element Declarations
Elements Bound to Complex Types The binding of UBL elements to their xsd:complexTypes is based on the associations identified in the UBL model. For the BBIEs and ABIEs, the UBL elements are directly associated to their corresponding xsd:complexTypes.
[ELD3] For every class and property identified in the UBL model, a global element bound to the corresponding xsd:complexType MUST be declared.
<para id="para-1.7.4.2.4.2">For the Party.Details object class, a complex type/global element declaration pair is created through the declaration of a Party element that is of type PartyType.</para> <para id="para-1.7.4.2.4.3">The element thus created can be reused in the building of new business messages. The complex type thus created can be used through the declaration of new elements of that type in the building of both new and contextualized business messages.</para> </example> <example id="example-5.2.1.2"> <title/> <programlisting><xsd:element name="SupplierParty" type="SupplierPartyType"/> <xsd:complexType name="SupplierPartyType"/> ... </xsd:complexType></programlisting> </example> </section> <section id="section-5.2.2"> <title>Elements Representing ASBIEs An ASBIE is not a class like an ABIE. Rather, it is an association between two classes, and therefore the element declaration binds the element to the xsd:complexType of the associated ABIE. There are two types of ASBIEs — those that have qualifiers in the object class, and those that do not.
[ELD4] When a CCTS ASBIE is unqualified, it is bound via reference to the global CCTS ABIE element with which it is associated.
[ELD11] When a CCTS ASBIE is qualified, a new element MUST be declared and bound to the xsd:complexType of its associated CCTS ABIE.
Code List Import
[ELD6] The code list xsd:import element MUST contain the namespace and schema location attributes.
Empty Elements
[ELD7] Empty elements MUST not be declared, except in the case of extension where the UBL Extensions element is used.
Code Lists The following rules apply to the use of code lists in UBL.
[CDL1] All UBL codes MUST be part of a UBL or externally maintained code list.
The majority of code lists are owned and maintained by external agencies. UBL makes maximum use of such external code lists where they exist.
[CDL2] The UBL Library SHOULD identify and use external standardized code lists rather than develop its own UBL-native code lists.
In some cases, UBL may extend an existing code list to meet specific business requirements. In others cases, UBL may create and maintain a code list where a suitable code list does not exist in the public domain. Both of these types of code lists would be considered UBL-internal code lists.
[CDL3] The UBL Library MAY design and use an internal code list where an existing external code list needs to be extended, or where no suitable external code list exists.
Miscellaneous XSD Rules As a business standard vocabulary, UBL requires consistency in its development. The number of UBL schema developers will expand over time. To ensure consistency, it is necessary to address the optional features in XSD that are not addressed elsewhere.
xsd:simpleType XSD provides for 44 built-in data types expressed as simple types. For maximum reuse, these built-in simple types should be used wherever possible.
[GXS3] Built-in xsd:simpleTypes SHOULD be used wherever possible.
Namespace Declaration XSD allows any prefixes to be used in referencing its namespaces. To ensure consistency, UBL has adopted the generally accepted convention of using the "xsd" prefix for the XSD namespace.
[GXS4] All XSD constructs in UBL schema and schema modules MUST contain the following namespace declaration on the xsd:schema element:
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsd:substitutionGroup The xsd:substitutionGroup feature enables a type definition to identify substitution elements in a group. Although a useful feature in document-centric XML applications, this feature is not used by UBL.
[GXS5] The xsd:substitutionGroup feature MUST NOT be used.
xsd:final UBL does not use extensions in its normative schemas. Extensions are allowed by customizers as outlined in the Guidelines for Customization. In cases where type definitions are inappropriate for any customization, the xsd:final attribute is used.
[GXS6] The xsd:final attribute MUST be used to control extensions where there is a desire to prohibit further extensions.
xsd: notation The UBL schema model does not require or support the use of xsd:notation.
[GXS7] xsd:notation MUST NOT be used.
xsd:all When xsd:all is used, elements can occur in any order, are always optional, and can never occur more than once. Such restrictions are inconsistent with the applications of UBL.
[GXS8] xsd:all MUST NOT be used.
xsd:choice xsd:choice allows one of a set of alternatives to appear in a document instance. This is useful in some contexts but xsd:choice cannot be extended and therefore is not recommended.
[GXS9] The xsd:choice element SHOULD NOT be used where customization and extensibility are a concern.
xsd:include xsd:include may be used in accordance with rule GXS10.
[GXS10] xsd:include can only be used when the including schema is in the same namespace as the included schema.
xsd:union The xsd:union feature provides a mechanism whereby a datatype is created as a union of two or more existing datatypes. As UBL strictly adheres to the use of CCTS Datatypes that are explicitly declared in the UBL library, this feature is inappropriate except for code lists.
[GXS11] The xsd:union technique MUST NOT be used except for code lists.
xsd:appinfo The xsd:appinfo feature is used by schemas to convey processing instructions to a processing application, stylesheet, or other tool. Some users of UBL believe that this technique poses a security risk and have employed techniques for stripping xsd:appinfo from schemas. As UBL is committed to ensuring the widest possible target audience for its XML library, this feature is used only to convey information.
[GXS12] UBL schemas SHOULD NOT use xsd:appinfo. If used, xsd:appinfo MUST be used only to convey non-normative information.
xsd:schemaLocation UBL is an international standard that will be used in perpetuity by companies around the globe. It is important that these users have unfettered access to all UBL schemas.
[GXS15] Each xsd:schemaLocation attribute declaration MUST contain a system-resolvable URL, which at the time of release from OASIS shall be a relative URL referencing the location of the schema or schema module in the release package.
xsd:nillable
[GXS16] The built in xsd:nillable attribute MUST NOT be used for any UBL declared element.
xsd:any UBL disallows the use of xsd:any because this feature permits the introduction of unknown attributes into an XML instance. UBL intends that all constructs within an instance be governed by the schemas describing that instance, and therefore xsd:any is not allowed outside of the ExtensionContentType definition.
[GXS14] xsd:any MUST NOT be used except within the ExtensionContentType type definition, and with xsd:processContents= "skip" for non-UBL namespaces.
Extension and Restriction UBL recognizes the value of supporting extension and restriction of its core schema library by customizers. The UBL schema extension and restriction recommendations are discussed in the Guidelines for the Customization of UBL 1.0 Schemas (SchCust) available as part of the UBL 1.0 Standard.
[GXS13] Complex type extension or restriction MAY be used where appropriate.
Instance Documents In addition to the UBL 2.0 document constraints formally expressed in the schemas, UBL mandates several other rules governing conformant UBL 2.0 instances that cannot be expressed using XSD. These additional UBL rules address instance validation, character encoding, and empty elements. Note that these rules first appeared in the OASIS UBL 1.0 and UBL 1.0 NDR Standards, as well as in the Universal Business Language v2.0 release package. They are copied here for reference and put in this section to separate them from the schema-specific rules contained in the rest of the NDR. The UBL library and document schemas are targeted at supporting business information exchanges. Business information exchanges require a high degree of precision to ensure that application processing and corresponding business cycle actions are reflective of the purpose, intent, and information content agreed to by both trading partners. Schemas provide the necessary mechanism for ensuring that instance documents do in fact support these requirements.
[IND1] All UBL instance documents MUST validate to a corresponding UBL schema.
XML supports a wide variety of character encodings. Processors must understand which character encoding is employed in each XML document. XML assumes a default value of UTF-8 for character encoding, but best practice is to always identify the character encoding being employed.
[IND2] All UBL instance documents MUST identify their character encoding within the XML declaration.
Example: <?xml version="1.0" encoding="UTF-8"?> UBL, as an OASIS TC, is obligated to conform to agreements OASIS has entered into. OASIS is a liaison member of the ISO IEC ITU UN/CEFACT eBusiness Memorandum of Understanding Management Group (MOUMG). Resolution 01/08 (MOU/MG01n83) requires the use of UTF-8.
[IND3] In conformance with ISO IEC ITU UN/CEFACT eBusiness Memorandum of Understanding Management Group (MOUMG) Resolution 01/08 (MOU/MG01n83) as agreed to by OASIS, all UBL XML SHOULD be expressed using UTF-8.
Example: <?xml version="1.0" encoding="UTF-8"?> Use of empty elements within XML instance documents is a source of controversy for a variety of reasons. An empty element does not simply represent data that is missing. It may express data that is not applicable for some reason, trigger the expression of an attribute, denote all possible values instead of just one, mark the end of a series of data, or appear as a result of an error in XML file generation. Conversely, missing data elements can also have meaning, for example, "data not provided by trading partner". In information exchange environments, different trading partners may allow, require, or ban empty elements. UBL has determined that empty elements do not provide the level of assurance necessary for business information exchanges and therefore will not be used.
[IND5] UBL conformant instance documents MUST NOT contain an element devoid of content or containing null values, except in the case of extension, where the UBLExtensionContent element is used.
To ensure that no attempt is made to circumvent rule IND5, UBL also prohibits attempting to convey meaning by not conveying an element.
[IND6] The absence of a construct or data in a UBL instance document MUST NOT carry meaning.
Conformance This document was prepared for the internal use of the UBL 2.0 development effort and has no external conformance implications. Any organization wishing to adapt the UBL 2.0 Naming and Design Rules to its own use should specify conformance requirements in its version of this document.
Acknowledgements The editors thank Betty Harvey and G. Ken Holman for their assistance in producing this document. Code List Metadata (Informative) Included here for convenience are some observations regarding instance-level code list metadata defined in UBL 2.0 schemas for the information items governed by code lists. Note that what follows are not UBL Naming and Design Rules but rather implications of UBL's use of the UN/CEFACT Unqualified Data Type Schema Module. For items based on the unqualified data type Amount, the attribute currencyID has the coded value, and the instance-level metadata is one attribute: currencyCodeListVersionID For items based on the unqualified data type MeasureType, the attribute unitCode has the coded value, and the instance-level metadata is one attribute: unitCodeListVersionID For items based on the unqualified data type QuantityType, the attribute unitCode has the coded value, and the instance-level metadata consists of three attributes: unitCodeListID unitCodeListAgencyID unitCodeListAgencyName For an element named <xxxxxCode> based on the unqualified data type CodeType, the element has the coded value, and the instance-level metadata consists of seven attributes: listName listID listVersionID listSchemeURI listURI listAgencyName listAgencyID For an element named <yyyyyID> based on the unqualified data type IdentifierType, the element has the coded value, and the instance-level metadata consists of six attributes: schemeName schemeVersionID schemeURI schemeDataURI schemeAgencyName schemeAgencyID All instance-level code list metadata attributes are optional and can be specified separately for each coded value used; there are no global document-wide properties representing these attributes. Any combination of allowable metadata attributes can be specified by the author of the UBL instance to identify the semantics associated with the coded value in the information item. Absent any of these attributes, an implementation must make its own judgements about the implied semantics of the code based on the information available. In some cases, an incomplete set of metadata attributes may be enough to uniquely identify an associated code list. For example, a listSchemeURI or schemeURI value is probably sufficient to uniquely identify, respectively, a code or identifier. A combination of listName or listID with listVersionID for a code, or schemeName and schemeVersionID for an identifier, would probably also be sufficient. In the extreme case, all code list information associated with a coded value may be missing; for example: <cbc:DocumentCurrencyCode>USD</cbc:DocumentCurrencyCode> There is no harm in omitting code list identification for this code value if the application can safely assume that a value of "USD" for DocumentCurrencyCode means U.S. Dollar, which is usually a safe assumption if the instance comes from a known trading partner. Omission of code list metadata can be useful when it is desired to leave the exact version unspecified, as for example when making updates to a particular code list within a particular trading community. Omitting the metadata attributes associating instance data with a particular release of a code list makes it unnecessary to change instance generation at the moment the update is deployed. This assumes, of course, that such changes are being managed out-of-band by protocols within the community. Identifying metadata should be included in the instance if the sender thinks the receiver might misinterpret the code. And if an information item allows the union of two lists, and there happens to be an overlap between the two lists such that one or more codes appear on both lists, then identifying metadata must be used to unambiguously specify which code is intended. UBL-approved Acronyms and Abbreviations (Informative) The information included in this appendix is historical and has been included for informational purposes only.
Abbreviation and Acronym Table for UBL 2.0
Credit Card Verification Numbering System CV2
Identifier ID
Uniform Resource Identifier URI
United Nations Dangerous Goods UNDG
Universal Business Language UBL
Universally Unique Identifier UUID
Technical Terminology (Informative) Aggregate Business Information Entity (ABIE) A collection of related pieces of business information that together convey a distinct business meaning in a specific Business Context. Expressed in modelling terms, it is the representation of an Object Class, in a specific Business Context. Application-level validation Adherence to business requirements, such as valid account numbers. Assembly Using parts of the library of reusable UBL components to create a new kind of business document type. Business Context Defines a context in which a business has chosen to employ an information entity. The formal description of a specific business circumstance as identified by the values of a set of Context Categories allowing different business circumstances to be uniquely distinguished. Business Object An unambiguously identified, specified, referenceable, registerable, and re-useable scenario or scenario component of a business transaction. The term business object is used in two distinct but related ways, with slightly different meanings for each usage: In a business model, business objects describe its business context. The business objects capture business concepts and express an abstract view of the business's "real world". The term "modeling business object" is used to designate this usage. In a design for a software system or in program code, business objects reflect how business concepts are represented in software. The term "system business objects" is used to designate this usage. Business semantic(s) The precise meaning of words from a business perspective. Business Term A synonym under which the Core Component or Business Information Entity is commonly known and used in the business. A Core Component or Business Information Entity may be known by several business terms or synonyms. Class A description of a set of objects that share the same attributes, operations, methods, relationships, and semantics. A class may use a set of interfaces to specify collections of operations it provides to its environment. Class diagram (OMG Distilled) Shows Static structure of concepts, types, and classes. Concepts show how users think about the world; types show interfaces of software components; classes show implementation of software components. (Rational Unified Process) A diagram that shows a collection of declarative (static) model elements, such as classes, types, and their contents and relationships. Classification scheme Officially supported scheme to describe a given Context Category. Document schema A schema document corresponding to a single namespace, which is likely to include or import schema modules. Core Component A building block for the creation of a semantically correct and meaningful information exchange package. It contains only the information pieces necessary to describe a specific concept. Core Component Type A Core Component which consists of one and only one Content Component that carries the actual content plus one or more Supplementary Components giving an essential extra definition to the Content Component. Core Component Types do not have business semantics. Data type (XSD) A descriptor of a set of values that lack identity and whose operations do not have side effects. XSD data types include primitive pre-defined types and user-definable types. Pre-defined types include numbers, string, and time. User-definable types include enumerations. (CCTS) Defines the set of valid values that can be used for a particular Basic Core Component Property or Basic Business Information Entity Property. It is defined by specifying restrictions on the Core Component Type that forms the basis of the data type. Instance An individual entity satisfying the description of a class or type. In XML, an individual document of a certain type (a specific purchase order, invoice, etc.). Instance constraint checking Additional validation checking of an instance, beyond what XSD makes available, that relies only on constraints describable in terms of the instance and not additional business knowledge; e.g., checking co-occurrence constraints across elements and attributes. Such constraints might be described using Schematron, for example. Intermediate element An element not at the top level that is of a complex type, only containing other elements and attributes. Internal schema module A schema module that does not declare a target namespace. Leaf element An element containing only character data (though it may also have attributes). Note that, because of the XSD mechanisms involved, a leaf element that has attributes must be declared as having a complex type, but a leaf element with no attributes may be declared with either a simple type or a complex type. Lower-level element An element that appears inside a business message. Lower-level elements consist of intermediate and leaf level. Object Class The logical data grouping (in a logical data model) to which a data element belongs (ISO11179). The Object Class is the part of a Core Component's Dictionary Entry Name that represents an activity or object in a specific Context. Namespace schema module A schema module that declares a target namespace and is likely to include or import schema modules. Naming convention The set of rules that together comprise how the Dictionary Entry Name for Core Components and Business Information Entities are constructed. (XML) Schema An XML Schema consists of components such as type definitions and element declarations. These can be used to assess the validity of well-formed element and attribute information items (as defined in [XSD]), and furthermore may specify augmentations to those items and their descendants. Schema module A schema that can be included or imported by other schemas. Schema processing Schema validation checking plus provision of default values and provision of new infoset properties. Schema validation The process of programmatically checking a document instance for adherence to an XSD schema. Semantic Relating to meaning in language; relating to the connotations of words. Top-level element An element that encloses a whole UBL business message. Note that UBL business messages might be carried by messaging transport protocols that themselves have higher-level XML structure. Thus, a UBL top-level element is not necessarily the root element of the XML document that carries it. Type Description of a set of entities that share common characteristics, relations, attributes, and semantics. UBL NDR Checklist The following checklist reproduces all the UBL XML naming and design rules defined in this document. The checklist is in alphabetical sequence as follows: Attribute Declaration Rules (ATD) Code List Rules (CDL) ComplexType Definition Rules (CTD) ComplexType Naming Rules (CTN) Documentation Rules (DOC) Element Declaration Rules (ELD) Element Naming Rules (ELN) General Naming Rules (GNR) General Type Definition Rules (GTD) General XML Schema Rules (GXS) Instance Document Rules (IND) Modeling Constraints Rules (MDC) Naming Constraints Rules (NMC) Namespace Rules (NMS) Root Element Declaration Rules (RED) Schema Structure Modularity Rules (SSM) Standards Adherence Rules (STA) Versioning Rules (VER) Code List Rules CDL1 All UBL codes MUST be part of a UBL or externally maintained code list. CDL2 The UBL Library SHOULD identify and use external standardized code lists rather than develop its own UBL-native code lists. CDL3 The UBL Library MAY design and use an internal code list where an existing external code list needs to be extended, or where no suitable external code list exists. ComplexType Definition rules CTD1 For every class identified in the UBL model, a named xsd:complexType MUST be defined. CTD2 Every CCTS ABIE xsd:complexType definition content model MUST contain an xsd:sequence element containing the appropriate global element declarations. CTD3 Every CCTS BBIE Property xsd:complexType definition content model MUST contain an xsd:simpleContent element. CTD4 Every CCTS BBIE Property xsd:complexType content model xsd:simpleContent element MUST consist of an xsd:extension element. CTD5 Every CCTS BBIE Property xsd:complexType xsd:base attribute value MUST be the UN/CEFACT Unqualified Datatype or UBL Qualified Datatype as appropriate. CTD6 For every CCTS Qualified Datatype used in the UBL model, a named xsd:complexType or xsd:simpleType MUST be defined. CTD20 A CCTS Qualified DataType MUST be based on an CCTS Unqualified Datatype and add some semantic and/or technical restriction to the CCTS Unqualified Datatype. CTD21 The name of a UBL Qualified DataType MUST be the qualifier term followed by the name of its base CCTS Unqualified DataType with separators and spaces removed. CTD22 Every Qualified Datatype based on an Unqualified Datatype xsd:complexType whose supplementary components map directly to the properties of an XSD built-in data type MUST be defined as an xsd:simpleType, MUST contain one xsd:restriction element, and MUST include an xsd:base attribute that defines the specific XSD built-in data type required for the content component. CTD23 Every CCTS Qualified Datatype based on a CCTS Unqualified Datatype xsd:complexType whose supplementary components do not map directly to the properties of an XSD built-in data type MUST be defined as an xsd:complexType, MUST contain one xsd:simpleContent element, MUST contain one xsd:restriction element, and MUST include the Unqualified Datatype as its xsd:base attribute. CTD24 Every CCTS Qualified Datatype based on a CCTS Unqualified Datatype xsd:simpleType MUST contain one xsd:restriction element MUST include the unqualified datatype as its xsd:base attribute. CTD25 For every CCTS BBIE Property identified in the UBL model, a named xsd:complexType MUST be defined. Complex Type Naming rules CTN1 A UBL xsd:complexType name based on a CCTS ABIE MUST be the CCTS Dictionary Entry Name with the separators removed and with the "Details" suffix replaced with "Type". CTN2 A UBL xsd:complexType name based on a CCTS BBIE Property MUST be the CCTS Dictionary Entry Name shared Property Term and its qualifiers and the Representation Term of the BBIE with the separators removed and with the "Type" suffix appended after the Representation Term. CTN6 A UBL xsd:complexType name based on a CCTS BBIE Property and with a CCTS BBIE Representation Term of "Text" MUST have the word "Text" removed from the end of its name. CTN7 A UBL xsd:complexType name based on a CCTS BBIE Property and with a CCTS BBIE Representation Term of "Identifier" MUST replace "Identifier" with "ID" at the end of its name. CTN8 A UBL xsd:complexType name based on a CCTS BBIE Property MUST remove all duplication of words that occurs as a result of duplicate Property Terms and Representation Terms. Documentation rules DOC1 The xsd:documentation element for every data type MUST contain a set of annotations in the following order (as defined in CCTS Section 7): DictionaryEntryName (mandatory) Version (mandatory) Definition (mandatory) RepresentationTerm (mandatory) QualifierTerm(s) (mandatory, where used) UniqueIdentifier (mandatory) Usage Rule(s) (optional) Content Component Restriction (optional) DOC2 A datatype definition MAY contain one or more Content Component Restrictions to provide additional information on the relationship between the datatype and its corresponding Core Component Type. If used, the Content Component Restrictions MUST contain a set of annotations in the following order: RestrictionType (mandatory): Defines the type of format restriction that applies to the Content Component. RestrictionValue (mandatory): The actual value of the format restriction that applies to the Content Component. ExpressionType (optional): Defines the type of the regular expression of the restriction value. DOC3 A datatype definition MAY contain one or more Supplementary Component Restrictions to provide additional information on the relationship between the datatype and its corresponding Core Component Type. If used, the Supplementary Component Restrictions MUST contain a set of annotations in the following order: SupplementaryComponentName (mandatory): Identifies the Supplementary Component to which the restriction applies. RestrictionValue (mandatory, repetitive): The actual value(s) that is (are) valid for the Supplementary Component. DOC4 The xsd:documentation element for every BBIE MUST contain a set of annotations in the following order: ComponentType (mandatory): The type of component to which the object belongs. For BBIEs this MUST be "BBIE". DictionaryEntryName (mandatory): The official name of a BBIE. Version (optional): An indication of the evolution over time of the BBIE Entity. Definition (mandatory): The meaning of a BBIE. Cardinality (mandatory): Indicates whether the BBIE represents a not-applicable, optional, mandatory, or repetitive characteristic of the Aggregate Business Information Entity to which it belongs. ObjectClassQualifier (optional): The qualifier for the Object Class. ObjectClass (mandatory): The Object Class containing the BBIE. PropertyTermQualifier (optional): A word or words which help define and differentiate a BBIE. PropertyTerm (mandatory): Conveys the characteristic or Property of the Object Class. RepresentationTerm (mandatory): Describes the form in which the BBIE is represented. DataTypeQualifier (optional): A meaningful name that differentiates the data type of the BBIE from its underlying Core Component Type. DataType (mandatory): Defines the data type used for the BBIE. AlternativeBusinessTerms (optional): Any synonymous terms under which the BBIE is commonly known and used in the business. Examples (optional): Examples of possible values for the BBIE. DOC5 The xsd:documentation element for every ABIE MUST contain a set of annotations in the following order: ComponentType (mandatory): The type of component to which the object belongs. For ABIEs this MUST be "ABIE". DictionaryEntryName (mandatory): The official name of the ABIE . Version (optional): An indication of the evolution over time of the ABIE. Definition (mandatory): The meaning of the ABIE. ObjectClassQualifier (optional): The qualifier for the Object Class. ObjectClass (mandatory): The Object Class represented by the ABIE. AlternativeBusinessTerms (optional): Any synonymous terms under which the ABIE is commonly known and used in the business. DOC6 The xsd:documentation element for every ASBIE element declaration MUST contain a set of annotations in the following order: ComponentType (mandatory): The type of component to which the object belongs. For ASBIEs this MUST be "ASBIE". DictionaryEntryName (mandatory): The official name of the ASBIE. Version (optional): An indication of the evolution over time of the ASBIE. Definition (mandatory): The meaning of the ASBIE. Cardinality (mandatory): Indicates whether the ASBIE represents an optional, mandatory, or repetitive assocation. ObjectClass (mandatory): The Object Class containing the ASBIE. PropertyTermQualifier (optional): A word or words which help define and identify the ASBIE. PropertyTerm (mandatory): Represents the ASBIE contained by the Association Business Information Entity. AssociatedObjectClassQualifier (optional): The Associated Object Class Qualifiers describe the "context" of the relationship with another ABIE. That is, it is the role the contained ABIE plays within its association with the containing ABIE. AssociatedObjectClass (mandatory): The Object Class at the other end of the association. It represents the ABIE contained by the ASBIE. DOC8 The xsd:documentation element for every Supplementary Component attribute declaration MUST contain a set of annotations in the following order: Name (mandatory) Name in the Registry of a Supplementary Component of a Core Component Type. Definition (mandatory): An explanation of the meaning of a Supplementary Component and its relevance for the related Core Component Type. Primitive type (mandatory): The PrimitiveType to be used for the representation of the value of a Supplementary Component. Possible Value(s) (optional): Possible values of Supplementary Components. DOC9 The xsd:documentation element for every Supplementary Component attribute declaration containing restrictions MUST include the following additional information appended to the information required by DOC8: Restriction Value(s) (mandatory): The actual value(s) that is (are) valid for the Supplementary Component. Element Declaration rules ELD2 All element declarations MUST be global. ELD3 For every class and property identified in the UBL model, a global element bound to the corresponding xsd:complexType MUST be declared. ELD4 When a CCTS ASBIE is unqualified, it is bound via reference to the global CCTS ABIE element with which it is associated. ELD6 The code list xsd:import element MUST contain the namespace and schema location attributes. ELD7 Empty elements MUST not be declared, except in the case of extension where the UBL Extensions element is used. ELD11 When a CCTS ASBIE is qualified, a new element MUST be declared and bound to the xsd:complexType of its associated CCTS ABIE. ELD12 The UBL Extensions element MUST be declared as the first child of the document element with xsd:minOccurs="0". ELD13 The UBLProfileID element MUST be declared immediately following the UBL Extensions element with xsd:minOccurs="0". ELD14 The UBLSubsetID element MUST be declared immediately following the UBLProfileID element with xsd:minOccurs="0". Element Naming rules ELN1 A UBL global element name based on a CCTS ABIE MUST be the same as the name of the corresponding xsd:complexType to which it is bound, with the word "Type" removed. ELN2 A UBL global element name based on a CCTS BBIE Property MUST be the same as the name of the corresponding xsd:complexType to which it is bound, with the word "Type" removed. ELN3 A UBL global element name based on a CCTS ASBIE MUST be the CCTS ASBIE Dictionary Entry Name Property Term and its qualifiers and the Object Class Term and qualifiers of its associated CCTS ABIE. All CCTS Dictionary Entry Name separators MUST be removed. General Naming rules GNR1 UBL XML element and type names MUST be in the English language, using the primary English spellings provided in the Oxford English Dictionary. GNR2 UBL XML element and type names MUST be consistently derived from CCTS conformant Dictionary Entry Names. GNR3 UBL XML element and type names constructed from CCTS Dictionary Entry Names MUST NOT include periods, spaces, other separators, or characters not allowed by XSD. GNR4 UBL XML element names and simple and complex type names MUST NOT use acronyms, abbreviations, or other word truncations, except those in the list of exceptions maintained and published by the UBL TC. GNR6 The acronyms and abbreviations listed in the UBL-approved list MUST always be used in place of the word or phrase they represent. GNR7 UBL XML element and type names MUST be in singular form unless the concept itself is plural. GNR8 The UpperCamelCase (UCC) convention MUST be used for naming elements and types. GNR9 The lowerCamelCase (LCC) convention MUST be used for naming attributes. GNR10 Acronyms and abbreviations at the beginning of an attribute name MUST appear in all lower case. Acronyms and abbreviations elsewhere in an attribute name MUST appear in upper case. GNR11 Acronyms and abbreviations MUST appear in all upper case for all element and type names. General Type Definition Rules GTD1 All types MUST be named. GTD2 The predefined XML schema type xsd:anyType MUST NOT be used. General XML Schema Rules GXS1 Except in the case of extension, where the "UBL Extensions" element is used, UBL schemas SHOULD conform to the following physical layout as applicable: See . GXS2 UBL MUST provide two schemas for each transaction. One normative schema shall be fully annotated. One non-normative schema shall be a run-time schema devoid of documentation. GXS3 Built-in xsd:simpleTypes SHOULD be used wherever possible. GXS4 All XSD constructs in UBL schema and schema modules MUST contain the following namespace declaration on the xsd:schema element:
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 GXS5 The xsd:substitutionGroup feature MUST NOT be used. GXS6 The xsd:final attribute MUST be used to control extensions where there is a desire to prohibit further extensions. GXS7 xsd:notation MUST NOT be used. GXS8 xsd:all MUST NOT be used. GXS9 The xsd:choice element SHOULD NOT be used where customization and extensibility are a concern. GXS10 xsd:include can only be used when the including schema is in the same namespace as the included schema. GXS11 The xsd:union technique MUST NOT be used except for code lists. GXS12 UBL schemas SHOULD NOT use xsd:appinfo. If used, xsd:appinfo MUST be used only to convey non-normative information. GXS15 Each xsd:schemaLocation attribute declaration MUST contain a system-resolvable URL, which at the time of release from OASIS shall be a relative URL referencing the location of the schema or schema module in the release package. GXS16 The built in xsd:nillable attribute MUST NOT be used for any UBL declared element. GXS14 xsd:any MUST NOT be used except within the ExtensionContentType type definition, and with xsd:processContents= "skip" for non-UBL namespaces. GXS13 Complex type extension or restriction MAY be used where appropriate. Instance document rules IND1 All UBL instance documents MUST validate to a corresponding UBL schema. IND2 All UBL instance documents MUST identify their character encoding within the XML declaration. 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. IND5 UBL conformant instance documents MUST NOT contain an element devoid of content or containing null values, except in the case of extension, where the UBLExtensionContent element is used. IND6 The absence of a construct or data in a UBL instance document MUST NOT carry meaning. Modelling constraint rules MDC0 The sequence of the business information entities that is expressed in the UBL model MUST be preserved in the schema. MDC1 UBL libraries and schemas MUST only use CCTS Core Component Types, except in the case of extension, where the UBLExtensions element is used. MDC2 XML mixed content MUST NOT be used except where contained in an xsd:documentation element. Naming constraint rules NMC1 Each Dictionary Entry Name MUST define one and only one fully qualified path (FQP) for an element or attribute. Namespace Rules NMS1 Every UBL-defined or -used schema module, except internal schema modules, MUST declare a namespace using the xsd:targetNamespace attribute. NMS2 Every UBL-defined or -used major version schema set MUST have its own unique namespace. NMS3 UBL namespaces MUST only contain UBL developed schema modules. NMS4 The namespace names for UBL schemas holding committee draft status MUST be of the form urn:oasis:names:tc:ubl:schema:<subtype>:<document-id> NMS5 The namespace names for UBL schemas holding OASIS Standard status MUST be of the form urn:oasis:names:specification:ubl:schema:<subtype>:<document-id> NMS6 UBL published namespaces MUST never be changed. NMS7 The UBL Common Aggregate Components schema module MUST reside in its own namespace. NMS8 The UBL Common Aggregate Components schema module namespace MUST be represented by the namespace prefix "cac" when referenced in other schemas. NMS9 The UBL Common Basic Components schema module MUST reside in its own namespace. NMS10 The UBL Common Basic Components schema module namespace MUST be represented by the namespace prefix "cbc" when referenced in other schemas. NMS15 The UBL Qualified Datatypes schema module MUST reside in its own namespace. NMS16 The UBL Qualified Datatypes schema module namespace MUST be represented by the namespace prefix "qdt" when referenced in other schemas. NMS17 The CCTS Unqualified Datatypes schema module namespace MUST be represented by the prefix "udt" when referenced in other schemas. NMS18 The CommonExtensionComponents schema module namespace MUST be represented by the namespace prefix "ext" when referenced in other schemas. Root element declaration rules RED2 The root element MUST be the only global element declared in the document schema. Schema structure modularity rules SSM1 UBL schema expressions MAY be split into multiple schema modules. SSM2 A schema in one UBL namespace that is dependent upon type definitions or element declarations in another schema namespace MUST only import that schema. SSM3 A schema in one UBL namespace that is dependent upon type definitions or element declarations defined in another schema namespace MUST NOT import the internal schema modules of that schema. SSM6 All UBL internal schema modules MUST be in the same namespace as their corresponding document schema. SSM7 Each UBL internal schema module MUST be named <ParentSchemaModuleName><InternalSchemaModuleFunction> SSM8 UBL schema modules MAY be created for reusable components. SSM9 A schema module defining all UBL Common Aggregate Components MUST be created. SSM10 The UBL Common Aggregate Components schema module MUST be identified as CommonAggregateComponents in the document name within the schema header. SSM11 A schema module defining all UBL Common Basic Components MUST be created. SSM12 The UBL Common Basic Components schema module MUST be identified as CommonBasicComponents in the document name within the schema header. SSM18 A schema module defining all UBL Qualified Datatypes MUST be created. SSM19 The UBL Qualified Datatypes schema module MUST be identified as QualifiedDatatypes in the document name in the schema header. SSM20 The UBL Qualified Datatypes schema module MUST import the CCTS Unqualified Datatypes schema module. SSM21 The UBL extension schema module MUST be identified as CommonExtensionComponents in the document name within the schema header. Versioning rules VER2 Every UBL schema module major version MUST have an RFC 3121 document-id of the form <modulename>-<major> VER4 Every minor version release of a UBL schema module MUST have a document-id of the form <modulename>-<major> VER5 For UBL minor version changes, the namespace name MUST not change. VER6 Every UBL schema module major version number MUST be a sequentially assigned integer greater than zero. VER7 Every UBL schema module minor version number MUST be a sequentially assigned, non-negative integer. VER12 Every major version release of a UBL schema module MUST capture its version number in the xsd:version attribute of the xsd:schema element in the form <major>.0 VER14 Every minor version release of a UBL schema module MUST capture its version information in the xsd:version attribute in the form <major>.<non-zero> VER15 Every UBL document schema MUST declare an optional element named UBLVersionID immediately following the optional UBL Extensions element.