Document syntax
Character reference
A &#nnn; or &#xhhhh; escape naming a Unicode code point directly rather than by an entity name. It needs no declaration, unlike an entity reference.
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 replaced by that entity's replacement text during parsing. Only five names are predefined, which is why fails in XML.
- Predefined entityThe five entities every XML parser knows without a declaration: &, <, >, ' and ". Only two of them must always be escaped.
- 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 one of the two every conforming parser must support. A file with no declaration and no BOM is UTF-8 by definition.
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.