Document syntax
Parameter entity
An entity declared with <!ENTITY % name "…"> and referenced as %name;, usable only inside markup declarations rather than in document content.
Parameter entities are DTD-internal machinery: they let one DTD compose another, parameterise a content model, or switch a block of declarations on and off. They never appear in a document's content, and a %name; in element content is simply a percent sign followed by text.
They are also the most dangerous corner of the DTD grammar. A parameter entity can be defined in terms of an external resource and is expanded inside declarations, which is what makes blind XXE possible. Our pipeline refuses them rather than implementing them.
- Defined in
- XML 1.0 §4.1
- Category
- Document syntax
- Also written
- %name;, PE
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.
A percent sign in ordinary content is just a character — parameter entities do not apply there.
document.xml <x>100% parsed</x>What the engine returns
Well-formed.Inside a declaration, our pipeline reads the document but refuses to build structure from it.
document.xml <!DOCTYPE x [<!ENTITY % p "<!ENTITY inner 'deep'>"> %p;]> <x>&inner;</x>What the engine returns
Well-formed. The document is well-formed, but its structure could not be extracted: Invalid entity name %
What catches people out
- %name; in content is not a reference to anything. Only markup declarations see parameter entities.
- Parameter entity expansion inside an external DTD is how blind XXE exfiltrates data, which is why so many parsers disable it.
- The space in <!ENTITY % name …> is required by the grammar.
Where it bites
A definition on its own is trivia. These are the pages where this term decides whether a document works.
Related terms
- General entityAn entity declared with <!ENTITY name "text"> whose replacement text is substituted wherever &name; appears in content.
- Internal subsetThe markup declarations written inline between square brackets in a DOCTYPE, rather than fetched from an external DTD file.
- DTDThe original XML schema language: element and attribute declarations written in their own non-XML syntax, plus the entity declarations nothing else provides.
- XXE (XML external entity attack)An attack in which a submitted document declares an external entity so that a trusting parser reads a local file or makes a request on the attacker's behalf.
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.