UBL 2.1 PRD2 modeling issues from SGTG

[Jon Bosak <bosak@pinax.com>]

Hello UBL TC,

Ken Holman has left both PSC and TSC with two modeling issues that we've
known about for quite a while and haven't yet addressed.  See

    http://lists.oasis-open.org/archives/ubl/201102/msg00026.html

First, there are 14 occurrences of non-ASCII characters in the models.
These are reported in Ken's analysis and should be fixed.  That's the
easy issue.

Second, there are many instances of what Ken calls "tautological
definitions."  I never thought of them that way, but I certainly did
think that many were empty definitions.  His example is:

    "Waybill. Shipment" :An association to Shipment.

As Ken correctly observes, this "tells the reader nothing at all and so
isn't a good definition."

On looking over the list in Ken's report that (arbitrarily) flagged all
definitions shorter than six words, I see these short definitions
falling fairly easily into one of just a few categories.

First are definitions that just happen to be short.  Examples:

    "Address. Building Name. Name" :The name of a building.

    "Budget Account. Details" :Information about the budget
    account.

There's actually not much more to say about these items, so they seem to
me to be reasonable short definitions.

Some definitions are correct but could use more detail, e.g.,

    "Allowance Charge. Amount" :The Allowance Charge amount.

    "Budget Account Line. Identifier" :Identifies a Budget Account Line

There's a lot of this bare-bones kind of definition, and a lot of room
for improvement, but there will always be room for improvement in
explaining these items, and the task of adding more detail is resource
constrained and somewhat open-ended.  So while I think there's work that
can and should be done in this category for PRD2, I don't see these
entries as actually broken.

Finally, however, there are a large number of definitions that are
"tautological" in the sense that they just don't seem to be saying
anything.  In every case that I have found, these are definitions of
ASBIEs, and they all have the form seen in

    "Catalogue. Trading Terms" :An association to trading terms.

    "Consumption Line. Delivery" :An association to delivery.

    "Debit Note Line. Item" :An association to Item.

and so on.  In most of these cases, the problem can be formally
corrected with a simple rewrite to lose the "association to" formula,
like this:

    "Catalogue. Trading Terms" :Trading terms associated with this
    Catalogue.

    "Consumption Line. Delivery" :Delivery information associated
    with this Consumption Line.

    "Debit Note Line. Item" :Item associated with this Debit Note
    Line.

These could be further improved by using the definite and indefinite
articles to distinguish cardinality; for example (I'm making up these
cardinalities):

    "Catalogue. Trading Terms" :The set of trading terms associated
    with this Catalogue.

    "Debit Note Line. Item" :One of the items associated with this
    Debit Note Line.

I would expect to find in many of these cases that some further
information is needed to make a really satisfactory definition, but this
simple transformation is a good place to start.

There are a few cases that will resist this transformation, e.g.:

    "Credit Note. Statement_ Document Reference. Document
    Reference" :An associative reference to Statement.

Such pathological cases will require a genuine rewrite in more detail,
but I'm hoping that they're relatively rare.

Ken's leave of absence has given us the perfect opportunity to go
through the definitions and improve them.  Yes, it's an open-ended task,
but we've been ignoring some real problems here for a long time, and
it's not going to get any easier to fix them.  I am certain that a
couple of weeks of effort invested in this will make a very substantial
improvement to the UBL document models, and I propose to the PSC and the
TSC that they undertake this as their final project for PRD2.

I'm putting this on the agenda for this week's UBL TC calls to discuss
it further.

Jon