XML - XML Entities and Entity References

XML entities are a mechanism used to represent certain pieces of data or characters within an XML document. Instead of writing a character or a repeated piece of content directly, an entity can provide a reference that the XML parser replaces with its corresponding value during processing. Entities are particularly useful when XML contains reserved characters, special characters, or reusable content.

1. What Is an XML Entity?

An XML entity is a named reference to a piece of data. The entity can represent a single character, a sequence of characters, or, in some cases, external content.

For example, XML uses certain characters for its own syntax. The < character indicates the beginning of an element, so it cannot normally be written directly as text when it could be interpreted as markup.

Instead, XML provides a predefined entity:

<message>5 &lt; 10</message>

Here, < represents the < character. When the XML document is processed, the parser interprets < as <.

2. Entity References

An entity reference is the syntax used to refer to an entity. It generally begins with & and ends with ;.

The general form is:

&entityName;

For example:

&copy;

If an entity named copy has been declared, the parser can replace this reference with its associated value.

Character references are another closely related mechanism. They allow characters to be represented by their Unicode code point.

Decimal character reference:

&#169;

Hexadecimal character reference:

&#xA9;

Both represent the copyright symbol.

3. Predefined XML Entities

XML defines five predefined entities that are especially important because their corresponding characters have special meanings in XML syntax.

Entity	Character	Purpose
`<`	`<`	Less-than symbol
`>`	`>`	Greater-than symbol
`&`	`&`	Ampersand
`"`	`"`	Double quotation mark
`'`	`'`	Apostrophe/single quotation mark

For example:

<comparison>10 &lt; 20</comparison>

The parser interprets this as:

10 < 20

Another example is:

<text>Tom &amp; Jerry</text>

The resulting text is:

Tom & Jerry

The ampersand is particularly important because it introduces an entity reference. Therefore, writing a raw & in ordinary XML text can make the document invalid if it is not part of a valid entity or character reference.

4. Character References

Character references allow XML documents to represent characters using their numeric Unicode values.

There are two forms.

Decimal Character Reference

&#65;

This represents the character A, because Unicode code point 65 corresponds to A.

Hexadecimal Character Reference

&#x41;

This also represents A.

For example:

<letter>&#65;</letter>

and:

<letter>&#x41;</letter>

both represent:

Character references are useful when a character is difficult to enter directly or when maintaining consistent character representation across systems.

5. General Entities

General entities are named entities that can be referenced throughout an XML document.

They can be declared using a Document Type Definition (DTD).

For example:

<!DOCTYPE company [
    <!ENTITY companyName "ABC Technologies">
]>
<company>
    <name>&companyName;</name>
</company>

Here, companyName is a custom entity. The reference:

&companyName;

is replaced with:

ABC Technologies

The resulting logical content is:

<name>ABC Technologies</name>

This can be useful when the same piece of information appears repeatedly.

6. Internal Entities

An internal entity contains its replacement value directly within the XML document's DTD.

Example:

<!DOCTYPE product [
    <!ENTITY company "ABC Corporation">
]>
<product>
    <manufacturer>&company;</manufacturer>
</product>

The entity declaration is:

<!ENTITY company "ABC Corporation">

Whenever &company; occurs in the document, it refers to the declared replacement text.

Internal entities are relatively simple because all information required to resolve the entity is contained within the document itself.

7. External Entities

External entities refer to content stored outside the main XML document.

For example:

<!DOCTYPE document [
    <!ENTITY information SYSTEM "information.txt">
]>
<document>
    <content>&information;</content>
</document>

Here, the entity information refers to an external resource named information.txt.

External entities can be useful when large or reusable content needs to be maintained separately. However, they require careful security consideration because an XML parser may be instructed to access external resources.

Modern XML applications commonly disable unnecessary external entity processing to reduce security risks.

8. Parameter Entities

Parameter entities are primarily used inside DTD declarations. Unlike general entities, they are referenced using %.

For example:

<!DOCTYPE employee [
    <!ENTITY % commonAttributes "id CDATA #REQUIRED">
    <!ELEMENT employee (#PCDATA)>
    <!ATTLIST employee %commonAttributes;>
]>

The %commonAttributes; reference is used within the DTD itself.

Parameter entities can make complex DTD definitions more modular and reusable.

9. Entity References in Attribute Values

Entity references can also appear in XML attribute values.

For example:

<product name="Tom &amp; Jerry"/>

The XML representation contains:

&amp;

which represents the actual ampersand character.

Similarly:

<message text="5 &lt; 10"/>

represents an attribute whose value is:

5 < 10

Using the appropriate entity references ensures that reserved XML characters do not interfere with the document's structure.

10. Why Entities Are Important

XML entities serve several important purposes.

First, they allow reserved characters to be safely represented. For example, < and & have special meanings in XML syntax.

Second, entities can provide reusable content. A frequently repeated value can be declared once and referenced multiple times.

Third, character references provide a standardized way of representing Unicode characters.

Fourth, entities can help separate content into external resources, although external entities should only be used when there is a clear requirement and appropriate security controls.

11. Entities and Well-Formed XML

Incorrect entity usage can cause an XML document to become not well-formed.

For example:

<message>Tom & Jerry</message>

is problematic because the ampersand begins an entity reference, but Jerry is not a valid declared entity reference in this context.

The correct representation is:

<message>Tom &amp; Jerry</message>

Similarly:

<value>5 < 10</value>

should be written as:

<value>5 &lt; 10</value>

Correct entity usage is therefore an important part of writing valid XML documents.

12. Entities vs Character References

Although both mechanisms can represent characters, they are not exactly the same.

An entity reference normally refers to a named entity:

&amp;

A character reference identifies a character by its numeric Unicode value:

&#38;

or:

&#x26;

All three can represent an ampersand character, but they use different mechanisms.

13. Practical Example

Consider an XML document containing product information:

<product>
    <name>Tom &amp; Jerry Collection</name>
    <description>Price &lt; $50</description>
    <copyright>&#169; 2026 ABC Corporation</copyright>
</product>

Here:

&amp;

represents &.

&lt;

represents <.

&#169;

represents the copyright symbol.

The parser interprets these references and makes the corresponding characters available to the application.

14. Important Security Consideration

External XML entities can introduce security vulnerabilities when an XML parser automatically processes external resources. An application that accepts XML from untrusted sources should therefore configure its XML parser carefully.

In particular, developers should understand whether the parser permits external entity resolution, external DTD retrieval, and access to local or network resources.

This is why XML entity handling is not only a syntax concept but also an important application-security topic.

15. Summary

XML entities provide a mechanism for representing special characters, reusable content, and external resources within XML documents. The most commonly encountered entities are the five predefined entities: <, >, &, ", and '. Character references such as A and A provide another way to represent Unicode characters.

Custom entities can be declared through DTDs and can be internal, external, or parameter entities. While entities can improve XML flexibility and reusability, external entities require particular attention because of their potential security implications.

Understanding entities and entity references is therefore essential for creating well-formed XML documents, handling special characters correctly, working with DTDs, and developing secure XML-processing applications.