XSLT - Importing and Including Stylesheets in XSLT (xsl:import vs xsl:include)

As XSLT projects grow in size and complexity, managing all transformation rules in a single stylesheet becomes difficult. Developers often divide large stylesheets into smaller, reusable modules to improve readability, simplify maintenance, and encourage code reuse. XSLT provides two important elements for combining multiple stylesheets into one transformation: xsl:include and xsl:import. Although both allow one stylesheet to use another, they serve different purposes and follow different processing rules.

Understanding the difference between these two elements is essential for building scalable and maintainable XML transformation solutions.

Why Modular Stylesheets Are Important

Imagine an organization that processes XML files for invoices, employee records, and customer information. Many transformations may use common templates for formatting dates, generating headers, or displaying addresses. Instead of copying the same templates into every stylesheet, developers can place common templates in a shared stylesheet and reuse them wherever needed.

Modular stylesheets provide several advantages:

  • Reduce duplicate code.

  • Simplify maintenance.

  • Encourage code reuse.

  • Make large projects easier to understand.

  • Allow multiple developers to work on different stylesheet modules simultaneously.

Both xsl:include and xsl:import help achieve these goals, but they differ in how template conflicts are handled.

Understanding xsl:include

The xsl:include element inserts the contents of another stylesheet into the current stylesheet. It behaves almost as if the included stylesheet were copied and pasted directly into the main stylesheet.

Syntax

<xsl:include href="common.xsl"/>

The href attribute specifies the path to the stylesheet being included.

When the XSLT processor reads the main stylesheet, it loads the included stylesheet and treats all templates as part of the same stylesheet.

Example

Suppose there is a stylesheet named common.xsl.

<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template match="header">
<h2>Company Report</h2>
</xsl:template>

</xsl:stylesheet>

The main stylesheet can include it like this:

<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:include href="common.xsl"/>

<xsl:template match="/">
<html>
<body>
<xsl:apply-templates select="header"/>
</body>
</html>
</xsl:template>

</xsl:stylesheet>

The included template becomes available exactly as if it had been written inside the main stylesheet.

Characteristics of xsl:include

  • Combines multiple stylesheets into one.

  • Suitable for splitting large projects into manageable files.

  • Included templates have the same priority as templates in the main stylesheet.

  • Duplicate template conflicts usually generate an error if they have identical match patterns and priorities.

Understanding xsl:import

The xsl:import element also brings another stylesheet into the current stylesheet, but it introduces the concept of import precedence.

The importing stylesheet has higher priority than the imported stylesheet.

This allows developers to override templates from an existing stylesheet without modifying the original file.

Syntax

<xsl:import href="base.xsl"/>

Unlike xsl:include, all xsl:import elements must appear before every other top-level element except namespace declarations.

Example

Assume base.xsl contains:

<xsl:template match="title">
<h1>Original Title</h1>
</xsl:template>

The main stylesheet imports it:

<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:import href="base.xsl"/>

<xsl:template match="title">
<h1>Customized Title</h1>
</xsl:template>

</xsl:stylesheet>

When processing the XML document, the customized template is used instead of the original because imported templates have lower precedence.

Why Use xsl:import

Suppose a software company provides a standard stylesheet for generating reports. A client wants to customize only a few sections while keeping the rest unchanged.

Instead of editing the original stylesheet, the client creates a new stylesheet that imports the original and overrides only the necessary templates.

This approach preserves the original stylesheet while allowing customized behavior.

Import Precedence

Import precedence determines which template is selected when multiple templates match the same XML node.

The stylesheet that performs the import always has higher precedence.

For example:

Imported stylesheet:

<xsl:template match="employee">
<p>Employee Information</p>
</xsl:template>

Importing stylesheet:

<xsl:template match="employee">
<p>Updated Employee Information</p>
</xsl:template>

The second template is chosen because it belongs to the importing stylesheet.

Differences Between xsl:include and xsl:import

Feature xsl:include xsl:import
Purpose Combines multiple stylesheets Extends another stylesheet
Template Priority Equal priority Importing stylesheet has higher priority
Conflict Handling Duplicate templates may cause errors Higher-precedence templates override imported ones
Placement Can appear with other top-level elements Must appear before other top-level elements
Best Use Modular organization Customizing existing stylesheets

When to Use xsl:include

Use xsl:include when:

  • Dividing a large stylesheet into smaller modules.

  • Sharing common templates across multiple projects.

  • Organizing code for easier maintenance.

  • No template overriding is required.

Examples include:

  • Common formatting templates.

  • Date formatting utilities.

  • Shared navigation layouts.

  • Frequently used helper templates.

When to Use xsl:import

Use xsl:import when:

  • Extending an existing stylesheet.

  • Replacing selected templates.

  • Building customized versions of standard transformations.

  • Supporting different customer-specific outputs from a common base stylesheet.

Examples include:

  • Brand-specific report layouts.

  • Country-specific invoice formats.

  • Customized XML-to-HTML transformations.

  • Enterprise applications requiring configurable output.

Best Practices

Developers should follow several best practices when working with imported and included stylesheets:

  • Keep reusable templates in separate utility stylesheets.

  • Use descriptive file names such as common.xsl, layout.xsl, or formatting.xsl.

  • Use xsl:include for shared functionality without changing template behavior.

  • Use xsl:import when customization or overriding is required.

  • Avoid unnecessary imports to keep stylesheet dependencies manageable.

  • Organize stylesheets into logical folders for easier project navigation.

  • Test imported stylesheets thoroughly to ensure template precedence behaves as expected.

Common Mistakes

Some common errors developers encounter include:

  • Placing xsl:import after other top-level elements, which violates XSLT rules.

  • Using xsl:include when template overriding is actually needed.

  • Creating circular includes where two stylesheets include each other.

  • Including multiple stylesheets with identical template definitions, leading to conflicts.

  • Failing to understand how import precedence affects template selection.

Practical Applications

xsl:include and xsl:import are widely used in enterprise XML processing systems. They support modular stylesheet design in document publishing, financial reporting, e-commerce catalogs, healthcare data exchange, publishing workflows, government document processing, and content management systems. By separating shared logic from specialized transformations, organizations can maintain cleaner codebases, reduce duplication, and implement changes more efficiently while preserving consistency across multiple XML transformation projects.