Re: [ubl-ndrsc] R13 contradiction

[Eduardo Gutentag <eduardo.gutentag@sun.com>]

If the problem is as described by Bill (fix of documentation bug
resulting in wrong element names [wrong in the sense of "not intended"])
then I agree that the bug fix should be backed out.


Burcham, Bill wrote:
> Gosh you're absolutely right Eve!  I totally missed the "with the separators
> and object class term removed"  Sorry about that Eve and group.  The rule
> looks fine and it's perfectly clear that the object class term is (by
> default) elided.
> 
> That being said, how does NDRSC feel about UBL going out the door with every
> single tag name *including* the object class term?  That's what's about to
> happen if no one says different.
> 
> Problem was that when the Perl scripts were upgraded to do "global elements"
> a _documentation_ bug was introduced that caused the ID's for elements
> representing Basic BIE Properties to be kind of messed up.  For each BIE,
> all the Basic BIE Properties that referred to it got the same ID and
> documementation annotation.  Note that for some reason this bug did not
> affect the Ids on elements representing Association BIE Properties -- they
> each got their own ID and documentation annotation just fine.  By changing
> the Perl scripts to tack the object class term on the front of every single
> element (in fact both those representing BBIEPs and ABIEPs) the
> documentation problem disappeared.  But now, element names are long and
> there is never any reuse of tag names across content models, e.g.:
> 
> 	<xsd:complexType name="ReceivedTransportHandlingUnitDetailsType">
> 		<xsd:annotation>
> 			<xsd:documentation>
> 				<ccts:ABIE dictionaryEntryName="Received_
> Transport Handling Unit. Details" definition="information about a set of
> items which can be considered to be an undividable set of items for the
> purposes of delivery, also know as a 'logistics unit'."
> qualifierTermObjectClassTerm="Received" objectClassTerm="Transport Handling
> Unit" qualifierTerm_PropertyTerm="" propertyTerm="Details"
> representationTerm="Details" xmlns:ccts="CCTS.xsd"/>
> 			</xsd:documentation>
> 		</xsd:annotation>
> 		<xsd:sequence>
> 			<xsd:element ref="ReceivedTransportHandlingUnitID"/>
> 			<xsd:element
> ref="ReceivedTransportHandlingUnitTypeCode"/>
> 			<xsd:element
> ref="ReceivedTransportHandlingUnitHandlingUnitReceiptLine"
> maxOccurs="unbounded"/>
> 		</xsd:sequence>
> 	</xsd:complexType>
> 
> I especially loathe "ReceivedTransportHandlingUnitHandlingUnitReceiptLine".
> 
> To me it seems better to release schemas with the documentation problem and
> tag names that will be stable across releases, than to introduce unstable
> tag names (they'll have to change back in the next release right?) just to
> get the doc clean.
> 
> Now I understand that the documentation isn't "just" documentation -- that
> in fact we envision sophisticated processing on those Ids.  But is that a
> priority in this very first release?  Should that priority trump the
> stability of our tag names?  My worst fear is that we release with these
> long (non-reusable) tag names and then we're stuck with them forever.
> 
> Recall too that the action that triggered the Perl script changes in the
> first place was a realization that a crucial NDR design decision was
> violated and that we had to fix it (local versus global).  Now it seems we
> are in danger of violating an equally crucial and hard-won decision (tag
> naming).
> 
> -Bill
> 
> 
> -----Original Message-----
> From: Eve L. Maler [mailto:eve.maler@sun.com] 
> Sent: Friday, January 17, 2003 9:37 AM
> To: ubl-ndrsc@lists.oasis-open.org
> Subject: Re: [ubl-ndrsc] R13 contradiction
> 
> 
> I wrote this in an attempt to put the naming instructions for each kind 
> of thing in its own separate numbered rule.  The element name does not 
> directly equal the dictionary entry name; it is the entry name with a 
> bunch of truncating rules applied (object class term removed, separators 
> removed, duplicated words removed, etc.).  Is this unclear in R13?  I 
> hadn't thought so.
> 
> Also, your compressed version of the subsequent paragraph is a little 
> misleading: It's more like "If the object class term would have been 
> (would be?) helpful in the (XML), it should be (appear) in the property 
> qualifier field (of the spreadsheet)" -- not "it should appear in the 
> XML", which would be tautological.  This bit is supposed to serve as 
> advice for modelers, and should ideally belong somewhere in the LC 
> methodology in addition to having a non-normative reminder here.
> 
> 	Eve
> 
> Burcham, Bill wrote:
> 
>>R13 and the subsequent paragraph are contradictory.  R13 says 
>>(incorrectly) that the element name = the "(full dictionary entry name 
>>of the property)..."  The subsequent paragraph goes on to say that "if 
>>the object class term would have been helpful in the (XML) it should 
>>be (present) in the (XML)".  If R13 is correct then the object class 
>>term is always present and there's no need for the subsequent 
>>paragraph.
>>
>>I know I've missed some subsequent discussions, but when we ratified 
>>global elements in Boston, we did not say we would start generating 
>>element names = dictionary entry terms.  Doing so would eliminate all 
>>opportunity for element reuse since there would be no way the same tag 
>>name could occur in two  content models (since the two content models 
>>would have different "object class terms").
>>
>>If I'm right R13 is wrong and also we've got quite an issue with the 
>>schemas that are about to be shipped as UBL 1.0.
>>
>>Here's the two paragraphs for your reference:
>>
>>[R 13]	An element name in an element declaration [TBD: ref= or
> 
> name=?]
> 
>>based on a property must be the full dictionary name of the property 
>>in the syntax-neutral model, with the separators and object class term 
>>removed, and with the property term removed if it is identical or 
>>similar to the representation term, with the following term pairs 
>>considered similar: Identification/Identifier and Identification/Code. 
>>If the representation term is "Text", it must be removed.  If the 
>>representation term is "Identifier", it must be replaced with "ID". 
>>Examples: Person. Name. Text becomes Name, Person. Residence. Address 
>>becomes ResidenceAddress, and Address. Country. Identifier becomes 
>>CountryID. [TBD: This rule seems very long. Is there any way it can be 
>>broken down into multiple rules?]
>>
>>If the object class term would have been helpful in the resulting XML 
>>name for clarity, it should be repeated in the property qualifier 
>>field. For example, if Party. Identification. Identifier would result 
>>in an element name of ID, and if this name would be confusing because 
>>a Party object has many different identifiers as properties, then the 
>>property should have been named Party. Party Identification. 
>>Identifier instead, resulting in an element name of PartyID.
> 
> 
> 
> 


-- 
Eduardo Gutentag               |         e-mail: eduardo.gutentag@Sun.COM
XML Technology Center          |         Phone:  (510) 986-3651
Sun Microsystems Inc.          |