[ubl-ndrsc] Comments on Markup Naming positions

Following are my comments on the Markup Naming positions proposed in Mark's 
12 November NDR document draft.

	Eve

----------------------------------------------------------------------
----------------------------------------------------------------------
General organizational comments:

Even if we use line numbering, having the lists be numbered as well would 
be helpful for referencing.

It would be nice to have Markup Naming be its own top-level section, to 
avoid the heavy nesting and because it's a nice clear dividing line, with 
few hard decisions about what goes here vs. elsewhere.  Also, some of the 
names that I use below for the various markup-naming topics might make good 
subsection titles, or at least "handles" for list items.

This is how the TOC could look if they're made into subsections:

n Markup Naming
   n.1 Name Structure
       n.1.1 English in names
       n.1.2 Naming patterns
       n.1.3 Abbreviations
       n.1.4 Element name length
   n.2 Name Content
       n.2.1 Parts of speech
       n.2.2 Singular and plural names
       n.2.3 Naming strategy
       n.2.4 Redundancy in names
       n.2.5 Document type naming

----------------------------------------------------------------------
*All UBL type, element, and attribute names must Oxford English:
(Section 5.1, list item #3)

I think this should be moved into 5.2.1, Markup Structure.

I suppose I'm fine with this recommendation, if this is what everybody else 
chooses.  Does OED mean British-style spellings for things like colo[u]r?

----------------------------------------------------------------------
*The name of the UBL message set must be consistent with its definition:
(Section 5.1, list item #6)

This should probably be moved into 5.2.1.2, Markup Content.  The reason is 
that a "UBL message set" is a UBL "document type" (right?), and I think the 
root element should be the same as the name we give the document type.

That said, I'm not sure what this means.  It does sound like a generally 
good prescription, but perhaps too vague to help, unless some examples and 
non-examples are supplied.  It is reminiscent of the item in 5.2.2 that 
talks about "meaningful aggregate names", and it seems to address the Ed. 
Note in the intro to Section 5.2.1 that talks about "naming convention for 
root element...".

----------------------------------------------------------------------
*Group naming:
(Section 5.2.1 intro)

When you say "Groups" here, are you referring to model group and attribute 
groups?  At first blush, I wonder if we can simply use the same rules as 
for types.

----------------------------------------------------------------------
UCC and LCC:
(Section 5.2.1.1 items #1, 2, and 3)

(BTW, can the lists be numbered for easy reference?  This will be helpful 
even if we use line-numbering.)

I imagine that any other choice here would be sacrilege. :-)  If we cover 
model and attribute groups, they should be listed in item #1.

----------------------------------------------------------------------
Naming patterns:
(would go in Section 5.2.1.1 somewhere)

Some schemas use suffixes to indicate the sort of thing being named, such 
as AssertionType and IDSimpleType; this is something to consider.  Also, we 
should guide the naming of elements/types where there is a 1:1 relationship 
(that is, where an anonymous type would theoretically serve just as 
well).  Do we want to say that the element and type names match?  That they 
match except the type name has "Type" on the end?

My recommendation: I'm not thrilled about the verbosity that "Type" adds, 
but it can be marginally useful when you're reading a schema, just because 
you can't get confused about what sort of thing (or what sort of 
thing-reference) you're looking at.  I say we use it.  We don't really need 
a "SimpleType" variant, but for consistency, we should probably use "Group" 
as a suffix (if we have any groups) too.

----------------------------------------------------------------------
Acronyms and abbreviations:
(Section 5.2.1.1 items #4 and 5)

Item #4 seems fine, other than the fact that XML is an initialism, not an 
acronym. :-)  Item #5 seems to contract #4, and I think it should be removed.

----------------------------------------------------------------------
Punctuation:
(Section 5.2.1.1 item #6)

Could this simply be combined with items #1, 2, and 3?  The prohibition 
seems to go hand in hand with the camel case.

----------------------------------------------------------------------
Element name length:
(Section 5.2.1.1 item #7)

I have a feeling that a limit of 30 characters may be hard to achieve, if 
we use the "build up the name" technique in Section 5.2.1.2.  Is 30 a hard 
limit?  What happens if a name goes over -- does a human make a judgment 
call about designing a shorter name?  Will customizers still suffer if they 
have to add "My-" to a name for some reason?  Do attribute names not 
present any of the same problems as element names?  I would prefer it if we 
could avoid dealing with hard limits.

Finally, the hard-limit information (if there is any) belongs here, but the 
reference to limiting verbosity in general is wholly a matter for the 
Markup Semantics section and the reference should be removed here.

----------------------------------------------------------------------
----------------------------------------------------------------------
Uniqueness:
(Section 5.2.1.2 item #1)

This would seem to prohibit local elements, which can have the same name 
but be qualified by being defined in different complex types.  And if the 
entire set of element, atribute, type, group, etc. names is unique, then we 
definitely *will* need suffixes or some other scheme to disambiguate them, 
since without a guideline, many type names will mirror their associated 
element names.

----------------------------------------------------------------------
Naming strategy:
(Section 5.2.1.2 items #2, 3, 4, 6, 7, 8, 9, 10 and table)

This got some debate on the last call: dictionary names or intuitive 
"common usage" names?  I would love to see a bunch of examples using both 
styles.  I'm inclined towards intuitive names, though, because I can barely 
wend my way through the description provided here (even with the 
definitions for Object Class, Property Term, etc. provided).  Also, Arofan 
brought up the benefits of using "non-hierarchical" short names: they can 
be reused in more places.  (Though I suppose this gets into the local vs. 
global issue again...)

----------------------------------------------------------------------
Redundancy in names:
(Section 5.2.1.2 item #5)

The mention of conciseness isn't too helpful, it seems to me, given the 
rigid way several terms have to be sewn together in the EDR 
methodology.  More helpful is the rule about removing redundancy of 
consecutive words.  I also wonder if this is related to item #8, about 
syntactic and/or semantic redundancy in Representation Terms and Property 
Terms; should it be subsumed there?

----------------------------------------------------------------------
Singular vs. plural:
(Section 5.2.1.2 item #11)

Makes sense to me.  If elements that contain repeated items are always 
given a suffix of "Detail" (or whatever), it might be nice to mention or 
refer to that here.

----------------------------------------------------------------------
Non-letter characters:
(Section 5.2.1.2 item #12)

Does this mean that if you're using a language other than English for your 
tags, it's okay to use funky things like combining accents and numbers 
because that's what's used in that language?  If so, this conflicts with 
the OED rule.  If not, this seems more like it should go with the "don't 
use periods and hyphens" rule.  Somehow it doesn't seem to belong in the 
Markup Content section no matter what.

----------------------------------------------------------------------
Parts of speech:
(Section 5.2.1.2 item #13)

This rule seems fine.

----------------------------------------------------------------------
----------------------------------------------------------------------
--
Eve Maler                                    +1 781 442 3190
Sun Microsystems XML Technology Center   eve.maler @ sun.com