Re: [ubl] Rules for Names (Dictionary Entry Names and UBLNames) -urgent action required.

[Tim McGrath <tmcgrath@portcomm.com.au>]

Thanks for going over this.  i am concerned you think this is a major 
issue.  i suspect that the most work will be in changing the text of the 
NDR to reflect what you already do, not changing the application.  its 
just that when you see these rules all together they do appear 
daunting.  anyway see my comments in line - maybe things aren't that bad!

Sylvia Webb wrote:

>Tim,
> 
>We have discussed your comments below internally at GEFEG and have the
>following response.
>
>1. We don't like to "guess" what the NDR could mean or do not mean. We
>expect clear rules for all cases. Because our resources are very limited we
>do not have time to read all possible documents which contain a few words
>about CCTS in order to create simple UBL schemas.
>
>  
>
i was actually trying to do that for you.  the only two sources we need 
are CCTS 2.01 and UBL NDR (latest working draft).  the purpose of the 
email was to allow us to explicitly state what is required in the NDR 
for GEFEG.  in other words, i agree. no-one wants you to guess.

>2. The NDR (2006-05-25) says for BBIEs:
>
>[CTN2] A UBL xsd:complexType name based on a ccts:BasicBusiness
>InformationEntityProperty MUST be the ccts:Dictionary EntryName shared
>property term and its qualifiers and representation term of the
>ccts:BasicBusinessInformationEntity, with the separators removed and with
>the "Type" suffix appended after the representation term.
>
>[ELN2] A UBL global element name based on an unqualified ccts:BBIEProperty
>MUST be the same as the name of the corresponding xsd:complexType to which
>it is bound, with the word "Type" removed.
>
>One line below there is a rule for ASBIEs, that says clearly something about
>redundant words.
>
>[ELN3] A UBL global element name based on a qualified ccts:ASBIE MUST be the
>ccts:ASBIE dictionary entry name property term and its qualifiers; and the
>object class term and qualifiers of its associated ccts:ABIE. All
>ccts:DictionaryEntryName separators MUST be removed. Redundant words in the
>ccts:ASBIE property term or its qualifiers and the associated ccts:ABIE
>object class term or its qualifiers MUST be dropped.
>
>Why is it so hard to do the same for BBIEs? This is all that we are
>requesting to provide clear instructions for developers and eliminate
>guessing and assumptions.
>
>  
>
i also include rules CTN2, ELN2 and ELN3 in my examples so i am unsure 
why you repeat them.  i agree these rules could have been more clearly 
written, but they are unambiguous.    its just that the rule for BBIEs 
is based on defining types before elements.  this doesn't apply to 
ASBIEs becasue the types have already been defined (as ABIE types).  it 
took me a while but i worked it out eventually.

>3. We cannot recognize that the DEN is the beginning for building element
>and type names. We understand that the names should be built from some terms
>that are also a component of the DEN. In the case of an ASBIE the element
>name actually consists of additional parts that are not part of the DEN. The
>qualifier(s) of the associated object class are not part of the DEN (CCTS
>2.01).
>
>  
>
Ah ha! I see your point. ELN3 says "and the object class term and 
qualifiers of its associated ccts:ABIE." when CCTS says there are no 
qualifiers for the associated ccts:ABIE.  It seems we have got out of 
synch here and the ELN3 need changing to only say "and the object class 
term of its associated ccts:ABIE."

But this is not deliberate variation from CCTS rules, just a mistake.  
The principle still stands, we want element and type names to be derived 
from DENs.

>4. Before we started to implement the UBL 2.0 schema generation we asked for
>an action item list that clearly says what we should implement. The answer
>was "Implement the NDR!". We did this as the best we know how, but if UBL
>would like to have more "convoluted" rules then we should return to the
>action item list.
>
>  
>
i thought we were trying to clarify the rules, not convolute them.  As 
far as i can see GEFEG already do most of these rules and we just want 
to ensure we follow CCTS for the DEN.  i didn't think we were doing more 
than you asked us to do.  if this looks like too much then we should 
talk about an alternative approach.

>5. You state "that as of the UBL NDR the DEN and only the DEN has to be
>used. This is not correct. [ELN3] says "A UBL global element name based on a
>qualified ccts:ASBIE MUST be the ccts:ASBIE dictionary entry name property
>term and its qualifiers; and the object class term and qualifiers of its
>associated ccts:ABIE. All ccts:DictionaryEntryName separators MUST be
>removed. Redundant words in the ccts:ASBIE property term or its qualifiers
>and the associated ccts:ABIE object class term or its qualifiers MUST be
>dropped." The qualifiers of the object class term of the associated ccts:
>ABIE are NOT part of the DEN. See CCTS B25.
>
>  
>
i agree, but isn't this just repeating your point 3?

>Regards,
>Sylvia
>________________________________
>
>From: Tim McGrath [mailto:tmcgrath@portcomm.com.au] 
>Sent: Monday, June 26, 2006 9:58 PM
>To: ubl@lists.oasis-open.org
>Subject: [ubl] Rules for Names (Dictionary Entry Names and UBLNames) -
>urgent action required.
>
>
>At today's Pacific call we had a discussion about the rules for truncating
>names.  This lead from a request by GEFEG (the builders of the software that
>we use to create schemas) to specify where we get naming rules from.  We
>need to conclude this issue immediately so we can update the NDRs and get
>the 2.0 schemas built.
>
>My research has brought me to the following position.  I am not aware of any
>other rules (either in CCTS or UBL NDRs) that affect naming.  If anyone
>knows then please add to this set so we can get our NDRs updated this week.
>
>Firstly, the initial name for any BIE (information item) is the Dictionary
>Entry Name (DEN).  The UBLName is then based on this DEN.  The DEN is the
>responsibility of the ebXML CCTS and the UBLName is the responsibility of
>the UBL NDRs.  
>
>Details of these rules are given below. I will focus on Basic and
>Association BIEs as the naming of Aggregate BIEs appears not the be the
>issue and describing them would only add complexity to an already complex
>issue.
>
>All Dictionary Entry Names (DEN) are specified by following the ebXML CCTS
>(v2.01). 
>
>For Basic BIEs this is initially as Rule B24...
>"The Dictionary Entry Name of a Basic Business Information Entity shall
>consist of the following components in the specified order:
>* the Object Class Term of the corresponding Basic Core Component, and
>possibly additional Qualifier Term(s),
>* the Property Term of the corresponding Basic Core Component, and possibly
>additional Qualifier Term(s),
>* the Representation Term of the Data Type on which the corresponding Basic
>Business Information Entity Property is based."
>
>So the initial DEN for identifying a Contact might be 'Contact. Identifier.
>Identifier'
>
>For Association BIEs there is a similar Rule B25...
>"The Dictionary Entry Name of an Association Business Information Entity
>shall consist of the following components in the specified order:
>* the Object Class Term of the corresponding Association Core Component, and
>possibly additional Qualifier Term(s),
>* the Property Term of the corresponding Association Core Component, and
>possibly additional Qualifier Term(s),
>* the Object Class Term of the Association Business Information Entity on
>which the corresponding Association Business Information Entity Property is
>based."
>
>So the initial DEN for other communcation channels associated with a Contact
>be 'Contact. Other_ Communication. Communication'
>
>These DENs are then refined using Rule B29...
>"For Basic and Association Business Information Entities, if the Property
>Term is equal to the third component of the Dictionary Entry Name, and the
>Property Term is not qualified, the Property Term shall be removed from the
>Dictionary Entry Name."
>
>So the DEN for identifying a Contact would then be 'Contact. Identifier'.
>But the DEN for any other communications associated with a Contact is not
>shortened, because it is qualified by "Other_ ".  So it remains 'Contact.
>Other_ Communication. Communication'.  If it were not qualified it would
>have become 'Contact. Communication'
>
>As far as I can see, these are the only rules for shortening Dictionary
>Entry Names.  
>
>There are no UBL NDR rules about forming Dictionary Entry Names. Our NDRs
>state, "Since UBL is an implementation of CCTS, UBL uses CCTS dictionary
>entry names as the basis for UBL XML schema construct names. UBL converts
>these ccts:DictionaryEntryNames into UBL XML schema construct names using
>strict transformation rules."  We have rule GNR2 that says, "UBL XML element
>and type names MUST be consistently derived from CCTS conformant dictionary
>entry names."  Elements names are what we also know as the UBLName. These
>rules for consistent derivations of CCTS conformant dictionary entry names
>are what we have in the UBL NDRs.  
>
>Rule CTN 2 states:
>"A UBL xsd:complexType name based on a
>ccts:BasicBusinessInformationEntityProperty MUST be the ccts:Dictionary
>EntryName shared property term and its qualifiers and representation term of
>the ccts:BasicBusinessInformationEntity, with the separators removed and
>with the "Type" suffix appended after the representation term."
> 
>So the complexType name for identifying a Contact would then be
>'IdentifierType'
>
>Then ELN2 adds:
>"A UBL global element name based on an unqualified ccts:BBIEProperty MUST be
>the same as the name of the corresponding xsd:complexType to which it is
>bound, with the word "Type" removed."
>
>So the element name for identifying a Contact would then be 'Identifier'.  A
>convoluted way of saying it, but it works!  
>
>For Association BIEs, rule ELN 3 states:
>"A UBL global element name based on a qualified ccts:ASBIE MUST be the
>ccts:ASBIE dictionary entry name property term and its qualifiers; and the
>object class term and qualifiers of its associated ccts:ABIE. All
>ccts:DictionaryEntryName separators MUST be removed. Redundant words in the
>ccts:ASBIE property term or its qualifiers and the associated ccts:ABIE
>object class term or its qualifiers MUST be dropped."
>NB I suspect that the first use of 'qualified' is not what was meant. All
>ASBIEs follow this rule regardless of their qualification.  Otherwise we
>have no rule for ASBIE element names!
>
>Following this rule means the element name for the other communcations
>associated with a Contact becomes "OtherCommunciation".
>
>However, we aren't finished because there are some UBL truncation rules for
>UBLNames. These are...
>
>"Each Basic BIE Property results in an element in the XML Schema. The tag
>name is derived like this:
><Basic BIE Property Property Term>( ( <BBIE Object Class Term> != "Text" &&
><Basic BIE Property Property Term> != <BBIE Object Class Term>) ? (<BBIE
>Object Class Term> == "Identifier" ? "ID" : <BBIE Object Class Term>)
>So the tag name is the name of the Basic BIE Property followed by the name
>of the pertinent BBIE. If the BBIE is named "Text" or if the name of the
>Basic BIE Property is the same as the name of the BBIE then it must be
>elided. If the BBIE Object Class Term is Identifier then it is translated to
>"ID" in the tag name.
>Here are some examples: "
>
>
>Basic BIE Property Property Term
>
>	BBIE Object Class Term
>
>	Tag name
>
>	
>Purpose
>
>	Code
>
>	PurposeCode
>
>	
>Name
>
>	Text
>
>	Name
>
>	
>Party
>
>	Identifier
>
>	PartyID
>
>	
>
>also, described as...
>"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. "
>
>NB. This rule is taken from the UBL NDR Working Draft 22, 18 February 2003
>(wd-ublndrsc-ndrdoc-22 ) currently posted at
>http://www.oasis-open.org/apps/org/workgroup/ubl/ubl-ndrsc/document.php?docu
>ment_id=1380.  This rule never made it to the NDR 1.0 but we made no
>decision to remove it and have been following it regardless.  I propose it
>be reworded (eg Object Class Term should have been Representation Term) ,
>update the examples and then have it re-instated.
>
>To summarize, if we use some of elements from the structure called "Contact"
>in UBL 2.0, it has examples of most of these rules.
>
>BBIE DEN = "Contact. Identifier. Identifer" shortens to "Contact.
>Identifier", gives UBLName = "ID"
>BBIE DEN = "Contact. Name. Name" shortens to "Contact. Name", gives UBLName
>= "Name"
>BBIE DEN = "Contact. Telephone. Text" does not shorten, gives UBLName =
>"Telephone"
>ASBIE DEN = "Contact. Other_ Communication. Communication" does not shorten,
>gives UBLName = "OtherCommunication"
>
>
>
>  
>

-- 
regards
tim mcgrath
phone: +618 93352228  
postal: po box 1289   fremantle    western australia 6160
web: http://www.portcomm.com.au/tmcgrath