XML style guidelines

MALDATA · 03-25-2009, 11:45 PM

I'm writing an application that accepts user input from an XML file. I've never done this before, so I'm not sure exactly what the style guidelines are for XML.

Specifically, my question has to do with attributes and tags. For example, have a look at the sample from the Wikipedia article on XML:

Code:

 <recipe name="bread" prep_time="5 mins" cook_time="3 hours">
   <title>Basic bread</title>
   <ingredient amount="8" unit="dL">Flour</ingredient>
   <ingredient amount="10" unit="grams">Yeast</ingredient>
   <ingredient amount="4" unit="dL" state="warm">Water</ingredient>
   <ingredient amount="1" unit="teaspoon">Salt</ingredient>
   <instructions>
     <step>Mix all ingredients together.</step>
     <step>Knead thoroughly.</step>
     <step>Cover with a cloth, and leave for one hour in warm room.</step>
     <step>Knead again.</step>
     <step>Place in a bread baking tin.</step>
     <step>Cover with a cloth, and leave for one hour in warm room.</step>
     <step>Bake in the oven at 180(degrees)C for 30 minutes.</step>
   </instructions>
 </recipe>

My question is this: when do you use an attribute and when do you just use another set of tags? In this case, "Basic bread" is inside title tags, rather than being an attribute of the recipe element. Similarly, one could choose to make "cook_time" an element rather than an attribute. Obviously either will work, but is there some rule of thumb for choosing the more appropriate method?

I can make this work any way I want, but I'm curious which way is more universal. Any thoughts?

Thanks!

ta0kira · 03-26-2009, 02:14 AM

If you want to use proper XML, I reluctantly recommend libxml2. I'm reluctant because although it gives you extremely compliant XML, it's ambiguous, poorly documented, and difficult to work with. Additionally, the loaded data isn't suitable for run-time use; only for importing and exporting.

That being said, real XML is overrated unless you want to communicate with other XML-compliant software. If you don't plan to have other programs load and use your files, you're wasting your time trying to replicate XML, especially if you're writing it by hand.

I highly encourage you to use what you have available to create your program's files. Often times you can create a very simple, yet effective, parser with a little C++ and and some tokenizing. I've written several parsers, even one that can assemble XML-like files into a tree of arbitrary C++ objects, but I'm not about to try to write a compliant XML parser.

Also keep in mind that unlike HTML, XML isn't meant to be hand-written. It's meant to be the end-all file format so that developers stop coming up with new formats every time they write a new application. Because of that, it's extremely unfriendly to even simple errors like forgetting to quote e.g. name=bread and having a closing tag in the wrong order, which are both easy mistakes to make.

Leave the XML dirty work to someone who's already been through the headache. That's why they invented XML, after all!
Kevin Barry

Biddle · 03-26-2009, 06:44 AM

Elements or attributes. This is something which I came across and was frustrated by a while ago. According to some XML design styles documents such as this, there are instances when an element should be used instead of an attribute. The problem being is the data inside an element is CDATA and I failed to find an XSLT or XQuery library which was to my satisfaction, thus it leaves it to you to interpret the data inside the element. So in theory use elements yet sometimes in reality use attributes.

paulsm4 · 03-26-2009, 08:40 AM

Maldata -

Quote:

1. ...I'm not sure exactly what the style guidelines are for XML.

ta0kira is correct - XML is meant to be processed by machines, so "style" is really secondary. Indentation is nice ... but basically, you get what you get.

Quote:

2. when do you use an attribute and when do you just use another set of tags?

This is actually relatively important. XML is all about data modelling, and the difference between an "attribute" and an "element" in XML is really the difference between an "entity" and an "attribute" in data modelling.

An "id" is, by definition, an "attribute" of some "entity". "Id" is entirely dependent on the entity: you can't really have an "id" without the thing you're identifying.

But, in general, you *want* to use tags wherever possible. It makes for a more robust data model, it tends to make parsing easier (and the code simpler) ... and, yes ... it also tends to make for (slightly) larger XML files. EXAMPLE (from Biddle's Developerworks article):

Code:

<!-- OK -->
<customer>
  <name>Gabriel Okara</name>
  <occupation>Poet</occupation>
</customer>

<!-- No real improvement: slightly worse -->
<customer name="Gabriel Okara">
  <occupation>Poet</occupation>
</customer>

<!-- Probably not a good idea... -->
<customer name="Gabriel Okara" occupation="Poet" />

Here are a couple of other links that might help:

http://www.w3schools.com/Xml/xml_attributes.asp
http://recycledknowledge.blogspot.co...ttributes.html

I basically agree with these sentiments:

Quote:

There are no rules about when to use attributes and when to use elements. Attributes are handy in HTML. In XML my advice is to avoid them. Use elements instead.

'Hope that helps .. PSM

MALDATA · 03-26-2009, 09:33 AM

Thanks for the info, everyone... very informative!

I think that last bit...

Quote:

There are no rules about when to use attributes and when to use elements. Attributes are handy in HTML. In XML my advice is to avoid them. Use elements instead.

...was the Cliff's Notes version of what I was looking for.

Just to explain myself a little bit, the application is written in Java, so it's really easy to use XML. Also, the files need to be machine-readable as well as human-readable, and the tree structure models the data to be written fairly well. The REAL reason I'm doing it this way is because I wanted to learn how to use XML in an actual application. Determining the proper "style," however, didn't seem to be completely straightforward. And since I'm not entirely up-to-speed on all the terminology yet, my googling didn't hit that Developerworks page...

Thanks again!

paulsm4 · 03-26-2009, 09:45 AM

Hi, again -

Here's a (less-than-ambiguous!) example that might help make things clearer:

Code:

<!-- Bad! -->
<student name>Gabriel Okara" class1="math" class2="physics" class3="home ec" />

<!-- Good -->
<student>
  <name>Gabriel Okara</name>
  <class>math</class>
  <class>physics</class>
  <class>home ec</class>
</student>

'Hope that helps .. PSM

graemef · 03-26-2009, 04:54 PM

I try and adhere to the adage that in xml attributes are metadata, tags are data. This means that I rarely use attributes, probably the most common usage would be to define the version of the xml format. So in the original example that you cited I would rewrite it to convert all of the attributes to tags. It is valid but xml but not conforming to the styles that I would use!