Customization Discussion Revised 29 August 2007

Guidelines for Customization Introduction Design For conformance For compatibility Specification Using UBL 1.0 Context Methodology Using Schema Subset Schema Using UBLExtension Using XPath Validation Identifying customizations Validating documents conform to the required model.

Definitions: Customization Customization: To alter something in order to better fit actual requirements. UBL Customization: The description of XML instances, or XML- based applications acting on those instances, that are somehow based on or derived from the UBL 2.0 specification. The goal is to maximize interoperability so that all parties understand the meaning of information in the documents being exchanged.

When to Customize Decision is whether to use UBL as-is or modify to satisfy additional requirements. Historically, businesses have not been given a satisfactory off-the-shelf solution. Although, for many, UBL will suit that need, there will still be those who have additional requirements that are not met. The decision is driven by real world needs balanced against perceived economic benefits.

Definitions: Conformance Instances: An XML instance is considered UBL conformant if there are no constraint violations when validating the instance against a published UBL schema. Systems: Producer The system will produce an instance that will validate against any UBL schema whose minor version number (within the indicated major range) is equal to or greater than the version to which the system claims conformance. Consumer The system will accept instances that validate against any UBL schema whose minor version number (within the indicated major range) is equal to or less than the version to which the system claims conformance.

Definitions: Compatibility To be consistent or in keeping with the principles behind UBL's models and/or their development. While we cannot expect automatic conformance and interoperability of these customized documents we can expect some degree of familiarity through the re-use of common patterns.

DESIGN

Design for Conformance All schema-valid instances of a conformant customization are simultaneously schema-valid instances of UBL. But not the other way around. Conformance design only allows for restrictions: Subsets of the document model. Constraints on document content.

Subsets of the Document Model If all information entities within a UBL Order were instantiated in a single document, we would find approximately 800,000 elements. Applications may not wish to process this massive structure. Subsets remove from the document model any optional information entities that are not needed to satisfy business requirements. Subsets cannot reduce the permitted minimum number of occurrences or extend the permitted maximum number of occurrences can become 1..1, or 0..0 (not used) 0..n can become 0..1, 1..n, or 0..0 (not used) 1..n can become cannot be restricted

Constraints on Document Content Some requirements involve additional constraints on the value space of information entities. "The Total Value of an Order cannot exceed $100,000“ "The Currency Code should be expressed using ISO 4217 codes". There may also be rules about dependencies between values of components "The Shipping Address must be the same as the Billing Address“ "The Start Date must be earlier than the End Date“ Code lists or enumerated lists of possible values are a common form of value constraints.

Designing for Compatibility All schema-valid instances of a compatible customization are not schema-valid instances of UBL. But may be the other way around. Compatible design only allows for extensions (supersets) Adding to the model any information entities that are needed to satisfy business requirements.

Design Criteria for Compatibility Re-use UBL Patterns: Re-use Information Entities. Re-use Datatypes. Use UBL principles for new BIEs: Normalize aggregates. Base on component model. Re-use patterns. Use ebXML CCTS. Use UBL NDR for any schema.

Possible Extensions New BBIEs Original Data Types New Data Types New ASBIEs New ABIEs By inclusion of UBL By association with UBL New document types New assemblies

New Document type New ABIE New BBIE (or ASBIE) The Customization Ripple Effect New Data Type Drop a change into any point and it ripples out NB Wavelength equates to precision of context of use.

A customized ABIE means creating a new ABIE. Customizing a BBIE creates a new ABIE Customizing a Data Type creates a new BBIE Customizing an ASBIE creates a new ABIE Any new ABIE means a new document type. The Customization Ripple Effect

The Atomic Rule The ripple effect creates “the Atomic Rule”… All UBL ABIEs must be treated as if each is a single, indivisible entity, conveying its unique structure, assigned meanings and identity as described by its schema. This applies recursively down through each and every constituent ASBIE, BBIE, and Data Type used. Applications must know what to expect. e.g. A UBL “Address” is always the same structure.

Re-using ABIEs by Association If the required aggregation has the same structure as an existing ABIE. New Association (ASBIE) with the existing ABIE. Just different context of use. Use qualifying terms to describe the role. For example, Address Re-used in contexts such as Postal_ Address, Delivery_ Address, and Pickup_ Address. Postal_, Delivery_, and Pickup_ are qualifying terms. All the same structure for Address.

Qualification of Names The ebXML Core Component Technical Specification supports the idea of qualifying the Property Terms of Dictionary Entry Names as a means of indicating a context of use. The qualifying terms should describe the role of the BIE.

Extending ABIEs by Inclusion If the required aggregation is an extension of an existing ABIE: New Aggregate (ABIE) New ABIE has a new name not a qualified name. The new ABIE includes the extended ABIE as a child (by association). For example: Buyer Party is a new ABIE has a different structure to Party. The Party structure is re-used by inclusion in Buyer Party ABIE. Buyer Party also has additional BIEs. The name Buyer Party is not a qualification of the name Party.

Customizing Data Types Another form of re-use by association. Known as qualifying Data Types. Qualifying Data Types can re-use Unqualified Data Types. As defined by CCTS. Currency_ Code. Type is a restriction on the Code Data Type. Qualifying Data Types can also re-use other Qualified Data Types. European Currency_ Code. Type is a restriction on the Currency_ Code Data Type. Always use genericode for defining values of Data Types.

Creating Customized Document Models Assemble new pathways from customized model. Principles for document assembly... Choose entry point ABIE. Noting cardinality constraints… Assemble required BBIEs. Assemble required associations to other ABIEs. Proceed recursively through other ABIEs.

SPECIFICATION

Using UBL 1.0 Context Methodology Using Schema Subset Schema Using UBLExtension Using XPath Specify UBL customizations

Specifying Customizations: Context of Use ebXML CCTS Context Based on the premise that by using formalized classification taxonomies (context drivers) will allow automatic identification of context. Context drivers have been provided for the current UBL BIEs. This is part of ongoing work, and as yet the necessary methodology to achieve this level of automation has not been developed.

UBL 1.0 Context Methodology Based on W3C Schema Derivation Ensures backwards compatibility Relatively straightforward Supports inheritance Maintains semantic lineage my:NewParty extends cac:Party my:NewParty is a cac:Party

Issues with Context Methodology Unable to declare derivatives of the extension point Unable to express different enumeration restrictions based on context Unable to express co-occurrence constraints Unable to elide optional elements through derivation Unable to maintain UBL conventions using XSD extension

Specifying Customizations: W3C XML Schema Generate new schemas. Edit a model representation and translate the model into a schema expression GEFEG.FX by GEFEG mbH UBLer by Invinet Systems UBLish (UBL inter-schema helper) by SoftML Adhere to UBL NDRs Create new schemas. Edit an existing UBL schema either by hand or by a program "Simplified UBL schema customization" (Crane Resources)

Specifying Customizations: UBLExtensions Provided as a means of specifying (at a schema level) extensions to the document model without affecting UBL conformance. A placeholder for extensions. Has no inherent constraints. Uses xsd:any UBLExtensions content model should aim for UBL compatibility.

Content of UBLExtensions ‘ExtensionContent’ should contain a collection of the extended BIES required for the context of use. Extensions should never be used for information that may properly be conveyed in standard UBL patterns elsewhere in the document. Injudicious use will have damaging consequences for interoperability of documents.

Limitations with UBLExtension If there are embedded optional extensions. The instance of the document may not use the extension every time… And the values in the UBLExtension need to identify which parent they belong to. Example: Item may be extended to have Carbon Emission Rating. Not all items will have a rating. If the document has several items which ones do the Carbon Emission Ratings refer to.

Specifying Customizations: XPath A set of XPaths can express all of the possible combinations of XML hierarchy for the information items described by a document model. They can be generated from: XSD schemas XML instances UBL spreadsheets (or any spreadsheets describing content nesting and definition)

VERIFICATION

Identifying Customizations Profiles enable 'families' of customizations. For example, “Stand Alone Invoicing” may be a profile for the “Northern European Subset” customization. Meaning the requirements for stand alone invoicing in the northern European context. The following BBIEs allow instances to identify their customization specification: 'UBLVersionID' the UBL version being customized. 'UBLCustomizationID' an identifier (such as a namespace) for a specified customization of UBL. 'UBLProfileID' an identifier (such as a namespace) for a specified profile of the customization being used.

Validating Customizations: Subset Schema The UBL 2.0 Small Business Subset is one example of how a conformant subset may be specified through the use of a subset schema All instances of UBL 2.0 SBS are instances of full UBL 2.0 The UBL 2.0 SBS schemas are pruned copies of the normative UBL 2.0 schemas Research is underway to demonstrate the pruned schemas are provably correct proper subsets of the full schemas

Validating Customizations: XPath XPaths can be utilized to check for the presence of a given information item. An exhaustive proof of conformance and compatibility can be implemented using XPath files. An XPath file can be rigorously tested as being a proper subset of UBL by programmatically checking: all of the XPath entries of the subset are found in UBL. none of the mandatory items in the UBL are missing from the subset. An XPath file can be rigorously tested as being a proper superset of UBL by programmatically checking: none of the mandatory items in the UBL are missing from the superset.

Multi-Stage Validation A UBL schema defines UBL conformance. Other processes apply additional validation. Customized Document Model validation. Document Content validation. Pre-conformance processes Separate extensions. Post-conformance processes Validate restrictions. e.g. UBL Code List Value Validation methodology. Experience suggests we will evolve toward this approach.