Document syntax
Entity reference
An &name; reference to an entity, replaced by that entity's replacement text during parsing.
XML predefines exactly five entity names. Every other name has to be declared, in the internal subset or in an external DTD, before it can be referenced — which is why fails in XML while working everywhere in HTML.
Expansion happens during parsing, so nothing downstream can tell whether a character arrived literally or through an entity. That is also what makes entities a security surface: the replacement text can be fetched from elsewhere, or can expand exponentially.
- Defined in
- XML 1.0 §4.1
- Category
- Document syntax
- Also written
- &name;
Shown, not asserted
All 2 claims are executed on every test run, against the same engines the tools use. If the behaviour changes, the test fails rather than this page quietly becoming wrong.
An undeclared entity is fatal. is an HTML entity, not an XML one.
document.xml <x>Ada Lovelace</x>What the engine returns
Entity 'nbsp' not defined (line 1)A declared one resolves before anything downstream sees the document.
document.xml <!DOCTYPE x [<!ENTITY nbsp " ">]> <x>Ada Lovelace</x>expression string-length(string(/x))What the engine returns
12
What catches people out
- Only &, <, >, ' and " are predefined. Everything else needs a declaration, including every HTML entity you know by name.
- An entity reference inside an attribute value is expanded there too, so the same rules apply within quotes.
- Because expansion is invisible downstream, a document's byte size is a poor guide to how much text it will produce.
Where it bites
A definition on its own is trivia. These are the pages where this term decides whether a document works.
- Parse errorsEntity is not definedThe message an undeclared entity name produces — most often .
- Parse errorsDetected an entity reference loopWhat happens when entities reference each other in a cycle.
- ToolsXML escape & unescapeConverts text to the predefined entities, which never need declaring.
Related terms
- Predefined entityOne of the five entities every XML parser knows without a declaration: &, <, >, ' and ".
- General entityAn entity declared with <!ENTITY name "text"> whose replacement text is substituted wherever &name; appears in content.
- Character referenceA &#nnn; or &#xhhhh; escape naming a Unicode code point directly, rather than by an entity name.
- Internal subsetThe markup declarations written inline between square brackets in a DOCTYPE, rather than fetched from an external DTD file.
- Entity expansion attackA denial of service in which nested entity definitions expand exponentially, turning a few hundred bytes of document into gigabytes of text.
Get started
Bring order to the XML your team can't afford to ignore.
Create a free account and get a private workspace to search, validate, diff, and monitor your XML feeds, sitemaps, schemas, and vendor integrations.