[Accessibility conventions are described at the bottom of the page]

10. Customization specification
[> 11.][< 9.1.11][^^^]
10.0 Customization specification
[> 10.0.1][> 10.1][> 11.][< 10.][^^][^^^]
At least two ways to view interoperability when customizing UBL for one's own purposes
[[1] - model-level interoperability (UBL compatibility)
[[2] - objective to be create new information items and messages based on UBL library of constructs
][1] - document-level interoperability (UBL conformance)
[[2] - objective to be able to interchange UBL messages
]]
In these two diagrams, the thin-edged ovals represent the set of vocabulary information items (names and namespaces) for an implementation of UBL, while the thick-edged ovals represent the basis upon which the vocabularies are derived
[[1] - the top diagram illustrates how there is no overlap of vocabularies between UBL, the Korean Customs Service implementation of UBL and the New TradeNet implementation of UBL
[[2] - the business objects in all vocabularies are derived from UBL business objects
][1] - the bottom diagram illustrates how there is a big overlap of vocabulary between UBL, the North European Subset (NES), and the BII vocabulary
[[2] - both the NES and BII vocabularies use a subset of the UBL vocabulary
[[3] - opportunity to add extensions, though in practice this hasn't yet happened
][2] - all three vocabularies are based on the information items and unqualified data types of UBL, thus the XSD module is utilized in the declaration of the constructs
]]
[Figure 10.1:
The diagram is split horizontally into two halves.
The top half is titled "Model-level interoperability" and subtitled "UBL Compatibility". Above an oval labeled "UBL" annotated with "base business object definitions" are three separated and non-overlapping ovals labeled "Korean Customs Service", "UBL" and "New TradeNet", each annotated with "vocabulary and namespaces".
The bottom half is titled "Document-level Interoperability" and subtitled "UBL Conformance". Above an oval titled "UBL UDT" and annotated with "base information items and unqualified data types" are three overlapping ovals titled "UBL", "NES" and "BII" where the group of three is annotated with "vocabulary and namespaces".
]
10.0.1 Expressing a conformant UBL subset
[> 10.1][> 11.][< 10.0][^][^^][^^^]
The W3C schema modules for a conformant UBL subset express the customization constraints
[[1] - customization fragments partially overwrite a copy of the UBL xsd/ and xsdrt/ directories
]
The following subset schema fragments replace the UBL schema fragments:
[[1] - the document schema (e.g. Statement, Waybill, etc.)
 [1] - the definition of ABIE (and, therefore, ASBIE) constructs
 [1] - the definition of BBIE constructs
 [1] - all unused constructs are removed from the fragments
]
[Figure 10.2: Schema replacements for customization
A chart illustrating the dependencies of schema fragments has boxes for each schema file, starting with the Document Schema box at the top representing an invoice, or an order, or other UBL document, in that document type's namespace.
The Document Schema imports the Common Aggregate Components (cac), Common Basic Components (cbc) and Common Extension Components (ext) fragments.
The Common Aggregate Components (cac) fragment imports the Common Basic Components (cbc), Unqualified Datatypes (udt) and Qualified/Specialized Datatypes (qdt) fragments.
The Common Basic Components (cbc) fragment imports the Unqualified Datatypes (udt) and Qualified/Specialized Datatypes (qdt) fragments.
The Qualified/Specialized Datatypes (qdt) fragment imports the Unqualified Datatypes (udt) fragment.
The Common Extension Components (ext) fragment imports the Common Basic Components (cbc) and Unqualified Datatypes (udt) fragments, and includes the Extension Content Datatype (ext) fragment.
Shown to the side in a box labeled "Customization Restriction Replacement Schemas" are the replacement Customization Document Schema, Customization Aggregate Components (cac) and Customization Basic Components (cbc) fragments as required for the customization.
]
10.1 Defining a customization of UBL
[> 11.][< 10.0.1][^^][^^^]
10.1.1 Defining a compatible UBL customization
[> 10.1.2][> 11.][< 10.0.1][^^][^^^]
Could consider working with the UML models (see [UBL UML information models - Section 3.2.4 UBL UML information models])
[[1] - the UML models were created with the Sparx Enterprise Architect 6.5 tool and are available here:
 [1] - [http://www.oasis-open.org/committees/document.php?document_id=21918]
]
Instance level conformance is of secondary (or no) consideration
[[1] - for interoperability the business objects of the compatible schema should be derived from the business objects of UBL
]
10.1.2 Defining a conformant UBL subset
[> 10.1.3][> 11.][< 10.1.1][^][^^][^^^]
A conformant subset of UBL is one whose constraints are constrained by UBL
[[1] - every valid instance of the conformant subset document model is a valid instance of UBL
]
Allowed customization changes in sequence and cardinality
[[1] - cannot rearrange elements
 [1] - limited changes to cardinality
[[2] - minimums can be increased
 [2] - maximums can be decreased
]]
Applying the constraints to the normative document schemas
[[1] - any process creating a suite of schema conforming simultaneously to the UBL NDR and the constraints of the UBL model is acceptable
[[2] - e.g. create W3C Schema XSD files from scratch
][1] - Crane's approach in Crane-UBLProfile is to transform the UBL W3C Schema XSD files
[[2] - original declarations of elided elements are commented out
 [2] - original cardinalities of changed elements are added as comments
 [2] - the entire original OASIS W3C Schema expression can be seen in the actual declarations or commented declarations in each file
[[3] - thus all changes can be visually confirmed if one is uncertain
]][1] - those constructs not used anywhere in the hierarchy of the document schemas are removed from the fragments
]
10.1.3 Strict and permitted subsets
[> 10.1.4][> 11.][< 10.1.2][^][^^][^^^]
At least two ways to approach specifying a subset of a UBL information model
[[1] - these were proposed in early research work done by and for the Government of Denmark
 [1] - a strict subset
[[2] - nothing is wanted except those items with any specified cardinalities
][1] - a permitted subset
[[2] - everything is wanted except those items with a zero cardinality
]]
Mandatory items are obliged to be in all subsets
[[1] - otherwise an instance of the customization without the mandatory item would not be a valid instance of UBL
]
10.1.4 Limitations and cautions to pruning
[> 10.1.5][> 11.][< 10.1.3][^][^^][^^^]
Recall the UBL document constraint regarding empty elements ([UBL documents - Section 5.2.2 UBL documents])
[[1] - a UBL document is not allowed to have empty elements
 [1] - many of the constructs are optional
 [1] - very easy when defining a strict subset to end up with no child elements specified for a parent
]
No ABIE can have all of its items pruned if an ASBIE might use it
[[1] - it is irrelevant if an ABIE has no children if that ABIE is never used for a given document model
 [1] - one need only concentrate on those ABIE constructs that have been referenced by ASBIE constructs, recursively, from the document ABIE
]
Crane-UBLProfile reports ABIE constructs where all of the children have been pruned
[[1] - reported in the summary report and HTML reports
]
10.1.5 Acknowledging OASIS copyright
[> 11.][< 10.1.4][^][^^][^^^]
Guidelines from UBL TC regarding UBL customizations
[[1] - [http://lists.oasis-open.org/archives/ubl/200806/msg00002.html]
]
Requirements for inclusion in derivative works:
[[1] - OASIS policies support implementations, subsetting and extensions of OASIS works, so long as they respect conformance, in the sense of not claiming compliance with an OASIS work, or identity with an OASIS work, incorrectly.
Specifications and models published for use by others that incorporate OASIS work should include the following in an appropriate place, usually near the author's own copyright notice:
Portions copyright © OASIS Open 200[8]. All Rights Reserved.
 [1] - [http://lists.oasis-open.org/archives/ubl/200802/msg00038.html]
[[2] - guidelines received from OASIS executives
]]


This is an accessible version of Crane's commercial training material. The content has been specifically designed to assist screen reader software in viewing the entire textual content. Figures are replaced with text narratives.

Navigation hints are in square brackets:
[Tx.x] and [Fx.x] are textual representations of the applicability icons;
[digit] indicates list depth for nested lists;
[link [URL]] indicates the URL of a hyperlink if different than link;
[EXAMPLE] indicates an example listing of code;
[FIGURE] indicates the presence of a figure replaced by its description;
[>] jumps forward;
[<] jumps backward;
[^] jumps to start of the section;
[^^] jumps to the start of the chapter;
[^^^] jumps to the table of contents.
Suggestions for improvement are welcome: [info@CraneSoftwrights.com]
Book sales: [http://www.CraneSoftwrights.com/links/trn-acc.htm]
Information: [http://www.CraneSoftwrights.com/links/info-acc.htm]
This content is protected by copyright and, as there are no means to protect this accessible version from plagiarism, please do not make any commercial edition available to others.

+//ISBN 1-894049::CSL::Presentation::UBL//DOCUMENT Practical Universal Business Language Deployment 2009-02-12 13:50UTC//EN
Practical Universal Business Language Deployment
Third Edition - 2009-02-12
ISBN 978-1-894049-23-8
Copyright © Crane Softwrights Ltd.