Universal Business Language (UBL) Naming and Design Rules · 6/28/2006 · 216 A.12Modelling...

cd-UBL-NDR-2.0.DRAFT 1 12 May 2006

1

Universal Business Language (UBL)2

Naming and Design Rules3

Publication Date4

28 June 20065Document identifier:6

cd-UBL-NDR-2.07Location:8

http://docs.oasis-open.org/ubl/cd-UBL-NDR-2.0910

Editors:11Mavis Cournane, Cognitran Limited <[email protected]>12

Mike Grimley, US Navy <[email protected]>13

Contributors:14

Bill Burcham, Sterling Commerce15Fabrice Desré, France Telecom16Matt Gertner, Schemantix17Jessica Glace, LMI18Arofan Gregory, Aeon LLC19Michael Grimley, US Navy20Eduardo Gutentag, Sun Microsystems21Sue Probert, CommerceOne22Gunther Stuhec, SAP23Paul Thorpe, OSS Nokalva24Jim Wilson, CIDX25

Past Chair26Eve Maler, Sun Microsystems <[email protected]>27

Abstract:28

This specification documents the naming and design rules and guidelines for the29construction of XML components for the UBL vocabulary.30

Status:31

This document has been approved by the OASIS Universal Business Language32Technical Committee as a Committee Draft and is submitted for consideration as33an OASIS Standard34


Table of Contents37

1 Introduction38611939

1.1 Audiences40712041

1.2 Scope42712043

1.3 Terminology and Notation44712045

1.4 Guiding Principles46912247

1.4.1 Adherence to General UBL Guiding Principles48912249

1.4.2 Design For Extensibility501112451

1.4.3 Code Generation521212553

1.5 Choice of schema language541312655

2 Relationship to ebXML Core Components561412757

2.1 Mapping Business Information Entities to XSD581713059

3 General XML Constructs602213561

3.1 Overall Schema Structure622213563

3.1.1 Element declarations within document schemas642313865

3.2 Naming and Modeling Constraints662413867

3.2.1 Naming Constraints682413969

3.2.2 Modeling Constraints702413971

3.3 Reusability Scheme722514073

3.4 Extension Scheme742614175


3.5 Namespace Scheme762714277

3.5.1 Declaring Namespaces782814379

3.5.2 Namespace Uniform Resource Identifiers803014481

3.5.3 Schema Location823114583

3.5.4 Persistence843114585

3.6 Versioning Scheme863214587

3.7 Modularity Strategy883615089

3.7.1 UBL Modularity Model903615191

3.7.2 Internal and External Schema Modules924015893

3.7.3 Internal Schema Modules944015895

3.7.4 External Schema Modules964115997

3.8 Annotation and Documentation Requirements984516499

3.8.1 Schema Annotation10045165101

3.8.2 Embedded documentation10245165103

4 Naming Rules10450171105

4.1 General Naming Rules10650171107

4.2 Type Naming Rules10853175109

4.2.1 Complex Type Names for CCTS Aggregate Business Information Entities11053175111

4.2.2 Complex Type Names for CCTS Basic Business Information Entity112Properties113

541751144.2.3 55176115


4.3 Element Naming Rules11655178117

4.3.1 Element Names for CCTS Aggregate Business Information Entities11855178119

4.3.2 Element Names for CCTS Basic Business Information Entity Properties12056179121

4.3.3 Element Names for CCTS Association Business Information Entities12256179123

4.4 Attributes in UBL12457180125

5 Declarations and Definitions12658182127

5.1 Type Definitions12858182129

5.1.1 General Type Definitions13058182131

5.1.2 Simple Types13258182133

5.1.3 Complex Types13459183135

5.2 Element Declarations13662189137

5.2.1 Elements Bound to Complex Types13862189139

5.2.2 Elements Representing ASBIEs14063190141

5.2.3 Elements Bound to Core Component Types142Error! Bookmark not defined.190143

5.2.4 Code List Import14463190145

5.2.5 Empty Elements14663190147

6 Code Lists14864195149

7 Miscellaneous XSD Rules15066197151

7.1 xsd:simpleType15266197153

7.2 Namespace Declaration15466197155


7.3 xsd:substitutionGroup15666197157

7.4 xsd:final15866197159

7.5 xsd: notation16067198161

7.6 xsd:all16267198163

7.7 xsd:choice16467198165

7.8 xsd:include16667198167

7.9 xsd:union16867199169

7.10 xsd:appinfo17068199171

7.11 xsd:schemaLocation17268199173

7.12 xsd:nillable17468199175

7.13 xsd:anyAttribute17668199177

7.14 Extension and Restriction17869200179

8 Instance Documents18070201181

8.1 Root Element18270201183

8.2 Validation18470201185

8.3 Character Encoding18670201187

8.4 Schema Instance Namespace Declaration18871202189

8.5 Empty Content.19071202191

Appendix A. UBL NDR 2.0 Checklist19273205193

A.1 Attribute Declaration rules19474206195


A.2 Code List rules19674206197

A.3 ComplexType Definition rules19875207199

A.4 Complex Type Naming rules20076208201

A.5 Documentation rules20277209203

A.6 Element Declaration rules20481213205

A.7 Element Naming rules20682214207

A.8 General Naming rules20883215209

A.9 General Type Definition Rules21084216211

A.10General XML Schema Rules21284216213

A.11Instance document rules21487219215

A.12Modelling constraint rules21688220217

A.13Naming constraint rules21888221219

A.14Namespace Rules22088221221

A.15Root element declaration rules22290222223

A.16Schema structure modularity rules22490222225

A.17Standards Adherence rules22691224227

A.18Versioning rules22891224229

Appendix B. Approved Acronyms and Abbreviations23095228231

Appendix C. Technical Terminology23296229233

Appendix D. References234102235235


Appendix E. Notices236103236237


1 Introduction238

XML is often described as the lingua franca of e-commerce. The implication is that by239standardizing on XML, enterprises will be able to trade with anyone, any time, without240the need for the costly custom integration work that has been necessary in the past. But241this vision of XML-based “plug-and-play” commerce is overly simplistic. Of course242XML can be used to create electronic catalogs, purchase orders, invoices, shipping243notices, and the other documents needed to conduct business. But XML by itself doesn't244guarantee that these documents can be understood by any business other than the one that245creates them. XML is only the foundation on which additional standards can be defined246to achieve the goal of true interoperability. The Universal Business Language (UBL)247initiative is the next step in achieving this goal.248

The task of creating a universal XML business language is a challenging one. Most large249enterprises have already invested significant time and money in an e-business250infrastructure and are reluctant to change the way they conduct electronic business.251Furthermore, every company has different requirements for the information exchanged in252a specific business process, such as procurement or supply-chain optimization. A253standard business language must strike a difficult balance, adapting to the specific needs254of a given company while remaining general enough to let different companies in255different industries communicate with each other.256

The UBL effort addresses this problem by building on the work of the electronic business257XML (ebXML) initiative. The ebXML effort, currently continuing development in the258Organization for the Advancement of Structured Information Standards (OASIS), is an259initiative to develop a technical framework that enables XML and other payloads to be260utilized in a consistent manner for the exchange of all electronic business data. UBL is261organized as an OASIS Technical Committee to guarantee a rigorous, open process for262the standardization of the XML business language. The development of UBL within263OASIS also helps ensure a fit with other essential ebXML specifications. UBL will be264promoted to the level of international standard.265

The UBL Technical Committee has established the UBL Naming and Design Rules266Subcommittee with the charter to "Recommend to the TC rules and guidelines for267normative-form schema design, instance design, and markup naming, and write and268maintain documentation of these rules and guidelines". Accordingly, this specification269documents the rules and guidelines for the naming and design of XML components for270the UBL library. It contains only rules that have been agreed on by the OASIS UBL271Naming and Design Rules Subcommittee (NDR SC). Proposed rules, and rationales for272those that have been agreed on, appear in the accompanying NDR SC position papers,273which are available at http://www.oasis-open.org/committees/ubl/ndrsc/.274


1.1 Audiences275

This document has several primary and secondary targets that together constitute its276intended audience. Our primary target audience is the members of the UBL Technical277Committee. Specifically, the UBL Technical Committee will use the rules in this278document to create normative form schema for business transactions. Developers279implementing ebXML Core Components may find the rules contained herein sufficiently280useful to merit adoption as, or infusion into, their own approaches to ebXML Core281Component based XML schema development. All other XML Schema developers may282find the rules contained herein sufficiently useful to merit consideration for adoption as,283or infusion into, their own approaches to XML schema development.284

1.2 Scope285

This specification conveys a normative set of XML schema design rules and naming286conventions for the creation of business based XML schema for business documents287being exchanged between two parties using XML constructs defined in accordance with288the ebXML Core Components Technical Specification.289

1.3 Terminology and Notation290

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD,291SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to292be interpreted as described in Internet Engineering Task Force (IETF) Request for293Comments (RFC) 2119. Non-capitalized forms of these words are used in the regular294English sense.295

[Definition] – A formal definition of a term. Definitions are normative.296[Example] – A representation of a definition or a rule. Examples are informative.297[Note] – Explanatory information. Notes are informative.298[RRRn] – Identification of a rule that requires conformance to ensure that an XML299Schema is UBL conformant. The value RRR is a prefix to categorize the type of300rule where the value of RRR is as defined in Table 1 and n (1..n) indicates the301sequential number of the rule within its category. In order to ensure continuity302across versions of the specification, rule numbers that are deleted in future303versions will not be re-issued, and any new rules will be assigned the next higher304number – regardless of location in the text. Future versions will contain an305appendix that lists deleted rules and the reason for their deletion. Only rules and306definitions are normative; all other text is explanatory.307

Figure 1 - Rule Prefix Token Value308

Rule Prefix Token ValueATD Attribute DeclarationATN Attribute NamingCDL Code List


CTD ComplexType DefinitionDOC DocumentationELD Element DeclarationELN Element NamingGNR General NamingGTD General Type DefinitionGXS General XML SchemaIND Instance DocumentMDC Modeling ConstraintsNMC Naming ConstraintsNMS NamespaceRED Root Element DeclarationSSM Schema Structure ModularitySTA Standards AdherenceVER Versioning

Bold – The bolding of words is used to represent example names or parts of names taken309from the library.310

Courier – All words appearing in courier font are values, objects, and keywords.311

Italics – All words appearing in italics, when not titles or used for emphasis, are special312terms defined in Appendix C.313

Keywords – keywords reflect concepts or constructs expressed in the language of their314source standard. Keywords have been given an identifying prefix to reflect their source.315The following prefixes are used:316

xsd: – represents W3C XML Schema Definition Language. If a concept, the words will317be in upper camel case, and if a construct, they will be in lower camel case.318

xsd: – complexType represents an XSD construct319

xsd: – SchemaExpression represents a concept320

ccts: – represents ISO 15000-5 ebXML Core Components Technical Specification321

ubl: – represents the OASIS Universal Business Language322

The terms “W3C XML Schema” and “XSD” are used throughout this document. They323are considered synonymous; both refer to XML Schemas that conform to Parts 1 and 2 of324the W3C XML Schema Definition Language (XSD) Recommendations. See Appendix C325for additional term definitions.326


1.4 Guiding Principles327

The UBL guiding principles encompass three areas:328

General UBL guiding principles329

Extensibility330

Code generation331

1.4.1 Adherence to General UBL Guiding Principles332

The UBL Technical Committee has approved a set of high-level guiding principles. The333UBL Naming and Design Rules Subcommittee (NDRSC) has followed these high-level334guiding principles for the design of UBL NDR. These UBL guiding principles are:335

Internet Use – UBL shall be straightforwardly usable over the Internet.336

Interchange and Application Use – UBL is intended for interchange and337application use.338

Tool Use and Support – The design of UBL will not make any assumptions339about sophisticated tools for creation, management, storage, or presentation340being available. The lowest common denominator for tools is incredibly low341(for example, Notepad) and the variety of tools used is staggering. We do not342see this situation changing in the near term.343

Legibility – UBL documents should be human-readable and reasonably clear.344

Simplicity – The design of UBL must be as simple as possible (but no345simpler).346

80/20 Rule – The design of UBL should provide the 20% of features that347accommodate 80% of the needs.348

Component Reuse –The design of UBL document types should contain as349many common features as possible. The nature of e-commerce transactions is350to pass along information that gets incorporated into the next transaction down351the line. For example, a purchase order contains information that will be352copied into the purchase order response. This forms the basis of our need for a353core library of reusable components. Reuse in this context is important, not354only for the efficient development of software, but also for keeping audit355trails.356

Standardization – The number of ways to express the same information in a357UBL document is to be kept as close to one as possible.358


Domain Expertise – UBL will leverage expertise in a variety of domains359through interaction with appropriate development efforts.360

Customization and Maintenance – The design of UBL must facilitate361customization and maintenance.362

Context Sensitivity – The design of UBL must ensure that context-sensitive363document types aren’t precluded.364

Prescriptiveness – UBL design will balance prescriptiveness in any single365usage scenario with prescriptiveness across the breadth of usage scenarios366supported. Having precise, tight content models and datatypes is a good thing367(and for this reason, we might want to advocate the creation of more368document type “flavors” rather than less). However, in an interchange format,369it is often difficult to get the prescriptiveness that would be desired in any370single usage scenario.371

Content Orientation – Most UBL document types should be as “content-372oriented” (as opposed to merely structural) as possible. Some document types,373such as product catalogs, will likely have a place for structural material such374as paragraphs, but these will be rare.375

XML Technology – UBL design will avail itself of standard XML processing376technology wherever possible (XML itself, XML Schema, XSLT, XPath, and377so on). However, UBL will be cautious about basing decisions on “standards”378(foundational or vocabulary) that are works in progress.379


Relationship to Other Namespaces – UBL design will be cautious about380making dependencies on other namespaces. UBL does not need to reuse381existing namespaces wherever possible. For example, XHTML might be382useful in catalogs and comments, but it brings its own kind of processing383overhead, and if its use is not prescribed carefully it could harm our goals for384content orientation as opposed to structural markup.385

Legacy formats – UBL is not responsible for catering to legacy formats;386companies (such as ERP vendors) can compete to come up with good387solutions to permanent conversion. This is not to say that mappings to and388from other XML dialects or non-XML legacy formats wouldn’t be very389valuable.390

Relationship to xCBL – UBL will not be a strict subset of xCBL, nor will it be391explicitly compatible with it in any way.1392

1.4.2 Design For Extensibility393

Many e-commerce document types are, broadly speaking, useful but require minor394structural modifications for specific tasks or markets. When a truly common XML395structure is to be established for e-commerce, it needs to be easy and inexpensive to396modify.397

Many data structures used in e-commerce are very similar to ’standard‘ data structures,398but have some significant semantic difference native to a particular industry or process.399In traditional Electronic Data Interchange (EDI), there has been a gradual increase in the400

1 XML Common Business Library (xCBL) is a set of XML business documents and their components.


number of published components to accommodate market-specific variations. Handling401these variations are a requirement, and one that is not easy to meet. A related EDI402phenomenon is the overloading of the meaning and use of existing elements, which403greatly complicates interoperation.404

To avoid the high degree of cross-application coordination required to handle structural405variations common to EDI and XML based systems–it is necessary to accommodate the406required variations in basic data structures without either overloading the meaning and407use of existing data elements, or requiring wholesale addition of new data elements. This408can be accomplished by allowing implementers to specify new element types that inherit409the properties of existing elements, and to also specify exactly the structural and data410content of the modifications.411

This approach can be expressed by saying that extensions of core elements are driven by412context.2 Context driven extensions should be renamed to distinguish them from their413parents, and designed so that only the new elements require new processing. Similarly,414data structures should be designed so that processes can be easily engineered to ignore415additions that are not needed. The UBL context methodology is discussed in the416Guidelines for the Customization of UBL Schemas available as part of UBL 1.0.417

1.4.3 Code Generation418

The UBL NDR makes no assumptions on the availability or capabilities of tools to419generate UBL conformant XSD Schemas. In conformance with UBL guiding principles,420the UBL NDR design process has scrupulously avoided establishing any naming or421

2 ebXML, Core Components Technical Specification – Part 8 of the ebXML TechnicalFramework, V2.01, 15 November, 2003


design rules that sub-optimize the UBL schemas in favor of tool generation. Additionally,422in conformance with UBL guiding principles, the NDR is sufficiently rigorous to avoid423requiring human judgment at schema generation time.424

1.5 Choice of schema language425

The W3C XML Schema Definition Language has become the generally accepted schema426language that is experiencing the most widespread adoption. Although other schema427languages exist that offer their own advantages and disadvantages, UBL has determined428that the best approach for developing an international XML business standard is to base429its work on W3C XSD.430

[STA1] All UBL schema design rules MUST be based on the W3C XML Schema431Recommendations: XML Schema Part 1: Structures and XML Schema432Part 2: Datatypes.433

A W3C technical specification holding recommended status represents consensus within434the W3C and has the W3C Director's stamp of approval. Recommendations are435appropriate for widespread deployment and promote W3C's mission. Before the Director436approves a recommendation, it must show an alignment with the W3C architecture. By437aligning with W3C specifications holding recommended status, UBL can ensure that its438products and deliverables are well suited for use by the widest possible audience with the439best availability of common support tools.440

[STA2] All UBL schema and messages MUST be based on the W3C suite of441technical specifications holding recommendation status.442


2 Relationship to ebXML Core Components443

UBL employs the methodology and model described in Core Components Technical444Specification, Part 8 of the ebXML Technical Framework, Version 2.01 of 15 November4452003 (CCTS) to build the UBL Component Library. The Core Components work is a446continuation of work that originated in, and remains a part of, the ebXML initiative. The447Core Components concept defines a new paradigm in the design and implementation of448reusable syntactically neutral information building blocks. Syntax neutral Core449Components are intended to form the basis of business information standardization450efforts and to be realized in syntactically specific instantiations such as ANSI ASC X12,451UN/EDIFACT, and XML representations such as UBL.452

The essence of the Core Components specification is captured in context neutral and453context specific building blocks. The context neutral components are defined as Core454Components (ccts:CoreComponents). Context neutral ccts:CoreComponents are455defined in CCTS as “A building block for the creation of a semantically correct and456meaningful information exchange package. It contains only the information pieces457necessary to describe a specific concept.”3 Figure 2-1 illustrates the various pieces of the458overall ccts:CoreComponents metamodel.459

The context specific components are defined as Business Information Entities460(ccts:BusinessInformationEntities).4 Context specific ccts:Business461

3 Core Components Technical Specification, Part 8 of the ebXML Technical Framework Version 2.0(Second Edition), UN/CEFACT, 15 November 2003

4 See CCTS Section 6.2 for a detailed discussion of the ebXML context mechanism.


InformationEntities are defined in CCTS as “A piece of business data or a group of462pieces of business data with a unique Business Semantic definition.”5 Figure 2-2463illustrates the various pieces of the overall ccts:BusinessInformationEntity464metamodel and their relationship with the ccts:CoreComponents metamodel.465

As shown in Figure 2-2, there are different types of ccts:CoreComponents and466ccts:BusinessInformationEntities. Each type of ccts:CoreComponent and467ccts:BusinessInformationEntity has specific relationships between and468amongst the other components and entities. The context neutral ccts:Core469Components are the linchpin that establishes the formal relationship between the various470context-specific ccts:BusinessInformationEntities.471

Figure 2-1 Core Components and Datatypes Metamodel6472




473


Figure 2-2. Business Information Entities Basic Definition Model474

475

2.1 Mapping Business Information Entities to XSD476

UBL consists of a library of ccts:BusinessInformationEntities. In creating this477library, UBL has defined how each of the ccts:BusinessInformationEntity478components map to an XSD construct (See figure 2-3). In defining this mapping, UBL479has analyzed the CCTS metamodel and determined the optimal usage of XSD to express480the various ccts:BusinessInformationEntity components. As stated above, a481


Figure 2-3. UBL Document Metamodel482

483ccts:BusinessInformationEntity can be a ccts:AggregateBusiness484InformationEntity, a ccts:BasicBusinessInformationEntity, or a485ccts:AssociationBusinessInformationEntity. In understanding the logic of486the UBL binding of ccts:BusinessInformationEntities to XSD expressions, it is487important to understand the basic constructs of the ccts:AggregateBusiness488InformationEntities and their relationships as shown in Figure 2-2.489

Both Aggregate and Basic Business Information Entities must have a unique name490(Dictionary Entry Name). The ccts:AggregateBusinessInformationEntities491are treated as objects and are defined as xsd:complexTypes. The ccts:Basic492BusinessInformationEntities are treated as attributes of the ccts:Aggregate493


BusinessInformationEntity and are found in the content model of the494ccts:AggregateBusinessInformationEntity as a referenced xsd:element.495The ccts:BasicBusinessInformationEntities are based on a reusable496ccts:BasicBusinessInformationEntityProperty which are defined as497xsd:complexTypes.498

A Basic Business Information Entity Property represents an intrinsic property of an499Aggregate Business Information Entity. Basic Business Information Entity properties are500linked to a Datatype. UBL uses two types of Datatypes – unqualified that are provided by501the UN/CEFACT Unqualified Datatype (udt) schema module, and qualified datatypes502that are defined by UBL.503

UBL’s use of the UN/CEFACT Unqualified Datatype schema module is primarily504confined to its importation. It must not be assumed that UBL’s adoption of the UDT505schema module extends to any of ATG’s rules that have a bearing on the use of the506UDT.507

The ccts:UnqualifiedDatatypes correspond to ccts:RepresentationTerms.508The ubl:QualifiedDatatypes are derived from ccts:UnqualifiedDatatypes509with restrictions to the allowed values or ranges of the corresponding510ccts:ContentComponent or ccts:SupplementaryComponent.511

CCTS defines an approved set of primary and secondary representation terms. However,512these representation terms are simply naming conventions to identify the Datatype of an513object, not actual constructs. These representation terms are in fact the basis for514Datatypes as defined in the CCTS.515


A ccts:Datatype “defines the set of valid values that can be used for a particular516Basic Core Component Property or Basic Business Information Entity Property517Datatype”7 The ccts:Datatypes can be either unqualified—no restrictions518applied—or qualified through the application of restrictions. The sum total of the519datatypes is then instantiated as the basis for the various XSD simple and complex types520defined in the UBL schemas. CCTS supports datatypes that are qualified, i.e. it enables521users to define their own datatypes for their syntax neutral constructs. Thus522ccts:Datatypes allow UBL to identify restrictions for elements when restrictions to523the corresponding ccts:ContentComponent or ccts:SupplementaryComponent524are required.525

There are two kinds of Business Information Entity Properties - Basic and Association. A526ccts:AssociationBusinessInformationEntityProperty represents an527extrinsic property – in other words an association from one ccts:Aggregate528BusinessInformationEntityProperty instance to another ccts:Aggregate529BusinessInformationEntityProperty instance. It is the ccts:Aggregate530BusinessInformationEntityProperty that expresses the relationship between531ccts:AggregateBusinessInformationEntities. Due to their unique extrinsic532association role, ccts:AssociationBusinessInformationEntities are not533defined as xsd:complexTypes, rather they are either declared as elements that are then534bound to the xsd:complexType of the associated ccts:AggregateBusiness535InformationEntity, or they are reclassified ABIEs.536

As stated above, ccts:BasicBusinessInformationEntities define the intrinsic537structure of a ccts:AggregateBusinessInformationEntity. These538



ccts:BasicBusinessInformationEntities are the “leaf” types in the system in539that they contain no ccts:AssociationBusinessInformationEntity properties.540

A ccts:BasicBusinessInformationEntity must have a ccts:CoreComponent541Type. All ccts:CoreComponentTypes are low-level types, such as Identifiers and542Dates. A ccts:CoreComponentType describes these low-level types for use by543ccts:CoreComponents, and (in parallel) a ccts:Datatype, corresponding to that544ccts:CoreComponentType, describes these low-level types for use by545ccts:BusinessInformationEntities. Every ccts:CoreComponentType has a546single ccts:ContentComponent and one or more ccts:Supplementary547Components. A ccts:ContentComponent is of some Primitive Type. All548ccts:CoreComponentTypes and their corresponding content and supplementary549components are pre-defined in the CCTS. UBL has developed an xsd:SchemaModule550that defines each of the pre-defined ccts:CoreComponentTypes as an551xsd:complexType or xsd:simpleType and declares ccts:Supplementary552Components as an xsd:attribute or uses the predefined facets of the built-in553xsd:Datatype for those that are used as the base expression for an554xsd:simpleType. UBL continues to work with UN/CEFACT and the Open555Applications Group to develop a single normative schema for representing556ccts:CoreComponentTypes.557

3 General XML Constructs558

This chapter defines UBL rules related to general XML constructs to include:559

Overall Schema Structure560

Naming and Modeling Constraints561

Reusability Scheme562

Namespace Scheme563

Versioning Scheme564

Modularity Strategy565

Annotation and Documentation Requirements566

3.1 Overall Schema Structure567

A key aspect of developing standards is to ensure consistency in their development. Since568UBL is envisioned to be a collaborative standards development effort, with liberal569developer customization opportunities through use of the xsd:extension and570xsd:restriction mechanisms, it is essential to provide a mechanism that will571guarantee that each occurrence of a UBL conformant schema will have the same look and572feel.573

[GXS1] UBL Schema MUST conform to the following physical layout as applicable:574

575

<?xml version="1.0" encoding="UTF-8"?>576

577

Document Name: < Document name as indicated in Section 3.6 >578

Generated On: < Date schema was generated >579

580

xsd:schema element to include version attribute and namespace declarations in the581following order:582

xmlns:xsd583

Target namespace584

Default namespace585

CommonAggregateComponents586

CommonBasicComponents587

CoreComponentTypes588

Unqualified Datatypes589

Qualified Datatypes590

Identifier Schemes591

Code Lists592

Attribute Declarations – elementFormDefault="qualified"593attributeFormDefault="unqualified"594

Version Attribute595

596

CommonAggregateComponents schema module597

CommonBasicComponents schema module598

Unqualified Types schema module599

Qualified Types schema module600

601

602

Root Element Declaration603

Root Element Type Definition604

605

alphabetized order606

607

All type definitions segregated by basic and aggregates as follows608

609

alphabetized order of ccts:AggregateBusinessInformationEntity xsd:TypeDefinitions610

611

alphabetized order of ccts:BasicBusinessInformationEntities612

613

Required OASIS full copyright notice.614

3.1.1 Element declarations within document schemas615

[Definition] Document schema –616


The overarching schema within a specific namespace that conveys the business617document functionality of that namespace. The document schema declares a target618namespace and is likely to xsd:include internal schema modules or xsd:import619external schema modules. Each namespace will have one, and only one, document620schema.621

In order to facilitate the management and reuse of UBL constructs, all global elements,622excluding the root element of the document schema must reside in either the CAC or623CBC schema modules.624

[ELD10] The root element MUST be the only global element declared in document625schemas.626

3.2 Naming and Modeling Constraints627

A key aspect of UBL is to base its work on process modeling and data analysis as628precursors to developing the UBL library. In determining how best to affect this work,629several constraints have been identified that directly impact both the process modeling630and data analysis, and the resultant UBL Schema.631

3.2.1 Naming Constraints632

A primary aspect of the UBL library documentation are its spreadsheet models. The633entries in these spreadsheet models fully define the constructs available for use in UBL634business documents. These spreadsheet entries contain fully conformant CCTS dictionary635entry names as well as truncated UBL XML element names developed in conformance636with the rules in section 4. The dictionary entry name ties the information to its637standardized semantics, while the name of the corresponding XML element is only638shorthand for this full name. The rules for element naming and dictionary entry naming639are different.640

[NMC1] Each dictionary entry name MUST define one and only one fully qualified641path (FQP) for an element or attribute.642

The fully qualified path anchors the use of that construct to a particular location in a643business message. The definition of the construct identifies any semantic dependencies644that the FQP has on other elements and attributes within the UBL library that are not645otherwise enforced or made explicit in its structural definition.646

3.2.2 Modeling Constraints647

In keeping with UBL guiding principles, modeling constraints are limited to those648necessary to ensure consistency in development of the UBL library.649


3.2.2.1 Defining Classes650

UBL is based on instantiating ebXML ccts:BusinessInformationEntities. UBL651models and the XML expressions of those models are class driven. Specifically, the UBL652library defines classes for each ccts:AggregateBusinessInformationEntity and653the UBL schemas instantiate those classes. The attributes of those classes consist of654ccts:BasicBusinessInformationEntities.655

3.2.2.2 Core Component Types656

Each ccts:BasicBusinessInformationEntity has an associated ccts:Core657ComponentType. The CCTS specifies an approved set of ccts:Core658ComponentTypes. To ensure conformance, UBL is limited to using this approved set.659

[MDC1] UBL Libraries and Schemas MUST only use ebXML Core Component660approved ccts:CoreComponentTypes.661

Customization is a key aspect of UBL’s reusability across business verticals. The UBL662rules have been developed in recognition of the need to support customizations. Specific663UBL customization rules are detailed in the UBL customization guidelines.664

3.2.2.3 Mixed Content665

UBL documents are designed to effect data-centric electronic commerce. Including666mixed content in business documents is undesirable because business transactions are667based on exchange of discrete pieces of data that must be clearly unambiguous. The668white space aspects of mixed content make processing unnecessarily difficult and add a669layer of complexity not desirable in business exchanges.670

[MDC2] Mixed content MUST NOT be used except where contained in an671xsd:documentation element.672

3.3 Reusability Scheme673

The effective management of the UBL library requires that all element declarations are674unique across the breadth of the UBL library. Consequently, UBL elements are declared675globally.676

3.3.1.4 Reusable Elements677

UBL elements are global and qualified. Hence in the example below, the <Address>678element is directly reusable as a modular component and some software can be used679without modification.680

Example681

<xsd:element name="Party" type="PartyType"/>682 <xsd:complexType name="PartyType">683


<xsd:annotation>684 <!—Documentation goes here -->685 </xsd:annotation>686 <xsd:sequence>687 <xsd:element ref="cbc:MarkCareIndicator" minOccurs="0"688maxOccurs="1">689 ...690 </xsd:element>691 <xsd:element ref="cbc:MarkAttentionIndicator" minOccurs="0"692maxOccurs="1">693 ...694 </xsd:element>695 <xsd:element ref="PartyIdentification" minOccurs="0"696maxOccurs="unbounded">697 ...698 </xsd:element>699 <xsd:element ref="PartyName" minOccurs="0" maxOccurs="1">700 ...701 </xsd:element>702 <xsd:element ref="Address" minOccurs="0" maxOccurs="1">703 ...704 </xsd:element>705

...706 </xsd:sequence>707 </xsd:complexType>708<xsd:element name="Address" type="AddressType"/>709<xsd:complexType name="AddressType">710 ...711 <xsd:sequence>712 <xsd:element ref="cbc:CityName" minOccurs="0" maxOccurs="1">713 ...714 </xsd:element>715 <xsd:element ref="cbc:PostalZone" minOccurs="0" maxOccurs="1">716 ...717 </xsd:element>718 ...719 </xsd:sequence>720</xsd:complexType>721

Software written to work with UBL's standard library will work with new assemblies of722the same components since global elements will remain consistent and unchanged. The723globally declared <Address> element is fully reusable without regard to the reusability724of types and provides a solid mechanism for ensuring that extensions to the UBL core725library will provide consistency and semantic clarity regardless of its placement within a726particular type.727

728

[ELD2] All element declarations MUST be global729

3.4 Extension Scheme730

There is a recognized requirement that some organizations are required by law to send731additional information not covered by the UBL document structure, thus requiring an732extension to the UBL message. The xsd:any construct is seen as the most efficient way733to implement this requirement.734


In general, UBL restricts the use of xsd:any because this feature permits the735introduction of potentially unknown elements into an XML instance. However, limiting736its use to a single, predefined element mitigates this risk. Since it is a priority that there737can be meaningful validation of the UBL document instances the value of the738xsd:processContents attribute of the element must be set to “skip”, thereby739removing the potential for errors in the validation layer. Any use of xsd:any should also740allow no more than one element in the non-UBL namespace to ease serialization of the741extending element as its own XML instance that can then be validated, if an implementer742wishes to do so, outside the UBL validation process.743

744

[GXS14] The xsd:any element MUST NOT be used except within the745'UBLExtensionType' type definition, and with xsd:processContents=746"skip" for non-UBL namespaces.747

The following rules apply in the order below.748

[ELD12] The 'UBL Extension' element declaration MUST exist with749xsd:minOccurs="0".750

751

[ELD13] The 'UBLProfileID' element declaration MUST exist with752xsd:minOccurs="0".753

754

755


[ELD14] The 'UBLSubset' element declaration MUST exist with756xsd:minOccurs="0".757

758

759

3.5 Namespace Scheme760

The concept of XML namespaces is defined in the W3C XML namespaces technical761specification.8 The use of XML namespace is specified in the W3C XML Schema (XSD)762Recommendation. A namespace is declared in the root element of a Schema using a763namespace identifier. Namespace declarations can also identify an associated764prefix—shorthand identifier—that allows for compression of the namespace name. For765each UBL namespace, a normative token is defined as its prefix. These tokens are defined766in the versioning scheme section.767

3.5.1 Declaring Namespaces768

Neither XML 1.0 nor XSD require the use of Namespaces. However the use of769namespaces is essential to managing the complex UBL library. UBL will use UBL-770defined schemas (created by UBL) and UBL-used schemas (created by external771activities) and both require a consistent approach to namespace declarations.772

8 Tim Bray, D Hollander, A Layman, R Tobin; Namespaces in XML 1.1, W3C Recommendation, February2004.


[NMS1] Every UBL-defined –or -used schema module, except internal schema773modules, MUST have a namespace declared using the774xsd:targetNamespace attribute.775

Each UBL schema module consists of a logical grouping of lower level artifacts that776together comprise an association that will be able to be used in a variety of UBL777schemas. These schema modules are grouped into a schema set. Each schema set is778assigned a namespace that identifies that group of schema modules. As constructs are779changed, new versions will be created. The schema set is the versioned entity, all schema780modules within that package are of the same version, and each version has a unique781namespace.782

[Definition] Schema Set –783

A collection of schema instances that together comprise the names in a specific UBL784namespace.785

Schema validation ensures that an instance conforms to its declared schema. There786should never be two (different) schemas with the same namespace Uniform Resource787Identifier (URI). In keeping with Rule NMS1, each UBL schema module will be part of a788versioned namespace.789

[NMS2] Every UBL-defined-or -used major version schema set MUST have its own790unique namespace.791

UBL’s extension methodology encourages a wide variety in the number of schema792modules that are created as derivations from UBL schema modules. Clarity and793


consistency requires that customized schema not be confused with those developed by794UBL.795

[NMS3] UBL namespaces MUST only contain UBL developed schema modules.796

3.5.2 Namespace Uniform Resource Identifiers797

A UBL namespace name must be a URI reference that conforms to RFC 2396.9 UBL has798adopted the Uniform Resource Name (URN) scheme as the standard for URIs for799UBLnamespaces, in conformance with IETF’s RFC 3121, as defined in this next800section.10801

Rule NMS2 requires separate namespaces for each UBL schema set. The UBL802namespace rules differentiate between committee draft and OASIS Standard status. For803each schema holding draft status, a UBL namespace must be declared and named.804

[NMS4] The namespace names for UBL Schemas holding committee draft status805MUST be of the form:806

urn:oasis:names:tc:ubl:schema:<subtype>:<document-id>807

The format for document-id is found in the next section.808

9 T. Berners-Lee, R. Fielding, L. Masinter; Internet Engineering Task Force (IETF) RFC 2396, UniformResource Identifiers (URI): Generic Syntax, Internet Society, August 1998.

10 Karl Best, N. Walsh,; Internet Engineering Task Force (IETF) RFC 3121, A URN Namespace for OASIS,June 2001.


For each UBL schema holding OASIS Standard status, a UBL namespace must be809declared and named using the same notation, but with the value ‘specification”810replacing the value ‘tc’.811

[NMS5] The namespace names for UBL Schemas holding OASIS Standard status812MUST be of the form:813

814urn:oasis:names:specification:ubl:schema:<subtype>:<docum815ent-id>816

3.5.3 Schema Location817

UBL schemas use a URN namespace scheme. In contrast, schema locations are typically818defined as a Uniform Resource Locator (URL). UBL schemas must be available both at819design time and run time. As such, the UBL schema locations will differ from the UBL820namespace declarations. UBL, as an OASIS TC, will utilize an OASIS URL for hosting821UBL schemas. UBL will use the committee directory http://www.oasis-822open.org/committees/ubl/schema/.823

3.5.4 Persistence824

A key differentiator in selecting URNs to define UBL namespaces is URN persistence.825UBL namespaces must never violate this functionality by subsequently changing once it826has been declared. Conversely, changes to a schema may result in a new namespace827declaration. Thus a published schema version and its namespace association will always828be inviolate.829

[NMS6] UBL published namespaces MUST never be changed.830


3.6 Versioning Scheme831

UBL has adopted a two-layer versioning scheme. Major version information is captured832within the namespace name of each UBL schema module while combined major and833minor version information is captured within the xsd:version attribute of the xsd:schema834element.835

UBL namespaces conform to the OASIS namespace rules defined in RFC 3121. 11 The836last field of the namespace name is called document-id. UBL has decided to include837versioning information as part of the document-id component of the namespace. Only major838version information will be captured within the document-id. The major field has an839optional revision extension which can be used for draft schemas. For example, the840namespace URI for the draft Invoice domain has this form:841

urn:oasis:names:tc:ubl:schema:xsd:Invoice-<major>[.<revision>]842843

The major-version field is “1” for the first release of a namespace. Subsequent major844releases increment the value by 1. For example, the first namespace URI for the first845major release of the Invoice document has the form:846

urn:oasis:names:tc:ubl:schema:xsd:Invoice-1847

The second major release will have a URI of the form:848

urn:oasis:names:tc:ubl:schema:xsd:Invoice-2849

11 Karl Best, N. Walsh; Internet Engineering Task Force (IETF) RFC 3121, A URN Namespace for OASIS,June 2001.


In general, the namespace URI for every major release of the Invoice domain has the850form:851

urn:oasis:names:tc:ubl:schema:xsd:Invoice:-<major-852number>[.<revision>]853

854[VER1] Every UBL Schema and schema module major version committee draft855

MUST have an RFC 3121 document-id of the form856

<name>-<major>[.<revision>]857858859

[VER11] Every UBL Schema and schema module major version committee draft860MUST capture its version number in the xsd:version attribute of the861xsd:schema element in the form862

<major>.0[.<revision>]863864865

[VER2] Every UBL Schema and schema module major version OASIS Standard866MUST have an RFC 3121 document-id of the form867

<name>-<major>868869

[VER12] Every UBL Schema and schema module major version OASIS Standard870MUST capture its version number in the xsd:version attribute of the871xsd:schema element in the form872

<major>.0873

For each document produced by the TC, the TC will determine the value of the <name>874variable. In UBL, the major-version field must be changed in a release that breaks875compatibility with the previous release of that namespace. If a change does not break876compatibility then only the minor version need change. Subsequent minor releases begin877with minor-version 1.878

Example879

The namespace URI for the first minor release of the Invoice domain has this form:880881

urn:oasis:names:tc:ubl:schema:xsd:Invoice-<major>882883

The value of the xsd:schema xsd:version attribute for the first minor release of the884Invoice domain has this form:885

886<major>.1887888[VER3] Every minor version release of a UBL schema or schema module draft MUST889

have an RFC 3121 document-id of the form890

<name>-<major>[.<revision>]891892893


[VER13] Every minor version release of a UBL schema or schema module draft MUST894capture its version information in the xsd:version attribute in the form895

<major>.<non-zero>[.<revision>]896897898899

[VER4] Every minor version release of a UBL schema or schema module OASIS900Standard MUST have an RFC 3121 document-id of the form901

<name>-<major>902903904

[VER14] Every minor version release of a UBL schema or schema module OASIS905Standard MUST capture its version information in the xsd:version906attribute in the form907

<major>.<non-zero>908

Once a schema version is assigned a namespace, that schema version and that namespace909will be associated in perpetuity. However, because minor schema versions will retain the910major version namespace, this is not a one-to-one relationship.911

[VER5] For UBL Minor version changes the namespace name MUST not change,912

UBL is composed of a number of interdependent namespaces. For instance, namespaces913whose URI’s start with urn:oasis:names:tc:ubl:schema:xsd:Invoice-* are914dependent upon the common basic and aggregate namespaces, whose URI’s have the915form urn:oasis:names:tc:ubl:schema:xsd:CommonBasicComponents-* and916urn:oasis:names:tc:ubl:schema:xsd:CommonAggregateComponents-* respectively.917If either of the common namespaces requires a major version change then its namespace918URI must change. If its namespace URI changes then any schema that imports the new919version of the namespace must also change (to update the namespace declaration). And920since this would require a major version change to the importing schema, its namespace921URI in turn must change. The outcome is twofold:922

There should never be ambiguity at the point of reference in a namespace923declaration or version identification. A dependent schema imports precisely924the version of the namespace that is needed. The dependent schema never925needs to account for the possibility that the imported namespace can change.926

When a dependent schema is upgraded to import a new version of a schema,927the dependent schema’s version must change.928

Minor version changes, however, would not require changes to the namespace URI of929any schemas.930

Version numbers are based on a logical progression. All major and minor version931numbers will be based on positive integers. Version numbers always increment positively932by one.933


[VER6] Every UBL Schema and schema module major version number MUST be a934sequentially assigned, incremental number greater than zero.935

936[VER7] Every UBL Schema and schema module minor version number MUST be a937

sequentially assigned, incremental non-negative integer.938

UBL version information will also be captured in instances of UBL document schemas939via a ubl:UBLVersion element.940

[VER15] Every UBL document schema MUST include a required element named941"UBLVersion" as the first child of its root element. This element MUST have942a default value that matches the value of the xsd:version attribute of its943containing schema.944

A minor revision (of a schema) imports the schema module for the previous version. For945instance, the schema module defining xsd:version = “1.2” will import the schema946defining xsd:version = “1.1”947

The version 1.2 revision may define new complex types by extending version 1.1948types. It may define brand new complex types and elements by composition. It may also949use the XSD redefine element to change the definition of a type or element in the 1.1950version as long as it only redefines via the xsd:extension mechanism.951

For a particular namespace, the minor versions of a major version form a linearly-linked952family. The first minor version schema imports its parent major version schema. Each953successive minor version schema imports the schema module of the preceding minor954version.955

Example956

The minor version schema module defining xsd:version = “1.2” will import the957minor version schema defining xsd:version = “1.1” which will, in turn, import958the major version schema defining xsd:version = “1.0”. Each of these schemas959will have the namespace name that is declared in the major version 1.0 schema.960961962[VER8] A UBL minor version document schema MUST import its immediately963

preceding version document schema.964

To ensure that backwards compatibility through polymorphic processing of minor965versions within a major version always occurs, minor versions must be limited to certain966allowed changes. This guarantee of backward compatibility is built into the967xsd:extension mechanism. Thus, backward incompatible version changes can not be968expressed using this mechanism.969

[VER9] UBL Schema and schema module minor version changes MUST be limited to970the use of xsd:extension or xsd:restriction to alter existing types or971add new constructs.972


In addition to polymorphic processing considerations, semantic compatibility across973minor versions (as well as major versions) is essential. Semantic compatibility in this974sense pertains to preserving the business function. This does not preclude the deprecation975of a particular syntactic construct, and its replacement by a completely new syntactic976construct with a new name.977

[VER10] UBL Schema and schema module minor version changes MUST not break978semantic compatibility with prior versions.979

3.7 Modularity Strategy980

There are many possible mappings of XML schema constructs to namespaces and to981files. In addition to the logical taming of complexity that namespaces provide, dividing982the physical realization of schema into multiple files—schema modules—provides a983mechanism whereby reusable components can be imported as needed without the need to984import overly complex complete schema.985

[SSM1] UBL Schema expressions MAY be split into multiple schema modules.986

[Definition] schema module –987

A schema document containing type definitions and element declarations intended to988be reused in multiple schemas.989

3.7.1 UBL Modularity Model990

UBL relies extensively on modularity in schema design. There is no single UBL root991schema. Rather, there are a number of UBL document schemas, each of which expresses992a separate business function. The UBL modularity approach is structured so that users993can reuse individual document schemas without having to import the entire UBL994document schema library. Additionally, a document schema can import individual995modules without having to import all UBL schema modules. Each document schema will996define its own dependencies. The UBL schema modularity model ensures that logical997associations exist between document and internal schema modules and that individual998modules can be reused to the maximum extent possible. This is accomplished through the999use of document and internal schema modules as shown in Figure 3-1.1000

If the contents of a namespace are small enough then they can be completely specified1001within a single schema.1002

Figure 3-1. UBL Schema Modularity Model1003


W 3C XML SchemaFile Namespace

Document Schema SchemaModule

ExternalSchemaModule

Internal Schema Module

1

11 1 1

Shaded area is a "schema set "

Internal Schema Modules are in same namespace as

Document Schema

The four required namespaces are

represented by their prefixes - udt, qdt , cbc,

cac

In different namespace than

Document Schema

imported

5..*

included

0..*

udt = Unqualified Datatype , qdt = Qualified Datatype , cbc = Common Basic Components , cac = Common Aggregate Components ,

10041005

Figure 3-1 shows the one-to-one correspondence between document schemas and1006namespaces. It also shows the one-to-one correspondence between files and schema1007modules. As shown in figure 3-1, there are two types of schema in the UBL library –1008document schema and schema modules. Document schemas are always in their own1009namespace. Schema modules may be in a document schema namespace as in the case of1010internal schema modules, or in a separate namespace as in the ubl:qdt, ubl:cbc,1011ubl:cac, ubl:cl, and ubl:ccts schema modules. Both types of schema modules are1012conformant with W3C XSD.1013

A namespace is a collection of semantically related elements, types and attributes. For1014larger namespaces, schema modules – internal schema modules – may be defined. UBL1015document schemas may have zero or more internal modules that they include. The1016document schema for a namespace then includes those internal modules.1017

[Definition] Internal schema module –1018

A schema that is part of a schema set within a specific namespace.1019

Figure 3-2 Schema Modules1020


Document Schema Module

Internal Schema Module(s)

Message Assembly

External Schema Modules

Common Basic Components (CBC )

Schema Module

Common Aggregate Components (CAC )

Schema Module

UnqualifiedDataTypes (UDT ) Schema Module

Quaified DataTypes (QDT ) Schema

Module

Code List (CL) Schema Module (s)

0..*

1ImportedImported

0..*

1

1

Included

1

1

Imported

Imported

1Imported

0..*

Imported

Imported

Imported

Imported

Imported

1

1

Imported

10211022

1023

Another way to visualize the structure is by example. Figure 3-2 depicts instances of the1024various schema modules from the previous diagram.1025

Figure 3-3 Order and Invoice Schema Import of Common Component Schema Modules1026


...:Invoice-1.0

urn:oasis:names:specification:ubl:schema:Order-1.0

Order

Invoice

CommonBasic

Components

CommonAggregate

Components

Qualified Datatypes

...:CommonBasicComponents-1.0

...:CommonAggregateComponents-1.0

...:QualifiedDatatypes-1.0

...:UnqualifiedDatatypes-1.0

import

include

x:y:z urn

Document Schema

Internal Schema Module

External Schema Module

Legend

Unqualfied Datatypes

1027

Figure 3-3 shows how the order and invoice document schemas import the1028"CommonAggregateComponents Schema Module” and “CommonBasicComponents1029Schema Module” external schema modules. It also shows how the order document1030schema includes various internal modules – modules local to that namespace. The clear1031boxes show how the various schema modules are grouped into namespaces.1032

Any UBL schema module, be it a document schema or an internal module, may import1033other document schemas from other namespaces.1034


3.7.1.5 Limitations on Import1035

If two namespaces are mutually dependent then clearly, importing one will cause the1036other to be imported as well. For this reason there must not exist circular dependencies1037between UBL schema modules. By extension, there must not exist circular dependencies1038between namespaces. A namespace “A” dependent upon type definitions or element1039declaration defined in another namespace “B” must import “B’s” document schema.1040

[SSM2] A document schema in one UBL namespace that is dependent upon type1041definitions or element declarations defined in another namespace MUST only1042import the document schema from that namespace.1043

To ensure there is no ambiguity in understanding this rule, an additional rule is necessary1044to address potentially circular dependencies as well – schema A must not import internal1045schema modules of schema B.1046

[SSM3] A document schema in one UBL namespace that is dependant upon type1047definitions or element declarations defined in another namespace MUST NOT1048import internal schema modules from that namespace.1049

3.7.1.6 Module Conformance1050

UBL has defined a set of naming and design rules that are carefully crafted to ensure1051maximum interoperability and standardization.1052

[SSM4] Imported schema modules MUST be fully conformant with UBL naming and1053design rules.1054

3.7.2 Internal and External Schema Modules1055

UBL will create schema modules which, as illustrated in Figure 3-1 and Figure 3-2, will1056either be located in the same namespace as the corresponding document schema, or in a1057separate namespace.1058

[SSM5] UBL schema modules MUST either be treated as external schema modules or1059as internal schema modules of the document schema.1060

3.7.3 Internal Schema Modules1061

UBL internal schema modules do not declare a target namespace, but instead reside in the1062namespace of their parent schema. All internal schema modules will be accessed using1063xsd:include.1064

[SSM6] All UBL internal schema modules MUST be in the same namespace as their1065corresponding document schema.1066


UBL internal schema modules will necessarily have semantically meaningful names.1067Internal schema module names will identify the parent schema module, the internal1068schema module function, and the schema module itself.1069

[SSM7] Each UBL internal schema module MUST be named1070{ParentSchemaModuleName}{InternalSchemaModuleFunction}{sc1071hema module}1072

3.7.4 External Schema Modules1073

UBL is dedicated to maximizing reuse. As the complex types and global element1074declarations will be reused in multiple UBL schemas, a logical modularity approach is to1075create UBL schema modules based on collections of reusable types and elements.1076

[SSM8] A UBL schema module MAY be created for reusable components.1077

As identified in rule SSM2, UBL will create external schema modules. These external1078schema modules will be based on logical groupings of contents. At a minimum, UBL1079schema modules will be comprised of:1080

UBL CommonAggregateComponents1081

UBL CommonBasicComponents1082

UBL Code List(s)1083

UBL Qualified Datatypes1084

CCTS Core Component Parameters (Used as a reference only.)1085

In addition UBL will use the following schema modules provided by UN/CEFACT.1086

CCTS Core Component Types1087

CCTS Unqualified Datatypes1088

UN/CEFACT Code Lists1089

3.7.4.7 UBL Common Aggregate Components Schema Module1090

The UBL library will also contain a wide variety of ccts:AggregateBusiness1091InformationEntities. As defined in rule CTD1, each of these ccts:Aggregate1092BusinessInformationEntity classes will be defined as an xsd:complexType.1093Although some of these complex types may be used on only one UBL Schema, many will1094be reused in multiple UBL schema modules. An aggregation of all of the1095ccts:AggregateBusinessInformationEntity xsd:complexType1096


definitions that are used in multiple UBL schema modules into a single schema module1097of common aggregate types will provide for maximum ease of reuse.1098

[SSM9] A schema module defining all UBL Common Aggregate Components MUST1099be created.1100

The normative name for this xsd:ComplexType schema module will be based on its1101ccts:AggregateBusinessInformationEntity content.1102

[SSM10] The UBL Common Aggregate Components schema module MUST be1103identified as CommonAggregateComponents in the document name within1104the schema header.1105

1106

Example1107

Document Name: CommonAggregateComponents1108

3.7.4.7.1 UBL CommonAggregateComponents Schema Module Namespace1109

In keeping with the overall UBL namespace approach, a singular namespace must be1110created for storing the ubl:CommonAggregateComponents schema module.1111

[NMS7] The ubl:CommonAggregateComponents schema module MUST reside in1112its own namespace.1113

To ensure consistency in expressing this module, a normative token that will be used1114consistently in all UBL Schemas must be defined.1115

[NMS8] The ubl:CommonAggregateComponents schema module namespace1116MUST be represented by the namespace prefix “cac” when referenced in1117other schemas.1118

3.7.4.8 UBL CommonBasicComponents Schema Module1119

The UBL library will contain a wide variety of ccts:BasicBusinessInformation1120Entities. These ccts:BasicBusinessInformationEntities are based on1121ccts:BasicBusinessInformationEntityProperties. BBIE properties are1122reusable in multiple BBIEs. As defined in rule CTD25, each of these ccts:Basic1123BusinessInformationEntityProperties is defined as an xsd:complexType.1124Although some of these complex types may be used in only one UBL Schema, many will1125be reused in multiple UBL schema modules. To maximize reuse and standardization, all1126of the ccts:BasicBusinessInformationEntity1127Property xsd:ComplexType definitions that are used in multiple UBL schema1128modules will be aggregated into a single schema module of common basic types.1129


[SSM11] A schema module defining all UBLCommon Basic Components MUST be1130created.1131

The normative name for this schema module will be based on its1132ccts:BasicBusinessInformationEntityProperty xsd:ComplexType content.1133

[SSM12] The UBL Common Basic Components schema module MUST be identified as1134CommonBasicComponents in the document name within the schema1135header.1136

3.7.4.8.1 UBL CommonBasicComponents Schema Module Namespace1137

In keeping with the overall UBL namespace approach, a singular namespace must be1138created for storing the ubl:CommonBasicComponents schema module.1139

[NMS9] The ubl:CommonBasicComponents schema module MUST reside in its1140own namespace.1141

To ensure consistency in expressing the ubl:CommonBasicComponents schema1142module, a normative token that will be used consistently in all UBL Schema must be1143defined.1144

[NMS10] The UBL:CommonBasicComponents schema module namespace MUST be1145represented by the namespace prefix “cbc” when referenced in other schemas.1146

3.7.4.9 CCTS CoreComponentType Schema Module1147

The CCTS defines an authorized set of Core Component Types (ccts:Core1148ComponentTypes) that convey content and supplementary information related to1149exchanged data. As the basis for all higher level CCTS models, the ccts:Core1150ComponentTypes are reusable in every UBL schema. An external schema module1151consisting of a complex type definition for each ccts:CoreComponentType is1152essential to maximize reusability. UBL uses the ccts:CoreComponentType schema1153module provided by UN/CEFACT.1154

1155

3.7.4.10 CCTS Datatypes Schema Modules1156

The CCTS defines an authorized set of primary and secondary Representation Terms1157(ccts:RepresentationTerms) that describes the form of every ccts:Business1158InformationEntity. These ccts:RepresentationTerms are instantiated in the1159form of datatypes that are reusable in every UBL schema. The ccts:Datatype defines1160the set of valid values that can be used for its associated ccts:BasicBusiness1161InformationEntity Property. These datatypes may be qualified or unqualified, that1162is to say restricted or unrestricted. We refer to these as ccts:Unqualified1163


Datatypes (even though they are technically ccts:Datatypes)or1164ubl:QualifiedDatatypes.1165

3.7.4.10.1 CCTS Unqualified Datatypes Schema Module1166

UBL has adopted the UN/CEFACT Unqualified Datatype schema module.This includes1167the four code list schema modules that are imported into this schema module. When the1168ccts:UnqualifiedDatatypes schema module is referenced the “udt” namespace1169prefix must be used.1170

[NMS17] The ccts:UnqualifiedDatatypes schema module namespace MUST be1171represented by the token “udt” when referenced in other schemas.1172

1173

3.7.4.10.2 UBL Qualified Datatypes Schema Module1174

The ubl:QualifiedDatatype is defined by specifying restrictions on the1175ccts:UnqualifiedDatatype. To ensure the consistency of UBL qualified Datatypes1176(ubl:QualifiedDatatypes) with the UBL modularity and reuse goals requires1177creating a single schema module that defines all ubl:QualifiedDatatypes.1178

[SSM18] A schema module defining all UBL Qualified Datatypes MUST be created.1179

The ubl:QualifiedDatatypes must be based upon the1180ccts:UnqualifiedDatypes.1181

[SSM20] The UBL Qualified Datatypes schema module MUST import the1182ccts:UnQualifiedDatatypes schema module.1183

The ubl:QualifiedDatatypes schema module name must follow the UBL module1184naming approach.1185

[SSM19] The UBL Qualified Datatypes schema module MUST be identified as1186QualifiedDatatypes in the document name in the schema header.1187

3.7.4.10.3 UBL Qualified Datatypes Schema Module Namespace1188

In keeping with the overall UBL namespace approach, a singular namespace must be1189created for storing the ubl:QualifiedDatatypes schema module.1190

[NMS15] The ubl:QualifiedDatatypes schema module MUST reside in its own1191namespace.1192

To ensure consistency in expressing the ubl:QualifiedDatatypes schema1193module, a normative token that will be used in all UBL schemas must be defined.1194


[NMS16] The ubl:QualifiedDatatypes schema module namespace MUST be1195represented by the namespace prefix “qdt” when referenced in other schemas.1196

3.8 Annotation and Documentation Requirements1197

Annotation is an essential tool in understanding and reusing a schema. UBL, as an1198implementation of CCTS, requires an extensive amount of annotation to provide all1199necessary metadata required by the CCTS specification. Each construct declared or1200defined within the UBL library contains the requisite associated metadata to fully1201describe its nature and support the CCTS requirement. Accordingly, UBL schema1202metadata for each construct will be defined in the CCTS core component parameters1203schema.1204

3.8.1 Schema Annotation1205

Although the UBL schema annotation is necessary, its volume results in a considerable1206increase in the size of the UBL schemas with undesirable performance impacts. To1207address this issue, two normative schema will be developed for each UBL schema. A1208fully annotated schema will be provided to facilitate greater understanding of the schema1209module and its components, and to meet the CCTS metadata requirements. A schema1210devoid of annotation will also be provided that can be used at run-time if required to meet1211processor resource constraints.1212

[GXS2] UBL MUST provide two normative schemas for each transaction. One1213schema shall be fully annotated. One schema shall be a run-time schema1214devoid of documentation.1215

3.8.2 Embedded documentation1216

The information about each UBL ccts:BusinessInformationEntity is in the UBL1217spreadsheet models. UBL spreadsheets contain all necessary information to produce fully1218annotated Schemas. Fully annotated Schemas are valuable tools to implementers to assist1219in understanding the nuances of the information contained therein. UBL annotations will1220consist of information currently required by Section 7 of the CCTS and supplemented by1221metadata from the UBL spreadsheet models.1222

The absence of an optional annotation inside the structured set of annotations in the1223documentation element implies the use of the default value. For example, there are1224several annotations relating to context such as ccts:BusinessContext or1225ccts:IndustryContext whose absence implies that their value is "all contexts".1226

The following rules describe the documentation requirements for each1227ubl:QualifiedDatatype and ccts:UnqualifiedDatatype definition.1228


[DOC1] The xsd:documentation element for every Datatype MUST contain a1229structured set of annotations in the following sequence and pattern (as defined1230in CCTS Section 7):1231

• DictionaryEntryName (mandatory)1232

• Version (mandatory):1233

• Definition(mandatory)1234

• RepresentationTerm (mandatory)1235

• QualifierTerm(s) (mandatory, where used)1236

• UniqueIdentifier (mandatory)1237

• Usage Rule(s) (optional)1238

• Content Component Restriction (optional)12391240

[DOC2] A Datatype definition MAY contain one or more Content Component1241Restrictions to provide additional information on the relationship between the1242Datatype and its corresponding Core Component Type. If used the Content1243Component Restrictions must contain a structured set of annotations in the1244following patterns:1245

• RestrictionType (mandatory): Defines the type of format restriction that1246applies to the Content Component.1247

• RestrictionValue (mandatory): The actual value of the format restriction that1248applies to the Content Component.1249

• ExpressionType (optional): Defines the type of the regular expression of the1250restriction value.1251

1252[DOC3] A Datatype definition MAY contain one or more Supplementary Component1253

Restrictions to provide additional information on the relationship between the1254Datatype and its corresponding Core Component Type. If used the1255Supplementary Component Restrictions must contain a structured set of1256annotations in the following patterns:1257

• SupplementaryComponentName (mandatory): Identifies the1258Supplementary Component on which the restriction applies.1259

• RestrictionValue (mandatory, repetitive): The actual value(s) that is1260(are) valid for the Supplementary Component1261

The following rule describes the documentation requirements for each ccts:Basic1262BusinessInformationEntity definition.1263

[DOC4] The xsd:documentation element for every Basic Business Information1264Entity MUST contain a structured set of annotations in the following patterns:1265


• ComponentType (mandatory): The type of component to which the object1266belongs. For Basic Business Information Entities this must be “BBIE”.1267

• DictionaryEntryName (mandatory): The official name of a Basic Business1268Information Entity.1269

• Version (optional): An indication of the evolution over time of the Basic1270Business Information Entity.1271

• Definition(mandatory): The semantic meaning of a Basic Business1272Information Entity.1273

• Cardinality(mandatory): Indication whether the Basic Business Information1274Entity represents a not-applicable, optional, mandatory and/or repetitive1275characteristic of the Aggregate Business Information Entity.1276

• ObjectClassQualifier (optional): The qualifier for the object class.1277

• ObjectClass(mandatory): The Object Class containing the Basic Business1278Information Entity.1279

• PropertyTermQualifier (optional): A qualifier is a word or words which help1280define and differentiate a Basic Business Information Entity.1281

• PropertyTerm(mandatory): Property Term represents the distinguishing1282characteristic or Property of the Object Class and shall occur naturally in the1283definition of the Basic Business Information Entity.1284

• RepresentationTerm (mandatory): A Representation Term describes the1285form in which the Basic Business Information Entity is represented.1286

• DataTypeQualifier (optional): semantically meaningful name that1287differentiates the Datatype of the Basic Business Information Entity from its1288underlying Core Component Type.1289

• DataType (mandatory): Defines the Datatype used for the Basic Business1290Information Entity.1291

• AlternativeBusinessTerms (optional): Any synonym terms under which the1292Basic Business Information Entity is commonly known and used in the1293business.1294

• Examples (optional): Examples of possible values for the Basic Business1295Information Entity.1296

The following rule describes the documentation requirements for each1297ccts:AggregateBusinessInformationEntity definition.1298

[DOC5] The xsd:documentation element for every Aggregate Business1299Information Entity MUST contain a structured set of annotations in the1300following sequence and pattern:1301


• ComponentType (mandatory): The type of component to which the object1302belongs. For Aggregate Business Information Entities this must be “ABIE”.1303

• DictionaryEntryName (mandatory): The official name of the Aggregate1304Business Information Entity .1305

• Version (optional): An indication of the evolution over time of the1306Aggregate Business Information Entity.1307

• Definition(mandatory): The semantic meaning of the Aggregate Business1308Information Entity.1309

• ObjectClassQualifier (optional): The qualifier for the object class.1310

• ObjectClass(mandatory): The Object Class represented by the Aggregate1311Business Information Entity.1312

• AlternativeBusinessTerms (optional): Any synonym terms under which the1313Aggregate Business Information Entity is commonly known and used in the1314business.1315

The following rule describes the documentation requirements for each1316ccts:AssociationBusinessInformationEntity definition.1317

[DOC6] The xsd:documentation element for every Association Business1318Information Entity element declaration MUST contain a structured set of1319annotations in the following sequence and pattern:1320

• ComponentType (mandatory): The type of component to which the object1321belongs. For Association Business Information Entities this must be “ASBIE”.1322

• DictionaryEntryName (mandatory): The official name of the Association1323Business Information Entity.1324

• Version (optional): An indication of the evolution over time of the1325Association Business Information Entity.1326

• Definition(mandatory): The semantic meaning of the Association Business1327Information Entity.1328

• Cardinality(mandatory): Indication whether the Association Business1329Information Entity represents an optional, mandatory and/or repetitive1330assocation.1331

• ObjectClass(mandatory): The Object Class containing the Association1332Business Information Entity.1333

• PropertyTermQualifier (optional): A qualifier is a word or words which help1334define and differentiate the Association Business Information Entity.1335

• PropertyTerm(mandatory): Property Term represents the Aggregate1336Business Information Entity contained by the Association Business1337Information Entity.1338


• AssociatedObjectClassQualifier (optional): Associated Object Class1339Qualifiers describe the 'context' of the relationship with another ABIE. That is,1340it is the role the contained Aggregate Business Information Entity plays within1341its association with the containing Aggregate Business Information Entity.1342

• AssociatedObjectClass (mandatory); Associated Object Class is the Object1343Class at the other end of this association. It represents the Aggregate Business1344Information Entity contained by the Association Business Information Entity.1345

1346

1347

1348

[DOC8] The xsd:documentation element for every Supplementary Component1349attribute declarationMUST contain a structured set of annotations in the1350following sequence and pattern:1351

• Name (mandatory): Name in the Registry of a Supplementary Component of1352a Core Component Type.1353

• Definition (mandatory): A clear, unambiguous and complete explanation of1354the meaning of a Supplementary Component and its relevance for the related1355Core Component Type.1356

• Primitive type (mandatory): PrimitiveType to be used for the representation1357of the value of a Supplementary Component.1358

• Possible Value(s) (optional): one possible value of a Supplementary1359Component.1360

1361

[DOC9] The xsd:documentation element for every Supplementary Component1362attribute declaration containing restrictions MUST include the following1363additional information appended to the information required by DOC8:1364

• Restriction Value(s) (mandatory): The actual value(s) that is (are) valid for1365the Supplementary Component.1366

1367

1368


4 Naming Rules1369

The rules in this section make use of the following special concepts related to XML1370elements.1371

Top-level element: An element that encloses a whole UBL business message.1372Note that UBL business messages might be carried by messaging transport1373protocols that themselves have higher-level XML structure. Thus, a UBL top-1374level element is not necessarily the root element of the XML document that1375carries it.1376

Lower-level element: An element that appears inside a UBL business1377message. Lower-level elements consist of intermediate and leaf level.1378

Intermediate element: An element not at the top level that is of a complex1379type, only containing other elements and attributes.1380

Leaf element: An element containing only character data (though it may also1381have attributes). Note that, because of the XSD mechanisms involved, a leaf1382element that has attributes must be declared as having a complex type, but a1383leaf element with no attributes may be declared with either a simple type or a1384complex type.1385

4.1 General Naming Rules1386

The CCTS contains specific Internal Organization for Standardization (ISO)/International1387Electrotechnical Commission (IEC) Technical Specification 11179 Information1388technology– -- Metadata registries (MDR) based naming rules for each CCTS construct.1389The UBL component library, as a syntax-neutral representation, is fully conformant to1390those rules. The UBL syntax-specific XSD instantiation of the UBL component1391library—in some cases—refines the CCTS naming rules to leverage the capabilities of1392XML and XSD. Specifically, truncation rules are applied to allow for reuse of element1393names across parent element environments and to maintain brevity and clarity.1394

In keeping with CCTS, UBL will use English as its normative language. If the UBL1395Library is translated into other languages for localization purposes, these additional1396languages might require additional restrictions. Such restrictions are expected be1397formulated as additional rules and published as appropriate.1398

[GNR1] UBL XML element and type names MUST be in the English language, using1399the primary English spellings provided in the Oxford English Dictionary.1400

UBL fully supports the concepts of data standardization contained in ISO 11179. CCTS,1401as an implementation of 11179, furthers its basic tenets of data standardization into1402


higher-level constructs as expressed by the ccts:DictionaryEntryNames of those1403constructs – such as those for ccts:BasicBusinessInformationEntities and1404ccts:AggregateBusinessInformationEntities. Since UBL is an1405implementation of CCTS, UBL uses CCTS dictionary entry names as the basis for UBL1406XML schema construct names. UBL converts these ccts:DictionaryEntryNames1407into UBL XML schema construct names using strict transformation rules.1408

[GNR2] UBL XML element and type names MUST be consistently derived from1409CCTS conformant dictionary entry names.1410

The ISO 11179 specifies—and the CCTS uses—periods, spaces, other separators, and1411characters not allowed by W3C XML. These separators and characters are not1412appropriate for UBL XML component names.1413

[GNR3] UBL XML element and type names constructed from1414ccts:DictionaryEntryNames MUST NOT include periods, spaces, other1415separators, or characters not allowed by W3C XML 1.0 for XML names.1416

Acronyms and abbreviations impact on semantic interoperability, and as such are to be1417avoided to the maximum extent practicable. Since some abbreviations will inevitably be1418necessary, UBL will maintain a normative list of authorized acronyms and abbreviations.1419Appendix B provides the current list of permissible acronyms, abbreviations and word1420truncations. The intent of this restriction is to facilitate the use of common semantics and1421greater understanding. Appendix B is a living document and will be updated to reflect1422growing requirements.1423

[GNR4] UBL XML element, and simple and complex type names MUST NOT use1424acronyms, abbreviations, or other word truncations, except those in the list of1425exceptions published in Appendix B.1426

UBL does not desire a proliferation of acronyms and abbreviations. Appendix B is an1427exception list and will be tightly controlled by UBL. Any additions will only occur after1428careful scrutiny to include assurance that any addition is critically necessary, and that any1429addition will not in any way create semantic ambiguity.1430

[GNR5] Acronyms and abbreviations MUST only be added to the UBL approved1431acronym and abbreviation list after careful consideration for maximum1432understanding and reuse.1433

Once an acronym or abbreviation has been approved, it is essential to ensuring semantic1434clarity and interoperability that the acronym or abbreviation is always used.1435

[GNR6] The acronyms and abbreviations listed in Appendix B MUST always be used1436in place of the word or phrase they represent.1437

Generally speaking, the names for UBL XML constructs must always be singular. The1438only exception permissible is where the concept itself is pluralized.1439


[GNR7] UBL XML element, and type names MUST be in singular form unless the1440concept itself is plural.1441

Example:1442

Terms1443[GNR10] Acronyms and abbreviations at the beginning of an attribute name MUST1444

appear in all lower case. All other acronym and abbreviation usage in an1445attribute declaration MUST appear in upper case.1446

1447

[GNR11] Acronyms and abbreviations MUST appear in all upper case for all element1448declarations and type definitions.1449

1450

XML is case sensitive. Consistency in the use of case for a specific XML component1451(element, type) is essential to ensure every occurrence of a component is treated as the1452same. This is especially true in a business-based data-centric environment such as what is1453being addressed by UBL. Additionally, the use of visualization mechanisms such as1454capitalization techniques assist in ease of readability and ensure consistency in1455application and semantic clarity. The ebXML architecture document specifies a standard1456use of upper and lower camel case for expressing XML elements and attributes1457respectively.12 UBL will adhere to the ebXML standard. Specifically, UBL element and1458type names will be in UpperCamelCase (UCC).1459

12 ebXML, ebXML Technical Architecture Specification v1.0.4, 16 February 2001


[GNR8] The UpperCamelCase (UCC) convention MUST be used for naming elements1460and types.Example:1461

CurrencyBaseRate1462CityNameType1463

1464

4.2 Type Naming Rules1465

UBL identifies several categories of naming rules for types, namely for complex types1466based on Aggregate Business Information Entities, Basic Business Information Entities,1467Primary Representation Terms, Secondary Representation Terms and the Core1468Component Types.1469

Each of these CCTS constructs have a ccts:DictionaryEntryName that is a fully1470qualified construct based on ISO 11179. As such, these names convey explicit semantic1471clarity with respect to the data being described. Accordingly, these ccts:Dictionary1472EntryNames provide a mechanism for ensuring that UBL xsd:complexType names1473are semantically unambiguous, and that there are no duplications of UBL type names for1474different xsd:type constructs.1475

4.2.1 Complex Type Names for CCTS Aggregate Business1476

Information Entities1477

UBL xsd:complexType names for ccts:AggregateBusinessInformation1478Entities will be derived from their dictionary entry name by removing separators to1479follow general naming rules, and appending the suffix “Type” to replace the word1480“Details.”1481

[CTN1] A UBL xsd:complexType name based on an ccts:Aggregate1482BusinessInformationEntity MUST be the ccts:Dictionary1483EntryName with the separators removed and with the “Details” suffix1484replaced with “Type”.1485

Example:1486

ccts:AggregateBusiness InformationEntity

UBL xsd:complexType

Address. Details AddressTypeFinancial Account. Details FinancialAccountType

4.2.2 Complex Type Names for CCTS Basic Business Information1487

Entity Properties1488

All ccts:BasicBusinessInformationEntityProperties are reusable across1489multiple ccts:BasicBusinessInformationEntities. The CCTS does not specify,1490but implies, that ccts:BasicBusinessInformationEntityProperty names are1491the reusable property term and representation term of the family of1492ccts:BasicBusinessInformationEntities that are based on it. The UBL1493xsd:complexType names for ccts:BasicBusinessInformationEntity1494properties will be derived from the shared property and representation terms portion1495of the dictionary entry names in which they appear by removing separators to follow1496general naming rules, and appending the suffix “Type”.1497

[CTN2] A UBL xsd:complexType name based on a ccts:BasicBusiness1498InformationEntityProperty MUST be the ccts:Dictionary1499EntryName shared property term and its qualifiers and representation term of1500the ccts:BasicBusinessInformationEntity, with the separators1501removed and with the “Type” suffix appended after the representation term.1502

Example:1503

1505

<xsd:complexType name="ChargeIndicatorType">1506...1507

</xsd:comlextType>1508

[CTNX1] A UBL xsd:complexType name based on a ccts:BasicBusiness1509InformationEntityProperty and with a . ccts:BasicBusiness1510InformationEntityRepresentationTerm of 'Text' MUST have1511the word "Text" removed from the end of its name.1512

1513

[CTNX2] A UBL xsd:complexType name based on a ccts:BasicBusiness1514InformationEntityProperty and with a . ccts:BasicBusiness1515InformationEntityRepresentationTerm of 'Identifier' MUST1516have the word "Identifier" replaced by the word "ID" at the end of its name.1517

1518

[CTNX3] A UBL xsd:complexType name based on a ccts:BasicBusiness1519InformationEntityProperty MUST remove all duplication of words1520that occur as a result of duplicate property terms and representation terms.1521

1522


4.2.3 1523

1524

4.3 Element Naming Rules1525

As defined in the UBL Model (See Figure 2-3), UBL elements will be created for1526ccts:AggregateBusinessInformationEntities, ccts:BasicBusiness1527InformationEntities, and ccts:AssociationBusinessInformation1528Entities. UBL element names will reflect this relationship in full conformance with1529ISO11179 element naming rules.1530

4.3.1 Element Names for CCTS Aggregate Business Information1531

Entities1532

[ELN1] A UBL global element name based on a ccts:ABIE MUST be the same as1533the name of the corresponding xsd:complexType to which it is bound, with1534the word “Type” removed.1535

Example:1536

For a ccts:AggregateBusinessInformationEntity of Party.Details,1537Rule CTN1 states that the Party.Details object class becomes PartyType1538xsd:ComplexType. Rule ELD3 states that for the PartyType xsd:complexType,1539a corresponding global element must be declared. Rule ELN1 states that the name of1540this corresponding global element must be Party.1541

1542<xsd:element name="Party" type="PartyType"/>1543 <xsd:complexType name="PartyType">1544

1545 <xsd:annotation>1546

1547 —!--Documentation goes here--> </xsd:annotation>1548

1549 <xsd:sequence>1550

1551 <xsd:element ref="cbc:MarkCareIndicator" minOccurs="0"1552maxOccurs="1">1553

1554 ...1555

1556 </xsd:element>1557

1558 <xsd:element ref="cbc:MarkAttentionIndicator" minOccurs="0"1559maxOccurs="1">1560

1561 ...1562


1565 <xsd:element ref="PartyIdentification" minOccurs="0"1566maxOccurs="unbounded">1567

1568 ...1569

1572 <xsd:element ref="PartyName" minOccurs="0" maxOccurs="1">1573

1574 ...1575


1578 <xsd:element ref="Address" minOccurs="0" maxOccurs="1">1579

1580 ...1581 </xsd:element>1582

...15831584

</xsd:sequence>15851586

4.3.2 Element Names for CCTS Basic Business Information Entity1587

Properties1588

The same naming concept used for ccts:AggregateBusinessInformation1589Entities applies to ccts:BasicBusinessInformationEntityProperty.1590

[ELN2] A UBL global element name based on a ccts:BBIEProperty MUST be the1591same as the name of the corresponding xsd:complexType to which it is1592bound, with the word “Type” removed.1593

Example:1594

1602<xsd:element name="ChargeIndicator" type="ChargeIndicatorType"/>1603

4.3.3 Element Names for CCTS Association Business Information1604

Entities1605

A ccts:AssociationBusinessInformationEntity is not a class like1606ccts:AggregateBusinessInformationEntities and like ccts:Basic1607BusinessInformationEntityProperties that are reused as ccts:Basic1608BusinessInformationEntities. Rather, it is an association between two classes.1609As such, an element representing the ccts:AssociationBusinessInformation1610Entity does not have its own unique xsd:ComplexType. Instead, when an element1611representing a ccts:AssociationBusinessInformationEntity is declared, the1612element is bound to the xsd:complexType of its associated ccts:Aggregate1613BusinessInformationEntity by referencing its global element declaration.1614


[ELN3] A UBL global element name based on a ccts:ASBIE MUST be the1615ccts:ASBIE dictionary entry name property term and its qualifiers; and the1616object class term and qualifiers of its associated ccts:ABIE. All1617ccts:DictionaryEntryName separators MUST be removed..1618

1619[1620

4.4 Attributes in UBL1621

UBL, as a transactional based XML exchange format, has chosen to significantly restrict1622the use of attributes. This restriction is in keeping with the fact that attribute usage is1623relegated to supplementary components only; all “primary” business data appears1624exclusively in element content. These attributes are defined in the UN/CEFACT1625Unqualified Datatype schema module,1626


5 Declarations and Definitions1627

In W3C XML Schema, elements are defined in terms of complex or simple types and1628attributes are defined in terms of simple types. The rules in this section govern the1629consistent structuring of these type constructs and the manner for unambiguously and1630thoroughly documenting them in the UBL Library.1631

5.1 Type Definitions1632

5.1.1 General Type Definitions1633

Since UBL elements and types are intended to be reusable, all types must be named. This1634permits other types to establish elements that reference these types, and also supports the1635use of extensions for the purposes of versioning and customization.1636

[GTD1] All types MUST be named.1637

Example:1638

<xsd:complexType name="QuantityType">1639...1640

</xsd:complexType>16411642

UBL disallows the use of xsd:anyType, because this feature permits the introduction of1643potentially unknown types into an XML instance. UBL intends that all constructs within1644the instance be described by the schemas describing that instance - xsd:anyType is seen1645as working counter to the requirements of interoperability. In consequence, particular1646attention is given to the need to enable meaningful validation of the UBL document1647instances. Were it not for this, xsd:anyType might have been allowed.1648

[GTD2] The xsd:anyType MUST NOT be used.1649

5.1.2 Simple Types1650

The Core Components Technical Specification provides a set of constructs for the1651modeling of basic data, Core Component Types. These are represented in UBL with a1652library of complex types, with the effect that most "simple" data is represented as1653property sets defined according to the CCTs, made up of content components and1654supplementary components. In most cases, the supplementary components are expressed1655as XML attributes, the content component becomes element content, and the CCT is1656represented with an xsd:complexType. There are exceptions to this rule in those cases1657where all of a CCT's properties can be expressed without the use of attributes. In these1658cases, an xsd:simpleType is used.1659


UBL does not define its own simple types. These are defined in the UN/CEFACT1660Unqualified Datatype schema module. UBL may define restrictions of these simple types1661in the UBL Qualified datatype schema module.1662

5.1.3 Complex Types1663

Since even simple datatypes are modeled as property sets in most cases, the XML1664expression of these models primarily employs xsd:complexType. To facilitate reuse,1665versioning, and customization, all complex types are named. In the UBL model,1666ccts:AggregateBusinessInformationEntities are considered classes(objects) .1667

[CTD1] For every class and property identified in the UBL model, a named1668xsd:complexType MUST be defined.1669

Example:1670

<xsd:complexType name="BuildingNameType">1671167216731674


Every class identified in the UBL model consists of properties. These properties are1677either ASBIEs, when the property represents another class, or BBIE properties.1678

[CTD25] For every ccts:BBIEProperty identified in the UBL model a named1679xsd:complexType must be defined.1680

1681

5.1.3.11 Aggregate Business Information Entities1682

The relationship expressed by an Aggregate Business Information Entity is not directly1683represented with a class. Instead, this relationship is captured in UBL with a containment1684relationship, expressed in the content model of the parent object’s type with a sequence1685of elements. (Sequence facilitates the use of xsd:extension for versioning and1686customization.) The members of the sequence – elements which are themselves defined1687by reference to complex types – are the properties of the containing type.1688

[CTD2] Every ccts:ABIE xsd:complexType definition content model MUST use1689the xsd:sequence element containing references to the appropriate global1690element declarations.1691

Example:1692

<xsd:complexType name=”AddressType”>16931694

...16951696


<xsd:sequence>16971698 <xsd:element ref=”cbc:CityName” minOccurs=”0” maxOccurs=”1”>1699

1700 ...1701


1704 <xsd:element ref=”cbc:PostalZone” minOccurs=”0” maxOccurs=”1”>1705

1706 ...1707 </xsd:element>...1708

1709 </xsd:sequence>1710

1711 </xsd:complexType>1712

5.1.3.12 Basic Business Information Entities1713

All ccts:BasicBusinessInformationEntities, in accordance with the Core1714Components Technical Specification, always have a representation term. This may be a1715primary or secondary representation term. Representation terms describe the structural1716representation of the BBIE. These representation terms are expressed in the UBL Model1717as Unqualified Datatypes bound to a Core Component Type that describes their structure.1718In addition to the Unqualified Datatypes defined in CCTS, UBL has defined a set of1719Qualified Datatypes that are derived from the CCTS Unqualified Datatypes.There are a1720set of rules concerning the way these relationships are expressed in the UBL XML1721library. As discussed above, ccts:BasicBusinessInformation1722EntityProperties are represented with complex types. Within these are1723simpleContent elements that extend the Datatypes.1724

[CTD3] Every ccts:BBIEProperty xsd:complexType definition content model1725MUST use the xsd:simpleContent element.1726

1727[CTD4] Every ccts:BBIEProperty xsd:complexType content model1728

xsd:simpleContent element MUST consist of an xsd:extension1729element.1730

1731[CTD5] Every ccts:BBIEProperty xsd:complexType content model xsd:base1732

attribute value MUST be the UN/CEFACT Unqualified Datatype or UBL1733Qualified Datatype as appropriate.1734

Example:1735

<xsd:complexType name="StreetNameType”>1736<xsd:simpleContent>1737

<xsd:extension base=”udt:NameType”/>1738</xsd:simpleContent>1739



5.1.3.13 Datatypes1741

There is a direct one-to-one relationship between ccts:CoreComponentTypes and1742ccts:PrimaryRepresentationTerms. Additionally, there are several1743ccts:SecondaryRepresentationTerms that are semantic refinements of their1744parent ccts:PrimaryRepresentationTerm. The total set of1745ccts:RepresentationTerms by their nature represent ccts:Datatypes.1746Specifically, for each ccts:PrimaryRepresentationTerm or1747ccts:SecondaryRepresentationTerm, a ccts:UnqualifiedDatatype exists. In1748the UBL XML Library, these ccts:UnqualifiedDatatypes are expressed as1749complex or simple types that are of the type of its corresponding1750ccts:CoreComponentType. UBL uses the ccts:UnqualifiedDatatypes that are1751provided by the UN/CEFACT Unqualified Datatype (udt) schema module.1752

5.1.3.13.1 Qualified Datatypes1753

The data types defined in the unqualified data type schema module are intended to be1754suitable as the xsd:base type for some, but not all BBIEs. As business process modeling1755reveals the need for specialized data types, new ‘qualified’ types will need to be defined.1756These new ccts:QualifiedDatatype must be based on an1757ccts:UnqualifiedDatatype and must represent a semantic or technical restriction of1758the ccts:UnqualifiedDatatype. Technical restrictions must be implemented as a1759xsd:restriction or as a new xsd:simpleType if the supplementary components of the1760qualified data type map directly to the properties of a built-in XSD data type.1761

[CTD6] For every Qualified Datatype used in the UBL model, a named1762xsd:complexType or xsd:simpleType MUST be defined.1763

1764

[CTD20] A ccts:QualifiedDataType MUST be based on an unqualified data type1765and add some semantic and/or technical restriction to the unqualified data1766type.1767

1768

[CTD21] The name of a ccts:QualifiedDataType MUST be the name of its base1769ccts:UnqualifiedDataType with separators and spaces removed and1770with its qualifier term added.1771

In accordance with rule GXS3 built-in XSD data types will be used whenever possible.1772

[CTD22] Every qualified datatype based on an unqualified datatype1773xsd:complexType whose supplementary components map directly to the1774properties of an XSD built-in data type1775

MUST be defined as an xsd:simpleType1776


MUST contain one xsd:restriction element1777

MUST include an xsd:base attribute that defines the specific XSD built-in1778data type required for the content component1779

1780

1781

[CTD23] Every qualified datatype based on an unqualified datatype1782xsd:complexType whose supplementary components do not map directly to1783the properties of an XSD built-in data type1784

MUST be defined as an xsd:complexType1785

MUST contain one xsd:simpleContent element1786


MUST include the unqualified datatype as its xsd:base attribute1788

1789

[CTD24] Every qualified datatype based on an unqualified datatype xsd:simpleType1790


MUST include the unqualified datatype as its xsd:base attribute1792

1793

179417951796

5.1.3.14 Core Component Types1797

UBL has adopted UN/CEFACT's Core Component Type schema module.1798

5.2 Element Declarations1799

5.2.1 Elements Bound to Complex Types1800

The binding of UBL elements to their xsd:complexType is based on the associations1801identified in the UBL model. For the ccts:BasicBusinessInformationEntities1802and ccts:AggregateInformationEntities, the UBL elements will be directly1803associated to its corresponding xsd:complexType.1804

[ELD3] For every class and property identified in the UBL model, a global element1805bound to the corresponding xsd:complexType MUST be declared.1806


Example:1807

For the Party.Details object class, a complex type/global element declaration pair1808is created through the declaration of a Party element that is of type PartyType.1809

The element thus created is useful for reuse in the building of new business messages.1810The complex type thus created is useful for both reuse and customization, in the building1811of both new and contextualized business messages.1812

Example:1813

<xsd:element name=”BuyerParty” type=”BuyerPartyType”/>1814<xsd:complexType name=”BuyerPartyType" ...1815</xsd:complexType>1816

5.2.2 Elements Representing ASBIEs1817

A ccts:AssociationBusinessInformationEntity is not a class like1818ccts:AggregateBusinessInformationEntities. Rather, it is an association1819between two classes. As such, the element declaration will bind the element to the1820xsd:complexType of the associated ccts:AggregateBusinessInformation1821Entity. There are two types of ASBIEs – those that have qualifiers in the object class,1822and those that do not.1823

[ELD4] When a ccts:ASBIE is unqualified, it is bound via reference to the global1824ccts:ABIE element to which it is associated.1825

1826

[ELD11] When a ccts:ASBIE is qualified, a new element MUST be declared and1827bound to the xsd:complexType of its associated ccts:ABIE.1828

5.2.3 Code List Import1829

[ELD6] The code list xsd:import element MUST contain the namespace and1830schema location attributes.1831

5.2.4 Empty Elements1832

[ELD7] Empty elements MUST not be declared, except in the case of extension,1833where the 'UBL Extension' element is used.1834


6 Code Lists1835

UBL has determined that the best approach for code lists is to handle them as schema1836modules. In recognition of the fact that most code lists are maintained by external1837agencies, UBL has determined that if code list owners all used the same normative form1838schema module, all users of those code lists could avoid a significant level of code list1839maintenance.1840

By having each code list owner develop, maintain, and make available via the internet1841their code lists using the same normative form schema, code list users would be spared1842the unnecessary and duplicative efforts required for incorporation in the form of1843enumeration of such code lists into Schema, and would subsequently avoid the1844maintenance of such enumerations since code lists are handled as imported schema1845modules rather than cumbersome enumerations. To make this mechanism operational,1846UBL has defined a number of rules. To avoid enumeration of codes in the document or1847reusable schemas, UBL has determined that codes will be handled in their own schema1848modules.1849

[CDL1] All UBL Codes MUST be part of a UBL or externally maintained Code List.1850

Because the majority of code lists are owned and maintained by external agencies, UBL1851will make maximum use of such external code lists where they exist.1852

[CDL2] The UBL Library SHOULD identify and use external standardized code lists1853rather than develop its own UBL-native code lists.1854

In some cases the UBL Library may extend an existing code list to meet specific business1855requirements. In others cases the UBL Library may have to create and maintain a code1856list where a suitable code list does not exist in the public domain. Both of these types of1857code lists would be considered UBL-internal code lists.1858

[CDL3] The UBL Library MAY design and use an internal code list where an existing1859external code list needs to be extended, or where no suitable external code list1860exists.1861

UBL-internal code lists will be designed with maximum re-use in mind to facilitate1862maximum use by others.1863

If a UBL code list is created, the lists should be globally scoped (designed for reuse and1864sharing, using named types and namespaced Schema Modules) rather than locally scoped1865(not designed for others to use and therefore hidden from their use).1866

To guarantee consistency within all code list schema modules all ubl-internal code lists1867and externally used code lists will use the UBL Code List Schema Module. This schema1868module will contain an enumeration of code list values.1869


[CDL4] All UBL maintained or used Code Lists MUST be enumerated using the UBL1870Code List Schema Module.1871

To guarantee consistency of code list schema module naming, the name of each UBL1872Code List Schema Module will adhere to a prescribed form.1873

[CDL5] The name of each UBL Code List Schema Module MUST be of the form:1874

{Owning Organization}{Code List Name}{Code List Schema1875Module}1876

Example1877ISO 8601 Country Code Code List Schema Module1878ISO 3055 Kitchen equipment–- Coordinating sizes Code Code List1879Schema Module1880

Code list attribute values for UBL code lists should be set to 'default' rather than fixed.1881This facilitates customization and caters for instances whereby the values are not1882specified.1883

1884

[CDL9] UBL Code list attribute values SHOULD be set to 'default'.1885

Each UBL Code List Schema Module will import the UBL QDT Schema Module where1886there is defined a UBLCodeType. This type will be a trivial extension of the1887udt:CodeType in the ATG2 UDT schema by creating a union of the UDT code type and1888an enumeration — each enumeration being a restriction on the udt:CodeType.1889

Each code list used in the UBL schema MUST be imported individually.1890

[CDL6] An xsd:import element MUST be declared for every code list required in a1891UBL schema.1892

The UBL library allows partial implementations of code lists which may required by1893customizers.1894

[CDL7] Users of the UBL Library MAY identify any subset they wish from an1895identified code list for their own trading community conformance1896requirements.1897

The following rule describes the requirements for the xsd:schemaLocation for the1898importation of the code lists into a UBL business document.1899

[CDL8] The xsd:schemaLocation MUST include the complete URI used to1900identify the relevant code list schema.1901


7 Miscellaneous XSD Rules1902

UBL, as a business standard vocabulary, requires consistency in its development. The1903number of UBL Schema developers will expand over time. To ensure consistency, it is1904necessary to address the optional features in XSD that are not addressed elsewhere.1905

7.1 xsd:simpleType1906

UBL guiding principles require maximum reuse. XSD provides for forty four built-in1907Datatypes expressed as simple types. In keeping with the maximize re-use guiding1908principle, these built-in simple types should be used wherever possible.1909

[GXS3] Built-in XSD Simple Types SHOULD be used wherever possible.1910

7.2 Namespace Declaration1911

The W3C XSD specification allows for the use of any token to represent its location. To1912ensure consistency, UBL has adopted the generally accepted convention of using the1913“xsd” token for all UBL schema and schema modules.1914

[GXS4] All W3C XML Schema constructs in UBL Schema and schema modules1915MUST contain the following namespace declaration on the xsd schema1916element:1917

xmlns:xsd="http://www.w3.org/2001/XMLSchema”1918

7.3 xsd:substitutionGroup1919

The xsd:substitutionGroup feature enables a type definition to identify substitution1920elements in a group. Although a useful feature in document centric XML applications,1921this feature is not used by UBL.1922

[GXS5] The xsd:substitutionGroup feature MUST NOT be used.1923

7.4 xsd:final1924

UBL does not use extensions in its normative schema. Extensions are allowed by1925customizers as outlined in the Guidelines for Customization. UBL may determine that1926certain type definitions are innapropriate for any customization. In those instances, the1927xsd:final attribute will be used.1928

[GXS6] The xsd:final attribute MUST be used to control extensions where there is1929a desire to prohibit further extensions.1930


7.5 xsd: notation1931

The xsd:notation attribute identifies a notation. Notation declarations corresponding1932to all the <notation> element information items in the [children], if any, plus any1933included or imported declarations. Per XSD Part 2, “It is an ·error· for NOTATION to be1934used directly in a schema. Only Datatypes that are ·derived· from NOTATION by1935specifying a value for ·enumeration· can be used in a schema.” The UBL schema model1936does not require or support the use of this feature.1937

[GXS7] xsd:notation MUST NOT be used.1938

7.6 xsd:all1939

The xsd:all compositor requires occurrence indicators of minOccurs = 0 and1940maxOccurs = 1. The xsd:all compositor allows for elements to occur in any order.1941The result is that in an instance document, elements can occur in any order, are always1942optional, and never occur more than once. Such restrictions are inconsistent with data-1943centric scenarios such as UBL.1944

[GXS8] The xsd:all element MUST NOT be used.1945

7.7 xsd:choice1946

The xsd:choice compositor allows for any element declared inside it to occur in the1947instance document, but only one. As with the xsd:all compositor, this feature is1948inconsistent with business transaction exchanges. UBL recognizes that it is a very useful1949construct in situations where customization and extensibility are not a concern, however,1950UBL does not recommend its use because xsd:choice cannot be extended.1951

[GXS9] The xsd:choice element SHOULD NOT be used where customisation and1952extensibility are a concern.1953

7.8 xsd:include1954

xsd:include can only be used when the including schema is in the same namespace as the1955included schema.1956

7.9 xsd:union1957

The xsd:union feature provides a mechanism whereby a datatype is created as a union1958of two or more existing datatypes. With UBL’s strict adherence to the use of1959ccts:Datatypes that are explicitly declared in the UBL library, this feature is1960inappropriate except for codelists. In some cases external customizers may choose to use1961


this technique for codelists and as such the use of the union technique may prove1962beneficial for customizers.1963

[GXS11] The xsd:union technique MUST NOT be used except for Code Lists. The1964xsd:union technique MAY be used for Code Lists.1965

7.10 xsd:appinfo1966

The xsd:appinfo feature is used by schema to convey processing instructions to a1967processing application, Stylesheet, or other tool. Some users of UBL have determined1968that this technique poses a security risk and have employed techniques for stripping1969xsd:appinfo from schemas. As UBL is committed to ensuring the widest possible1970target audience for its XML library, this feature is not used – except to convey non-1971normative information.1972

[GXS12] UBL designed schema SHOULD NOT use xsd:appinfo. If used,1973xsd:appinfo MUST only be used to convey non-normative information.1974

7.11 xsd:schemaLocation1975

UBL is an international standard that will be used in perpetuity by companies around the1976globe. It is important that these users have unfettered access to all UBL schema.1977

[GXS15] Each xsd:schemaLocation attribute declaration MUST contain a system-1978resolvable URL, which at the time of release from OASIS shall be a relative1979URL referencing the location of the schema or schema module in the release1980package.1981

7.12 xsd:nillable1982

[GXS16] The built in xsd:nillable attribute MUST NOT be used for any UBL1983declared element.1984

7.13 xsd:anyAttribute1985

UBL disallows the use of xsd:anyAttribute, because this feature permits the1986introduction of potentially unknown attributes into an XML instance. UBL intends that1987all constructs within the instance be described by the schemas describing that –instance–-1988xsd:anyAttribute is seen as working counter to the requirements of interoperability.1989In consequence, particular attention is given to the need to enable meaningful validation1990of the UBL document instances. Were it not for this, xsd:anyAttribute might have1991been allowed.1992

[GXS17] The xsd:anyAttribute MUST NOT be used.1993


7.14 Extension and Restriction1994

UBL fully recognizes the value of supporting extension and restriction of its core library1995by customizers. The UBL extension and restriction recommendations are discussed in the1996Guidelines for the Customization of UBL Schemas available as part of UBL 1.0.1997

[GXS13] Complex Type extension or restriction MAY be used where appropriate.1998

1999


8 Instance Documents2000

Consistency in UBL instance documents is essential in a trade environment. UBL has2001defined several rules to help affect this consistency.2002

8.1 Root Element2003

UBL has chosen a global element approach. Inside a UBL document schema only a2004single global element is declared. Because all UBL instance documents conform to a2005UBL document schema, the single global element declared in that document schema will2006be the root element of the instance.2007

[RED1] Every UBL instance document MUST validate to a UBL document schema.2008

8.2 Validation2009

The UBL library and supporting schema are targeted at supporting business information2010exchanges. Business information exchanges require a high degree of precision to ensure2011that application processing and corresponding business cycle actions are reflective of the2012purpose, intent, and information content agreed to by both trading partners. Schemas2013provide the necessary mechanism for ensuring that instance documents do in fact support2014these requirements.2015

[IND1] All UBL instance documents MUST validate to a corresponding schema.2016

2017

[IND7] All UBL instance documents MUST include an element named2018"UBLVersion" as the first child of its root element. The value of this element2019MUST match the value of the xsd:version attribute of its controlling schema.2020

8.3 Character Encoding2021

XML supports a wide variety of character encodings. Processors must understand which2022character encoding is employed in each XML document. XML 1.0 supports a default2023value of UTF-8 for character encoding, but best practice is to always identify the2024character encoding being employed.2025

[IND2] All UBL instance documents MUST identify their character encoding within2026the XML declaration.2027

Example:2028

<?xml version="1.0" encoding="UTF-8"?>2029


UBL, as an OASIS TC, is obligated to conform to agreements OASIS has entered into.2030OASIS is a liaison member of the ISO/IETF/ITU/UNCEFACT Memorandum of2031Understanding Management Group (MOUMG). Resolution 01/08 (MOU/MG01n83)2032requires the use of UTF-8.2033

[IND3] In conformance with ISO/IETF/ITU/UNCEFACT Memorandum of2034Understanding Management Group (MOUMG) Resolution 01/082035(MOU/MG01n83) as agreed to by OASIS, all UBL XML SHOULD be2036expressed using UTF-8.2037

Example:2038

<?xml version=”1.0” encoding=”UTF-8” ?>2039

8.4 Schema Instance Namespace Declaration2040

[IND4] All UBL instance documents MUST contain the following namespace2041declaration in the root element:2042

xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”2043

8.5 Empty Content.2044

Usage of empty elements within XML instance documents are a source of controversy2045for a variety of reasons. An empty element does not simply represent data that is missing.2046It may express data that is not applicable for some reason, trigger the expression of an2047attribute, denote all possible values instead of just one, mark the end of a series of data, or2048appear as a result of an error in XML file generation. Conversely, missing data elements2049can also have meaning – data not provided by a trading partner. In information exchange2050environments, different trading partners may allow, require or ban empty elements. UBL2051has determined that empty elements do not provide the level of assurance necessary for2052business information exchanges and as such will not be used.2053

[IND5] UBL conformant instance documents MUST NOT contain an element devoid2054of content or null values, except in the case of extension, where the 'UBL2055Extension' element is used.2056

To ensure that no attempt is made to circumvent rule IND5, UBL also prohibits2057attempting to convey meaning by not conveying an element.2058

[IND6] The absence of a construct or data in a UBL instance document MUST NOT2059carry meaning except in the case of extension, where the 'UBL Extension'2060element is used.2061

2062

2063


2064

2065

2066

2067

2068

2069

2070

2071

2072

2073

2074

2075

2076

2077


Appendix A. UBL NDR 2.0 Checklist2078

The following checklist constitutes all UBL XML naming and design rules as defined in2079UBL Naming and Design Rules version 2.0, 26 January 2006. The checklist is in2080alphabetical sequence as follows:2081

Attribute Declaration Rules (ATD)2082

Code List Rules (CDL)2083

ComplexType Definition Rules (CTD)2084

ComplexType Naming Rules (CTN)2085

Documentation Rules (DOC)2086

Element Declaration Rules (ELD)2087

Element Naming Rules (ELN)2088

General Naming Rules (GNR)2089

General Type Definition Rules (GTD)2090

General XML Schema Rules (GXS)2091

Instance Document Rules (IND)2092

Modeling Constraints Rules (MDC)2093

Naming Constraints Rules (NMC)2094

Namespace Rules (NMS)2095

Root Element Declaration Rules (RED)2096

Schema Structure Modularity Rules (SSM)2097

Standards Adherence Rules (STA)2098

Versioning Rules (VER)2099

2100


A.1 Attribute Declaration rules

[ATD6] (See GXS15)

[ATD7] (See GXS16)

[ATD8] (See GXS17)

2101

A.2 Code List rules

[CDL1] All UBL Codes MUST be part of a UBL or externally maintained CodeList.

[CDL2] The UBL Library SHOULD identify and use external standardized codelists rather than develop its own UBL-native code lists.

[CDL3] The UBL Library MAY design and use an internal code list where anexisting external code list needs to be extended, or where no suitableexternal code list exists.

[CDL4] All UBL maintained or used Code Lists MUST be enumerated using theUBL Code List Schema Module.

[CDL5] The name of each UBL Code List Schema Module MUST be of the form:

{Owning Organization}{Code List Name}{Code List SchemaModule}

[CDL6] An xsd:import element MUST be declared for every code list requiredin a UBL schema.

[CDL7] Users of the UBL Library MAY identify any subset they wish from anidentified code list for their own trading community conformancerequirements.

[CDL8] The xsd:schemaLocation MUST include the complete URI used toidentify the relevant code list schema.


identify the relevant code list schema.

[CDL9] UBL Code list attribute values SHOULD be set to 'default'.

2102

A.3 ComplexType Definition rules

[CTD1] For every class and property identified in the UBL model, a namedxsd:complexType MUST be defined.

[CTD2] Every ccts:ABIE xsd:complexType definition content model MUSTuse the xsd:sequence element containing references to the appropriateglobal element declarations.

[CTD3] Every ccts:BBIEProperty xsd:complexType definition contentmodel MUST use the xsd:simpleContent element.

[CTD4] Every ccts:BBIEProperty xsd:complexType content modelxsd:simpleContent element MUST consist of an xsd:extensionelement.

[CTD5] Every ccts:BBIEProperty xsd:complexType content modelxsd:base attribute value MUST be the UN/CEFACT UnqualifiedDatatype or UBL qualified Datatype as appropriate.

[CTD6] For every Qualified Datatype used in the UBL model, a namedxsd:complexType or xsd:simpleType MUST be defined.

[CTD20] A ccts:QualifiedDataType MUST be based on an unqualified datatype and add some semantic and/or technical restriction to the unqualifieddata type.

[CTD21] The name of a ccts:QualifiedDataType MUST be the name of itsbase ccts:UnqualifiedDataType with separators and spaces removedand with its qualifier term added.

[CTD22] Every qualified datatype based on an unqualified datatypexsd:complexType whose supplementary components map directly to theproperties of an XSD built-in data type


properties of an XSD built-in data type

MUST be defined as an xsd:simpleType

MUST contain one xsd:restriction element

MUST include an xsd:base attribute that defines the specific XSDbuilt-in data type required for the content component

[CTD23] Every qualified datatype based on an unqualified datatypexsd:complexType whose supplementary components do not map directly tothe properties of an XSD built-in data type

MUST be defined as an xsd:complexType

MUST contain one xsd:simpleContent element


MUST include the unqualified datatype as its xsd:base attribute

[CTD24] Every qualified datatype based on an unqualified datatype xsd:simpleType


MUST include the unqualified datatype as its xsd:base attribute

[CTD25] For every ccts:BBIEProperty identified in the UBL model a namedxsd:complexType must be defined.

2103

A.4 Complex Type Naming rules

[CTN1] A UBL xsd:complexType name based on an ccts:AggregateBusinessInformationEntity MUST be the ccts:Dictionary EntryName withthe separators removed and with the “Details” suffix replaced with “Type”.

[CTN2] A UBL xsd:complexType name based on a ccts:BasicBusinessInformationEntityProperty MUST be the ccts:Dictionary EntryNameshared property term and its qualifiers and representation term of theccts:BasicBusinessInformationEntity, with the separators removed andwith the “Type” suffix appended after the representation term.


[CTNX1] A UBL xsd:complexType name based on a ccts:BasicBusinessInformationEntityProperty and with a . ccts:BasicBusinessInformationEntityRepresentationTerm of 'Text' MUST havethe word "Text" removed from the end of its name.

[CTNX2] A UBL xsd:complexType name based on a ccts:BasicBusinessInformationEntityProperty and with a . ccts:BasicBusinessInformationEntityRepresentationTerm of 'Identifier'

MUST have the word "Identifier" replaced by the word "ID" at the end ofits name.

[CTNX3] A UBL xsd:complexType name based on a ccts:BasicBusinessInformationEntityProperty MUST remove all duplication of wordsthat occur as a result of duplicate property terms and representation terms.

2104

A.5 Documentation rules

[DOC1] The xsd:documentation element for every Datatype MUST contain astructured set of annotations in the following sequence and pattern (asdefined 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 ComponentRestrictions to provide additional information on the relationship betweenthe Datatype and its corresponding Core Component Type. If used theContent Component Restrictions must contain a structured set ofannotations in the following patterns:


Content Component Restrictions must contain a structured set ofannotations in the following patterns:

• RestrictionType (mandatory): Defines the type of formatrestriction that applies to the Content Component.

• RestrictionValue (mandatory): The actual value of the formatrestriction that applies to the Content Component.

• ExpressionType (optional): Defines the type of the regularexpression of the restriction value.

[DOC3] A Datatype definition MAY contain one or more SupplementaryComponent Restrictions to provide additional information on therelationship between the Datatype and its corresponding Core ComponentType. If used the Supplementary Component Restrictions must contain astructured set of annotations in the following patterns:

• SupplementaryComponentName (mandatory): Identifies theSupplementary Component on which the restriction applies.

• RestrictionValue (mandatory, repetitive): The actual value(s) thatis (are) valid for the Supplementary Componen

[DOC4] The xsd:documentation element for every Basic Business InformationEntity MUST contain a structured set of annotations in the followingpatterns:

• ComponentType (mandatory): The type of component to whichthe object belongs. For Basic Business Information Entities thismust be “BBIE”.

• DictionaryEntryName (mandatory): The official name of a BasicBusiness Information Entity.

• Version (optional): An indication of the evolution over time of theBasic Business Information Entity.

• Definition(mandatory): The semantic meaning of a Basic BusinessInformation Entity.

• Cardinality(mandatory): Indication whether the Basic BusinessInformation Entity represents a not-applicable, optional, mandatoryand/or repetitive characteristic of the Aggregate BusinessInformation Entity.


• ObjectClassQualifier (optional): The qualifier for the object class.

• ObjectClass(mandatory): The Object Class containing the BasicBusiness Information Entity.

• PropertyTermQualifier (optional): A qualifier is a word or wordswhich help define and differentiate a Basic Business InformationEntity.

• PropertyTerm(mandatory): Property Term represents thedistinguishing characteristic or Property of the Object Class andshall occur naturally in the definition of the Basic BusinessInformation Entity.

• RepresentationTerm (mandatory): A Representation Termdescribes the form in which the Basic Business Information Entityis represented.

• DataTypeQualifier (optional): semantically meaningful name thatdifferentiates the Datatype of the Basic Business Information Entityfrom its underlying Core Component Type.

• DataType (mandatory): Defines the Datatype used for the BasicBusiness Information Entity.

• AlternativeBusinessTerms (optional): Any synonym terms underwhich the Basic Business Information Entity is commonly knownand used in the business.

• Examples (optional): Examples of possible values for the BasicBusiness Information Entity

[DOC5] The xsd:documentation element for every Aggregate Business InformationEntity MUST contain a structured set of annotations in the followingsequence and pattern:

• ComponentType (mandatory): The type of component to whichthe object belongs. For Aggregate Business Information Entitiesthis must be “ABIE”.

• DictionaryEntryName (mandatory): The official name of theAggregate Business Information Entity .

• Version (optional): An indication of the evolution over time of theAggregate Business Information Entity.


• Definition(mandatory): The semantic meaning of the AggregateBusiness Information Entity.

• ObjectClassQualifier (optional): The qualifier for the object class.

• ObjectClass(mandatory): The Object Class represented by theAggregate Business Information Entity.

• AlternativeBusinessTerms (optional): Any synonym terms underwhich the Aggregate Business Information Entity is commonlyknown and used in the business.

[DOC6] The xsd:documentation element for every Association BusinessInformation Entity element declaration MUST contain a structured set ofannotations in the following sequence and pattern:

• ComponentType (mandatory): The type of component to whichthe object belongs. For Association Business Information Entitiesthis must be “ASBIE”.

• DictionaryEntryName (mandatory): The official name of theAssociation Business Information Entity.

• Version (optional): An indication of the evolution over time of theAssociation Business Information Entity.

• Definition(mandatory): The semantic meaning of the AssociationBusiness Information Entity.

• Cardinality(mandatory): Indication whether the AssociationBusiness Information Entity represents an optional, mandatoryand/or repetitive assocation.

• ObjectClass(mandatory): The Object Class containing theAssociation Business Information Entity.

• PropertyTermQualifier (optional): A qualifier is a word or wordswhich help define and differentiate the Association BusinessInformation Entity.

• PropertyTerm(mandatory): Property Term represents theAggregate Business Information Entity contained by theAssociation Business Information Entity.

• AssociatedObjectClassQualifier (optional): Associated ObjectClass Qualifiers describe the 'context' of the relationship withanother ABIE. That is, it is the role the contained AggregateBusiness Information Entity plays within its association with thecontaining Aggregate Business Information Entity.


another ABIE. That is, it is the role the contained AggregateBusiness Information Entity plays within its association with thecontaining Aggregate Business Information Entity.

• AssociatedObjectClass (mandatory); Associated Object Class isthe Object Class at the other end of this association. It representsthe Aggregate Business Information Entity contained by theAssociation Business Information Entity.

[DOC8] The xsd:documentation element for every Supplementary Componentattribute declarationMUST contain a structured set of annotations in thefollowing sequence and pattern:

• Name (mandatory): Name in the Registry of a SupplementaryComponent of a Core Component Type.

• Definition (mandatory): A clear, unambiguous and completeexplanation of the meaning of a Supplementary Component and itsrelevance for the related Core Component Type.

• Primitive type (mandatory): PrimitiveType to be used for therepresentation of the value of a Supplementary Component.

• Possible Value(s) (optional): one possible value of aSupplementary Component.

[DOC9] The xsd:documentation element for every Supplementary Componentattribute declaration containing restrictions MUST include the followingadditional information appended to the information required by DOC8:

• Restriction Value(s) (mandatory): The actual value(s) that is (are)valid for the Supplementary Component.

2105

A.6 Element Declaration rules

[ELD2] All element declarations MUST be global

[ELD3] For every class and property identified in the UBL model, a global elementbound to the corresponding xsd:complexType MUST be declared.


[ELD4] When a ccts:ASBIE is unqualified, it is bound via reference to the globalccts:ABIE element to which it is associated.

[ELD6] The code list xsd:import element MUST contain the namespace andschema location attributes.

[ELD7] Empty elements MUST not be declared, except in the case of extension,where the 'UBL Extension' element is used.

[ELD9] (See GXS14)

[ELD10] The root element MUST be the only global element declared in documentschemas.

[ELD11] When a ccts:ASBIE is qualified, a new element MUST be declared andbound to the xsd:complexType of its associated ccts:ABIE.

[ELD12] The 'UBL Extension' element declaration MUST exist withxsd:minOccurs="0".

[ELD13] The 'UBLProfileID' element declaration MUST exist withxsd:minOccurs="0".

[ELD14] The 'UBLSubset' element declaration MUST exist withxsd:minOccurs="0".

2106

A.7 Element Naming rules

[ELN1] A UBL global element name based on a ccts:ABIE MUST be the same asthe name of the corresponding xsd:complexType to which it is bound, withthe word “Type” removed.

[ELN2] A UBL global element name based on a ccts:BBIEProperty MUST bethe same as the name of the corresponding xsd:complexType to whichit is bound, with the word “Type” removed.


[ELN3] A UBL global element name based on a ccts:ASBIE MUST be theccts:ASBIE dictionary entry name property term and its qualifiers; and theobject class term and qualifiers of its associated ccts:ABIE. Allccts:DictionaryEntryName separators MUST be removed..

A.8 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 EnglishDictionary.

[GNR2] UBL XML element and type names MUST be consistently derived fromCCTS conformant dictionary entry names.

[GNR3] UBL XML element and type names constructed fromccts:DictionaryEntryNames MUST NOT include periods, spaces, otherseparators, or characters not allowed by W3C XML 1.0 for XML names

[GNR4] UBL XML element, and simple and complex type names MUST NOT useacronyms, abbreviations, or other word truncations, except those in the listof exceptions published in Appendix B.

[GNR5] Acronyms and abbreviations MUST only be added to the UBL approvedacronym and abbreviation list after careful consideration for maximumunderstanding and reuse.

[GNR6] The acronyms and abbreviations listed in Appendix B MUST always beused in place of the word or phrase they represent.

[GNR7] UBL XML element, and type names MUST be in singular form unless theconcept itself is plural.

[GNR8] The UpperCamelCase (UCC) convention MUST be used for namingelements and types.

[GNR10] Acronyms and abbreviations at the beginning of an attribute name MUSTappear in all lower case. All other acronym and abbreviation usage in anattribute declaration MUST appear in upper case.

attribute declaration MUST appear in upper case.

[GNR11] Acronyms and abbreviations MUST appear in all upper case for all elementdeclarations and type definitions.

2107

A.9 General Type Definition Rules

[GTD1] All types MUST be named.

[GTD2] The xsd:anyType MUST NOT be used.

2108

A.10 General XML Schema Rules

[GXS1] UBL Schema MUST conform to the following physical layout asapplicable:



<?xml version="1.0" encoding="UTF-8"?>



Document Name: < Document name as indicated in Section 3.6 >

Generated On: < Date schema was generated >



“Copyright „ 2001-2004 The Organization for the Advancement ofStructured Information Standards (OASIS). All rights reserved.



xsd:schema element to include version attribute and namespacedeclarations in the following order:

xmlns:xsd

Target namespace

Default namespace

CommonAggregateComponents

CommonBasicComponents

CoreComponentTypes

Unspecialized Unqualified Datatypes

Specialized Qualified Datatypes

Identifier Schemes

Code Lists

Attribute Declarations – elementFormDefault="”qualified"”attributeFormDefault="”unqualified"”

Version Attribute



CommonAggregateComponents schema module

CommonBasicComponents schema module

Unspecialized Unqualified Types schema module

Specialized Qualified Types schema module



Global Attributes and Attribute Groups



Root Element Declaration

Root Element Type Definition



alphabetized order

All type definitions segregated by basic and aggregates as follows



alphabetized order of ccts:AggregateBusinessInformationEntityxsd:TypeDefinitions



alphabetized order of ccts:BasicBusinessInformationEntities



Required OASIS full copyright notice.

[GXS2] UBL MUST provide two normative schemas for each transaction. Oneschema shall be fully annotated. One schema shall be a run-time schemadevoid of documentation.

[GXS3] Built-in XSD Simple Types SHOULD be used wherever possible.

[GXS4] All W3C XML Schema constructs in UBL Schema and schema modulesMUST contain the following namespace declaration on the xsd schemaelement: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 thereis a desire to prohibit further extensions.

[GXS7] xsd:notation MUST NOT be used.

[GXS8] The xsd:all element MUST NOT be used.

[GXS9] The xsd:choice element SHOULD NOT be used where customisationand extensibility are a concern.


[GXS11] The xsd:union technique MUST NOT be used except for Code Lists.The xsd:union technique MAY be used for Code Lists.

[GXS12] UBL designed schema SHOULD NOT use xsd:appinfo. If used,xsd:appinfo MUST only be used to convey non-normative information.

[GXS13] Complex Type extension or restriction MAY be used where appropriate.

[GXS14] The xsd:any element MUST NOT be used except within the'UBLExtensionType' type definition, and with xsd:processContents= "skip"for non-UBL namespaces.

[GXS15] Each xsd:schemaLocation attribute declaration MUST contain asystem-resolvable URL, which at the time of release from OASIS shall bea relative URL referencing the location of the schema or schema module inthe release package.

[GXS16] The built in xsd:nillable attribute MUST NOT be used for any UBLdeclared element.

[GXS17] The xsd:anyAttribute MUST NOT be used.

2109

A.11 Instance document rules

[IND1] All UBL instance documents MUST validate to a corresponding schema.

[IND2] All UBL instance documents MUST identify their character encoding withinthe XML declaration.

[IND3] In conformance with ISO/IETF/ITU/UNCEFACT Memorandum ofUnderstanding Management Group (MOUMG) Resolution 01/08(MOU/MG01n83) as agreed to by OASIS, all UBL XML SHOULD beexpressed using UTF-8.

[IND4] All UBL instance documents MUST contain the following namespacedeclaration in the root element:


xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”

[IND5] UBL conformant instance documents MUST NOT contain an element devoidof content or null values, except in the case of extension, where the 'UBLExtension' element is used.

[IND6] The absence of a construct or data in a UBL instance document MUST NOTcarry meaning except in the case of extension, where the 'UBL Extension'element is used

[IND7] All UBL instance documents MUST include an element named"UBLVersion" as the first child of its root element. The value of this elementMUST match the value of the xsd:version attribute of its controlling schema.

2110

A.12 Modelling constraint rules

[MDC1] UBL Libraries and Schemas MUST only use ebXML Core Componentapproved ccts:CoreComponentTypes.

[MDC2] Mixed content MUST NOT be used except where contained in anxsd:documentation element

2111

A.13 Naming constraint rules

[NMC1] Each dictionary entry name MUST define one and only one fully qualifiedpath (FQP) for an element or attribute.

2112

A.14 Namespace Rules

[NMS1] Every UBL-defined –or -used schema module, except internal schemamodules, MUST have a namespace declared using thexsd:targetNamespace attribute.


[NMS2] Every UBL-defined-or -used major version schema set MUST have its ownunique namespace.

[NMS3] UBL namespaces MUST only contain UBL developed schema modules.

[NMS4] The namespace names for UBL Schemas holding committee draft statusMUST be of the form:

urn:oasis:names:tc:ubl:schema:<subtype>:<document-id>

[NMS5] The namespace names for UBL Schemas holding OASIS Standard statusMUST be of the form:

urn:oasis:names:specification:ubl:schema:<subtype>:<document-id>

[NMS6] UBL published namespaces MUST never be changed.

[NMS7] The ubl:CommonAggregateComponents schema module MUST reside inits own namespace.

[NMS8] The ubl:CommonAggregateComponents schema module namespaceMUST be represented by the namespace prefix “cac” when referenced inother schemas.

[NMS9] The ubl:CommonBasicComponents schema module MUST reside in itsown namespace.

[NMS10] The UBL:CommonBasicComponents schema module namespace MUST berepresented by the namespace prefix “cbc” when referenced in other schemas.

[NMS15] The ubl:QualifiedDatatypes schema module MUST reside in its ownnamespace.

[NMS16] The ubl:QualifiedDatatypes schema module namespace MUST berepresented by the namespace prefix “qdt” when referenced in other schemas.

[NMS17] The ccts:UnqualifiedDatatypes schema module namespace MUST berepresented by the token “udt”when referenced in other schemas.


2113

A.15 Root element declaration rules

[RED1] Every UBL instance document MUST validate to a UBL document schema.

2114

A.16 Schema structure modularity rules

[SSM1] UBL Schema expressions MAY be split into multiple schema modules.

[SSM2] A document schema in one UBL namespace that is dependent upon typedefinitions or element declarations defined in another namespace MUST onlyimport the document schema from that namespace.

[SSM3] A document schema in one UBL namespace that is dependant upon typedefinitions or element declarations defined in another namespace MUSTNOT import internal schema modules from that namespace.

[SSM4] Imported schema modules MUST be fully conformant with UBL naming anddesign rules.

[SSM5] UBL schema modules MUST either be treated as external schema modules oras internal schema modules of the document schema.

[SSM6] All UBL internal schema modules MUST be in the same namespace as theircorresponding document schema.

[SSM7] Each UBL internal schema module MUST be named{ParentSchemaModuleName}{InternalSchemaModuleFunction}{schemamodule}

[SSM8] A UBL schema module MAY be created for reusable components.

[SSM9] A schema module defining all UBL Common Aggregate Components MUSTbe created.


[SSM10] The UBL Common Aggregate Components schema module MUST beidentified as CommonAggregateComponents in the document name withinthe schema header.

[SSM11] A schema module defining all UBLCommon Basic Components MUST becreated.

[SSM12] The UBL Common Basic Components schema module MUST be identifiedas CommonBasicComponents in the document name within the schemaheader.

[SSM18] A schema module defining all UBL Qualified Datatypes MUST be created.

[SSM19] The UBL Qualified Datatypes schema module MUST be identified asQualifiedDatatypes in the document name in the schema header.

[SSM20] The UBL Qualified Datatypes schema module MUST import theccts:UnQualifiedDatatypes schema module.

A.17 Standards Adherence rules

[STA1] All UBL schema design rules MUST be based on the W3C XML SchemaRecommendations: XML Schema Part 1: Structures and XML Schema Part2: Datatypes.

[STA2] All UBL schema and messages MUST be based on the W3C suite oftechnical specifications holding recommendation status.

2115

A.18 Versioning rules

[VER1] Every UBL Schema and schema module major version committee draftMUST have an RFC 3121 document-id of the form

<name>-<major>[.<revision>]

[VER2] Every UBL Schema and schema module major version OASIS StandardMUST have an RFC 3121 document-id of the form


<name>-<major>

[VER3] Every minor version release of a UBL schema or schema module draftMUST have an RFC 3121 document-id of the form

<name>-<major>[.<revision>]

[VER4] Every minor version release of a UBL schema or schema module OASISStandard MUST have an RFC 3121 document-id of the form

<name>-<major >

[VER5] For UBL Minor version changes the namespace name MUST not change

[VER6] Every UBL Schema and schema module major version number MUST be asequentially assigned, incremental number greater than zero.

[VER7] Every UBL Schema and schema module minor version number MUST be asequentially assigned, incremental non-negative integer.

[VER8] A UBL minor version document schema MUST import its immediatelypreceding version document schema.

[VER9] UBL Schema and schema module minor version changes MUST be limitedto the use of xsd:extension or xsd:restriction to alter existing typesor add new constructs.

[VER10] UBL Schema and schema module minor version changes MUST not breaksemantic compatibility with prior versions.

[VER11] Every UBL Schema and schema module major version committee draftMUST capture its version number in the xsd:version attribute of thexsd:schema element in the form

<major>.0[.<revision>]

[VER12] Every UBL Schema and schema module major version OASIS StandardMUST capture its version number in the xsd:version attribute of thexsd:schema element in the form

<major>.0


[VER13] Every minor version release of a UBL schema or schema module draftMUST capture its version information in the xsd:version attribute in theform

<major>.<non-zero>[.<revision>]

[VER14] Every minor version release of a UBL schema or schema module OASISStandard MUST capture its version information in the xsd:version attribute inthe form

<major>.<non-zero>

[VER15] Every UBL document schema MUST include a required element named"UBLVersion" as the first child of its root element. This element MUST havea default value that matches the value of the xsd:version attribute of itscontaining schema.

2116


2117


Appendix B. Approved Acronyms and Abbreviations2118

The following Acronyms and Abbreviations have been approved by the UBL NDR2119Subcommittee for UBL use:2120

A Dun & Bradstreet Data Universal Numbering System (DUNS) number must2121appear as "DUNS".2122

"Identifier" must appear as "ID".2123

"Uniform Resource Identifier" must appear as "URI"2124

[Example] the "Uniform Resource. Identifier" portion of the Binary Object.2125Uniform Resource. Identifier supplementary component becomes "URI" in2126the resulting XML name). The use of URI for Uniform Resource Identifier2127takes precedence over the use of "ID" for "Identifier".2128

This list will henceforth be maintained by the UBL TC as a committee of the whole, and2129additions included in current and future versions of the UBL standard will be maintained2130and published separately.2131


Appendix C. Technical Terminology2132

2133

Ad hoc schema processing Doing partial schema processing, but not with officialschema validator software; e.g., reading throughschema to get the default values out of it.

Aggregate BusinessInformation Entity (ABIE)

A collection of related pieces of business informationthat together convey a distinct business meaning in aspecific Business Context. Expressed in modellingterms, it is the representation of an Object Class, in aspecific Business Context.

Application-level validation Adherence to business requirements, such as validaccount numbers.

Assembly Using parts of the library of reusable UBL componentsto create a new kind of business document type.

Business Context Defines a context in which a business has chosen toemploy an information entity.

The formal description of a specific businesscircumstance as identified by the values of a set ofContext Categories, allowing different businesscircumstances to be uniquely distinguished.


Business Object An unambiguously identified, specified, referenceable,registerable and re-useable scenario or scenariocomponent of a business transaction.

The term business object is used in two distinct butrelated ways, with slightly different meanings for eachusage:

In a business model, business objects describe abusiness itself, and its business context. The businessobjects capture business concepts and express anabstract view of the business’s “real world”. The term“modeling business object” is used to designate thisusage.

In a design for a software system or in program code,business objects reflects how business concepts arerepresented in software. The abstraction here reflectsthe transformation of business ideas into a softwarerealization. The term “systems business objects” isused to designate this usage.

business semantic(s) A precise meaning of words from a businessperspective.

Business Term This is a synonym under which the Core Component orBusiness Information Entity is commonly known andused in the business. A Core Component or BusinessInformation Entity may have several business terms orsynonyms.

class A description of a set of objects that share the sameattributes, operations, methods, relationships, andsemantics. A class may use a set of interfaces tospecify collections of operations it provides to itsenvironment. See interface.


class diagram Shows static structure of concepts, types, and classes.Concepts show how users think about the world; typesshow interfaces of software components; classes showimplementation of software components. (OMGDistilled)

A diagram that shows a collection of declarative(static) model elements, such as classes, types, andtheir contents and relationships. (Rational UnifiedProcess)

classification scheme This is an officially supported scheme to describe agiven Context Category

Common attribute An attribute that has identical meaning on the multipleelements on which it appears. A common attributemight or might not correspond to an XSD globalattribute.

component One of the individual entities contributing to a whole.

context Defines the circumstances in which a Business Processmay be used. This is specified by a set of ContextCategories known as Business Context. (See BusinessContext.)

context category A group of one or more related values used to express acharacteristic of a business circumstance.

Document schema A schema document corresponding to a singlenamespace, which is likely to pull in (by including orimporting) schema modules.

Core Component A building block for the creation of a semanticallycorrect and meaningful information exchange package.It contains only the information pieces necessary todescribe a specific concept.


Core Component Type A Core Component which consists of one and only oneContent Component that carries the actual content plusone or more Supplementary Components giving anessential extra definition to the Content Component.Core Component Types do not have businesssemantics.

Datatype A descriptor of a set of values that lack identity andwhose operations do not have side effects. Datatypesinclude primitive pre-defined types and user-definabletypes. Pre-defined types include numbers, string andtime. User-definable types include enumerations.(XSD)

Defines the set of valid values that can be used for aparticular Basic Core Component Property or BasicBusiness Information Entity Property. It is defined byspecifying restrictions on the Core Component Typethat forms the basis of the Datatype. (CCTS)

Generic BIE A semantic model that has a “zeroed” context. We areassuming that it covers the requirements of 80% ofbusiness uses, and therefore is useful in that state.

instance An individual entity satisfying the description of a classor type.

Instance constraint checking Additional validation checking of an instance, beyondwhat XSD makes available, that relies only onconstraints describable in terms of the instance and notadditional business knowledge; e.g., checking co-occurrence constraints across elements and attributes.Such constraints might be able to be described in termsof Schematron.

Instance root/doctype This is still mushy. The transitive closure of all thedeclarations imported from whatever namespaces arenecessary. A doctype may have several namespacesused within it.

Intermediate element An element not at the top level that is of a complextype, only containing other elements and attributes.


Internal schema module: A schema module that does not declare a targetnamespace.

Leaf element An element containing only character data (though itmay also have attributes). Note that, because of theXSD mechanisms involved, a leaf element that hasattributes must be declared as having a complex type,but a leaf element with no attributes may be declaredwith 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 leaflevel.

Object Class The logical data grouping (in a logical data model) towhich a data element belongs (ISO11179). The ObjectClass is the part of a Core Component’s DictionaryEntry Name that represents an activity or object in aspecific Context.

Namespace schema module: A schema module that declares a target namespace andis likely to pull in (by including or importing) schemamodules.

Naming Convention The set of rules that together comprise how thedictionary entry name for Core Components andBusiness Information Entities are constructed.

(XML) Schema An XML Schema consists of components such as typedefinitions and element declarations. These can be usedto assess the validity of well-formed element andattribute information items (as defined in [XML-Infoset]), and furthermore may specify augmentationsto those items and their descendants.

Schema module A collection of XML constructs that together constitutean XSD conformant schema. Schema modules areintended to be used in combination with other XSDconformant schema.


Schema Processing Schema validation checking plus provision of defaultvalues and provision of new infoset properties.

Schema Validation Adherence to an XSD schema.

semantic Relating to meaning in language; relating to theconnotations of words.

Top-level element An element that encloses a whole UBL businessmessage. Note that UBL business messages might becarried by messaging transport protocols thatthemselves have higher-level XML structure. Thus, aUBL top-level element is not necessarily the rootelement of the XML document that carries it.

type Description of a set of entities that share commoncharacteristics, relations, attributes, and semantics.

A stereotype of class that is used to specify an area ofinstances (objects) together with the operationsapplicable to the objects. A type may not contain anymethods. See class, instance. Contrast interface.


Appendix D. References2134

[CCTS] ISO 15000-5 ebXML Core Components Technical Specification2135[ISONaming] ISO/IEC 11179, Final committee draft, Parts 1-6.2136(RFC) 2119 S. Bradner, Key words for use in RFCs to Indicate Requirement2137

Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March21381997.2139

[UBLChart] UBL TC Charter, http://oasis-2140open.org/committees/ubl/charter/ubl.htm2141

[XML] Extensible Markup Language (XML) 1.0 (Second Edition), W3C2142Recommendation, October 6, 20002143

(XSD) XML Schema, W3C Recommendations Parts 0, 1, and 2. 2 May21442001.2145

2146(XHTML) XHTML™ Basic, W3C Recommendation 19 December 2000:2147

http://www.w3.org/TR/2000/REC-xhtml-basic-2000121921482149


Appendix E. Notices2150

OASIS takes no position regarding the validity or scope of any intellectual property or2151other rights that might be claimed to pertain to the implementation or use of the2152technology described in this document or the extent to which any license under such2153rights might or might not be available; neither does it represent that it has made any effort2154to identify any such rights. Information on OASIS's procedures with respect to rights in2155OASIS specifications can be found at the OASIS website. Copies of claims of rights2156made available for publication and any assurances of licenses to be made available, or the2157result of an attempt made to obtain a general license or permission for the use of such2158proprietary rights by implementors or users of this specification, can be obtained from the2159OASIS Executive Director.2160

OASIS invites any interested party to bring to its attention any copyrights, patents or2161patent applications, or other proprietary rights which may cover technology that may be2162required to implement this specification. Please address the information to the OASIS2163Executive Director.2164

Copyright © The Organization for the Advancement of Structured Information Standards2165[OASIS] 2001, 2002, 2003, 2004. All Rights Reserved.2166

This document and translations of it may be copied and furnished to others, and2167derivative works that comment on or otherwise explain it or assist in its implementation2168may be prepared, copied, published and distributed, in whole or in part, without2169restriction of any kind, provided that the above copyright notice and this paragraph are2170included on all such copies and derivative works. However, this document itself does not2171be modified in any way, such as by removing the copyright notice or references to2172OASIS, except as needed for the purpose of developing OASIS specifications, in which2173case the procedures for copyrights defined in the OASIS Intellectual Property Rights2174document must be followed, or as required to translate it into languages other than2175English.2176

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

This document and the information contained herein is provided on an “AS IS” basis and2179OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING2180BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE2181INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED2182WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR2183PURPOSE.2184

2185

Universal Business Language (UBL) Naming and Design Rules · 6/28/2006 · 216 A.12Modelling...

Documents

Transcript of Universal Business Language (UBL) Naming and Design Rules · 6/28/2006 · 216 A.12Modelling...