XML syntax and well-formedness
Elements, attributes, entities and CDATA, plus the exact rules a document must satisfy to be well-formed.
The shape of a document
XML is a text format for trees. A document is a single root element containing nested elements, text and comments, and a parser rejects anything that breaks the nesting rules. A document the parser accepts is well-formed — a different question from whether it is valid against a schema.
<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://example.com/shop" version="1.0">
<!-- attributes are unstructured: order and repetition are not modelled -->
<book id="bk-101" available="true">
<title lang="en">Structured Data</title>
<price currency="USD">39.95</price>
<description><![CDATA[Contains & and angle brackets like <these> without escaping]]></description>
</book>
</catalog>- The declaration is optional but, if present, must be the first thing in the file — no BOM, no leading newline.
- Elements form the tree; attributes hang off elements and carry no ordering.
- Comments are for humans and are usually dropped by parsers that build a data model.
- Text between elements is real content, so indentation becomes data unless a schema says otherwise.
The well-formedness rules
- Exactly one root element, wrapping everything else.
- Every start tag has a matching end tag, correctly nested — overlapping tags are fatal.
- Names are case-sensitive:
<Book>and<book>are different elements. - Attribute values are always quoted, and the same attribute name may not appear twice on one element.
- The predefined entities must be escaped:
<>&"'. - Comments may not contain a double hyphen and may not sit inside a tag.
- Literal angle brackets in text need CDATA or escaping.
- An element name may not start with a digit, a hyphen or the letters x-m-l in any casing.
| Text you want | Escaped form | Why |
|---|---|---|
< | < | Otherwise it starts a tag |
& | & | Otherwise it starts an entity |
> | > | Technically optional, recommended |
| Double quote | " | Needed inside a double-quoted attribute |
| Apostrophe | ' | Needed inside a single-quoted attribute |
| Any character | © or © | Numeric character reference |
<!-- wrong: overlapping tags -->
<b><i>text</b></i>
<!-- right -->
<b><i>text</i></b>
<!-- wrong: a bare ampersand is an entity error -->
<p>Fish & chips</p>
<!-- right -->
<p>Fish & chips</p>
<!-- wrong: an attribute without quotes -->
<item id=42>
<!-- right: quoted, and unique per element -->
<item id="42">⚠️
Whitespace matters. Removing indentation to save bytes collapses text nodes that a human reader assumed were separate — and adding it can break a schema that forbids stray text in an element-only content model.
Attributes or child elements?
- Use an attribute for metadata that is short, atomic and never repeated: identifiers, units, language tags.
- Use a child element for anything that may repeat, contain markup, or carry its own attributes.
- Attributes have no order and cannot be grouped, so sequence-like data belongs in elements.
- XML has no null: represent absence by omitting the element, or by an explicit empty value plus a documented convention.
FAQ
Well-formed or valid?
Well-formed means any XML parser can read the document. Valid means it also conforms to a DTD or XSD. The first is mandatory, the second is a deliberate contract.
Why does my document fail on the XML declaration?
Usually a byte-order mark or whitespace precedes it. Save as UTF-8 without a BOM, or make sure the declaration is the very first byte sequence.
Related
Namespaces Validation with DTD and XSD
Last refreshed 2026-09-18.