Changes in 4.0 (next | previous)
A new serialization parameter escape-solidus is provided to control whether the character / is escaped as \/ by the JSON serialization method. [Issue 530 PR 534 9 June 2023]
The input to the serializer can be defined using the select attribute of xsl:result-document as an alternative to using a sequence constructor. [Issue 1534 ]
A new attribute xsl:result-document/@canonical is available to give control over serialization of XML, XHTML, and JSON. [Issue 938 2 November 2025]
<!-- Category: instruction -->
<xsl:result-document
format? = { eqname }
href? = { uri }
select? = expression
validation? = "strict" | "lax" | "preserve" | "strip"
type? = eqname
method? = { "xml" | "html" | "xhtml" | "text" | "json" | "adaptive" | eqname }
allow-duplicate-names? = { boolean }
build-tree? = { boolean }
byte-order-mark? = { boolean }
canonical? = { boolean }
cdata-section-elements? = { eqnames }
doctype-public? = { string }
doctype-system? = { string }
encoding? = { string }
escape-solidus? = { boolean }
escape-uri-attributes? = { boolean }
html-version? = { decimal }
include-content-type? = { boolean }
indent? = { boolean }
item-separator? = { string }
json-lines? = { boolean }
json-node-output-method? = { "xml" | "html" | "xhtml" | "text" | eqname }
media-type? = { string }
normalization-form? = { "NFC" | "NFD" | "NFKC" | "NFKD" | "fully-normalized" | "none" | nmtoken }
omit-xml-declaration? = { boolean }
parameter-document? = { uri }
standalone? = { boolean | "omit" }
suppress-indentation? = { eqnames }
undeclare-prefixes? = { boolean }
use-character-maps? = eqnames
output-version? = { nmtoken } >
<!-- Content: sequence-constructor -->
</xsl:result-document>
The xsl:result-document instruction is used to create a secondary result.
The select attribute and the contained sequence constructor are mutually exclusive; if the select attribute is present then the sequence constructor must be empty, and if the sequence constructor is non-empty then the select attribute must be absent [see ERR XTSE3185]. The value of the select attribute or the immediate result of the contained sequence constructor is referred to as the raw result.
As with the principal result of the transformation, a secondary result may be delivered to the calling application in three ways (see 2.3.6 Post-processing the Raw Result):
The raw result may be delivered as is.
The raw result may be used to construct a final result tree by invoking the process of sequence normalizationSE.
The raw result may be serialized to a sequence of octets (which may then, optionally, be saved to a persistent storage location).
Note:
The name of the instruction, xsl:result-document, is a little misleading. The instruction does not necessarily deliver either an XML document tree nor a serialized XML document. Instead, for example, it might deliver an array, a map, serialized JSON, or a sequence of atomic values.
The decision whether or not to serialize the raw result depends on the processor and on the way it is invoked. This is implementation-defined, and it is not controlled by anything in the stylesheet.
If the result is not serialized, then the decision whether to return the raw result or to construct a tree depends on the effective value of the build-tree attribute. If the effective value of the build-tree attribute is yes, then a final result tree is created by invoking the process of sequence normalizationSE. Conversely, if the result is serialized, then the decision whether or not to construct a tree depends on the choice of serialization method, and the build-tree attribute is then ignored. For example, with method="xml" a tree is always constructed, whereas with method="json" a tree is never constructed. If the result is not serialized, then the decision whether to return the raw result or to construct a tree depends on the effective value of the build-tree attribute. If the effective value of the build-tree attribute is yes, then a final result tree is created by invoking the process of sequence normalizationSE. Conversely, if the result is serialized, then the decision whether or not to construct a tree depends on the choice of serialization method, and the build-tree attribute is then ignored. For example, with method="xml" a tree is always constructed, whereas with method="json" a tree is never constructed. If the result is not serialized, then the decision whether to return the raw result or to construct a tree depends on the effective value of the build-tree attribute. If the effective value of the build-tree attribute is yes, then a final result tree is created by invoking the process of sequence normalizationSE. Conversely, if the result is serialized, then the decision whether or not to construct a tree depends on the choice of serialization method, and the build-tree attribute is then ignored. For example, with method="xml" a tree is always constructed, whereas with method="json" a tree is never constructed.
The xsl:result-document instruction defines a URI that may be used to identify the secondary result. The instruction may optionally specify the output format to be used for serializing the result.
Technically, the result of evaluating the xsl:result-document instruction is an empty sequence. This means it does not contribute anything to the result of the sequence constructor it is part of.
The effective value of the format attribute, if specified, must be an EQName. The value is expanded using the namespace declarations in scope for the xsl:result-document element. The resulting expanded QNamemust match the expanded QName of a named output definition in the stylesheet. This identifies the xsl:output declaration that will control the serialization of the final result tree (see 26 Serialization), if the result tree is serialized. If the format attribute is omitted, the unnamed output definition is used to control serialization of the result tree.
[ERR XTDE1460] It is a dynamic error if the effective value of the format attribute is not a valid EQName, or if it does not match the expanded QName of an output definition in the containing package. If the processor is able to detect the error statically (for example, when the format attribute contains no curly brackets), then the processor may optionally raise this as a static error.
Note:
The only way to select the unnamed output definition is to omit the format attribute.
The parameter-document attribute allows serialization parameters to be supplied in an external document. The external document must contain an output:serialization-parameters element with the format described in [Serialization 4.0] section 3.1 Setting Serialization Parameters by Means of a Parameter Document, and the parameters are interpreted as described in that specification.
If present, the effective value of the URI supplied in the parameter-document attribute is dereferenced, after resolution against the base URI of the xsl:result-document element if it is a relative reference. The parameter document should be read during run-time evaluation of the stylesheet. If the location of the stylesheet at development time is different from the deployed location, any relative reference should be resolved against the deployed location. A serialization error occurs if the result of dereferencing the URI is ill-formed or invalid; but if no document can be found at the specified location, the attribute should be ignored.
A serialization parameter specified in the parameter-document takes precedence over a value supplied directly as an attribute of xsl:result-document, which in turn takes precedence over a value supplied in the selected output definition, except that the values of the cdata-section-elements and suppress-indentation attributes are merged in the same way as when multiple xsl:output declarations are merged.
The attributes method, allow-duplicate-names, build-tree, byte-order-markcanonical, cdata-section-elements, doctype-public, doctype-system, encoding, escape-solidusescape-uri-attributes, html-version, indent, item-separator, json-lines, json-node-output-method, media-type, normalization-form, omit-xml-declaration, standalone, suppress-indentation, undeclare-prefixes, use-character-maps, and output-version may be used to override attributes defined in the selected output definition.
With the exception of use-character-maps, these attributes are all defined as attribute value templates, so their values may be set dynamically. For any of these attributes that is present on the xsl:result-document instruction, the effective value of the attribute overrides or supplements the corresponding value from the output definition. This works in the same way as when one xsl:output declaration overrides another. Some of the attributes have more specific rules:
In the case of cdata-section-elements and suppress-indentation, the value of the serialization parameter is the union of the expanded names of the elements named in this instruction and the elements named in the selected output definition.
In the case of use-character-maps, the character maps referenced in this instruction supplement and take precedence over those defined in the selected output definition.
In the case of doctype-public and doctype-system, setting the effective value of the attribute to a zero-length string has the effect of overriding any value for these attributes obtained from the output definition. The corresponding serialization parameter is not set (is “absent”).
In the case of item-separator, setting the effective value of the attribute to the special value "#absent" has the effect of overriding any value for this attribute obtained from the output definition. The corresponding serialization parameter is not set (is “absent”). It is not possible to set the value of the serialization parameter to the literal 7-character string "#absent".
In all other cases, the effective value of an attribute actually present on this instruction takes precedence over the value defined in the selected output definition.
In the case of the attributes method, json-node-output-methodcdata-section-elements, suppress-indentation, and use-character-maps, the effective value of the attribute contains an EQName or a space-separated list of EQNames. Where lexical QNames are used in these attributes (whether prefixed or unprefixed), the namespace context is established in the same way as for the corresponding attributes of xsl:output: see 26.2 Serialization parameters.
The output-version attribute on the xsl:result-document instruction overrides the version attribute on xsl:output (it has been renamed because version is available with a different meaning as a standard attribute: see 3.4 Standard Attributes). In all other cases, attributes correspond if they have the same name.
There are some serialization parameters that apply to some output methods but not to others. For example, the indent attribute has no effect on the text output method. If a value is supplied for an attribute that is inapplicable to the output method, its value is not passed to the serializer. The processor may validate the value of such an attribute, but is not required to do so.
The item-separator serialization parameter is used when the raw result is used to construct a result tree by applying sequence normalization, and it is also used when the result tree is serialized. For example, if the sequence constructor delivers a sequence of integers, and the text serialization method is used, then the result of serialization will be a string obtained by converting each integer to a string, and separating the strings using the defined item-separator.
The href attribute is optional. The default value is the zero-length string. The effective value of the attribute must be a URI Reference, which may be absolute or relative. If it is relative, then it is resolved against the base output URI. There may be implementation-defined restrictions on the form of absolute URI that may be used, but the implementation is not required to enforce any restrictions. Any valid relative URI reference must be accepted. Note that the zero-length string is a valid relative URI reference.
If the implementation provides an API to access secondary results, then it must allow a secondary result to be identified by means of the absolutized value of the href attribute. In addition, if a final result tree is constructed (that is, if the effective value of build-tree is yes), then this value is used as the base URI of the document node at the root of the final result tree.
Note:
The base URI of the final result tree is not necessarily the same thing as the URI of its serialized representation on disk, if any. For example, a server (or browser client) might store final result trees only in memory, or in an internal disk cache. As long as the processor satisfies requests for those URIs, it is irrelevant where they are actually written on disk, if at all.
Note:
It will often be the case that one final result tree contains links to another final result tree produced during the same transformation, in the form of a relative URI reference. The mechanism of associating a URI with a final result tree has been chosen to allow the integrity of such links to be preserved when the trees are serialized.
As well as being potentially significant in any API that provides access to final result trees, the base URI of the new document node is relevant if the final result tree, rather than being serialized, is supplied as input to a further transformation.
The optional attributes type and validation may be used on the xsl:result-document instruction to validate the contents of a final result tree, and to determine the type annotation that elements and attributes within the final result tree will carry. The permitted values and their semantics are described in 25.4.2 Validating Document Nodes. Any such validation is applied to the document node produced as the result of sequence normalizationSE. If sequence normalization does not take place (typically because the raw result is delivered to the application directly, or because the selected serialization method does not involve sequence normalization) then the validation and type attributes are ignored.
Note:
Validation applies after inserting item separators as determined by the item-separator serialization parameter, and an inappropriate choice of item-separator may cause the result to become invalid.
A processormay allow a final result tree to be serialized. Serialization is described in 26 Serialization. However, an implementation (for example, a processor running in an environment with no access to writable filestore) is not required to support the serialization of final result trees. An implementation that does not support the serialization of final result trees may ignore the format attribute and the serialization attributes. Such an implementation must provide the application with some means of access to the (un-serialized) result tree, using its URI to identify it.
Implementations may provide additional mechanisms, outside the scope of this specification, for defining the way in which final result trees are processed. Such mechanisms may make use of the XSLT-defined attributes on the xsl:result-document and/or xsl:output elements, or they may use additional elements or attributes in an implementation-defined namespace.
The following example takes an XHTML document as input, and breaks it up so that the text following each <h1> element is included in a separate document. A new document toc.html is constructed to act as an index:
<xsl:stylesheet
version="3.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<xsl:output name="toc-format" method="xhtml" indent="yes"
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"/>
<xsl:output name="section-format" method="xhtml" indent="no"
doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"/>
<xsl:template match="/">
<xsl:result-document href="toc.html"
format="toc-format"
validation="strict">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title>Table of Contents</title></head>
<body>
<h1>Table of Contents</h1>
<xsl:for-each select="/*/xhtml:body/(*[1] | xhtml:h1)">
<p>
<a href="section{position()}.html">
<xsl:value-of select="."/>
</a>
</p>
</xsl:for-each>
</body>
</html>
</xsl:result-document>
<xsl:for-each-group select="/*/xhtml:body/*" group-starting-with="xhtml:h1">
<xsl:result-document href="section{position()}.html"
format="section-format" validation="strip">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title><xsl:value-of select="."/></title></head>
<body>
<xsl:copy-of select="current-group()"/>
</body>
</html>
</xsl:result-document>
</xsl:for-each-group>
</xsl:template>
</xsl:stylesheet>