Proposed additions to the common library for DocumentReference

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

Fellow UBL Pre-award members,

This post captures the results of a discussion just held between 
Oriol and me regarding a possible approach to satisfying two new 
information requirements regarding document referencing:

 - identifying packages of documents

 - specifying activities expected to be performed with documents

Regarding packaging, we considered one way and then ended up drawing 
parallels with the grouping of item properties.  Historically, 
grouping has often been done "top-down", as in a file system, with 
subdirectories or folders containing subdirectories or folders.  More 
recently (I first saw this deployed in a major way with Google Drive) 
information organization has tended to be "bottom-up", using 
collections.  In a top-down orientation, there is only ever one path 
to a given resource.  In a bottom-up orientation, a given resource 
might be a member of multiple collections.

For example, in a tender, a picture of a chair might be used twice in 
a submission, once in the description of what is used to furnish a 
one-person cubicle, and again in the description of what is used to 
furnish a two-person cubicle.  The tender could refer to two 
different packages, and the document reference to the photograph 
identifies itself to be part of both packages.  When the recipient is 
gathering the resources for a given package, they walk through all of 
the resources identifying the package each is in.

A top-down orientation would end up with two copies of the chair 
picture, or some convoluted method (needing dereferencing) of 
pointing and/or including document reference references.

As I alluded above, we have a precedent, for the bottom-up approach 
in the way we deal with item properties.  A given item has item 
properties and each property identifies the zero-or-more groups in 
which that property belongs:

http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_ItemProperty.Details

We achieve the same flexibility using this approach for document 
references being members of a document package.  As I type this 
(without Oriol around) I'm thinking we could call this 
"DocumentGroup" as well (instead of "DocumentPackage"), since the 
same principle is being used for "ItemPropertyGroup".  So I've 
changed the name in the suggestion below without consulting Oriol, so 
Oriol can correct me if this is inappropriate.  I'm just trying to 
reuse the UBL use of words.  Users can be told that their packages 
are described in UBL as groups.

<cac:DocumentReference>

  ...

  <cac:DocumentGroup> 0..n  ABIE (new): DocumentGroup

    <cbc:ID> 1

    <cbc:Name> 0..1

    <cbc:VersionID> 0..1

    <cbc:PublicationDate> 0..1

    <cac:DocumentGroupReference> 0..n ABIE (new): DocumentGroupReference

       <cbc:GroupReferenceID> 1

Forgive me, Oriol, but my notes were incomplete regarding the 
proposed <cac:DocumentGroupReference> ASBIE ... how was that going to 
be used?  Was that for groups within groups?

Regarding describing the actions to perform on documents, we 
discussed the importance of keeping any new information added to UBL 
as declarative, rather than procedural.  It is up to a community of 
users to agree upon procedures to perform with documents, it is not 
up to the UBL instance to encode the procedural steps (we would never 
be able to describe all procedures and their properties formally to 
satisfy all users, nor appear biased to any given user).  It is also 
a long-standing XML issue of declarative vs. procedural, the 
challenge of describing ordinal steps using declarative syntax.

So, to remain declarative, we ended up agreeing upon allowing the 
document reference to have any number of requested actions, a new 
ASBIE pointing to a new ABIE of Action.  The action can be 
parameterized by using arbitrary item properties about the action.

<cac:DocumentReference>

  ...

  <cac:DocumentRequestedAction> 0..n  ABIE (new): Action

    <cbc:ID> 0..1

    <cbc:Name> 0..1

    <cbc:ActionCode> 1

    <cac:ActionItemProperty> 0..n ABIE (existing): ItemProperty

        <cbc:Name> 1

        <cbc:Value> 0..1

        (all the other existing bits)

With that, a community of users can agree upon an arbitrary number of 
actions (identified by their code) and an arbitrary number of 
parameters (identified by their name in name/value pairs), and then 
constituents can specify which agreed-upon actions are requested to 
be performed on the documents being referenced.  We don't have to 
cater to any one group's particular actions, and so we remain declarative.

I agreed to capture our thoughts in a post for general discussion ... 
I did not mean to forget what was meant by one of the items, so I'll 
leave that for Oriol to describe.

. . . . . . . . . Ken

--
Check our site for free XML, XSLT, XSL-FO and UBL developer resources |
Free 5-hour lecture:  http://www.CraneSoftwrights.com/links/video.htm |
Crane Softwrights Ltd.             http://www.CraneSoftwrights.com/o/ |
G. Ken Holman                    mailto:gkholman@CraneSoftwrights.com |
Google+ profile:       http://plus.google.com/+GKenHolman-Crane/about |
Legal business disclaimers:     http://www.CraneSoftwrights.com/legal |


---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus