Definitions of the Description element

[jon.bosak@sun.com]

For background, see

   http://lists.oasis-open.org/archives/ubl/200711/msg00025.html

Summary: The JPLSC raised questions regarding the definition of
"Description" in the Catalogue document.  The current definition of
Catalogue. Description. Text is:

-   A description of the catalogue.

The improved definition reported in the message referenced above
is:

-   Text that further describes what the catalogue is.

Now that I'm in the process of implementing revisions for the
Update Package, I see two problems with this reformulation.

1. The improved definition adds nothing to the original one, it
   just uses more words.  (It could be argued that the word
   "further" adds something to what would be found in any ordinary
   English dictionary definition of the word "description" because
   it suggests that the contents of the Description field add
   information to some other description of the Catalogue document
   that will be found elsewhere in the same document, but I don't
   know what that other description would be.)

2. If this definition is a problem in Catalogue, then it's a
   problem in the other 10 documents that have a Description
   element as well.  Here are all 11 UBL 2.0 documents that
   contain a Description element together with the definition of
   that element as currently given in each (the definitions have
   been extracted from the xsd files to save time):

      BillOfLading: Purpose of the document instance.

      Catalogue: A description of the catalogue.

      CatalogueDeletion: Describes the Catalogue Deletion.

      CatalogueItemSpecificationUpdate: A description of the
         Catalogue Revision.

      CataloguePricingUpdate: Describes the Catalogue Revision.

      CatalogueRequest: Describes the Catalogue Request.

      CertificateOfOrigin: Textual description of a Certificate Of
         Origin.

      ForwardingInstructions: Description of the type of
         Forwarding Instructions.

      PackingList: Textual description of a Packing List.

      TransportationStatus: Textual description of a status
         message.

      Waybill: Textual description of a Waybill.

   Some of the differences here make sense (apparently
   the thing being described in CatalogueItemSpecificationUpdate
   and CataloguePricingUpdate is not the document itself), but
   most of the rest of the variation appears to be random.

Unless there is some semantic reason for the variation I'm seeing
here, I would suggest the following revised definition of the
Description element in BillOfLading, Catalogue, CatalogueDeletion,
CatalogueRequest, CertificateOfOrigin, ForwardingInstructions,
PackingList, TransportationStatus, and Waybill:

-   Textual description of the document instance.

And this one for CatalogueItemSpecificationUpdate and
CataloguePricingUpdate:

-   Textual description of the catalogue revision.

Note the lowercase treatment of "catalogue revision."  If there is
some information entity named CatalogueRevision, I'm not seeing
it, and if in fact there is no such entity, then I suspect that
"catalogue revision" should be lowercased throughout.

Jon