Minutes of UBL Customization discussion, 8-9 May 2007

[jon.bosak@sun.com]

##################################################################
UBL CUSTOMIZATION DISCUSSION (MANHATTAN, MAY 2007)
##################################################################

This is an annex to the minutes of the UBL meeting held 7-11 May
2007 in Manhattan.  See

   http://lists.oasis-open.org/archives/ubl/200705/msg00018.html

The discussion began 8 May with the consideration of a set of
slides prepared by UBL NDR editor Mike Grimley and posted at

   http://www.oasis-open.org/committees/download.php/24099

In the following, each slide is discussed separately, and the
decisions made are generally stated as directions to the NDR
editors.

==================================================================
Definitions: Customization
==================================================================

[8 May:] Accept the definitions.

[9 May, revisiting this slide:] "A UBL customization is a
specialization of UBL for a user community."

Add an explanation of meaning constraints, etc., independent of
the technology.

==================================================================
Definitions: Conformance
==================================================================

First bullet: Accepted.

Second bullet: Change to reflect the understandings recorded in
the minutes of the UBL TC meeting 15 August 2006:

   http://lists.oasis-open.org/archives/ubl/200608/msg00056.html

In particular, the following:

   It's an error to think of UBLVersion as a report about the
   system generating the instance, because a "UBL 2.7 system" is
   still perfectly capable of generating an instance that uses
   elements defined no later than 2.3, say (and in an environment
   with lots of different trading partners, this will not be
   unusual).  Rather, the value of the UBLVersion element (if it
   has a value) is a claim by the originating system that the
   instance will validate against any UBL schema whose minor
   version number (within the indicated major range) is equal to
   or greater than the value given by UBLVersion.  So a UBLVersion
   value of 2.3, for example, does not mean "I come from a UBL 2.3
   system" but rather "I claim to be valid against any UBL schema
   from release 2.3 up to the latest major version 2 release"
   (because we define a minor version update as one that adds only
   optional elements).  Or, to put it another way, it says "I
   guarantee that you will find no elements in here defined later
   than the ones found in version 2.3." The same applies to the
   elements for profile version and subset version.

   It should be noted that the version number when applied to a
   receiving system means something different.  The expression "a
   UBL 2.3 system" means (or should mean) "a system that's been
   set up to validate incoming instances against a UBL 2.3
   schema."

Third bullet: Drop all references to "ubl-open" (not because it's
an invalid concept but because it's not needed to motivate the
rest of the customization methodology).

==================================================================
Definitions: Compatibility
==================================================================

Beyond the definition in the slide, compatibility means:

 - You can make new qualified data types based on UBL qualified
   data types or UN/CEFACT unqualified data types.

 - You must use literally the same vocabulary for items that
   already exist in standard UBL -- that is, don't invent new
   terms for existing items -- and reuse of standard items should
   take place at the highest level possible for maximum
   interoperability.

 - You must use the UBL naming and design rules.

Note that if new items are added to an existing document type
only in the extension area, instances validating against the
extended schema are still UBL conformant (not just UBL
compatible).

MarkC/MikeG/KenH: When you contextualize a BBIE, then by
definition it is based on a base type, reapplying it in a new
context; since the difference is strictly a contextualization, the
result is compatible.

==================================================================
When to Customize
==================================================================

No comments.

==================================================================
Context Methodology
==================================================================

For subbullet under second bullet: 

   CCTS 2.01 context drivers have been provided for the current
   UBL business information entities.  This is part of ongoing
   work, and as yet the necessary methodology to achieve this
   level of automation has not been developed.

Eliminate the list of context drivers at the bottom of the slide.

==================================================================
How to Customize
==================================================================

No comments.

==================================================================
Designing for Customization
==================================================================

Call this "Approaches to Customization."  Content:

   Designing a customization may involve:

    - Adding information items to meet contextual requirements

    - Omitting information items not needed in this context

    - Refining the meaning of information entities

    - Qualifying the data type of information entities

    - Combining (or recombining) and assembling information
      entities into new aggregations or documents

Remove the bottom two bullets.

==================================================================
... Reusing UBL Patterns
==================================================================

Fix grammar of quote from CHIN Chee-Kai.

Second bullet: This means that if designers [etc.]

Omit third bullet.

==================================================================
... Qualification
==================================================================

Replace the second bullet with the following:

   If the new construct has the same structure as the old
   construct, the qualified name points to the old type.  The
   qualifying terms themselves should describe the role of the
   re-used information entity in the association.

   If the new construct is different from the old construct, the
   new construct includes the old construct as a child.  The new
   construct has a new name, not a qualified name.

   The other children of the new construct are the additional
   information items needed to describe the new construct.

Omit the third bullet (it's included above).

==================================================================
... Restriction/Subsetting
==================================================================

"Approximately 50,000 elements" should read "approximately 800,000
elements" (not counting recursion).

For the third bullet:

   Subsetting involves some combination of (a) removing from the
   model any optional information entities that are not needed to
   satisfy business requirements and (b) adding constraints needed
   to meet business requirements, e.g., adding a code list or a
   length facet.

Use this later:

   In either case, the restriction may be accomplished either by
   removing items from the subset schema or by checking for their
   existence in the value validation phase.

Remove the example at the bottom of the slide (fourth bullet).

==================================================================
... Extension
==================================================================

Omit "There is a recognized requirement that" from first bullet.

Subbullets then read:

 - New aggregations created by the addition of new information
   entities to existing aggregations

 - Completely new aggregations

 - New associations [etc.]

Add to last bullet "such as adherence to CCTS."

==================================================================
... Value Constraints
==================================================================

Change "customizations" to "restrictions."

Then put the rest of this under Restriction/Subsetting.

(The discussion 8 May ended here and continued 9 May with the
following.)

==================================================================
Specifying Customizations: Versions, Subsets and Profiles
==================================================================

"Such as a namespace" should be "such as a URI."

Expand the example at the bottom: name all three NES profiles.

==================================================================
... The UBL Subset Scheme
==================================================================

First bullet:

   NES is an example of how a subset can be implemented without
   using XSD (it uses Schematron).

Plus some other minor changes not recorded (e.g. "schema" should
be plural).

==================================================================
... The UBL Extensions Scheme
==================================================================

Expand the final point into some guidelines (along with guidelines
for referencing).

==================================================================
... XSD Schema -- Extension Schema [two slides]
==================================================================

Replace the two slides on XSD extension with a discussion
(probably in an annex) of why we don't use XSD extension, and take
out the last two negatives in the second slide.

Then:

NO -- take out this whole discussion; these are guidelines for
making conformant instances.  [I.e., this isn't about
compatibility.]

==================================================================
... XSD Schema - Standalone
==================================================================

Change "customization schema" to "custom schema" throughout.

Update the language about available tools (no reference to 1.0).

Check with Chee-kai regarding a 2.0 version of UBLish.

==================================================================
Validating Customizations: XPath Files
==================================================================

At this point, the discussion continued with that part of G. Ken
Holman's paper "UBL 2.0 customizations, extensions, versions,
validation and interchange" relating to the validation of
customizations:

   http://www.oasis-open.org/committees/download.php/23654

Most of that discussion took place at the whiteboard; see

   http://www.oasis-open.org/committees/download.php/24102

Out of that discussion came the following...

##################################################################
PLAN FOR PRODUCING UBL 2.0 CUSTOMIZATION GUIDELINES
##################################################################

We will produce the following documents:

0. Customization Guidelines

   A. Customization for Conformance (example: NES)

      This document is to be based on the slides and commentary
      captured above.

   B. Customization for Compatibility (examples: Korean customs
      documents, Singaporean trade documents, Dutch criminal
      justice documents)

1. Case Studies in Customization (creating a custom schema)

   A. Implementing global (i.e., non-context-sensitive)
      constraints

      A subset is created simply by removing optional constructs
      from a standard UBL schema.  If done in a controlled way,
      proper subsetting is guaranteed without the need for
      independent verification.

      Example: USDOT TransportStatus.

   B. Implementing context-sensitive constraints

      A putative subset is created by some unspecified method (for
      example, regenerating schemas from modified spreadsheets)
      and then verified to be a proper subset by creating an
      exhaustive set of XPath files from the candidate schema and
      comparing it with the set of XPath files supplied as part of
      UBL 2.0.

      Example: Danish Invoice schema.

2. Interoperability through Input Filtering (this is the
   "Transform-before-validate process" in Holman's paper
   referenced above)

   A trading partner wishes to process UBL instances conforming to
   custom schemas (or minor versions) different from the version
   for which her software was designed.  Three different methods
   are described for transforming input documents into forms that
   will validate against the schemas resident in the system:

      Namespace-based transform-before-validate
      Name-based transform-before-validate
      Context-based transform-before-validate

3. Minor Versioning

   This is the namespace-based versioning scheme described in
   Holman's paper.  In the closing plenary, it was agreed that
   this methodology would be accepted if further investigation
   revealed no unforeseen problems.

##################################################################
WRITING ASSIGNMENTS
##################################################################

From the closing plenary, already reported in the minutes of the
meeting and copied here for reference:

   ACTION: TM to write section on Guidelines for Compatibility,
   draft to NDR editors by mid-August.

   ACTION: JB to write up GKH's subset generation, subset
   verification, and processing model proposals for inclusion in
   the Guidelines, draft to NDR editors by mid-August.

   ACTION: NDR editors MG and MC to write "Guidelines for
   Customization" based on this week's review of MG's slides and
   input from TM and JB; draft due 1 September for discussion at
   the UBL TC meeting in Stockholm.