OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help



   Re: [xml-dev] Friendly names in XML Schema best practice?

[ Lists Home | Date Index | Thread Index ]


Addressing the "friendly" names portion of your question: I always use
the ISO/IEC 11179 standard [1] for XML element naming in the schemas I
develop in the U.S. federal government space. 11179 pre-dates XML, its
focus being data elements; however, the concepts are very applicable to
XML elements. In summary, Part 5 ("Naming and Identification Principles
for Data Elements") of ISO/IEC 11179 uses a multi-part naming convention
for data element names.


The primary parts are:

- Object Class : Represents an activity or object in a context.  It
essentially answers the question "What is this data element about?"

* Examples: Organization, Address, Project

- Property Term : Further distinguishes the data element from other data
elements of the same Object Class. 

* Examples: Name, City, Start (may seem nebulous - please read on)

- Representation Term: Describes the representation format of a data

* Examples: Text, Date, Code, Amount


Joining these example data element names in the order given yields the
following complete data element names:

- OrganizationNameText (the "Text" term is typically dropped in schemas)
- AddressCityText
- ProjectStartDate


There will be occassions in which these 3 parts are not sufficient -
that's where Qualifiers come in. Qualifiers can be added in front of an
Object Class, a Property Term, or both - for example:

- OfficeAddressCityText ("Office" is a Qualifier for the "Address"
Object Class)

* This could be done to differentiate this data element from one named

- OrganizationShortNameText ("Short" is a Qualifier for the "Name"
Representation Term)

* This could be done to differentiate this data element from one named

- InternalProjectProposedStartDate ("Internal" is a Qualifier for the
"Project" Object Class, "Proposed" is a Qualifier for the "Start"
Representation Term)

* This could be done to differentiate this data element from one named
ExternalProjectApprovedStartDate, or ExternalProjectProposedStartDate;


The process I usually use when creating data element names is:

(1) Begin with the 2 "outer" parts (Object Class and Represention Term)

(2) Determine what Property Term would be most appropriate

(3) Ask yourself if the data element name is clear/unique enough for
your purposes (i.e. is there already a data element with that name)

(4) If so, apply Qualifier terms


This approach is used throughout the U.S. federal government, as well as
by emerging XML vocabularies such as OASIS UBL [1].

Kind Regards,
Joe Chiusano
Booz | Allen | Hamilton

[1] http://metadata-stds.org/11179
[2] http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl

Jeff Rafter wrote:
> I was curious if anyone had experience decorating XML Schemas (or any other
> schemas for that matter) with "friendly" names. That way, when importing
> schemas into editors for non XML users they are presented with something
> even more understandable. Additionally, if this has been done, has anyone
> seen it done in combination with xml:lang to specify language specific
> identifiers. I would imagine that it would go inside of <appInfo> inside
> something like <friendlyName xml:lang="en-US">.
> To add even more to this question, has anyone seen the use of language
> identifiers within the documentation element?
> Thanks,
> Jeff Rafter
> -----------------------------------------------------------------
> The xml-dev list is sponsored by XML.org <http://www.xml.org>, an
> initiative of OASIS <http://www.oasis-open.org>
> The list archives are at http://lists.xml.org/archives/xml-dev/
> To subscribe or unsubscribe from this list use the subscription
> manager: <http://lists.xml.org/ob/adm.pl>
tel;work:(703) 902-6923
org:Booz | Allen | Hamilton;IT Digital Strategies Team
adr:;;8283 Greensboro Drive;McLean;VA;22012;
title:Senior Consultant
fn:Joseph M. Chiusano


News | XML in Industry | Calendar | XML Registry
Marketplace | Resources | MyXML.org | Sponsors | Privacy Statement

Copyright 2001 XML.org. This site is hosted by OASIS