XML Syntax Rules

A small, well-formed document

<?xml version="1.0" encoding="UTF-8"?>
<!-- a comment -->
<library xmlns:dc="http://purl.org/dc/elements/1.1/">
  <book id="b1" available="true">
    <title>Tom &amp; Jerry</title>
    <dc:creator>Alex</dc:creator>
    <note><![CDATA[Use <b> for bold]]></note>
    <cover/>
  </book>
</library>

The rules

1. One root element. The whole document sits inside a single element. Only comments, processing instructions and whitespace may come before or after it.
2. Every element is closed. Each start tag has an end tag, or the element is written as an empty element with a slash: <cover/>.
3. Elements nest properly. The tag opened last is closed first. <a><b></a></b> is wrong.
4. Names are case sensitive. <Name> and <name> are different elements.
5. Attribute values are always in quotes, single or double, and an attribute may appear only once per element.
6. Special characters are escaped in text and attribute values.
7. Names start with a letter, an underscore or a colon, and continue with letters, digits, dots, hyphens, underscores and colons. They cannot contain spaces. Names that start with xml are reserved.

The five predefined entities

XML does not have the named entities of HTML, such as   or ©, unless a DTD declares them. Use a number instead:   or  . The HTML entities guide explains the forms.

CDATA sections

A CDATA section holds text in which < and & need no escaping: <![CDATA[ a < b && c ]]>. It ends at the first ]]>, so that sequence cannot appear inside. CDATA is only for text, and it cannot be used in attribute values.

Comments and processing instructions

• A comment is <!-- ... -->. The string -- is not allowed inside, and a comment cannot end with --->.
• A processing instruction is <?target data?>. The target xml is reserved for the declaration.
• The XML declaration <?xml version="1.0" encoding="UTF-8"?> is optional, but when it is there it must be the very first thing in the file, with no space before it.

Namespaces

Namespaces keep names from different vocabularies apart. A prefix is declared with an attribute: xmlns:dc="http://purl.org/dc/elements/1.1/", and then used as dc:creator. The declaration applies to the element and everything inside it. A plain xmlns="..." sets a default namespace for elements without a prefix. Using a prefix that nobody declared is an error.

Whitespace

XML keeps whitespace in text, and it leaves the meaning to the application. Programs usually ignore the spaces between elements, and keep the spaces in text. Where the exact spaces matter, add xml:space="preserve" to the element. This is why XML formatters must take care with mixed content. The XML formatting guide goes into this.

XML or HTML?

Encoding

XML documents are UTF-8 unless the declaration says otherwise. If the declared encoding does not match the real file, or if the file contains a character that the encoding cannot hold, parsers fail with errors about invalid characters. Save the file in the encoding that it declares, and prefer UTF-8.

Fixing errors

• Read the first error first. Later errors are often caused by it.
• Look at the line before the reported one. A missing quote or bracket is often only noticed on the next line.
• Escape ampersands. A bare & in a URL or in text is the most common cause. Write ?a=1&b=2.
• Check the case of start and end tags.

Tools

• XML validator, XML formatter, XML beautifier and XML minifier.
• XML to JSON and JSON to XML, and the JSON vs XML guide.
• On the command line: xmllint --noout file.xml checks a file, and xmllint --format file.xml formats it.