XML Well-Formedness: The Rules and How to Fix Common XML Errors
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
- There is exactly one root element.
- Every start tag has a matching end tag, or the element is self-closing:
<br/>. - Elements nest properly:
<a><b></b></a>, never<a><b></a></b>. - Names are case-sensitive:
<Item>must close with</Item>. - Attribute values are quoted, with single or double quotes, and an attribute appears only once per element.
<and&are escaped in text and attribute values.- An XML declaration, if present, comes first:
<?xml version="1.0" encoding="UTF-8"?>.
Escaping special characters
| Character | Entity | When |
|---|---|---|
| < | < | Required in text and attributes |
| & | & | Required in text and attributes |
| > | > | Recommended; required after ]] |
| " | " | Inside double-quoted attributes |
| ' | ' | 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) | Cause | Fix |
|---|---|---|
| Opening and ending tag mismatch | Tags closed in the wrong order or with different case | Match names exactly and close the innermost element first |
| EntityRef: expecting ';' | A bare & in text such as "R&D" | Write R&D |
| Extra content at the end of the document | Two root elements | Wrap them in one root element |
| Namespace prefix is not defined | A prefix used without its xmlns declaration | Declare 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).