Re: [ubl-dev] ExtensibleContent

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

At 2007-10-31 18:18 +0100, Kristian Berge Nessa wrote:
>We are currently implementing a system for the storage and exchange of
>electronic invoices in Norway, called "Fakturabank". For the transmission of
>invoices we have decided to use NES-UBL - and thus, indirectly, UBL.

Great!

>Upon reviewing the danish OIOXML standard, we found some extensions to UBL
>which could have been useful for this application, for example:
>  * ExtensibleContent
>  * EncodedDocument
>
>Browsing the list archives I've found that the inclusion of at least
>ExtensibleContent have been up for discussion before, however I cannot seem
>to find a conclusion:
>   http://www.oasis-open.org/archives/ubl/200602/msg00099.html
>   http://www.oasis-open.org/archives/ubl/200602/msg00015.html
>
>So, what is the status on this? More specifically, will this or some
>equivalent feature find its way into UBL-2.1?

It is already in UBL 2.0 under the name <UBLExtensions>, which is the 
first child of the document element of every UBL 2.0 document 
type.  This, in turn, has multiple <UBLExtension> elements, each for 
a particular domain of use (thus, one instance can support multiple 
extensions if it is going to be used in multiple domains).

There are a number of optional meta data attributes for a 
<UBLExtension> element, but all that is required is the element 
<ExtensionContent> under which you place a single element in a 
non-UBL namespace of your choosing.

This element then contains all of your extended information, which 
may of course use standard UBL library elements if the business 
objects that make up your extension are already standardized.  You 
wouldn't use the extension point just to put an already-standardized 
UBL concept all alone ... that's why you have UBL there in the first place.

>These are some of our use cases:
>1) Possibility to represent and store structured customer-specific and
>system-specific data attached to invoices on both Invoice and InvoiceLine
>level.
>2) Meta-information concerning the processing state of an invoice, i.e:
>    - Has this invoice been forwarded to the client's accounting system?
>    - Has a reminder of a passed duedate been sent?
>    - Does this invoice have attachments? etc.

These are perfect examples of using the extension point to collect 
supplemental information not standardized by UBL.

There are different strategies for deciding how to structure the 
information under the extension point, each with pros and cons ... 
I've participated in committee discussions where we have considered 
many ways to handle each given piece of non-UBL information under the 
extension point:

  (1) - an extension item of a global nature relative to the entire document
        and standardized information stands alone under the extension point

  (2) - an extension item relating to only a portion of the standardized
        information (say a line entry) could live two different ways under
        the extension point:

  (2a) - the item stands alone under the extension point and references
         the line entry through some mechanism of document referencing
         - possibly ID/IDREF
         - possibly contextual ancestry (suitable for XPath processing)
       - pro: no duplication of information
       - con: referencing/de-referencing needs extra work

  (2b) - the entire line entry is copied under the extension point, wherein
         one finds the extension item as a descendant of line entry
         information, using a different XML name for the line entry (because
         it has a different definition than the standardized line entry)
       - pro: item found easily in the context of other line entry information
       - con: the standardized line entry information is copied twice in
              the instance: once in the standardized location, and once in
              the customized line entry under the extension point
       - con: is the information guaranteed to be consistent?
       - con: has the document creator been rigourous in maintaining all
              standardized information items where available?

  (3) - define an entire XML document with customized XML element names
        whereby the entire document represents a compatible (based on UBL
        business objects) but not conformant (because it isn't using the same
        XML names) for the entire invoice under the extension point, while
        simultaneously creating a UBL instance for use in the standardized
        locations with the standardized vocabulary
      - pro: the entire extended instance is self contained and whole,
             reflecting all possible contextual issues
      - pro: the UBL subset of the instance is self contained and compatible
      - con: the standardized information is copied twice in the instance:
             once in the standardized locations, and once in the customized
             elements under the extension point
      - con: is the information guaranteed to be consistent?
      - con: has the document creator been rigourous in maintaining all
             standardized information items where available?

While I have already incorporated these approaches in my training 
material, the committee is including these thoughts and any more 
thoughts we receive in divining what guidance material can be written 
that will be made public.

Personally, I do not like the duplication, so personally I would go 
for (1) and (2a) and if I had to I would live with (2b) if I couldn't 
have (2a).  But there are those on the committee who wholeheartedly 
support (3) and will live with (2b) if they can't have (3).

I wouldn't say either approach is "right" or "wrong", they just both 
reflect two ways of considering how to describe extended information 
in a way that is meaningful to the recipient.  I think XML'ers (like 
myself) prefer (1) and (2a) because the XML vocabulary seems "whole", 
whereas information modelers might prefer (3) and (2b) because then 
the model seems "whole" and they regard the actual XML syntax as a 
necessary evil to have to deal with with secondary import.

All this is an interesting discussion and yet to be tried and tested 
in live implementation with metrics for complexity, ease of 
deployment, documentation, and ensuring consistent practice.

There is *always* a risk with an extension point that it will be 
abused.  There was a lot of push-back when it was first 
proposed.  There was worry that it would be mishandled and thus 
render the standardization of the UBL bits irrelevant.

But as I see it, the UBL bits are mandatory where they exist, and the 
extension point is to be used solely for business objects not already 
standardized.

The common thread is that a recipient of a document with extensions 
can always find the body of the information in the UBL standardized 
bits and the extension has the icing on top and only needed by those 
who are interested to have it.  Those who aren't interested should be 
able to work with the standardized bits.  The variability comes when 
thinking of how to represent the extended bits under the extension point.

Of course a community of users can mandate the use of their 
extension, such that business rules would reject a UBL instance if it 
conformed to standardized document schemas but did not include the 
extension expected by the community.  But, would that support 
interoperability in a serendipitous interchange where someone in the 
community receives a bona fide instance from an outsider that happens 
not to have provided the extension content?  I think that is a missed 
opportunity, and that the extension information should always be optional.

I hope this is considered helpful.  I hope that others will chime in 
with their own ideas on this issue.

. . . . . . . . . . . . . . . Ken


--
Comprehensive in-depth XSLT2/XSL-FO1.1 classes: Austin TX,Jan-2008
World-wide corporate, govt. & user group XML, XSL and UBL training
RSS feeds:     publicly-available developer resources and training
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/u/
Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
Male Cancer Awareness Jul'07  http://www.CraneSoftwrights.com/u/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal