Re: [ubl] [OASIS Issue Tracker] (UBL-168) Definitions and cardinality in DocumentReference ABIE

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

At 2018-02-05 14:27 -0500, you wrote:
> Sorry to jump in here after not following the discussion, but I
> find this list somewhat startling.

No apology necessary!  The input is welcome at any time and we, as a 
committee, need to be challenged to defend our decisions in 
situations such as these.  Thank you for speaking up!

> One of the big achievements of
> 2.1 was the provision of meaningful definitions rather than
> mindless repetitions of the name using slightly different
> words.

Indeed.  But we examined the semantic description of these particular 
elements after it was determined by users (actually, me in an 
implementation role) to be ambiguous and misleading.

We agree one cannot go arbitrarily changing the semantics, but when a 
semantic description is inaccurate or can be clarified for the users, 
we are proposing its change.

> When you go from
>
> 678 CopyIndicator An indicator that the referenced document is a
> copy (true) or the original (false).
>
> to
>
> 678 CopyIndicator The copy indicator of the referenced document.
>
> you're not saying much more than "the CopyIndicator is the copy
> indicator."

In the discussion it was felt the original "an indicator" opened up 
the possibility of the user creating something new rather than 
transcribing into the field the actual indicator value obtained from 
the document being referenced.  So by using "the" instead of "an", 
hopefully this conveys that there exists an indicator already and a 
new one cannot be determined.

Hopefully each document that is referenced has the same semantic 
meaning for the copy indicator, but it isn't the place for the 
document reference to redefine what the meaning is of the copy 
indicator that is being extracted from the referenced document.

It was felt, then, that this new wording conveys the original 
semantic of "a transcription into the document reference of an 
element value from the referenced document".  And so also for the 
first five elements in the list, this wording has been used.

The only other definition refined is for XPath because the original 
is inaccurate.  The XPath value is an address (slightly different 
than an arbitrary reference) and the use of the word "another" has no 
bearing on any kind of "other" in the first place.  It was thought 
the word "specific" would be better than "another".

Not all of the rows listed have had their definitions replaced ... 
they were included in the ticket so that the reader need not have to 
go to the model to compare the new wording with what is there.

> What's the point of losing the semantic content we worked so hard
> to put in? If the idea is to comprehend instances that don't fit
> into the original definition, then you'll have to invent a new
> data item with those new semantics; you can't go monkeying with
> the definition that's already out there. And if you're going to do
> that, why rob the original of its specific meaning?

Very few definitions have been touched in this go-around.  These 
particular definitions were addressed based on my trying to use the 
ABIE in a real-world application where I am transcribing the document 
information.  I challenged the others on the committee regarding the 
ambiguous definitions as I read them.

Note that there are still documentation shortcomings in the 
model.  For example, for the ABIEs:

  DeliveryChannel     A class to describe a delivery channel.
  DeliveryUnit        A class to describe a delivery unit.

I am negotiating with a college for a student seniors' project to 
examine the 350 ABIE definitions and propose back to the UBL public 
comment list candidate definitions to help the user understand what, 
say, a delivery channel actually is.  I will be giving the student 
project team the parameters of what we would find useful in a 
submission and their professors will assess them on their completion 
of a submission to the public comment list.  They won't be assessed 
on whether or not we decide their proposals are better than what we 
have.  But we then have the flexibility to leverage their efforts if 
we can improve on the documentation.  The curriculum is a business 
programme and so doing the research into the semantics of each of the 
ABIEs as defined by their BBIEs and ASBIEs is considered relevant to 
their studies ... plus they get introduced to international standardization.

Thanks for this input, Jon!  I hope I have allayed any 
concerns.  Please do not hesitate to continue to challenge us on this 
or any other issue.  Your committee credentials will get you into the 
JIRA system where your comments on any of the tickets will be most welcome.

. . . . . .  Ken

> Jon
>
> On Mon 5 Feb 2018 2:10 PM, OASIS Issues Tracker wrote:
> >     [ 
> > <https://issues.oasis-open.org/browse/UBL-168?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=68934#comment-68934>https://issues.oasis-open.org/browse/UBL-168?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=68934#comment-68934 
> > ]
> >
> > Ken Holman edited comment on UBL-168 at 2/5/18 7:10 PM:
> > --------------------------------------------------------
> >
> > After discussion during the teleconference the following is 
> > proposed for accuracy and consistency:
> >
> > Old:
> >
> > 677 ID An identifier for the referenced document.
> > 678 CopyIndicator An indicator that the referenced document is a 
> > copy (true) or the original (false).
> > 679 UUID A universally unique identifier for this document reference.
> > 680 IssueDate The date, assigned by the sender of the referenced 
> > document, on which the document was issued.
> > 681 IssueTime The time, assigned by the sender of the referenced 
> > document, at which the document was issued.
> > 682 DocumentTypeCode The type of document being referenced, 
> > expressed as a code.
> > 683 DocumentType The type of document being referenced, expressed as text.
> > 684 XPath A reference to another place in the referenced document
> > 685 LanguageID An identifier for the language used in the 
> > referenced document.
> > 686 LocaleCode A code signifying the locale in which the language 
> > in the referenced document is used.
> > 687 VersionID An identifier for the current version of the 
> > referenced document.
> > 688 DocumentStatusCode A code signifying the status of the 
> > reference document with respect to its original state.
> > 689 DocumentDescription Text describing the referenced document.
> >
> > New:
> >
> > 677 ID The identifier of the referenced document.
> > 678 CopyIndicator The copy indicator of the referenced document.
> > 679 UUID The universally unique identifier of the referenced document.
> > 680 IssueDate The issue date of the referenced document.
> > 681 IssueTime The issue time of the referenced document.
> > 682 DocumentTypeCode The type of the referenced document, expressed 
> > as a code.
> > 683 DocumentType The type of the referenced document, expressed as text.
> > 684 XPath An address to a specific place in the referenced document.
> > 685 LanguageID An identifier for the language used in the 
> > referenced document.
> > 686 LocaleCode A code signifying the locale in which the language 
> > in the referenced document is used.
> > 687 VersionID An identifier for the current version of the 
> > referenced document.
> > 688 DocumentStatusCode A code signifying the status of the 
> > referenced document with respect to its original state.
> > 689 DocumentDescription Text describing the referenced document.
> >
> > Not discussed is a question regarding line 688 "DocumentStatusCode" 
> > ...what is meant by "with respect to its original state"?  Can this 
> > phrase be removed or improved?
> >
> > It is agreed that the cardinality of line 677 ID should be "0..1" 
> > and not "1" because not all documents that can be referenced will 
> > have an ID (e.g. CallForTenders).
> >
> > (note that all row numbers above are from the UBL 2.1 model)
> >
> >
> > was (Author: gkholman):
> > After discussion during the teleconference the following is 
> > proposed for accuracy and consistency:
> >
> > Old:
> >
> > 677 ID An identifier for the referenced document.
> > 678 CopyIndicator An indicator that the referenced document is a 
> > copy (true) or the original (false).
> > 679 UUID A universally unique identifier for this document reference.
> > 680 IssueDate The date, assigned by the sender of the referenced 
> > document, on which the document was issued.
> > 681 IssueTime The time, assigned by the sender of the referenced 
> > document, at which the document was issued.
> > 682 DocumentTypeCode The type of document being referenced, 
> > expressed as a code.
> > 683 DocumentType The type of document being referenced, expressed as text.
> > 684 XPath A reference to another place in the referenced document
> > 685 LanguageID An identifier for the language used in the 
> > referenced document.
> > 686 LocaleCode A code signifying the locale in which the language 
> > in the referenced document is used.
> > 687 VersionID An identifier for the current version of the 
> > referenced document.
> > 688 DocumentStatusCode A code signifying the status of the 
> > reference document with respect to its original state.
> > 689 DocumentDescription Text describing the referenced document.
> >
> > New:
> >
> > 677 ID The identifier of the referenced document.
> > 678 CopyIndicator The copy indicator of the referenced document.
> > 679 UUID The universally unique identifier of the referenced document.
> > 680 IssueDate The issue date of the referenced document.
> > 681 IssueTime The issue time of the referenced document.
> > 682 DocumentTypeCode The type of the referenced document, expressed 
> > as a code.
> > 683 DocumentType The type of the referenced document, expressed as text.
> > 684 XPath An address to a specific place in the referenced document.
> > 685 LanguageID An identifier for the language used in the 
> > referenced document.
> > 686 LocaleCode A code signifying the locale in which the language 
> > in the referenced document is used.
> > 687 VersionID An identifier for the current version of the 
> > referenced document.
> > 688 DocumentStatusCode A code signifying the status of the 
> > referenced document with respect to its original state.
> > 689 DocumentDescription Text describing the referenced document.
> >
> > Not discussed is a question regarding line 688 "DocumentStatusCode" 
> > ...what is meant by "with respect to its original state"?  Can this 
> > phrase be removed or improved?
> >
> > It is agreed that the cardinality of line 667 ID should be "0..1" 
> > and not "1".
> >
> > > Definitions and cardinality in DocumentReference ABIE
> > > -----------------------------------------------------
> > >
> > >                 Key: UBL-168
> > >                 URL: 
> > > <https://issues.oasis-open.org/browse/UBL-168>https://issues.oasis-open.org/browse/UBL-168
> > >             Project: OASIS Universal Business Language (UBL) TC
> > >          Issue Type: Bug
> > >          Components: Documents and business objects
> > >            Reporter: Ken Holman
> > >            Assignee: Ken Holman
> > >            Priority: Minor
> > >
> > > In DocumentReference ABIE there are three definitions that I think 
> > > can be repaired/improved and I think we need to change one cardinality.
> > > Looking at the model at 
> > > <http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_DocumentStatus>http://docs.oasis-open.org/ubl/os-UBL-2.1/mod/summary/reports/UBL-AllDocuments-2.1.html#Table_DocumentStatus 
> > > I note the row definitions copied below where I've added an 
> > > asterisk to indicate old and proposed new definitions:
> > > 677* ID An identifier for the referenced document.
> > > 677* ID The identifier of the referenced document.
> > > 678  CopyIndicator An indicator that the referenced document is a 
> > > copy (true) or the original (false).
> > > 679* UUID A universally unique identifier for this document reference.
> > > 679* UUID The universally unique identifier of the referenced document.
> > > 680  IssueDate The date, assigned by the sender of the referenced 
> > > document, on which the document was issued.
> > > 681  IssueTime The time, assigned by the sender of the referenced 
> > > document, at which the document was issued.
> > > 682  DocumentTypeCode The type of document being referenced, 
> > > expressed as a code.
> > > 683  DocumentType The type of document being referenced, expressed as text.
> > > 684* XPath A reference to another place in the same XML document 
> > > instance in which DocumentReference appears.
> > > 684* XPath A reference to another place in the referenced document
> > > 685  LanguageID An identifier for the language used in the 
> > > referenced document.
> > > 686  LocaleCode A code signifying the locale in which the language 
> > > in the referenced document is used.
> > > 687  VersionID An identifier for the current version of the 
> > > referenced document.
> > > 688  DocumentStatusCode A code signifying the status of the 
> > > reference document with respect to its original state.
> > > 689  DocumentDescription Text describing the referenced document.
> > > So I think the UUID definition is just wrong and the XPath 
> > > definition can be made more consistent with the other 
> > > definitions.  As for the ID definition, the nuance is that it 
> > > cannot just be "an identifier for the referenced document" that 
> > > might be interpreted to be created anew, I believe it is supposed 
> > > the be "the identifier of the referenced document" that is found 
> > > inside. Certainly I'm assuming that for the CopyIndicator, UUID, 
> > > IssueDate and IssueTime and so should be the same for ID. Edited 
> > > to make the same observation about the UUID definition.  I believe 
> > > the five items are meant to be copied from the referenced document 
> > > and not created anew.
> > > Regarding cardinality, the ID cardinality is "1" and I think we 
> > > must change it to "0..1" because not all UBL documents have an ID 
> > > and I am in a project where I do not want to expose the ID of the 
> > > original document in the document status (I'm using the UUID in my 
> > > project because exposing the ID might expose business information 
> > > to the public; in my project the document is private but the 
> > > document status is public).
> > > I haven't gone through all the UBL documents but I note in the 
> > > first few alphabetically arranged document types the 
> > > AwardedNotification and the CallForTenders documents do not have a 
> > > mandatory ID.  If the original document doesn't have the ID, then 
> > > what goes into the DocumentStatus ID since it cannot be empty by 
> > > one of UBL's additional document constraints?
> > > I think these are important fixes.


--
Contact info, blog, articles, etc. http://www.CraneSoftwrights.com/o/ |
Check our site for free XML, XSLT, XSL-FO and UBL developer resources |
Streaming hands-on XSLT/XPath 2 training class @ US$45 (5 hours free) |