XSLT 3.0 vs 2.0 — What Actually Changed for Real Projects

Most XSLT write-ups treat 3.0 as a wholesale replacement for 2.0, but in practice most existing 2.0 stylesheets don’t need touching, and only a handful of the new features are worth adopting deliberately. This post looks at what actually changed between the two versions from the angle of someone maintaining production XSLT, not from the spec’s table of contents.

The problem

I’ve maintained XSLT stylesheets across several client projects going back to when 2.0 was still the newer version people were nervous about adopting. Every time 3.0 comes up in a conversation with a client, the question is the same: do we need to rewrite anything, and is it worth switching processors to get 3.0 support. The honest answer is almost always no rewrite, and switch only if one specific feature actually solves a real pain point you have. Below is what changed, filtered down to what matters for maintaining or writing stylesheets rather than for spec trivia.

Grouping got genuinely better, but 2.0 already fixed the worst of it

The classic XSLT 1.0 grouping problem — no xsl:for-each-group, forcing Muenchian grouping with keys — was already solved in 2.0. 3.0 doesn’t change the grouping model fundamentally; it adds group-starting-with and group-ending-with refinements and lets grouping interact more cleanly with maps and arrays (below), but if your 2.0 stylesheets already use xsl:for-each-group with group-by, there’s nothing here forcing a change.

<!-- This 2.0 grouping code is unchanged in 3.0 — still correct, still idiomatic -->
<xsl:for-each-group select="item" group-by="category">
  <category name="{current-grouping-key()}">
    <xsl:for-each select="current-group()">
      <item><xsl:value-of select="name"/></item>
    </xsl:for-each>
  </category>
</xsl:for-each-group>

Maps and arrays are the actual headline feature

This is the one change in 3.0 that’s worth learning deliberately, because it solves a real problem 2.0 has no good answer for: building and passing around structured, non-XML data inside a stylesheet. In 2.0, if you needed something like a lookup table, you either built it as an XML fragment and queried it with XPath, or you leaned on extension functions. 3.0 gives you actual map and array data types in XPath 3.1:

<!-- Building and querying a map — no XML fragment needed for a lookup table -->
<xsl:variable name="status-labels" as="map(xs:string, xs:string)"
  select="map{
    'A': 'Active',
    'P': 'Pending',
    'C': 'Closed'
  }"/>

<xsl:template match="record">
  <status><xsl:value-of select="map:get($status-labels, @code)"/></status>
</xsl:template>

For anyone doing the kind of JSON-adjacent transformation work I cover with the json2xml tool, this is the feature that actually matters — maps and arrays in XPath 3.1 line up conceptually with JSON objects and arrays, which makes round-tripping JSON through XSLT far less awkward than forcing it through an intermediate XML representation the whole way.

Native JSON functions close a real gap

Related to the above: 3.0 adds json-to-xml and xml-to-json as standard functions, meaning you can parse JSON directly inside a stylesheet without a pre-processing step outside it.

<!-- Parse JSON directly, no external conversion step required -->
<xsl:variable name="parsed" select="json-to-xml($json-string)"/>

<xsl:template match="/">
  <xsl:apply-templates select="$parsed//*:map/*:string[@key='name']"/>
</xsl:template>

In 2.0-only environments this meant either shelling out to an external converter as a build step, or writing your own JSON parser as an extension function — both workable, but both extra moving parts. If your pipeline already touches JSON anywhere, this alone can be a legitimate reason to move a specific stylesheet to a 3.0 processor, even if the rest of the codebase stays on 2.0.

Streaming: important, but only for a narrow case

3.0 formalizes streaming transformations — processing documents too large to hold in memory, using xsl:mode streamable="yes" and constraints on what constructs are allowed inside a streamable template. This is a real feature, but it’s also the one most likely to be irrelevant to your project. Unless you’re processing multi-gigabyte XML documents where loading the whole tree isn’t an option, streaming adds constraints to how you write templates without giving you anything back. I’ve used it exactly once, on a client project ingesting large exported database dumps in XML form, and it was worth the added complexity there specifically because the alternative was running out of memory on production hardware.

<!-- Streaming mode declaration — only worth this for genuinely large input -->
<xsl:mode name="stream-mode" streamable="yes"/>

<xsl:template match="records/record" mode="stream-mode">
  <xsl:copy-of select="."/>
</xsl:template>

Higher-order functions: nice, rarely necessary

3.0 lets you pass functions as values — xsl:function results can be assigned to variables and passed as arguments, and fn:function-lookup and inline function expressions let you write things like a generic filter or map over a sequence:

<!-- Inline function as a value, passed to fold-left -->
<xsl:variable name="total" as="xs:integer"
  select="fold-left(1 to 5, 0, function($acc, $x) { $acc + $x })"/>

This is genuinely useful if you’re writing reusable utility stylesheets meant to be imported across projects, since it lets you parameterize behavior rather than duplicating near-identical templates. For a one-off transformation stylesheet that does one specific job, it’s rarely worth reaching for — the added indirection costs more in readability than the abstraction saves.

Processor support is still the deciding factor

None of the above matters if your target environment’s processor doesn’t support 3.0. Saxon has had strong 3.0 support for a long time, including in its free Home Edition for a useful subset of features, but if you’re constrained to whatever XSLT processor ships with a specific platform — a database engine’s built-in transform function, an older application server, .NET’s System.Xml.Xsl which has stayed at 1.0 — none of this is available to you regardless of how useful maps or JSON functions would be. Check what’s actually running in production before planning around 3.0 features; I’ve seen more wasted effort from stylesheets written against features the deployed processor doesn’t support than from any of the version differences themselves.

Conclusion

Existing 2.0 stylesheets don’t need rewriting for 3.0 — the core template and XPath model most code relies on is unchanged — but maps, arrays, and native JSON functions are worth adopting deliberately wherever a stylesheet already deals with non-XML structured data, and everything else in 3.0 is a narrower tool worth reaching for only when the specific problem it solves is one you actually have.

FAQ