Best Practice: Element with data or element with child element?

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

Hi Folks,

Which approach is better, an image element that contains the location of a GIF file:

   <image>images/mighty_oj.gif</image>

Or, an image element that contains a child element, which contains the location of the GIF file:
   
    <image>
        <src>images/mighty_oj.gif</src>
    </image>


Likewise, which is better, a retailer element that contains the URL to a seller:

   <retailer>http://www.thewhitewhale.com/oj.htm</retailer>

Or, a retailer element that contains a child element, which contains the URL to a seller:

    <retailer>
        <href>http://www.thewhitewhale.com/oj.htm</href>
    </retailer>


The second approach (use child element) has a nice advantage which I describe here.

Suppose you wish to transform the <image> element into an HTML <img> element, i.e., transform the XML into this:

    <img src="images/mighty-oj.gif" />
  
If the XML uses this approach: 

   <image>images/mighty_oj.gif</image>

Then the transformation may be accomplished using XSLT like this:

    <img src="{image}" />

But this is a hardcoded solution. Furthermore, it's not extensible. Let's see why.


For an HTML <img> element we should provide not only the source location of the image (using the src attribute), but also alternative text (using the alt attribute). Further, to assist browsers in allocating space for the image, we should provide the width and height of the image. Using the second approach all this information can be provided in the XML document:

    <image>
        <src>images/mighty_oj.gif</src>
        <alt>OJ Home Juicer</alt>
        <width>276</width>
        <height>281</height>
    </image>

Now the <image> element can be transformed into an HTML <img> element, and the attributes of <img> can be dynamically added. Here's how to do that using XSLT:

    <img>
        <xsl:for-each select="image/*">
            <xsl:attribute name="{name(.)}">
                <xsl:value-of select="." />
            </xsl:attribute>
        </xsl:for-each>
    </img>

The XSLT is not hardcoded to add a specific set of attributes; it adds as attributes whatever child elements there are of <image>. 

Furthermore, the XML document can be extended; here I add a <title> and <class> element:

    <image>
        <src>images/mighty_oj.gif</src>
        <alt>OJ Home Juicer</alt>
        <width>276</width>
        <height>281</height>
        <title>Simple, inexpensive juicer</title>
        <class>juicer</class>
    </image>

The XSLT code requires no change. 


Thus, we see several benefits to the second approach:

   1. The transformation code can be unaware of the 
      specific set of attributes to be added to the 
      <img> element.

   2. The XML can be extended without changing the 
      transformation code.


The same arguments apply to the retailer example. Let's see.

Suppose you wish to transform the <retailer> element into an HTML <a> element, i.e., transform the XML into this:

    <a href="http://www.thewhitewhale.com/oj.htm";>
        http://www.thewhitewhale.com/oj.htm
    </a>
  
If the XML uses this approach: 

   <retailer>http://www.thewhitewhale.com/oj.htm</retailer>

Then the transformation may be accomplished using this XSLT:

    <a href="{retailer}">
        <xsl:value-of select="retailer" />
    </a>

However, this is a hardcoded solution. Furthermore, it's not extensible. Let's see why.


For an HTML <a> element we should provide not only the URL (using the href attribute), but also the language of the target document (using the hreflang attribute). Using the second approach all this information can be provided in the XML document:

    <retailer>
        <href>http://www.thewhitewhale.com/oj.htm</href>
        <hreflang>en</hreflang>
    </retailer>

Now the <retailer> element can be transformed into an HTML <a> element, and all the attributes of <a> can be dynamically added. Here's how to do that using XSLT:

    <a>
        <xsl:for-each select="retailer/*">
            <xsl:attribute name="{name(.)}">
                <xsl:value-of select="." />
            </xsl:attribute>
        </xsl:for-each>
        <xsl:value-of select="retailer/href" />
    </a>

The XSLT is not hardcoded to add a specific set of attributes. 

Furthermore, the XML document can be extended; here I add a <title> element: 

    <retailer>
        <href>http://www.thewhitewhale.com/oj.htm</href>
        <hreflang>en</hreflang>
        <title>Retailer for the Mighty OJ juicer</title>
    </retailer>

The XSLT code requires no change.


RECAP

If an XML element is to be transformed into an element with attributes then design the element like this:

   <element>
      <attribute-name>attribute-data</attribute-name>
   </element>

Not like this:

   <element>data</element>


Comments?

/Roger