xsl:namespace

The <xsl:namespace> instruction constructs a namespace node that is written to the result sequence. Constructing namespace nodes in this way is not a frequent requirement, but there are situations where it is the only way of getting a required namespace declaration in the output.

Changes in 2.0

This instruction is new in XSLT 2.0.

Format

 <xsl:namespace   name = { string }   select? = expression   <!-- content:  sequence-constructor -->  </xsl:namespace> 

Position

<xsl:namespace> is an instruction. It is always used as part of a sequence constructor.

Attributes

Name	Value	Meaning
name mandatory	Attribute value template returning an NCName or a zero-length string	The name of the namespace node (which represents the namespace prefix)
select optional	Expression	Expression to compute the string value of the namespace node (which represents the namespace URI)

Content

If the select attribute is present, the element must be empty. Otherwise, it must contain a nonempty sequence constructor.

Effect

The name attribute determines the name of the namespace node. This corresponds to the namespace prefix. If the value of the name attribute is a zero-length string, the namespace node defines the default namespace. Otherwise, the name must be an NCName (a valid XML name containing no colon ). The name attribute can be written as an attribute value template, allowing the name to be computed dynamically.

The string value of the namespace node, which represents the namespace URI, is established using either the select attribute or the contained sequence constructor. For consistency, this instruction uses the results of evaluating the select attribute or sequence constructor in the same way as other instructions such as <xsl:attribute> and <xsl:value-of> . This means that the result may be a sequence; the sequence is atomized, each item in the atomized sequence is converted to a string, and the resulting strings are concatenated , with an intervening space used as a separator in the case where the select attribute is used. Normally, however, the result of the select attribute should be a single string.

A zero-length string cannot be used as a namespace URI; so a runtime error occurs if the result of the computation just described is a zero-length string.

Note that a namespace node is not the same thing as a namespace declaration. An element has a namespace node for every namespace that is in scope. A namespace undeclaration, such as «xmlns="" » in XML Namespace 1.0, or «xmlns:z="" », which is allowed by XML Namespaces 1.1, is not represented by a namespace node. Rather, it is represented in the data model by the absence of a namespace node.

Usage and Examples

Although namespace declarations are a special kind of attribute in the surface XML syntax, they are represented quite differently in the XPath data model. This means that you cannot produce namespace declarations in the result document by using <xsl:attribute> , or by any other mechanism that produces attribute nodes.

The namespace declarations produced by the serializer are derived from the namespace nodes that are present in the result tree. However, there isn't a one-to-one mapping between namespace nodes and namespace declarations. An element in the result tree has a namespace node for every namespace prefix that is in scope for this element (even if it's also in scope for the element's parent).

Normally, the namespace nodes needed in a result tree are created automatically.

For namespaces used in the names of elements and attributes, this is guaranteed by the namespace fixup process described under <xsl:element> on page 265. This procedure is invoked whenever an element is created in a result tree, whether by <xsl:element> , a literal result element, or by <xsl:copy> or <xsl:copy-of> . It is the namespace fixup procedure that effectively decides what prefixes to use for these names.

The only difficulties that arise are therefore when you need namespaces to be declared in the result document that are not used in element and attribute names. An example is if you want to output the following:

  <price xsi:type="xs:decimal">23.50</price>  

Your document must then contain a namespace declaration that binds the namespace prefix «xs » to the namespace URI « http://www.w3.org/2001/XMLSchema ». The serializer will only produce such a declaration if it encounters a namespace node in the result tree that binds this prefix to this URI.

Here is one convenient way to output the above element:

  <price xsi:type="xs:decimal">   <xsl:namespace name="xs"   select="'http://www.w3.org/2001/XMLSchema'"/>   <xsl:value-of select="23.50"/>   </price>  

Note that there is no need to use <xsl:namespace> to produce a namespace declaration that binds the prefix «xsi » to the namespace http://www.w3.org/2001/XMLSchema-instance . Because this namespace is used in an attribute name, the namespace fixup process will ensure that it is declared. In fact, it would be declared in this case even without namespace fixup, because the rules for a literal result element ensure that all namespaces that are in scope for the literal result element in the stylesheet are copied to the result document, and the «xsi » namespace must be in scope here, or the stylesheet fragment would not be valid.

In fact there are four ways that an element in the result tree can acquire namespace nodes:

• When an element is copied from a source tree using an <xsl:copy> or <xsl:copy-of> instruction, its namespace nodes are also copied, unless this is suppressed by writing «copy-namespaces="no" » .

• When a literal result element is processed , all the namespace nodes that are in scope for this element in the stylesheet are copied to the result tree, unless this is suppressed using the [xsl:] exclude-result-prefixes attribute on some containing element. This attribute is described in the entry for <xsl:stylesheet> on page 448.

• Namespace nodes for namespaces used in element and attribute names are automatically created by the namespace fixup process.

• Namespace nodes can be created manually using the <xsl:namespace> instruction.

So the <xsl:namespace> instruction is needed only if none of the other mechanisms creates the required namespace declaration.

The namespace fixup process does not automatically create namespace nodes in respect of elements or attributes that have QName-valued content, even when there is a schema that describes the content as a QName. The reason for this is to allow namespace fixup and schema validation to operate as separate processes. Suppose that the schema defines the type of attribute start as being an xs:QName , and that you want to create the attribute «start="my:root" » . Schema validation takes the string value of this attribute as input, checks that the namespace prefix «my » is declared, and generates firstly the typed value of this attribute (consisting of the local name «root » and the namespace URI corresponding to prefix «my » ), and secondly the type annotation of the attribute as an xs:QName . So the namespace node has to be created before schema validation takes place. This means it cannot be done by an automatic namespace fixup process, because at the time namespace fixup takes place, the attribute node has no type annotation, so you don't yet know that it's an xs:QName .

If you write a stylesheet that produces an XSLT stylesheet as its output, then it becomes very important to get the right namespace declarations into the output, because XSLT makes heavy use of attributes that contain namespace prefixes: They arise both in attributes such as the name attribute of <xsl:variable> , <xsl:template> , and <xsl:function> , and wherever the stylesheet contains XPath expressions. It's worth remarking that there is nothing in the schema for XSLT stylesheets that marks these attributes out as special. Even the name attributes that appear to have QName-valued content do not actually have a type of xs:QName . This is because although their lexical space is the same as xs:QName , the schema processor would expand them incorrectly. XML Schema specifies (in an erratum, actually) that a schema processor, when it comes across an unprefixed xs:QName value, will expand it using the default namespace, and this is not the behavior required by XSLT. So these attributes are simply strings, which means it is the application that must choose a namespace prefix, and then create a namespace node to bind this to the correct namespace URI.

The <xsl:namespace> instruction adds a namespace node to the result sequence produced by the sequence constructor that it is part of. Normally this result sequence will immediately be used to create the content of an element node. In this case, the attribute and namespace nodes in the sequence need to come before any other nodes. It doesn't matter what order the attributes and namespace nodes are in relative to each other. It is an error if there are two namespace nodes that bind the same namespace prefix to different URIs; this could happen if you create a namespace node manually using <xsl:namespace> that clashes with one that is copied automatically from a source document by an <xsl:copy> or <xsl:copy-of> instruction, or from the stylesheet by a literal result element. This is only really likely to happen in the case of the default namespace. It is permissible to create a default namespace node using <xsl:namespace> , but it's probably not a good idea.

Namespace fixup happens after all the namespace nodes from this result sequence have been constructed , and it is constrained to generate prefixes that don't clash with these namespace nodes. If you have created a namespace node for the default namespace (that is, the empty prefix), then the system will have a problem if the element node itself is in the null namespace, because an element in the null namespace has to use the empty prefix, and it will no longer be available. This can cause a runtime failure.

See Also

• <xsl:attribute> on page 201.

• <xsl:element> on page 260.