RE: [xml-dev] Should one adopt the tag naming convention of anexisting X

["Costello, Roger L." <costello@mitre.org>]

Hi Folks,

Excellent discussion!

Below is a summary of the discussion. Have I captured everything? Do you agree with the recommendations?

---------------
Introduction
---------------

What convention should one use to name elements and attributes -- camel case, lower-case dash-separated, or something else? 

When reusing several XML vocabularies, each using a different naming convention, what convention should one use to name one’s own markup? 

Naming is just one issue when creating an XML vocabulary, there are also schema structural issues, terminology issues, and others. A Naming and Design Rules (NDR) document specifies the conventions for each issue. 

When reusing several XML vocabularies, each conforming to a different NDR, what NDR should one use for one’s own XML vocabulary? 

The purpose of this message is to provide answers, or at least options, for each of these questions.

--------------------
Naming Markup
--------------------

The XML specification is silent on how to create element and attribute names (markup names). Further, there is no industry standard on naming markup. Some commonly used conventions for naming markup include: 

-  Camel case: if a name contains multiple words then they are smashed together with the first letter of each word (except the first) in upper case. Examples: <jetFuel>, <airRefuelingRequest>.

-  Lower case, dash-separated: each word in a name is lower case and words are separated by a dash. Examples: <jet-fuel>, <air-refueling-request>.

-  Lower case, underscore-separated: each word in a name is lower case and words are separated by an underscore. Examples: <jet_fuel>, <air_refueling_request>.

Here is a sampling of naming conventions used by W3C and ISO technologies:

1.  XML Schema: elements and attributes are camel case. Examples: maxOccurs, elementFormDefault, substitutionGroup.

2.  XSLT: elements and attributes are lower case, dash-separated. Examples: apply-templates, exclude-result-prefixes, analyze-string.

3.  Schematron: most elements and attributes are a single, lower case word (e.g., assert, rule, pattern). There is an element and an attribute with multiple words (value-of, is-a). There are two elements that use camel case (queryBinding and defaultPhase).

Interestingly, XML Schema and XSLT -- both W3C technologies -- use different naming conventions. And Schematron -- an ISO technology -- is not entirely consistent in its naming convention.

Some developers argue against using dash-separated names. Their argument is that when XML is auto-converted (using a data binding tool) into a programming language syntax then the programming language compiler or interpreter may misinterpret a dash as a subtraction operator. However there are counterarguments:

-  When converting XML to programming language syntax it is easy to systematically remove the dashes, if necessary. For example, map Jet-Fuel to JetFuel or Jet_Fuel.

-  The convenience of a programmer should not be placed over the readability of the data. Hyphens and underscores make markup easier for non-programmers to read. Business users take precedence over programmer convenience.

Note that misinterpreting dashes in markup names for the subtraction operation is not an issue when using XML-aware tools such as XSLT, XML Schema, Relax NG, Schematron, and XQuery as they handle XML names properly.

Whatever naming convention one adopts, it is important to stick with it and be consistent in naming markup. 

---------------------------------------------------------------------------------
Reuse XML Vocabularies, each uses a Different Naming Convention
---------------------------------------------------------------------------------

As noted in the previous section, not every XML vocabulary uses the same markup naming convention. Even within the W3C there is variance (XML Schema uses camel case whereas XSLT uses lower case, dash-separated). 

What should one do when reusing several XML vocabularies, each using a different naming convention? XML instances consist of locally created markup and markup from external XML vocabularies. For the locally created markup, what naming convention should be used? 

Here are three options:

1.  Create a naming convention independent of the external XML vocabularies.

2.  Adopt the naming convention of one of the external XML vocabularies. (Which one?)

3.  Create a naming convention that is in harmony with the external XML vocabularies. For example, suppose the XML vocabularies being reused are XML Schema and XSLT. XML Schema defines “things” and uses camel case. XSLT defines “actions” and uses lower case, dash-separated. Thus, for locally created markup use camel case for “things” and lower case, dash-separated for “actions.”

Local practice may conflict with external practice. The key point is to create a naming convention that is suitable for one’s user community. Adopt a convention that balances consistency and existing local practice to minimize mental gear-changing by the users.  The convention should make the names "feel" consistent for users.

------------------------------------------------------------------------------------------
Reuse XML Vocabularies, each has Different Naming & Design Rules (NDR)
------------------------------------------------------------------------------------------

The previous discussion is now generalized. Naming convention is only one issue (a large one, but only one). Other conventions are also important, such as a schema structural convention and a terminology convention. 

A Naming and Design Rules (NDR) is a document that specifies the naming convention to be used when creating an XML vocabulary, schema stylistic issues (optionality, indications of list length), and terminology (simple words like order, list, and part may mean different things in different parts of a user community). Many NDR specifications have been created: 

-	ACORD Naming and Design Rules (NDR)
-	Danish XML Project: OIOXML Naming and Design Rules
-	EPA Exchange Network XML Design Rules and Conventions
-	Federal XML Naming and Design Rules Project
-	Global Justice XML Data Model (GJXDM) Naming and Design Rules
-	Hong Kong OGCIO Interoperability Framework for E-Government
-	 IRS XML Naming and Design Rules
-	OAGIS Naming and Design Rules (NDR)
-	OASIS LegalXML Exchange Document Methodology, Naming, and Design Rules (MNDR) Subcommittee
-	Universal Business Language (UBL) Naming and Design Rules
-	UN/CEFACT XML Naming and Design Rules Technical Specification
-	US Department of the Navy XML Naming and Design Rules
-	US National Information Exchange Model (NIEM) NDR

See the Cover Pages (http://xml.coverpages.org/ndr.html) for a description of each NDR.

What should one do when reusing several XML vocabularies, each conforming to a different NDR? How should one design a schema that reuses several external schemas, each conforming to a different NDR? Which NDR should be used? 

The options are similar to those described in the previous section.

1.  Create an NDR independent of the external XML vocabularies.

2.  Adopt the NDR of one of the external XML vocabularies. (Which one?)

3.  Create an NDR that is in harmony with the NDRs used by the external XML vocabularies. This involves harmonizing a naming convention (see the previous section for a brief description of how to do this), schema structural issues, and terminology issues.

Local practice may conflict with external NDRs. Favor local practice. If an external vocabulary conforms to an NDR that has rules which are inconsistent with one’s user community then don’t use those rules.