XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (159 page)

The
type
and
validation
attributes are mutually exclusive: if one is present, the other must be absent. These attributes are available only with a schema-aware XSLT processor.

Content

A sequence constructor.

Effect

The effect of this instruction is to create a new element node, and to return this node as the result of the instruction.

The name of the generated element node is determined using the
name
and
namespace
attributes. The way in which these attributes are used is described below in the section
The Name of the Element
.

The sequence constructor contained in the

instruction, together with the
use-attribute-sets
attribute, is used to form the content of the new element: that is, its namespaces, attributes, and child nodes. The way this works is described in the section
The Content of the Element
.

When a schema-aware XSLT processor is used, the new element (and its contained elements and attributes) may be validated to ensure that they conform to a type defined in a schema. This process results in the new element node having a type annotation. The type annotation affects the behavior of subsequent operations on this element node even though it is not visible when the result tree is serialized as raw XML. The validation and annotation of the new element node are controlled using the
type
and
validation
attributes. This is described in the section
Validating and Annotating the Element
.

The XSLT specification is written in terms instructions returning a value, which in this case is an element node. Sometimes it is convenient to think in terms of the start tag of the

element producing a start tag in the output XML file and the end tag of the

element producing the corresponding end tag, with the intervening sequence constructor producing the contents of the output element. However, this is a dangerous simplification, because writing the start tag and end tag are not separate operations that can be individually controlled, they are two things that happen together as a consequence of the

instruction being evaluated. This is explained in more detail in the section
Literal Result Elements
in Chapter 3, page 112.

The Name of the Element

The name of an element node has three parts: the prefix, the local name and the namespace URI. These are controlled using the
name
and the
namespace
attributes.

Both the
name
and the
namespace
attributes may be given as attribute value templates; that is, they may contain expressions nested within curly braces. One of the main reasons for using the

instruction in preference to a literal result element (described in the section
Literal Result Elements
in Chapter 3, page 112) is that

allows the name of the element to be decided at runtime, and this is achieved by using attribute value templates in these two attributes.

The result of expanding the
name
attribute value template must be a lexical QName; that is, a valid XML name with an optional namespace prefix, for example,
table
or
fo:block
. If there is a prefix, it must correspond to a namespace declaration that is in scope at this point in the stylesheet, unless there is also a
namespace
attribute, in which case it is taken as referring to that namespace.

The local part of the name of the created element node will always be the same as the local part of the QName supplied as the value of the
name
attribute.

If the

instruction has a
namespace
attribute, it is evaluated (expanding the attribute value template if necessary) to determine the namespace URI part of the name of the created element node:

• If the value is a zero-length string, the element will have a null namespace URI.
  
• Otherwise, the value should be a URI identifying a namespace. This namespace does not need to be in scope at this point in the stylesheet, in fact it usually won't be. The processor may report an error if the value is not a legal URI.
  

If there is no
namespace
attribute:

• If the supplied QName includes a prefix, the prefix must be a namespace prefix that is in scope at this point in the stylesheet. In other words, there must be an
  xmlns:prefix=“uri”
  declaration either on the
  
  instruction itself or on some containing element. The namespace URI in the output will be that of the namespace associated with this prefix in the stylesheet.
  
• Otherwise, the default namespace is used. This is the namespace declared, in some containing element in the stylesheet, with an
  xmlns=“uri”
  declaration. If there is no default namespace declaration in scope, then the element will have a null namespace URI. Note that this is one of the few places in XSLT where the default namespace is used to expand a
  QName
  having no prefix; in nearly all other cases, a null namespace URI is used. The reason is to ensure that the behavior is consistent with that of an element name used in the start tag of a literal result element.
  

The prefix part of the name of the new element node will normally be the same as the prefix part of the lexical QName supplied as the value of the
name
attribute (if that name has no prefix, then the new element node will have no prefix). In rare cases, however, the system may need to choose a different prefix to prevent conflicts: for example, if an attribute of the element uses the same prefix to refer to a different namespace.

The Content of the Element

The attributes, namespaces, and child nodes of the new element node are constructed in what is conceptually a four-stage process, though in practice most implementations are likely to collapse the four stages into one.