How Does XSLT Output Encoding Work?

The encoding attribute in the <xsl:output> element defines the character encoding scheme used by an XSLT processor when serializing the result tree into a byte stream. By specifying an encoding standard such as UTF-8, UTF-16, or ISO-8859-1, you instruct the serializer how to represent characters in the target document, write matching declaration headers, and automatically fall back to numeric character references when a character falls outside the target character set.

Role of the encoding Attribute

In XSLT, transformations occur in an abstract node-tree model where characters exist as independent Unicode code points. Character encoding only becomes relevant during the final serialization step, when the internal result tree is written out as raw text, HTML, or XML bytes.

The <xsl:output> element controls these serialization parameters:

<xsl:output method="xml" encoding="UTF-8" indent="yes"/>

When the processor serializes the output, the encoding attribute dictates:

• The binary encoding scheme used to save the file.
• The value placed inside the generated XML declaration (e.g., <?xml version="1.0" encoding="UTF-8"?>) or HTML <meta> charset tag.
• How the processor resolves characters that cannot be directly represented in the selected encoding.

Handling Unrepresentable Characters

Different character encodings support different subsets of the Unicode character repertoire. If a transformation produces a character that does not exist in the designated target encoding, the XSLT serializer handles it based on the output method:

• XML Output (method="xml"): The processor converts unrepresentable characters into numeric character references (NCRs), such as decimal (©) or hexadecimal (©) entities. This ensures the output remains well-formed XML without loss of data.
• HTML Output (method="html"): The serializer converts unrepresentable characters into named entity references (like ©) or numeric character references.
• Text Output (method="text"): Because plain text formats do not support XML/HTML entity escaping, unrepresentable characters cannot be turned into character references. The processor will either signal a serialization error or substitute a replacement character (such as ?), depending on the specific XSLT processor implementation and configuration.

Default Encoding Behaviors

If the encoding attribute is omitted from <xsl:output>, XSLT processors apply default values:

• XML Serialization: Defaults to UTF-8 or UTF-16.
• HTML Serialization: Typically defaults to ISO-8859-1 or UTF-8, depending on the XSLT version (XSLT 2.0+ defaults to UTF-8).
• Text Serialization: Often defaults to the system's native platform encoding or UTF-8.

Overriding and Unsupported Encodings

The values supplied to the encoding attribute must match registered charset names recognized by the Internet Assigned Numbers Authority (IANA) or standard Java/C# charset aliases supported by your runtime environment.

If you specify an encoding name that the XSLT processor does not recognize or support, standard XSLT behavior dictates that the processor must either raise an error or fall back to an encoding it does support (typically UTF-8 or UTF-16). When a fallback occurs, the generated output declaration reflects the actual encoding used rather than the unsupported requested value.