The output of a transformation includes a principal result and zero or more secondary results.
The way in which these results are delivered to an application is implementation-defined.
Serialization of results is described further in 26 Serialization
<!-- Category: instruction -->
<xsl:result-document
format? = { eqname }
href? = { uri }
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 }
cdata-section-elements? = { eqnames }
doctype-public? = { string }
doctype-system? = { string }
encoding? = { string }
escape-uri-attributes? = { boolean }
html-version? = { decimal }
include-content-type? = { boolean }
indent? = { boolean }
item-separator? = { string }
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 content of the
xsl:result-document
element is a sequence constructor,
and the value of the
secondary result (known as the raw result)
is the immediate result of this
sequence constructor.
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 normalizationSER30.
The raw result may be serialized to a sequence of octets (which may then, optionally, be saved to a persistent storage location).
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 normalizationSER30. The default for the
build-tree
attribute depends on the serialization method. For the
xml
, html
, xhtml
, and text
methods the default value is yes
. For
the json
and adaptive
methods (available only with XPath
3.1) the default value is no
.
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 QName
must 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 signal 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
Section
3.1 Setting Serialization Parameters by Means of a Data Model Instance
SER30, 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-mark
cdata-section-elements
, doctype-public
,
doctype-system
, encoding
,
escape-uri-attributes
, html-version
, indent
, item-separator
,
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.
Note:
In the case of the attributes method
,
cdata-section-elements
, suppress-indentation
, and
use-character-maps
, the effective value of the attribute contains a space-separated list of
EQNames. If any of these is a lexical QName with a prefix, the prefix is
expanded using the in-scope namespaces for the
xsl:result-document
element. In the case of
cdata-section-elements
and suppress-indentation
, an
unprefixed element name is expanded using the default namespace. In the case of
the method
attribute, if the method is not one of the system-defined
methods (xml, html, xhtml, text) then the expanded name must have a non-absent
namespace.
Unless the processor implements the XPath 3.1 Feature, the method
values json
and
adaptive
must be rejected as invalid, and the attributes
allow-duplicate-names
and json-node-output-method
must be ignored. The meaning of these output methods and
serialization parameters is defined in [XSLT and XQuery Serialization 3.1].
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 normalizationSER30.
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 processor
may 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>
xsl:result-document
There are restrictions on the use of the xsl:result-document
instruction, designed to ensure that the results are fully interoperable even when
processors optimize the sequence in which instructions are evaluated. Informally,
the
restriction is that the xsl:result-document
instruction can only be
used while writing a final result tree, not while writing to a temporary tree or a
sequence. This restriction is defined formally as follows.
[Definition: Each instruction in the stylesheet is evaluated in one of two possible output states: final output state or temporary output state ].
[Definition: The first of the two output states is called final output state. This state applies when instructions are writing to a final result tree.]
[Definition: The second of the two output states is called temporary output state. This state applies when instructions are writing to a temporary tree or any other non-final destination.]
The instructions in the initial named template are evaluated in
final output state. An instruction
is evaluated in the same output state as its
calling instruction, except that xsl:variable
,
xsl:param
, xsl:with-param
,
xsl:function
, xsl:key
, xsl:sort
,
xsl:accumulator-rule
, and
xsl:merge-key
always evaluate the instructions in their
contained sequence constructor in
temporary output state.
[ERR XTDE1480] It is a dynamic error to evaluate the
xsl:result-document
instruction in temporary output state.
[ERR XTDE1490] It is a dynamic error for a transformation to generate two or more final result trees with the same URI.
Note:
Note, this means that it is an error to evaluate more than one
xsl:result-document
instruction that omits the
href
attribute, or to evaluate any
xsl:result-document
instruction that omits the
href
attribute if an initial final result tree is created implicitly.
In addition, an implementation may report this error if it is able to detect that two or more final result trees are generated with different URIs that refer to the same physical resource.
[ERR XTDE1500] It is a dynamic error for a stylesheet to write to an external resource and read from the same resource during a single transformation, if the same absolute URI is used to access the resource in both cases.
In addition, an implementation may report this error if it is able to detect that a transformation writes to a resource and reads from the same resource using different URIs that refer to the same physical resource. Note that if the error is not detected, it is implementation-dependent whether the document that is read from the resource reflects its state before or after the result tree is written.
[Definition: The current output URI is the URI associated with the principal result or secondary result that is currently being written.]
Returns the value of the current output URI.
This function is deterministicFO30, focus-independentFO30, and context-dependentFO30.
On initial invocation of a stylesheet component, the current output uri is set to the base output URI.
During execution of an xsl:result-document
instruction with an href
attribute, the current output URI changes to the absolute URI obtained by resolving
the effective value
of the href
attribute against the base output URI.
The current output URI is cleared (set to absent) while evaluating stylesheet functions, dynamic function calls, evaluation of global variables, stylesheet parameters, and patterns. If the function is called when the current output URI is absent, the function returns the empty sequence.
The current output URI may also be absent in the event that a stylesheet is invoked without supplying a base output URI.
The current output URI is not cleared when evaluating a local variable, even though
xsl:result-document
cannot be used while evaluating a local variable.
The reason for this is to allow the value of current-output-uri
to be set as the value of a
tunnel parameter, so that the original
base output URI is accessible even when writing nested result documents.
It is possible to control the type annotation applied to
individual element and attribute nodes as they are constructed. This is done using
the type
and validation
attributes of the
xsl:element
, xsl:attribute
,
xsl:copy
, xsl:copy-of
,
xsl:document
, and xsl:result-document
instructions, or the xsl:type
and xsl:validation
attributes
of a literal result element.
The same attributes are used on
xsl:source-document
and xsl:merge-source
to control
validation of input documents.
The [xsl:]type
attribute is used to request validation of an element or
attribute against a specific simple or complex type defined in a schema. The
[xsl:]validation
attribute is used to request validation against the
global element or attribute declaration whose name matches the name of the element
or
attribute being validated.
The [xsl:]type
and [xsl:]validation
attributes are mutually
exclusive. Both are optional, but if one is present then the other
must be omitted. If both attributes are omitted, the effect is
the same as specifying the validation
attribute with the value specified
in the [xsl:]default-validation
attribute of
the innermost containing element having such an attribute; if this is not
specified, the effect is the same as specifying validation="strip"
.
The [xsl:]default-validation
attribute defines the
default value of the validation
attribute of all
xsl:element
, xsl:attribute
,
xsl:copy
, xsl:copy-of
,
xsl:document
, and xsl:result-document
instructions, and of the xsl:validation
attribute of all literal result elements
, appearing within its scope. It also determines
the validation applied to the implicit final
result tree created in the absence of an
xsl:result-document
instruction. This default applies within the
containing stylesheet module or
package: it does not extend to included or imported stylesheet
modules or used packages. If the attribute is omitted, the default is
strip
. The permitted values are preserve
and
strip
.
The [xsl:]default-validation
attribute has no
effect on the xsl:source-document
and xsl:merge-source
elements, which perform no validation unless explicitly requested.
[ERR XTSE1505] It is a static error if both the
[xsl:]type
and [xsl:]validation
attributes are
present on the xsl:element
, xsl:attribute
,
xsl:copy
, xsl:copy-of
,
xsl:document
, xsl:result-document
, xsl:source-document
, or
xsl:merge-source
elements, or on a literal result element.
The detailed rules for validation vary depending on the kind of node being validated. The rules for element and attribute nodes are given in 25.4.1 Validating Constructed Elements and Attributes, while those for document nodes are given in 25.4.2 Validating Document Nodes.
[xsl:]validation
AttributeThe [xsl:]validation
attribute defines the validation action to be
taken. It determines not only the type
annotation of the node that is constructed by the relevant
instruction itself, but also the type annotations of all element and attribute
nodes that have the constructed node as an ancestor. Conceptually, the
validation requested for a child element or attribute node is applied before
the validation requested for its parent element. For example, if the
instruction that constructs a child element specifies
validation="strict"
, this will cause the child element to be
checked against an element declaration, but if the instruction that constructs
its parent element specifies validation="strip"
, then the final
effect will be that the child node is annotated as xs:untyped
.
In the paragraphs below, the term contained nodes means the elements and attributes that have the newly constructed node as an ancestor.
The value strip
indicates that the new node and each of the
contained nodes will have the type
annotation
xs:untyped
if it is an element, or
xs:untypedAtomic
if it is an attribute. Any previous type
annotation present on a contained element or attribute node (for example,
a type annotation that is present on an element copied from a source
document) is also replaced by xs:untyped
or
xs:untypedAtomic
as appropriate. The typed value of the
node is changed to be the same as its string value, as an instance of
xs:untypedAtomic
. In the case of elements the
nilled
property is set to false
. The values
of the is-id
and is-idrefs
properties are
unchanged. Schema validation is not invoked.
The value preserve
indicates that nodes that are copied will
retain their type
annotations, but nodes whose content is newly constructed will
be annotated as xs:anyType
in the case of elements, or
xs:untypedAtomic
in the case of attributes. Schema
validation is not invoked. The detailed effect depends on the
instruction:
In the case of xsl:element
and literal result
elements, the new element has a type annotation of xs:anyType
, and the
type annotations of contained nodes are retained unchanged.
The nilled
,
is-id
and is-idrefs
properties on the
new element are set to false
.
In the case of xsl:attribute
, the effect is
exactly the same as specifying validation="strip"
:
that is, the new attribute will have the type annotation
xs:untypedAtomic
.
The is-id
and
is-idrefs
properties on the new attribute are set
to false
.
In the case of xsl:copy-of
, all the nodes that are
copied will retain their type annotations unchanged. The values of their
nilled
, is-id
and
is-idrefs
properties are also
unchanged.
In the case of xsl:copy
, the effect depends on the
kind of node being copied.
Where the node being copied is an attribute, the copied
attribute will retain its type annotation
and the values of its
is-id
and is-idrefs
properties.
Where the node being copied is an element, the copied element
will have a type
annotation of xs:anyType
(because
this instruction does not copy the content of the element, it
would be wrong to assume that the type is unchanged); but any
contained nodes will have their type annotations retained in
the same way as with xsl:element
. The values of the
nilled
, is-id
, and
is-idrefs
properties are handled in the
same way as xsl:element
.
The value strict
indicates that type annotations are established by
performing strict schema validity assessment on the element or attribute
node created by this instruction as follows:
In the case of an element, a top-level element declaration is
identified whose local name and namespace (if any) match the name
of the element, and schema-validity assessment is carried out
according to the rules defined in [XML Schema Part 1]
(section 3.3.4 "Element Declaration Validation Rules",
validation rule "Schema-Validity Assessment
(Element)", clauses 1.1 and 2, using the top-level element
declaration as the “declaration stipulated by the processor”, which
is mentioned in clause 1.1.1.1). The element is considered valid if
the result of the schema validity assessment is a PSVI in which the
relevant element node has a validity
property whose
value is valid
. If there is no matching element
declaration, or if the element is not considered valid, the
transformation fails [see ERR XTTE1510], [see ERR XTTE1512]. In effect this means that the element
being validated must be declared using a
top-level declaration in the schema, and must
conform to its declaration. The process of validation applies
recursively to contained elements and attributes to the extent
required by the schema definition.
Note:
It is not an error if the identified type definition is a simple type, although [XML Schema Part 1] does not define explicitly that this case is permitted.
In the case of an attribute, a top-level attribute declaration is
identified whose local name and namespace (if any) match the name
of the attribute, and schema-validity assessment is carried out
according to the rules defined in [XML Schema Part 1]
(section 3.2.4 "Attribute Declaration Validation
Rules", validation rule "Schema-Validity Assessment
(Attribute)"). The attribute is considered valid if the
result of the schema validity assessment is a PSVI in which the
relevant attribute node has a validity
property whose
value is valid
. If the attribute is not considered
valid, the transformation fails [see ERR XTTE1510].
In effect this means that the attribute being validated
must be declared using a top-level
declaration in the schema, and must conform to
its declaration.
The schema components used to validate an element or attribute may
be located in any way described by [XML Schema Part 1] (see
section 4.3.2, How schema documents are located on the
Web). The components in the schema constructed from the
synthetic schema document (see 3.15 Importing Schema Components) will
always be available for validating constructed nodes; if additional
schema components are needed, they may be
located in other ways, for example implicitly from knowledge of the
namespace in which the elements and attributes appear, or using the
xsi:schemaLocation
attribute of elements within the
tree being validated.
The type annotations on the resulting
nodes, as well as the values of their is-id
,
is-idrefs
, and nilled
properties, are
defined by the rules in Section
3.3 Construction from a PSVI
DM31.
If no validation is performed for a node, which can happen when the
schema specifies lax
or skip
validation
for that node or for a subtree, then the node is annotated as
xs:anyType
in the case of an element, and
xs:untypedAtomic
in the case of an attribute.
The value lax
has the same effect as the value
strict
, except that whereas strict
validation fails if there is no matching top-level element declaration or
if the outcome of validity assessment is a validity
property
of invalid
or notKnown
, lax
validation fails only if the outcome of validity assessment is a
validity
property of invalid
. That is,
lax
validation does not cause a type error when the outcome is
notKnown
.
In practice this means that the element or attribute being validated
must conform to its declaration if a top-level
declaration is available. If no such declaration is available, then the
element or attribute is not validated, but its attributes and children
are validated, again with lax validation. Any nodes whose validation
outcome is a validity
property of notKnown
are
annotated as xs:anyType
in the case of an element, and
xs:untypedAtomic
in the case of an attribute.
The type annotations on the resulting nodes,
as well as the values of their is-id
,
is-idrefs
, and nilled
properties, are defined
by the rules in Section
3.3 Construction from a PSVI
DM31.
Note:
When the parent element lacks a declaration, the XML Schema specification defines the recursive checking of children and attributes as optional. For this specification, this recursive checking is required.
Note:
If an element that is being validated has an xsi:type
attribute, then the value of the xsi:type
attribute will
be taken into account when performing the validation. However, the
presence of an xsi:type
attribute will not of itself
cause an element to be validated: if validation against a named type
is required, as distinct from validation against a top-level element
declaration, then it must be requested using the XSLT
[xsl:]type
attribute on the instruction that invokes
the validation, as described in section 25.4.1.2 Validation using the [xsl:]type Attribute
[ERR XTTE1510] If the validation
attribute of an
xsl:element
, xsl:attribute
,
xsl:copy
, xsl:copy-of
, or
xsl:result-document
instruction, or the
xsl:validation
attribute of a literal result element, has
the effective value strict
, and schema validity assessment
concludes that the validity of the element or attribute is invalid or
unknown, a type error occurs. As
with other type errors, the error may be signaled
statically if it can be detected statically.
[ERR XTTE1512] If the validation
attribute of an
xsl:element
, xsl:attribute
,
xsl:copy
, xsl:copy-of
, or
xsl:result-document
instruction, or the
xsl:validation
attribute of a literal result element, has
the effective value strict
, and there is no matching
top-level declaration in the schema, then a type error occurs. As with other type errors, the error
may be signaled statically if it can be detected
statically.
[ERR XTTE1515] If the validation
attribute of an
xsl:element
, xsl:attribute
,
xsl:copy
, xsl:copy-of
, or
xsl:result-document
instruction, or the
xsl:validation
attribute of a literal result element, has
the effective value lax
, and schema validity assessment
concludes that the element or attribute is invalid, a type error occurs. As with other type
errors, the error may be signaled statically if it can
be detected statically.
Note:
No mechanism is provided to validate an element or attribute against a local declaration in a schema. Such validation can usually be achieved by applying validation to a containing element for which a top-level element declaration exists.
[xsl:]type
AttributeThe [xsl:]type
attribute takes as its value a QName
.
This must be the name of a type definition included in the
in-scope schema
components for the stylesheet. If the QName has no prefix, it is
expanded using the default namespace established using the effective
[xsl:]xpath-default-namespace
attribute if there is one;
otherwise, it is taken as being a name in no namespace.
If the [xsl:]type
attribute is present, then the newly constructed
element or attribute is validated against the type definition identified by
this attribute.
In the case of an element, schema-validity assessment is carried out
according to the rules defined in [XML Schema Part 1] (section
3.3.4 "Element Declaration Validation Rules", validation
rule "Schema-Validity Assessment (Element)", clauses 1.2 and
2), using this type definition as the "processor-stipulated type
definition". The element is considered valid if the result of
the schema validity assessment is a PSVI in which the relevant element
node has a validity
property whose value is
valid
.
In the case of an attribute, the attribute is considered valid if (in the
terminology of XML Schema) the attribute’s normalized value is
locally valid with respect to that type definition according to the rules
for "String Valid" ([XML Schema Part 1], section
3.14.4). (Normalization here refers to the process of normalizing
whitespace according to the rules of the whiteSpace
facet
for the datatype).
If the element or attribute is not considered valid, as defined above, the transformation fails [see ERR XTTE1540].
If an element node is validated against the type
xs:untyped
, the effect is the same as specifying
validation="strip"
: that is, the elements and attributes in the
subtree rooted at the target element are copied with a type annotation of
xs:untyped
or xs:untypedAtomic
respectively.
If an element or attribute node is validated against the type
xs:untypedAtomic
, the effect is the same as specifying
[xsl:]type="xs:string"
except that when validation succeeds,
the returned element or attribute has a type annotation of
xs:untypedAtomic
. Validation fails in the case of an element
with element children.
[ERR XTSE1520] It is a static error if the
value of the type
attribute of an
xsl:element
, xsl:attribute
,
xsl:copy
, xsl:copy-of
,
xsl:document
, or xsl:result-document
instruction, or the xsl:type
attribute of a literal result
element, is not a valid QName
, or if it uses a prefix that
is not defined in an in-scope namespace declaration, or if the QName is
not the name of a type definition included in the in-scope schema
components for the package.
[ERR XTSE1530] It is a static error if the
value of the type
attribute of an
xsl:attribute
instruction refers to a complex type
definition.
[ERR XTTE1535] It is a type error if the value of
the type
attribute of an xsl:copy
or
xsl:copy-of
instruction refers to a complex type
definition and one or more of the items being copied is an attribute
node.
[ERR XTTE1540] It is a type error if an
[xsl:]type
attribute is defined for a constructed element
or attribute, and the outcome of schema validity assessment against that
type is that the validity
property of that element or
attribute information item is other than valid
.
Note:
Like other type errors, this error may be signaled statically if it can be
detected statically. For example, the instruction <xsl:attribute
name="dob" type="xs:date">1999-02-29</xsl:attribute>
may
result in a static error being signaled. If the error is not signaled
statically, it will be signaled when the instruction is evaluated.
As well as checking for validity against the schema, the validity assessment process causes type annotations to be associated with element and attribute nodes. If default values for elements or attributes are defined in the schema, the validation process will where necessary create new nodes containing these default values.
Validation of an element or attribute node only takes into account constraints on the content of the element or attribute. Validation rules affecting the document as a whole are not applied. Specifically, this means:
The validation rule "Validation Root Valid (ID/IDREF)" is not applied. This means that validation will not fail if there are non-unique ID values or dangling IDREF values in the subtree being validated.
The validation rule "Validation Rule: Identity-constraint Satisfied" should be applied.
There is no check that the document contains unparsed entities whose
names match the values of nodes of type xs:ENTITY
or
xs:ENTITIES
. (XSLT 3.0
provides no facility to construct unparsed entities within a tree.)
With these caveats, validating a newly constructed element, using strict or lax validation, is equivalent to the following steps:
The element is serialized to textual XML form, according to the rules defined in [XSLT and XQuery Serialization] using the XML output method, with all parameters defaulted. Note that this process discards any existing type annotations.
The resulting XML document is parsed to create an XML Information Set (see [XML Information Set].)
The Information Set produced in the previous step is validated according to the rules in [XML Schema Part 1]. The result of this step is a Post-Schema Validation Infoset (PSVI). If the validation process is not successful (as defined above), a type error is raised.
The PSVI produced in the previous step is converted back into the XDM data model by the mapping described in [XDM 3.0] (Section 3.3.1 Mapping PSVI Additions to Node Properties DM30). This process creates nodes with simple or complex type annotations based on the types established during schema validation.
The above process must be done in such a way that the base URI property of every node in the resulting XDM tree is the same as the base URI property of the corresponding node in the input tree.
Note:
As an alternative to steps 1 and 2, the XDM tree may be converted to an Infoset directly, using the mapping rules given for each kind of node in [XDM 3.0] (Section 6).
Validating an attribute using strict or lax validation requires a modified version of this procedure. A copy of the attribute is first added to an element node that is created for the purpose, and namespace fixup (see 5.7.3 Namespace Fixup) is performed on this element node. The name of this element is of no consequence, but it must be the same as the name of a synthesized element declaration of the form:
<xs:element name="E"> <xs:complexType> <xs:sequence/> <xs:attribute ref="A"/> </xs:complexType> </xs:element>
where A is the name of the attribute being validated.
This synthetic element is then validated using the procedure given above for validating elements, and if it is found to be valid, a copy of the validated attribute is made, retaining its type annotation, but detaching it from the containing element (and thus, from any namespace nodes).
The XDM data model does not permit an attribute node with no parent to have a
typed value that includes a namespace-qualified name, that is, a value whose
type is derived from xs:QName
or xs:NOTATION
. This
restriction is imposed because these types rely on the namespace nodes of a
containing element to resolve namespace prefixes. Therefore, it is an error to
validate a parentless attribute against such a type. This affects the
instructions xsl:attribute
, xsl:copy
, and
xsl:copy-of
.
[ERR XTTE1545] A type error occurs if a
type
or validation
attribute is defined
(explicitly or implicitly) for an instruction that constructs a new
attribute node, if the effect of this is to cause the attribute value to
be validated against a type that is derived from, or constructed by list
or union from, the primitive types xs:QName
or
xs:NOTATION
.
It is possible to apply validation to a document node. This happens when a new
document node is constructed by one of the XSLT elements xsl:source-document
, xsl:merge-source
, xsl:document
,
xsl:result-document
, xsl:copy
, or
xsl:copy-of
, and this element has a type
attribute, or a validation
attribute with the value
strict
or lax
.
Document-level validation is not applied to the document node that is created
implicitly when a variable-binding element has no select
attribute
and no as
attribute (see 9.4 Creating Implicit Document Nodes). This is
equivalent to using validation="preserve"
on
xsl:document
: nodes within such trees retain their type annotation. Similarly, validation is
not applied to document nodes created using xsl:message
or xsl:assert
.
The values validation="preserve"
and validation="strip"
do not request validation. In the first case, all element and attribute nodes
within the tree rooted at the new document node retain their type annotations. In the second case,
elements within the tree have their type annotation set to
xs:untyped
, while attributes have their type annotation set to
xs:untypedAtomic
.
When validation is requested for a document node (that is, when
validation
is set to strict
or lax
, or
when a type
attribute is present), the following processing takes
place:
[ERR XTTE1550] A type error occurs unless the children of the document node comprise exactly one element node, no text nodes, and zero or more comment and processing instruction nodes, in any order.
The single element node child is validated, using the supplied values of the
validation
and type
attributes, as described in
25.4.1 Validating Constructed Elements and Attributes.
Note:
The type
attribute on xsl:source-document
,
xsl:document
and
xsl:result-document
, and on xsl:copy
and xsl:copy-of
when copying a document node, thus
refers to the required type of the element node that is the only element
child of the document node. It does not refer to the type of the document
node itself.
The validation rule "Validation Root Valid (ID/IDREF)" is applied to the single element node child of the document node. This means that validation will fail if there are non-unique ID values or dangling IDREF values in the document tree.
Identity constraints, as defined in section 3.11 of [XML Schema Part 1], are checked. (This refers to constraints defined
using xs:unique
, xs:key
, and
xs:keyref
.)
There is no check that the tree contains unparsed entities whose names match
the values of nodes of type xs:ENTITY
or
xs:ENTITIES
. This is because there is no facility in XSLT
3.0 to create unparsed entities in a
result tree. It is possible to
add unparsed entity declarations to the result document by referencing a
suitable DOCTYPE during serialization.
All other children of the document node (comments and processing instructions) are copied unchanged.
[ERR XTTE1555] It is a type error if, when validating a document node, document-level constraints (such as ID/IDREF constraints) are not satisfied.
xml:id
attributesThis section provides a non-normative summary of the effect of validation on
attributes named xml:id
. The normative rules can be inferred from rules
given elsewhere in this section.
When an attribute named xml:id
is encountered
in the course of validation:
A validation error occurs if it the attribute is not lexically valid against type
xs:ID
.
The typed value of the attribute is whitespace-normalized.
The attribute is labeled with type annotation xs:ID
.
The attribute acquires the is-id
property.
The previous rule applies whether validation is strict, lax, or by type;
validation will never fail (or be skipped) on the grounds
that no global attribute declaration named xsl:id
is available.
Checking xml:id
attributes for uniqueness happens if and only if
validation is applied at the level of a document node.