How Does the match Attribute in XSLT Work?

The match attribute in XSLT templates defines pattern-matching rules that determine which nodes in an XML source document are processed by specific <xsl:template> blocks. By utilizing a subset of XPath expressions known as Match Patterns, the XSLT processor evaluates nodes against these patterns during recursive tree traversals. Understanding how match identifies candidate templates, resolves conflicts using default and explicit priorities, and integrates with structural context is essential for building predictable and maintainable XML transformations.

The Role of Match Patterns in Template Invocation

Unlike the select attribute—which actively queries and navigates the node tree from the current context—the match attribute acts as a passive filter. When an instruction like <xsl:apply-templates/> is encountered, the processor evaluates the child nodes or selected node-set against all available template rules in the stylesheet.

A template is considered a candidate for execution if the current node satisfies the pattern defined in its match attribute. Match patterns typically match node types, element names, attribute names, or specific hierarchical structures:

• Node-type patterns: match="node()", match="text()", or match="*"
• Element names: match="book" or match="author"
• Path patterns: match="catalog/book/title"
• Predicate patterns: match="book[@category='fiction']"

When multiple templates match a given node, the XSLT processor relies on a strict resolution algorithm to select the winning template.

Conflict Resolution and Template Priority

When more than one template matches a single node, the processor applies conflict resolution rules based on template import precedence, explicit priority attributes, and default computed priorities.

1. Import Precedence

Templates defined in the main stylesheet take precedence over templates brought in via <xsl:import>. Imported templates have lower precedence and are only considered if no matching template exists in the importing stylesheet, unless invoked explicitly via <xsl:apply-imports/>.

2. Explicit Priority

Stylesheet authors can override automatic conflict resolution by assigning a numerical priority attribute to a template:

<xsl:template match="book" priority="2">
    <!-- This executes over lower priority matches -->
</xsl:template>

Higher numbers take precedence over lower numbers.

3. Computed Default Priority

If no explicit priority is provided, the XSLT specification calculates a default priority based on pattern specificity:

• Priority +0.5: Specific path or predicate patterns (e.g., match="catalog/book", match="book[@id]").
• Priority 0: Simple element or attribute names (e.g., match="book", match="@id").
• Priority -0.25: Wildcard names with specific namespaces or processing-instruction targets (e.g., match="prefix:*").
• Priority -0.5: Generic wildcards and node-type tests (e.g., match="*", match="node()", match="text()").

If two matching templates share the same import precedence and computed priority, the XSLT processor reports an error or selects the template that appears last in the stylesheet.

Built-In Default Templates

If no user-defined template matches a node, XSLT invokes its built-in rule. For element and root nodes, the default rule recurses through child nodes by executing <xsl:apply-templates/>. For text and attribute nodes, the default rule copies the text value directly to the output. Defining a custom template with a match attribute effectively overrides these default behaviors for all matching nodes.