XML Well-Formedness: The Rules and How to Fix Common XML Errors

Published · Updated

Before an XML document can be validated against a schema, or used at all, it has to be well-formed. The rules are strict but short. This guide lists them with examples and explains the error messages browsers and libraries produce when one is broken.

The well-formedness rules

  1. There is exactly one root element.
  2. Every start tag has a matching end tag, or the element is self-closing: <br/>.
  3. Elements nest properly: <a><b></b></a>, never <a><b></a></b>.
  4. Names are case-sensitive: <Item> must close with </Item>.
  5. Attribute values are quoted, with single or double quotes, and an attribute appears only once per element.
  6. < and & are escaped in text and attribute values.
  7. An XML declaration, if present, comes first: <?xml version="1.0" encoding="UTF-8"?>.

Escaping special characters

CharacterEntityWhen
<&lt;Required in text and attributes
&&amp;Required in text and attributes
>&gt;Recommended; required after ]]
"&quot;Inside double-quoted attributes
'&apos;Inside single-quoted attributes

For long passages containing many special characters, a CDATA section avoids escaping: <![CDATA[ 1 < 2 && 3 > 2 ]]>. The XML Escape tool escapes text for you.

Well-formed versus valid

A well-formed document follows the syntax rules above. A valid document is well-formed and follows a schema (XSD, DTD or RELAX NG) that says which elements and attributes are allowed. Convert Ferry's XML tools check well-formedness; schema validation needs the schema and a validating parser in your own environment.

Common errors and their fixes

Message (Chrome wording)CauseFix
Opening and ending tag mismatchTags closed in the wrong order or with different caseMatch names exactly and close the innermost element first
EntityRef: expecting ';'A bare & in text such as "R&D"Write R&amp;D
Extra content at the end of the documentTwo root elementsWrap them in one root element
Namespace prefix is not definedA prefix used without its xmlns declarationDeclare it, for example xmlns:soap="..."
Attribute without value or quotes<item id=5>Quote it: id="5"

Messages differ slightly between browsers and libraries, but they point to the same problems. The XML Validator shows the line and column.

Namespaces in brief

Namespaces let one document combine vocabularies without name clashes, which is why SOAP messages are full of prefixes:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getPrice><sku>A-1</sku></getPrice>
  </soap:Body>
</soap:Envelope>

The prefix (soap) is only a shorthand; the namespace URI is what identifies the vocabulary. Paste a message like this into the XML Formatter to indent it.

Frequently asked questions

Is HTML well-formed XML?

Not necessarily. HTML allows unclosed elements such as p and li and unquoted attributes. XHTML is the XML-compatible form.

Does whitespace matter in XML?

Whitespace in text content is preserved. Whitespace between elements is usually insignificant, which is why formatting and minifying are safe for most documents.

Can XML element names start with a number?

No. Names must start with a letter or underscore (and may contain digits, hyphens and dots after that).

Related guides