Document syntax
Character reference
A &#nnn; or &#xhhhh; escape naming a Unicode code point directly, rather than by an entity name.
Character references are resolved by the parser into the character they name, before anything downstream sees the document. They need no declaration — unlike entity references, they are part of the language — so they work in any document, including one with no DOCTYPE.
They are the escape hatch for characters your encoding cannot carry, and for the ones your tooling mangles. They also differ from literal characters in one place that matters: attribute-value normalization replaces a literal tab with a space, but leaves 	 alone.
- Defined in
- XML 1.0 §4.1
- Category
- Document syntax
- Also written
- &, &, numeric entity
Shown, not asserted
All 3 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.
A decimal reference resolves to its character.
document.xml <x>café</x>expression string(/x)What the engine returns
caféThe hexadecimal form names the same code point.
document.xml <x>café</x>expression string(/x)What the engine returns
caféA reference to a code point XML forbids is an error, not a substitution.
document.xml <x>ab</x>What the engine returns
xmlParseCharRef: invalid xmlChar value 1 (line 1)
What catches people out
- The hexadecimal form needs the x: & is an ampersand,  is a control character and illegal.
- A character reference resolves before validation, so a pattern facet sees the resolved character rather than the escape.
- Referencing a character XML 1.0 forbids is fatal even though the escape itself looks well-formed.
Where it bites
A definition on its own is trivia. These are the pages where this term decides whether a document works.
- Parse errorsInvalid numeric character referenceThe message a reference to a forbidden code point produces.
- Parse errorsCharRef: invalid decimal valueWhat a malformed numeric reference reports.
- ToolsXML escape & unescapeProduces the references for you, and resolves them in the other direction.
Related terms
- Entity referenceAn &name; reference to an entity, replaced by that entity's replacement text during parsing.
- Predefined entityOne of the five entities every XML parser knows without a declaration: &, <, >, ' and ".
- Invalid XML characterA code point XML forbids in a document at all — most of the C0 control range — which cannot be included literally or as an escape.
- Attribute-value normalizationThe parser's rewriting of attribute values before anything sees them: literal tabs, newlines and carriage returns become spaces.
- UTF-8The default encoding for XML, and the one every conforming parser must support along with UTF-16.
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.