Customization DiscussionRevised 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.• 0..1 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 1..1• 1..1 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

NBWavelength 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.