What Is the Priority Attribute in XSLT Templates?

The priority attribute on an <xsl:template> element in XSLT is used to explicitly resolve conflicts when multiple template rules match the same source XML node. By assigning a numerical value to a template's priority, developers can override the default XSLT pattern-matching precedence and ensure that the correct template executes without ambiguity or processor warnings.

Why Conflict Resolution Matters in XSLT

When an XSLT processor encounters an <xsl:apply-templates> instruction, it searches the stylesheet for a matching template. In non-trivial transformations, a single XML node may satisfy the patterns of multiple templates simultaneously. For example, a <book category="fiction"> element could match both match="book" and match="book[@category='fiction']".

When multiple templates match a node, the processor applies strict conflict-resolution rules:

1. Import Precedence: Templates in the main stylesheet take precedence over imported stylesheets (<xsl:import>).
2. Explicit Priority: The template with the highest explicit priority attribute is chosen.
3. Default Priority: If no explicit priority is set, the processor calculates a default priority based on pattern complexity.
4. Document Order: If two or more matching templates share the same highest priority, the processor either reports an error or selects the one that occurs last in the stylesheet.

Default Priority Calculation

When you omit the priority attribute, the XSLT specification assigns a default priority ranging from -0.5 to 0.5 based on pattern specificity:

• 0.5 (Most Specific): Matches that specify an element name with a predicate or child axis (e.g., match="item[@active='true']" or match="parent/child").
• 0 (Specific Name): Matches that specify a single element, attribute, or processing instruction name (e.g., match="title" or match="@id").
• -0.25 (Wildcard Namespace): Matches with a namespace wildcard (e.g., match="ncname:*").
• -0.5 (Least Specific): Node type tests or general wildcards (e.g., match="*" or match="node()").

How the Explicit priority Attribute Works

The priority attribute accepts any real number (positive, negative, integer, or decimal). When present, this value supersedes any automatically calculated default priority.

<!-- General fallback template -->
<xsl:template match="article" priority="1">
    <div class="standard-article">
        <xsl:apply-templates />
    </div>
</xsl:template>

<!-- Override template for specific layout requirements -->
<xsl:template match="article" priority="2">
    <div class="featured-article">
        <xsl:apply-templates />
    </div>
</xsl:template>

In the example above, both templates match the pattern match="article". Without the priority attribute, both would have a default priority of 0, creating an ambiguity. By providing priority="2", the second template is guaranteed to execute.

Common Use Cases

1. Disambiguating Equal-Precedence Rules

When two patterns share the same calculated default priority—such as two distinct single-element names or complex predicate conditions—setting an explicit priority prevents reliance on stylesheet ordering.

2. Overriding Specialized Match Logic

You may want a simpler pattern to take precedence over a more complex one due to a specific processing condition. Adding a higher priority value ensures the broader pattern wins.

3. Maintaining Modular Stylesheets

When building extensible transformation pipelines, explicit priorities allow base template definitions and extensions to coexist reliably without unexpected match collisions across team-maintained files.