XSLT Reference
unparsed-entity-uri()
Returns the URI of an unparsed entity declared in the DTD of the source document, given the entity's name.
unparsed-entity-uri(name)Description
unparsed-entity-uri() retrieves the system identifier (URI) of an unparsed entity declared in the DTD of the source document. Unparsed entities are a DTD mechanism for embedding references to non-XML resources — typically binary files such as images, audio, or video — inside an XML document using ENTITY and NOTATION declarations.
Given the entity name (a string), the function returns the entity’s system identifier URI as declared in the DTD. If no unparsed entity with that name exists in the document’s DTD, the function returns the empty string "".
This function is rarely needed in modern XML processing. DTD-based unparsed entities have largely been superseded by direct URI references in attribute values or XLink. However, unparsed-entity-uri() remains the correct tool when processing legacy documents that rely on this mechanism.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | xs:string | Yes | The name of the unparsed entity as declared in the DTD. |
Return value
xs:string — the system identifier URI of the unparsed entity, or "" if not found.
Examples
Retrieve an image URI from an unparsed entity
Input XML (with DTD):
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE catalog [
<!NOTATION JPEG SYSTEM "image/jpeg">
<!ENTITY photo1 SYSTEM "images/photo1.jpg" NDATA JPEG>
<!ENTITY photo2 SYSTEM "images/photo2.jpg" NDATA JPEG>
<!ELEMENT catalog (product+)>
<!ELEMENT product EMPTY>
<!ATTLIST product name CDATA #REQUIRED image ENTITY #REQUIRED>
]>
<catalog>
<product name="Widget" image="photo1"/>
<product name="Gadget" image="photo2"/>
</catalog>
Stylesheet:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" indent="yes"/>
<xsl:template match="/catalog">
<html><body>
<xsl:for-each select="product">
<div>
<p><xsl:value-of select="@name"/></p>
<img src="{unparsed-entity-uri(@image)}" alt="{@name}"/>
</div>
</xsl:for-each>
</body></html>
</xsl:template>
</xsl:stylesheet>
Output:
<html><body>
<div>
<p>Widget</p>
<img src="images/photo1.jpg" alt="Widget"/>
</div>
<div>
<p>Gadget</p>
<img src="images/photo2.jpg" alt="Gadget"/>
</div>
</body></html>
Guard against missing entity
Input XML (with DTD as above):
Stylesheet:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes"/>
<xsl:template match="/catalog">
<results>
<xsl:for-each select="product">
<xsl:variable name="uri" select="unparsed-entity-uri(@image)"/>
<product name="{@name}">
<xsl:choose>
<xsl:when test="$uri != ''">
<image src="{$uri}"/>
</xsl:when>
<xsl:otherwise>
<image src="placeholder.jpg"/>
</xsl:otherwise>
</xsl:choose>
</product>
</xsl:for-each>
</results>
</xsl:template>
</xsl:stylesheet>
Notes
- The function only works when the source document is accompanied by a parsed DTD that includes the relevant
ENTITYandNOTATIONdeclarations. - If the XML processor is not validating or has not read the DTD, unparsed entity declarations may not be available, and the function will return
"". unparsed-entity-uri()is scoped to the context document only. It looks up entities in the DTD of the document containing the context node, not the stylesheet or any other loaded document.- In XSLT 2.0+, the function is available as
fn:unparsed-entity-uri()with the same semantics. A companion functionfn:unparsed-entity-public-id()was added to retrieve the public identifier. - Modern XML workflows rarely use unparsed entities. For new designs, prefer storing URIs directly in attributes without DTD entity indirection.