XSLT and XPath

for Visual Studio Code

143K Installs:

Settings

Visual Studio Code's settings let you tailor your working environment to fit requirements for specific languages or extensions, or to suit your own preferences.

A general guide to settings is provided by the Visual Studio Code documentation: User and Workspace Settings. This page lists the XSLT/XPath extension's own settings, and the editor settings of most interest for XSLT and XPath.

Creating User and Workspace Settings

From the Command Palette (⇧⌘P) you can either invoke Preferences: Open User Settings or Preferences: Open Workspace Settings. Editor settings can also be applied in a language-specific way: for this, use the command Preferences: Configure Language Specific Settings.

Settings are either edited in the Settings form or in a JSON editor. Open the JSON editor by clicking the Open Settings (JSON) button at the top right of the Editor Group. This opens the corresponding settings.json file directly.

User settings apply wherever you use VS Code, so they suit paths on your own computer, such as the Saxon jar. Workspace settings are saved in the project's .vscode/settings.json and apply to everyone who opens the project, so they suit settings a team shares, such as an XML catalog or XSLT packages.

XSLT/XPath Extension Settings

To list the extension's settings in the Settings editor, type XSLT in its search box. All of them are listed below, with their defaults. The sections after the tables describe the most important ones.

Running and debugging

Setting Default What it does
XSLT.tasks.saxonJar - The path of your Saxon jar file, needed to run or debug stylesheets with SaxonJ - see The Saxon jar.
XSLT.tasks.quickRunProcessor "xslt" The processor Quick Run uses: "xslt" (SaxonJ), "xslt-js" (SaxonJS) or "xslt-c" (SaxonC). Switching processor in Quick Run saves the choice here.
XSLT.tasks.java.enabled true Offer SaxonJ (xslt) tasks - see Task types.
XSLT.tasks.js.enabled true Offer SaxonJS (xslt-js) tasks.
XSLT.tasks.saxonc.enabled true Offer SaxonC (xslt-c) tasks.
XSLT.tasks.saxonCPath - The folder containing the SaxonC command-line executable (Transform or Transform.exe) - see SaxonC tasks.
XSLT.tasks.saxonCLicenseFileLocation - The path of SaxonC's saxon-license.lic file, passed to SaxonC as --licenseFileLocation: - see Licensing.
XSLT.tasks.saxonCLibraryPaths - More folders to search for SaxonC's native libraries. The lib folder beside the executable is always included - see Native library path.
XSLT.tasks.htmlParserJar - The path of the nu.validator htmlparser jar, added to SaxonJ's classpath for XSLT 4.0 stylesheets, for Saxon's parse-html() function.
XSLT.debug.openOutput false When debugging, open the output written so far beside the stylesheet, at the first pause where there is some - see Output while debugging.

Editing and checking

Setting Default What it does
XSLT.resources.catalog "" An OASIS XML catalog file, for resolving the href of xsl:import and xsl:include - also passed to Saxon - see XML catalog.
XSLT.resources.xsltPackages - The files for xsl:use-package names - see XSLT packages.
XSLT.resources.inferParentFromWorkspace true For a module that another stylesheet imports or includes, find that stylesheet from the workspace's files, so references to its declarations are resolved without opening it first - see Inferred imports.
XSLT.resources.useSourceFile "latest" Completion of element and attribute names in XPath: "latest" suggests the names that can occur at that point in the path, from the XML context file; "none" suggests the names already used in the stylesheet - see IntelliSense for XPath locations.
XSLT.validation.externalFunctionPrefixes [] Prefixes of functions the processor provides, such as Java extension functions - calls of functions with these prefixes aren't checked. The quick fix for a function that isn't found adds its prefix - see Java extension functions.
XSLT.validation.xslt30ItemTypesAndNotes false Allow XSLT 4.0 named item types and xsl:note in XSLT 3.0 stylesheets, for Saxon PE and EE 12.8 or later - see below.
XSLT.validation.xslt40UnionPriorities false Warn in every stylesheet before XSLT 4.0 about union patterns whose branches have different default priorities - not only where XSLT 4.0's rule applies already - see Union patterns and XSLT 4.0.

XSpec tests

Setting Default What it does
XSLT.xspec.home - The folder of another XSpec installation, e.g. a newer release, to compile and run tests with - by default the XSpec 4.1.2 included. See XSpec tests.
XSLT.xspec.allowSyntaxExtensions "auto" Run tests with Saxon's syntax extensions (--allowSyntaxExtensions:on), so the stylesheet tested can use XPath 4.0 syntax, or e.g. record types in an XSLT 3.0 stylesheet: "auto" - on only for tests of a stylesheet that's XSLT 4.0, or uses item types or notes, and not with Saxon-HE, which fails every transform with them on - "on" or "off". See XSpec tests.
XSLT.xspec.legacyCompatibility false Run tests written for XSpec before 1.0 (e.g. 0.5) as that ran them, where XSpec 4 stops the run - see Tests written for older XSpec.
XSLT.xspec.emphasiseLabels true In XSpec files, show scenario labels in bold and expectation labels in italic, so the scenarios read like headings.
XSLT.xspec.fadePending true In XSpec files, fade the pending scenarios and expectations, other than the reason they're pending.

AI assistants

Setting Default What it does
XSLT.mcp.enabled false Run the extension's MCP server, with tools for AI assistants such as GitHub Copilot and Claude Code - see The MCP server.
XSLT.mcp.port 6745 The port the MCP server listens at, on 127.0.0.1. With more than one window open, the first one opened has the server.

The Saxon jar

To run or debug stylesheets with SaxonJ - Saxon for Java - set XSLT.tasks.saxonJar to the full path of your Saxon jar file, usually as a user setting, since the path is specific to your computer. Any Saxon edition works, including Saxon-HE. The Debugger needs Saxon 12 or later, and a Java runtime must be on the PATH:

"XSLT.tasks.saxonJar": "/Users/me/saxon/SaxonHE12-9J/saxon-he-12.9.jar"

On Windows, write each \ in the path as \\, as JSON requires - e.g. "C:\\saxon\\saxon-he-12.9.jar". For Saxon-PE or Saxon-EE, keep the licence file, saxon-license.lic, in the same folder as the jar.

XSLT tasks refer to the setting as ${config:XSLT.tasks.saxonJar}. For downloading Saxon and Java, see SaxonJ tasks.

XSLT packages

Packages in the workspace are found without a setting. For a package outside the workspace, add its path to XSLT.resources.xsltPackages - its name and version are read from its xsl:package element. See XSLT Packages.

"XSLT.resources.xsltPackages": [ { "path": "../shared-xslt/strings.xsl" } ]

XML catalog

To resolve the href of xsl:import and xsl:include - and the URIs of fixed-namespaces - with an OASIS XML catalog, and pass the catalog to Saxon when a stylesheet is run, set XSLT.resources.catalog to the catalog file's path, relative to the workspace folder. See XML Catalogs.

"XSLT.resources.catalog": "catalog.xml"

Task types

The extension provides a task type for each Saxon processor - xslt for SaxonJ, xslt-js for SaxonJS and xslt-c for SaxonC - and all three are enabled by default. To stop a processor's tasks being offered, for example in Run Build Task, turn off its setting:

"XSLT.tasks.java.enabled": true, "XSLT.tasks.js.enabled": true, "XSLT.tasks.saxonc.enabled": true

See Tasks for configuring each task type.

XSLT 4.0 Item Types and Notes in XSLT 3.0

Saxon PE and EE 12.8 or later, run with syntax extensions, accept XSLT 4.0's named item types and xsl:note in a stylesheet with version="3.0". To edit such stylesheets with the same support as for XSLT 4.0, enable the setting XSLT.validation.xslt30ItemTypesAndNotes - it's off by default. For a team, add it to the workspace settings, in the project's .vscode/settings.json:

"XSLT.validation.xslt30ItemTypesAndNotes": true

With the setting, in an XSLT 3.0 stylesheet:

  • xsl:item-type declarations are accepted, with record(...) and enum(...) types - which can also be used directly in as attributes
  • the record and enumeration type support applies: completions of record fields, map keys and enumeration values, checks of map constructors, lookups and values, hover help, and renaming a record field
  • xsl:note needs no use-when attribute - see Code Documentation

Other XSLT 4.0 and XPath 4.0 features - such as xsl:switch, keyword arguments and fn(...) types - still need version="4.0", and are reported as errors in an XSLT 3.0 stylesheet.

Without the setting, xsl:item-type and record and enumeration types are reported as errors in an XSLT 3.0 stylesheet, and an xsl:note gets a warning unless it's excluded with use-when="false()", as an XSLT 3.0 processor reports XTSE0010 for it.

To run the stylesheets, Saxon needs syntax extensions: the --allowSyntaxExtensions:on option on the command line, or allowSyntaxExtensions="true" in a Saxon configuration file. The extension's XSLT tasks and Quick Run enable it with the default "allowSyntaxExtensions40": "auto" task property, for Saxon PE and EE, when the stylesheet - or a module it imports, includes or uses - has item types or notes.

Converting Saxon type aliases

Saxon's earlier syntax for named types - saxon:type-alias, tuple(...) types and ~name for a reference to a type alias - is ignored by Saxon 12.8 and later, which only report the references. The linter warns about a saxon:type-alias, and the command XSLT: Convert Saxon Type Aliases to xsl:item-type - also the warning's quick fix - converts them in all the workspace's files, shown for review in the refactor preview first:

  • <saxon:type-alias name="dfx:bounds" type="..."/> becomes <xsl:item-type name="dfx:bounds" as="..."/>
  • tuple(t: xs:integer, label?: xs:string) becomes record(t as xs:integer, label? as xs:string)
  • as="~dfx:bounds" becomes as="dfx:bounds"

A type alias with an extensible tuple type, e.g. tuple(a: xs:string, *), isn't converted - nor is one that references it - as XSLT 4.0 has no extensible record types. These are listed after the conversion, to convert by hand.

General Settings for XSLT

Default Editor Settings for XSLT, XPath and XML

The extension sets these VS Code editor settings for the xslt, xpath and xml languages - for .xsl, .xslt, .xpath and XML files. As they're set for each language, they don't affect files in other languages. Any of them can be changed in a language-specific setting, e.g. "[xslt]": { "editor.tabSize": 4 } - see Creating User and Workspace Settings.

Setting XSLT and XPath XML What it does
editor.defaultFormatter "deltaxml.xslt-xpath" This extension formats the file - see Code Formatting.
editor.formatOnType true Lines are indented as you type, e.g. a new line, or a closing tag.
editor.formatOnPaste true Pasted text is indented to fit where it's pasted.
editor.formatOnSave false The file isn't formatted when it's saved.
editor.formatOnSaveMode "file" If formatOnSave is turned on, the whole file is formatted - or only the lines changed, with "modifications".
editor.tabSize 2 4 The number of spaces for each level of indentation.
editor.insertSpaces true Indentation uses spaces, not tabs.
editor.detectIndentation true For an existing file, the tab size and spaces or tabs are detected from its content, instead of the two settings above.
editor.wordSeparators "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$" Unlike VS Code's default, - and . aren't word separators, so double-clicking selects a whole name, such as current-group - see Word Separators.
editor.semanticHighlighting.enabled true - Syntax highlighting for XSLT and XPath, which uses semantic tokens - see Syntax Highlighting. It's also set for the xsl language.
outline.showArrays false The Outline view doesn't show arrays - see Code Navigation.
The default settings, as JSON "[xslt]": { "editor.defaultFormatter": "deltaxml.xslt-xpath", "editor.formatOnSaveMode": "file", "editor.formatOnSave": false, "editor.formatOnPaste": true, "editor.formatOnType": true, "editor.semanticHighlighting.enabled": true, "editor.detectIndentation": true, "editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$", "editor.insertSpaces": true, "editor.tabSize": 2, "outline.showArrays": false }, "[xpath]": { "editor.defaultFormatter": "deltaxml.xslt-xpath", "editor.formatOnSaveMode": "file", "editor.formatOnSave": false, "editor.formatOnPaste": true, "editor.formatOnType": true, "editor.semanticHighlighting.enabled": true, "editor.detectIndentation": true, "editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$", "editor.insertSpaces": true, "editor.tabSize": 2, "outline.showArrays": false }, "[xml]": { "editor.defaultFormatter": "deltaxml.xslt-xpath", "editor.formatOnSaveMode": "file", "editor.formatOnSave": false, "editor.formatOnPaste": true, "editor.formatOnType": true, "editor.wordSeparators": "`~!@#%^&*()=+[{]}\\|;'\",:<>/?$", "editor.detectIndentation": true, "editor.insertSpaces": true, "editor.tabSize": 4, "outline.showArrays": false }, "[xsl]": { "editor.semanticHighlighting.enabled": true }

Built-in Editing Behaviour for XSLT

The extension also defines how the editor treats XSLT files in ways that aren't settings, so they can't be changed:

  • Comments - Toggle Block Comment (⇧⌥A) wraps the selection in <!-- and -->. In .xpath files it uses XPath's (: and :).
  • Auto-closing - typing {, [, (, a quote or a backtick adds the closing character. So does &, which adds ; for an entity reference, and (:, which adds : to start an XPath comment.
  • Surrounding - typing one of these characters with text selected surrounds the selection with the pair, e.g. selecting $total and typing ( gives ($total).
  • Words - a prefixed name such as xsl:template, a variable reference such as $total-price, and an attribute name test such as @select each count as one word - for example, when VS Code finds the word at the cursor for word-based suggestions.
  • Folding regions - <?region?> and <?endregion?> processing instructions mark a region that can be folded - see Folding.

Code Formatting

The following settings directly affect code formatting in the XSLT/XPath extension:

"editor.defaultFormatter": "deltaxml.xslt-xpath", "editor.formatOnSaveMode": "modifications", "editor.formatOnSave": true, "editor.formatOnPaste": true, "editor.formatOnType": true

The editor.formatOnSaveMode setting can be used to only format XSLT lines changed since the last commit on Git.

Syntax Highlighting

Syntax highlighting for XSLT and XPath is achieved using Visual Studio Code's Semantic Highlighting tokens alone. Almost all other languages in Visual Studio Code use a TextMate Grammar for tokens, which may be supplemented by Semantic Highlighting.

If XSLT and XPath are not syntax highlighted in a Color Theme, you can explicitly enable Semantic Highlighting with the setting:

"editor.semanticHighlighting.enabled": true

The XSLT Dark Themes extension provides a selection of popular dark color themes, enhanced for XSLT/XPath.

Screenshot of Gruvbox Theme extended for XSLT
XSLT in the X Gruvbox Material Dark theme
X Gruvbox Material Dark theme

Word Separators

The editor.wordSeparators setting affects how the full 'word' is selected when you double-click on a part of the word. The characters listed are used as word separators. Typically in XSLT, you do not want characters like - and . treated as word separators, as these characters are valid within a QName like an attribute name or a variable name.

The Agents Window

Visual Studio Code's Agents window only runs the extensions on a list chosen by Microsoft, and the XSLT/XPath extension isn't on it yet - so, there, XSLT files have plain XML highlighting, with none of the extension's features. To run the extension in the Agents window, add this to your user settings:

"extensions.supportAgentsWindow": { "deltaxml.xslt-xpath": true }

The Agents window uses its own profile of extensions, so an extension you've disabled elsewhere - such as Red Hat's XML extension - may be enabled there. See AI Assistants.

Emmet Snippets

Emmet Snippets provide a convenient shorthand for inserting a number of literal result elements and attributes into your XSLT in one go. For example, entering:

ul>li.item$*2

provides the following output:

<ul> <li class="item1"></li> <li class="item2"></li> </ul>

To enable Emmet snippets for XSLT, add the following setting:

"emmet.includeLanguages": { "xslt": "xml" }

On this page