Newly detected backward compatibility error - TransportContract

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

Hi folks,

It turns out our decision to accept new dictionary entry names for 
old constructs was hiding a backwards compatibility 
problem.  Thankfully the sample instances revealed the need to update 
the model checking.  And thankfully that updated model checking found 
only the one problem revealed by the sample instances and not any 
other problems of the same ilk.

Far below is the latest complete report and excerpted here below is 
the new addition:

ASBIEs found in error: 1
Old Parent DEN: "Consignment. Details"
New Parent DEN: "Consignment. Details"
Old name: "TransportContract"
New name: "TransportContract"
Old DEN: "Consignment. Transport_ Contract. Contract"
New DEN: "Consignment. Transport Contract"
Old associated class: "Contract"
New associated class: "Transport Contract"
   Old order:
    1 ID
   *2 IssueDate
   *3 IssueTime
   *4 ContractTypeCode
   *5 ContractType
   *6 ValidityPeriod
   *7 ContractDocumentReference

   New order (not including newly-introduced optional constructs):

   New order (all constructs):
    1 Contract
   *2 NominationPeriod
   *3 ContractualDelivery


What this means is that until this is fixed UBL 2.1 is not backward 
compatible to UBL 2.0 because UBL 2.0 is expecting:

   <cac:Consignment>
     <cac:TransportContract>
       ID, IssueDate, IssueTime, etc. (per the old order above)

But the way the schemas are now written, a UBL 2.1 instance is expecting:

   <cac:Consignment>
     <cac:TransportContract>
       Contract, NominationPeriod, ContractualDelivery

So, we need to change something.  Note in the error report the "old 
order" and "new order" are totally different, so that part of the 
error report is nonsensical for this particular situations.  In other 
error situations it might coincidentally be the same order.

<cac:TransportContract> is obliged to contain at least the old 
children, but it is allowed to have new optional children.  I see 
three ways to fix this:

(A) We could add the new items to the old <Contract> but they aren't 
related to contracts in general, only to transportation 
contracts.  But that isn't so bad since users are already used to 
finding things in objects that they don't need.

(B) We could add a new ABIE Transport Contract that has all of the 
children of Contract and then the new children as well (this way UBL 
2.0 is backward compatible to both the new <Contract> and the new 
<TransportContract>).  But in a future version of UBL if we have new 
contract properties we would have to remember to add them in two places.

(C) We could add a new ASBIE to <Consignment> which has only the new children:

   <cac:Consignment>
     <cac:TranportContract>
       ID, IssueDate, IssueTime, etc. (per the old order above)
     </cac:TransportContract>
     <cac:NewTransportThingy>
       <cac:NominationPeriod>
       </cac:NominationPeriod>
       <cac:ContractualDelivery>
       </cac:ContractualDelivery>
     </cac:NewTransportThingy>
   </cac:Consignment>

... so I thought I'd try and propose the name of the new element 
above "NewTransportThingy" by reading the definitions of the two members:

NominationPeriod - An association to Period. The nomination period is 
the period in which the transport user has to book the transport 
service before the transport should begin.
ContractualDelivery - An association to Delivery.


And because of the tautological definition used, I don't know what 
the combination is trying to represent.  So I'll leave it with the 
TSC to decide which of the three ways to go.  I think my vote is (A).

BTW, the prevalence in UBL 2.0 and 2.1 of these tautological 
definitions I think takes a lot away from our specification.  And, 
when I try to teach UBL in the classroom, I get burned by their 
presence in the model when a student asks me a question.  The 
definition above for "ContractualDelivery" tells me nothing at 
all.  I can see it is an association to Delivery because it is 
associated with delivery.  But I cannot (and my students cannot, and 
our users cannot) understand what to put in <ContractualDelivery> 
without knowing the definition the UBL designers had in mind 
regarding why they had to add it to the model.  Using a tautological 
definition adds nothing and doesn't serve the user.  I realize it 
will be a lot of work, but I would like to propose in PRD1 review 
that *every* tautological definition be replaced with a proper 
semantic definition that conveys some real definition information to 
the reader.

So, over to you TSC ... how do we fix the transport contract 
situation?  One of the above three approaches, or a fourth approach I 
haven't thought of?

Thanks!

. . . . . . . . . .  Ken

Renamed old DENs in new model: 18
Application Response. Version Identifier. Identifier: Application 
Response. Version. Identifier
Certificate Of Origin. Version Identifier. Identifier: Certificate Of 
Origin. Version. Identifier
Consignment. Transport_ Contract. Contract: Consignment. Transport Contract
Item Comparison. Price. Amount: Item Comparison. Price Amount. Amount
Monetary Total. Allowance Total Amount. Amount: Monetary Total. 
Allowance_ Total Amount. Amount
Monetary Total. Charge Total Amount. Amount: Monetary Total. Charge_ 
Total Amount. Amount
Order Change. Customer Reference. Text: Order Change. Customer_ Reference. Text
Order Change. Sales Order Identifier. Identifier: Order Change. 
Sales_ Order Identifier. Identifier
Order Change. Sequence_ Number. Identifier: Order Change. Sequence 
Number. Identifier
Order Reference. Sales Order Identifier. Identifier: Order Reference. 
Sales_ Order Identifier. Identifier
Order Response. Customer Reference. Text: Order Response. Customer_ 
Reference. Text
Order Response. Sales Order Identifier. Identifier: Order Response. 
Sales_ Order Identifier. Identifier
Order. Customer Reference. Text: Order. Customer_ Reference. Text
Order. Sales Order Identifier. Identifier: Order. Sales_ Order 
Identifier. Identifier
Packing List. Version Identifier. Identifier: Packing List. Version. Identifier
Receipt Line. Oversupply Quantity. Quantity: Receipt Line. 
Oversupply_ Quantity. Quantity
Signature. Validator Identifier. Identifier: Signature. Validator. Identifier
Status. Sequence. Identifier: Status. Sequence Identifier. Identifier


Bad code type property terms: 0


Duplicated class/qualifier/property terms: 0


Bad name components: 0


Mismatched name components for UBL Name: 3
"TaxExclusiveAmount": inconsistent naming components (2)
   Budget Amount. Tax Exclusive_ Amount. Amount
   Monetary Total. Tax Exclusive Amount. Amount **
"ValueAmount": inconsistent naming components (3)
   Capability. Value_ Amount. Amount
   Goods Item. Value. Amount **
   Stock Availability Report Line. Value_ Amount. Amount
"PackSizeNumeric": inconsistent naming components (2)
   Item. Pack Size. Numeric
   Utility Item. Pack_ Size Numeric. Text **


Orphaned ABIEs not being referenced by an ASBIE: 0


Qualified ABIEs:  0


Qualified ASBIEs:  0


Duplicate UBL Names for the same ABIE type: 0


Missing old Data Type Qualifications in new model: 1
"Status. Condition Code. Code" old="Transportation Status" new=""


Missing new Data Type Qualifications in new data types: 0


Cardinalities found in error: 0


Sequences found in error (by DEN): 0


Sequences found in error (by name): 0


ASBIEs found in error: 1
Old Parent DEN: "Consignment. Details"
New Parent DEN: "Consignment. Details"
Old name: "TransportContract"
New name: "TransportContract"
Old DEN: "Consignment. Transport_ Contract. Contract"
New DEN: "Consignment. Transport Contract"
Old associated class: "Contract"
New associated class: "Transport Contract"
   Old order:
    1 ID
   *2 IssueDate
   *3 IssueTime
   *4 ContractTypeCode
   *5 ContractType
   *6 ValidityPeriod
   *7 ContractDocumentReference

   New order (not including newly-introduced optional constructs):

   New order (all constructs):
    1 Contract
   *2 NominationPeriod
   *3 ContractualDelivery




--
XSLT/XQuery training:   after http://XMLPrague.cz 2011-03-28/04-01
Vote for your XML training:   http://www.CraneSoftwrights.com/o/i/
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/o/
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Male Cancer Awareness Nov'07  http://www.CraneSoftwrights.com/o/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal