ates prevents silent text leakage in complex documents.

• The sweet spot for enterprise stylesheets lies in combining apply-templates with explicit priorities and named modes.

Core Solution

How Match Patterns Work

When the processor visits a node, it evaluates every template's match attribute as an XPath pattern. A pattern is a restricted form of XPath that tests properties of a node rather than selecting nodes from a starting point. If the pattern is satisfied, that template is a candidate.

Priority and Conflict Resolution

More than one template can match the same node. The processor resolves the conflict using priority. Each pattern has a default priority calculated by the spec:

Pattern type	Default priority
node() or *	-0.5
element-name	0
prefix:element-name	0
a/b (path)	0.5
a[predicate]	0.5
@attr	0

More specific patterns automatically get higher priority. You can override this with the priority attribute:

Enter fullscreen mode Exit fullscreen mode

If two templates have equal computed priority, the processor signals an error (or picks the last one, depending on implementation — Saxon issues an error by default). Always assign explicit priorities when you have competing templates.

The Built-in Templates

XSLT has default templates for every node type. If no explicit template matches a node, the built-in fires. For elements and the document root, the built-in calls apply-templates on all children. For text and attribute nodes, it outputs the string value.

This means that without any templates at all, the processor will walk the entire tree and output all text content. Understanding this explains why simple stylesheets can produce unexpected extra text — a text node matched nothing explicit, and the built-in output it.

To suppress text output globally, add:

Enter fullscreen mode Exit fullscreen mode

This overrides the built-in with an empty template, producing no output for text nodes that are not handled elsewhere.

Modes

Modes let you have multiple templates for the same node that serve different purposes. A mode is a named context for a set of templates.

## 

Enter fullscreen mode Exit fullscreen mode

Call with mode:

Enter fullscreen mode Exit fullscreen mode

Modes are especially useful when you need to process the same nodes in multiple places in the output with different logic each time.

apply-templates vs for-each

Both iterate over a set of nodes. The difference is that apply-templates dispatches to the best matching template for each node, while for-each stays in the current context and does not do template lookup.

Use apply-templates when you want polymorphism — different node types handled differently. Use for-each when you are doing a simple iteration over a homogeneous set and do not need dispatch.

  - 

Enter fullscreen mode Exit fullscreen mode

Testing Patterns in XSLT Playground

XSLT Playground is a fast way to experiment with matching rules. Paste a stylesheet with multiple competing templates and check which one fires. Add `` in each template to trace which one the processor picks. The trace panel shows all messages in order so you can follow the dispatch chain.

Solid understanding of template matching pays off every time you work on a complex stylesheet. Once you know how priorities and built-ins interact, most "unexpected output" bugs become obvious.

Pitfall Guide

1. Relying on Implicit Priorities: Default priorities follow XPath specificity rules, but overlapping patterns (e.g., element-name vs prefix:element-name) often resolve to identical computed priorities. Always declare explicit priority attributes when multiple templates target the same node type.
2. Overlooking Built-in Template Rules: The XSLT specification defines fallback templates that output text nodes and recursively process children. Failing to suppress or override these rules causes silent text leakage, especially in mixed-content documents.
3. Substituting xsl:for-each for Template Dispatch: for-each bypasses the pattern-matching engine entirely. Using it for heterogeneous node sets destroys polymorphism, forces manual type-checking, and tightly couples iteration logic to node structure.
4. Ignoring Processor-Specific Conflict Handling: When computed priorities collide, implementations diverge. Saxon throws a fatal error by default, while older processors may silently select the last declared template. Explicit priorities guarantee cross-processor portability.
5. Neglecting Mode Isolation: Processing the same node hierarchy for different output contexts (e.g., HTML rendering vs. JSON serialization) without modes forces template overloading and priority wars. Named modes provide clean separation of concerns.
6. Failing to Trace Dispatch Chains: Complex stylesheets obscure which template fires. Without instrumentation (e.g., xsl:message or processor trace modes), developers waste hours debugging silent fallbacks or priority mismatches. Always instrument competing templates during development.

Deliverables

• XSLT Matching Blueprint: A structured reference mapping XPath pattern types to default priorities, conflict resolution strategies, and mode architecture guidelines for enterprise transformations.
• Conflict Resolution Checklist: A 12-point validation sequence covering priority declarations, built-in overrides, mode boundaries, and processor compatibility checks before stylesheet deployment.
• Configuration Templates: Production-ready snippets for global text suppression, explicit priority assignment, mode-based dispatch routing, and apply-templates vs for-each decision matrices.