Entities are a mechanism to define replacement values, an entity name is declared, and when that name is referenced the entity value is read in its place. Entity values can be defined in line (Internal) or read from a uri (External). The entity value data substituted in is normally treated as XML and parsed, however this behavior can be modified (see Unparsed Entities).

Parsed Internal General Entity Declaration

<!ENTITY entityName "entityValue">

Internal entities are a mechanism to define replacement values, whenever the entityName is referenced in the XML document, the entityValue is substituted in its place. The XML Parser parsers the substituted entityValue as XML data.

<!ENTITY CompanyName 'Liquid Technologies Ltd' >

This defines an Entity called "CompanyName", that when used will be replaced by the value "Liquid Technologies Ltd".

Entities can be referenced using the notation &EntityName;

<Vendor>&CompanyName;</Vendor>

<Vendor>Liquid Technologies Ltd</Vendor>

<Vendor name="&CompanyName;" />

<Vendor name="Liquid Technologies Ltd" />

<?xml version="1.0" standalone="no"?>
<!DOCTYPE product [
  <!ELEMENT product (name, manufactuer)>
  <!ELEMENT name (#PCDATA)>
  <!ELEMENT manufactuer (#PCDATA)>
  <!ENTITY CompanyName "Liquid Technologies">
]>
<product>
  <name>Liquid XML Studio</name>
  <manufactuer>&CompanyName;</manufactuer>
</product>

Pre-defined Entities

The XML standard also defines a set of pre-defined entities.

Parsed External General Entity Declaration

<!ENTITY entityName SYSTEM "entityUri">
<!ENTITY entityName PUBLIC "publicID" "entityUri">

A Parsed External General Entity Declaration is much the same as a XML Entity Refs except that the value for the replacement is read from an external file. As the XML Parser reads the data from the referenced entityUri (or retrieves it via the publicID), it parses it as XML data. This can be used to modularize large XML documents, i.e. a book could have every chapter stored in a separate file, and external entity references could be used pull them all together. They can also be used to hold common data, meaning only a single point of change should the shared data need amending.

Notes

• Data within an external file does not have to be XML data, it can just be character data, but if it does contain element tags then they must all balance up (i.e. be well formed).
• The data within an external entity file can itself contain entity references, but circular references are not allowed.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE experiment_a [
  <!ELEMENT book (chapter)*>
  <!ELEMENT chapter ANY>
  <!ENTITY BookChapter1 SYSTEM "Chapter1.xml">
]><book>&BookChapter1;</book>

Unparsed External General Entity Declaration

<!ENTITY entityName SYSTEM "entityUri" NDATA dataType>

If the ENTITY declaration contains the NDATA tag then the data read from the entityUri is not parsed and treated as data of type determined by the dataType argument.

The dataType argument is a reference to a NOTATION, which provides the consuming application within information about the type of data that will be contained at the entityUri.

This mechanism allows non-XML data to be brought into an XML Document.

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE img [
  <!ELEMENT img EMPTY>
  <!ATTLIST img src ENTITY #REQUIRED> 
  <!ENTITY companyLogo PUBLIC "-//W3C//GIF logo//EN" "http://www.w3.org/logo.gif" NDATA gif>
  <!NOTATION gif PUBLIC "gif viewer">
]>
<img src="companyLogo"/> 

Parsed Internal Parameter Entity Declaration

Parameter entities are very similar to general entities, except they can only be used within the structure of the DTD itself (i.e. they can not appear within the XML document elements, attributes or processing instructions).

Parameter entities are defined in a similar way, but prefixed with a %

<!ENTITY % ParameterEntityName SYSTEM "uri">

<!ENTITY % copyright '&#169;'>
<!ENTITY CompanyName 'Liquid Technologies Ltd %copyright;' >

<Vendor>Liquid Technologies %copyright;</Vendor>

Parsed External Parameter Entity Declaration

Parameter entities are very similar to external general entities, except they can only be used within the structure of the DTD itself (i.e. they can not appear within the XML document elements, attributes or processing instructions).

Parameter entities are defined in a similar way, but prefixed with a %

<!ENTITY % ParameterEntityName SYSTEM "uri">
<!ENTITY % ParameterEntityName PUBLIC "PublicID" "uri">

When the XML Parser reads the text referenced by the external entity it must treat it as DTD data and parse it accordingly.

This mechanism allows external DTD's to be included, which can make it possible to modularize DTD's for better manageability or re-use.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE invoice [
  <!ENTITY % addressTypes SYSTEM "http://www.liquid-technologies.com/AddressCommon.dtd">
  %addressTypes;
  ...
]> 

EBNF Syntax