Hello UBL 2.1 content providers, Many of you will recall my editorial review of the definitions in the UBL 2.1 PRD3 document models:
https://lists.oasis-open.org/archives/ubl-psc/201206/msg00001.html https://lists.oasis-open.org/archives/ubl-tsc/201206/msg00001.html I have just finally completed an initial editorial review of the definitions in the UBL 2.1 Common Library, and we can now begin to move this task toward completion. You can get the review version of the Common Library spreadsheet at
https://www.oasis-open.org/apps/org/workgroup/ubl/download.php/46900 Note that there are three files in this zip archive: an OpenOffice version, an Excel version (which for technical reasons is the one that I actually used for the review), and a PDF file containing a printout that I hope will work for people doing an initial read-through on paper. More about all this below, but note that the spreadsheet exists only for purposes of this review and is not a replacement for the version maintained in eDoCreator. I will begin with some background to the approach taken to the definition edits, and then give instructions for how I would like the subcommittee and stakeholder review to take place. Before I get to that, however, I want to emphasize the absolute need for a careful review by the teams that provided the 2.1 data models in the first place. You will find many places where questions have been posed that must be answered before we can continue, and obviously these will require close attention from the only people who can provide definitive answers to those questions; but nearly all of the definitions had to be modified in one way or another in order to regularize the language, and EVERY modification carries with it the risk that I have misunderstood the original definition in making the change. Thus, it is imperative that everyone involved in design of the models carefully review ALL of the revised definitions, not just the ones that I've flagged with specific questions. Now onward to some background explanation. 1. Approach to the definitions Here is an initial statement of the new approach I've taken in wording the definitions. I intend for some version of this to eventually end up in the hubdoc, probably in Appendix A. (No need to review this right now; it will be part of the overall document review. I'm including it here only by way of explanation.) /============================================================================ A Note Regarding the Definitions [The example used in the following will need to be revisited when final language is decided on for taxtotal.] Since the definitions for each of the 4000+ uniquely named data items in UBL 2.1 are normative, it is important that each be specified with the greatest care possible. However, there are two very different approaches that can be taken in accomplishing this objective. One approach, used more or less by default in UBL 2.0, is to give a definition for each item that correctly describes that item as a node in a data model. This is the approach that resulted in (for example) the UBL 2.0 definition of TaxTotal in CreditNoteLine as "An association to Tax Total". While perfectly correct from the standpoint of data model construction (the ASBIE for TaxTotal is, in fact, an association to the class or ABIE named Tax Total), such a definition is less than ideally useful for the business analyst attempting to determine the meaning of "TaxTotal" as an element name in an actual Credit Note. The definition of the ASBIE could, of course, have been extended through to the definition of the ABIE Tax Total, which in UBL 2.0 is "Information about a total amount of a particular tax", but even here an attempt to be absolutely correct can lead to a pathological expansion, as "Information about a total amount of a particular tax" becomes "A description of information about a total amount of a particular tax" and then "Structured data constituting a description of information about a total amount of a particular tax" and so on. The second approach, taken here in UBL 2.1, is to write each definition as an answer to the question "What does this mean?" in the context of an actual document instance containing the item. Thus, in UBL 2.1, the definition of TaxTotal in CreditNoteLine has changed from "An association to Tax Total" to "A total amount of taxes of a particular kind applicable to this credit note line." This compression of levels of abstraction has been carried through so far as to eliminate phrases such as "A description of" in the great majority of cases, leaving it to the reader's common sense to understand that a definition such as "The delivery requested by the party requesting a transportation service" refers to a description of the act of delivery and not the physical delivery itself, which of course could never literally be part of a document. The only widespread exceptions to this policy are the definitions of ABIEs in the Common Library, which begin "A class to describe..." or sometimes "A class to define..." in order to emphasize their more abstract role. The designers of UBL 2.1 believe that anything lost in technical correctness through this approach will be more than compensated for in improved practical usability. ============================================================================ I didn't add this in the explanation for the user, but you should understand in considering the edited definitions that I've taken an approach known in documentation and usability circles as "controlled vocabulary," which means that every attempt has been made to use as few different words as possible by employing a small library of set phrases for similar concepts. This reduces the amount of English required to understand the definitions and greatly aids in translation. 2. The Review Spreadsheet Take a look at the spreadsheet (either .xls or .ods) and you will see that it has been rearranged for purposes of this review. Many columns in the actual eDoCreator version have simply been omitted, and several new ones added. From left to right, they are: Column A: UBL Name From the original spreadsheet. A red background indicates a place where a change needs to be made to a name (e.g., "Criterion" for "Criteria", or to correct a misspelling). In such cases, the revised name is given in column K, "Corrected UBL Name (assumed)". Column B: Dictionary Entry Name From the original spreadsheet. A red background indicates a place where a change needs to be made to a name (e.g., "Criterion" for "Criteria", or to correct a misspelling). In such cases, the revised DEN is given in column L, "Corrected Dictionary Entry Name". Column C: Definition From the original spreadsheet. Column D: New Definition My rewritten definition based on what I THINK the original definition meant. Always requires at least a glance from a person knowledgeable about the originating project. Empty cells in this column indicate that the original definition needed no change. Places where I could not come up with a final edited version are (or should be) indicated with a question mark (?). Column E: Associated Object Class From the original spreadsheet. Column F: Cardinality From the original spreadsheet. Column G: Component Type From the original spreadsheet. Column H: Query A question or comment from me. Requires a response from a person knowledgeable about the originating project. Note that "Cf." in these queries means "Compare". Column I: Response The required response from a person knowledgeable about the originating project. Column J: Revised Definition Proposed by Reviewer A place to record a version the reviewer believes to be correct, if different from the New Definition (if that exists) or the old Definition (if no New Definition is provided). In the case where a question mark (?) has been written into the New Definition column, the expert respondent is expected to provide a correctly revised new definition in the "Revised Definition Proposed by Reviewer" column. Column K: Corrected UBL Name (assumed) and Column L: Corrected Dictionary Entry Name I'll take these in reverse order. The "Corrected Dictionary Entry Name" column records places where a change to the original DEN has been found necessary (e.g., "Criterion" for "Criteria"). Such changes will need to be made in eDoCreator. These cells have a red background to signal special attention. The corresponding entry in the "Corrected UBL Name (assumed)" column is what I'm assuming will be generated from the corrected DEN. Note that for readability, columns E, G, J, K, and L are omitted from the PDF containing the print version in the package linked above. REVIEW PROCESS Here's an outline of the process I'd now like us to follow. Details will need to be worked out at the subcommittee level. 1. PSC and TSC assign responsibility for each ABIE and its children to an expert associated with the originating project. 2. The expert reviews each New Definition (column D) and provides a response in column I for each query or comment in column H. If responding to a question mark (?) in column H, or if improved wording occurs to the reviewer, it is expected that a revised and corrected new definition will be provided in column J. 3. Subcommittee chairs provide the input in an organized way back to the TC level for further action. NOTE REGARDING FINAL AUTHORITY As has been the case since this project began, the judgement of the content providers will almost always be taken as final. If mistaken, my comments, questions, or wrongly conceived new definitions should not be taken as indicating more than a failure of understanding on my part; just correct things and move on. But please do remember that a failure of understanding on my part represents a failure of understanding on the part of many future users and indicates the need for some revision, even if it's not the kind I've provided.