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:]
> Sent: Friday, January 17, 2003 9:37 AM
> To:
> 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:
XML Technology Center | Phone: (510) 986-3651
Sun Microsystems Inc. |
