p:namespace-rename (3.1) 

Renames a namespace to a new URI.

Summary

<p:declare-step type="p:namespace-rename">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <option name="apply-to" as="item()*" required="false" select="'all'" values="('all','elements','attributes')"/>
  <option name="from" as="xs:anyURI?" required="false" select="()"/>
  <option name="to" as="xs:anyURI?" required="false" select="()"/>
</p:declare-step>

The p:namespace-rename step renames any namespace declaration or use of a namespace in a document to a new value.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to rename the namespace in.

result

output

true

xml html

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

apply-to

item()*

false

all

Whether to apply the changes to elements, attributes or both. See The apply-to option below.

from

xs:anyURI?

false

()

The namespace URI to rename from.

to

xs:anyURI?

false

()

The namespace URI to rename to.

Description

The p:namespace-rename step changes a namespace in a document into another namespace. It affects both the namespace bindings and the namespace usage. Usually that's all there is to it, you can rely on the step to take care of all the details (for those that need to know, see Detailed processing).

If you want to remove a namespace altogether, you need p:namespace-delete.

The apply-to option

The apply-to option can take the following values:

Value

Description

all (default)

Apply the changes to both elements and attributes.

attributes

Apply the changes to attributes only.

elements

Apply the changes to elements only.

The main reason for having an apply-to option is to avoid renaming attributes when the from option specifies no namespace. This happens when you want to turn a document that is not in a namespace into some namespace. Often however, attributes are never in a namespace. By setting the apply-to option to elements, the attributes are not affected.

Detailed processing

The step takes the document appearing on its source port and examines it for occurrences of the namespace mentioned in the from option:

  • A namespace binding with the from value, either defining a prefix (xmlns:…="…") or a default namespace (xmlns="…") declaration, gets the value as specified in the to option.

    If the from option is absent or the empty string, no bindings are changed/removed.

    If the to option is not specified or the empty string, the binding is removed.

  • Depending on the value of the apply-to option (see The apply-to option), elements and/or attributes that are in the from namespace are turned into the to namespace.

    If the from option is absent to the empty string, the changes apply to elements/attributes without a namespace (that are in the no-namespace).

    If the to option is not specified or the empty string, the namespace of the element/attribute is removed (putting it into the no-namespace).

Examples

Basic usage

Source document:

<some-document xmlns="#some-namespace">
   <contents a="b"/>
</some-document>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:namespace-rename from="#some-namespace" to="#some-other-namespace"/>

</p:declare-step>

Result document:

<some-document xmlns="#some-other-namespace">
   <contents a="b"/>
</some-document>

This also works when the source document uses a namespace prefix:

<ns:some-document xmlns:ns="#some-namespace">
   <ns:contents a="b"/>
</ns:some-document>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:namespace-rename from="#some-namespace" to="#some-other-namespace"/>

</p:declare-step>

Result document:

<ns:some-document xmlns:ns="#some-other-namespace">
   <ns:contents a="b"/>
</ns:some-document>

Renaming to a namespace

If you rename a document from the no-namespace into a namespace, you usually don’t want to rename the attributes to that namespace as well. However, if you don’t do anything special, this is exactly what will happen:

Source document:

<some-document>
   <contents a="b"/>
</some-document>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:namespace-rename to="#some-namespace"/>

</p:declare-step>

Result document:

<some-document xmlns="#some-namespace">
   <contents xmlns:_1="#some-namespace" _1:a="b"/>
</some-document>

The XProc processor invents a namespace prefix, and uses this to put the attribute(s) in the target namespace as well. To avoid this, set the apply-to option to elements:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:namespace-rename to="#some-namespace" apply-to="elements"/>

</p:declare-step>

Result document:

<some-document xmlns="#some-namespace">
   <contents a="b"/>
</some-document>

Additional details

  • p:namespace-rename preserves all document-properties of the document(s) appearing on its source port.

  • If the value of the from and to option are the same nothing happens. The step acts like a p:identity step.

Errors raised

Error code

Description

XC0014

It is a dynamic error if the XML namespace (http://www.w3.org/XML/1998/namespace) or the XMLNS namespace (http://www.w3.org/2000/xmlns/) is the value of either the from option or the to option.

XC0092

It is a dynamic error if as a consequence of changing or removing the namespace of an attribute the attribute's name is not unique on the respective element.

Reference information

This description of the p:namespace-rename step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:namespace-rename step can be found here.

The p:namespace-rename step is part of categories:

The p:namespace-rename step is also present in version: 3.0.