Elements and attributes · XML

XML offers two places to put a piece of data: in an element or in an attribute.

An element is a start tag, its content and an end tag. Attributes describe the element; child elements hold data that has structure of its own.

XML

<!-- the same information, stored two ways -->
<catalogue>
  <book>
    <id>b1</id>
    <title>Clean Code</title>
    <language>en</language>
  </book>
  <book id="b2" language="en">
    <title>Refactoring</title>
  </book>
</catalogue>

Both are valid XML. Which is better depends on what the data is.

Which to use

Use an element for	Use an attribute for
the content itself: titles, names, descriptions	information about the content: ids, units, language codes
values that can repeat, such as several authors	single values: an element can't have two attributes with the same name
values with structure inside them	short, simple values
long text	values used to identify or look something up

A rule of thumb: if a reader would want to see it, make it an element; if it's an identifier or a setting, make it an attribute.

Repeating and nesting

XML

<book id="b3" lang="en">
  <title>The Pragmatic Programmer</title>
  <authors>
    <author>Andrew Hunt</author>
    <author>David Thomas</author>
  </authors>
  <price currency="USD">49.99</price>
  <published year="1999" edition="1"/>
</book>

Two authors need two author elements, because attributes can't repeat: author="..." author="..." is an error.
A wrapper element, authors, keeps the repeated items together.
currency="USD" describes the price, information about the data rather than the data itself.
<published .../> is an empty element: it has attributes but no content, and closes itself with />.

Mixed content

XML

<lesson>
  <para>Use <code>print()</code> to show output, and <em>always</em> close your tags.</para>
</lesson>

An element can mix text with child elements, which suits documents such as articles and books. Data files, like invoices and configuration, usually avoid it: they're easier to process when each element holds either text or other elements.

Entities: special characters

XML

<examples>
  <rule>5 &lt; 10 &amp;&amp; 10 &gt; 5</rule>
  <quote said="&quot;Hello&quot;, she said">Quotes inside an attribute, as entities</quote>
  <price>Price: &#8377;499</price>
</examples>

Entity	Character
`<`	`<`
`>`	`>`
`&`	`&`
`"`	`"`
`'`	`'`
`₹`	any character, by its Unicode number (here, the rupee sign)

< and & must always be escaped in text. The quote entities are needed only inside an attribute value that uses the same kind of quote.

CDATA sections

XML

<snippet language="javascript"><![CDATA[
if (a < b && b > c) {
  console.log("no escaping needed in here");
}
]]></snippet>

Inside <![CDATA[ ... ]]>, < and & are ordinary characters, so code or markup can be pasted in without escaping every one. The only thing a CDATA section can't contain is its own ending, ]]>.

Comments and the declaration

XML

<?xml version="1.0" encoding="UTF-8"?>
<!-- A comment: programs reading the data ignore it -->
<config>
  <theme>dark</theme>
</config>

The declaration, if present, must be the very first thing in the file. Comments can go almost anywhere else, but not inside a tag, and they can't contain --.