10 Functions related to QNames

10.1 Functions to create a QName

In addition to the xs:QName constructor function, QName values can be constructed by combining a namespace URI, prefix, and local name, or by resolving a lexical QName against the in-scope namespaces of an element node. This section defines these functions. Leading and trailing whitespace, if present, is stripped from string arguments before the result is constructed.

Function Meaning
fn:QName Returns an xs:QName value formed using a supplied namespace URI and lexical QName.
fn:parse-QName Returns an xs:QName value formed by parsing an EQName.
fn:resolve-QName Returns an xs:QName value (that is, an expanded-QName) by taking an xs:string that has the lexical form of an xs:QName (a string in the form "prefix:local-name" or "local-name") and resolving it using the in-scope namespaces for a given element.

10.1.1 fn:QName

Summary

Returns an xs:QName value formed using a supplied namespace URI and lexical QName.

Signature
fn:QName(
$uri as xs:string?,
$qname as xs:string
) as xs:QName
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The namespace URI in the returned QName is taken from $uri. If $uri is the zero-length string or the empty sequence, it represents "no namespace".

The prefix (or absence of a prefix) in $qname is retained in the returned xs:QName value.

The local name in the result is taken from the local part of $qname.

Error Conditions

A dynamic error is raised [err:FOCA0002] if $qname does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised [err:FOCA0002] if $uri is the zero-length string or the empty sequence, and the value of $qname contains a colon (:).

A dynamic error may be raised [err:FOCA0002] if $uri is not a valid URI (XML Namespaces 1.0) or IRI (XML Namespaces 1.1).

Examples

fn:QName("http://www.example.com/example", "person") returns an xs:QName with namespace URI = "http://www.example.com/example", local name = "person" and prefix = "".

fn:QName("http://www.example.com/example", "ht:person") returns an xs:QName with namespace URI = "http://www.example.com/example", local name = "person" and prefix = "ht".

10.1.2 fn:parse-QName

Summary

Returns an xs:QName value formed by parsing an EQName.

Signature
fn:parse-QName(
$eqname as xs:string
) as xs:QName
Properties

This function is ·deterministic·, ·context-dependent·, and ·focus-independent·. It depends on namespaces.

Rules

Leading and trailing whitespace in $eqname is stripped.

If the resulting $eqname is castable to xs:NCName, the result is fn:QName("", $eqname): that is, a QName in no namespace.

Otherwise, if the resulting $eqname is in the lexical space of xs:QName (that is, if it is in the form prefix:local), the result is xs:QName($eqname). Note that this result depends on the in-scope prefixes in the static context, and may result in various error conditions.

Otherwise, if the resulting $eqname takes the form of an XPath BracedURILiteralXP40 (that is, Q{uri}local, where the uri part may be zero-length), then the result is fn:QName(uri, local).

The rules used for parsing a BracedURILiteral BracedURILiteral BracedURILiteral BracedURILiteral BracedURILiteral BracedURILiteralXP40 within a URIQualifiedNameXP40 are the XPath rules, not the XQuery rules (the XQuery rules require special characters such as < and & to be escaped).

Error Conditions

A dynamic error is raised [err:FOCA0002] if the supplied value of $eqname, after whitespace normalization, does not match the XPath production EQNameXP40

A dynamic error is raised [err:FONS0004] if the supplied value of $eqname, after whitespace normalization, is in the form prefix:local (with a non-absent prefix), and the prefix cannot be resolved to a namespace URI using the in-scope namespace bindings from the static context.

Examples

fn:parse-QName("Q{http://www.example.com/example}person") returns an xs:QName with namespace URI = "http://www.example.com/example", local name = "person" and prefix = "".

fn:parse-QName("person") returns an xs:QName with absent namespace URI, local name = "person" and prefix = "".

fn:parse-QName("Q{}person") returns an xs:QName with absent namespace URI, local name = "person" and prefix = "".

fn:parse-QName("p:person") returns an xs:QName with namespace URI obtained from the static context, local name = "person" and prefix = "p". (The result is the same as xs:QName("p:person")).

History

Accepted 2022-11-18

10.1.3 fn:resolve-QName

Summary

Returns an xs:QName value (that is, an expanded-QName) by taking an xs:string that has the lexical form of an xs:QName (a string in the form "prefix:local-name" or "local-name") and resolving it using the in-scope namespaces for a given element.

Signature
fn:resolve-QName(
$qname as xs:string?,
$element as element()
) as xs:QName?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $qname is the empty sequence, returns the empty sequence.

More specifically, the function searches the namespace bindings of $element for a binding whose name matches the prefix of $qname, or the zero-length string if it has no prefix, and returns an expanded-QName whose local name is taken from the supplied $qname, and whose namespace URI is taken from the string value of the namespace binding.

If the $qname has no prefix, and there is no namespace binding for $element corresponding to the default (unnamed) namespace, then the resulting expanded-QName has no namespace part.

The prefix (or absence of a prefix) in the supplied $qname argument is retained in the returned expanded-QName, as described in Section 2.1 TerminologyDM40.

Error Conditions

A dynamic error is raised [err:FOCA0002] if $qname does not have the correct lexical form for an instance of xs:QName.

A dynamic error is raised [err:FONS0004] if $qname has a prefix and there is no namespace binding for $element that matches this prefix.

Notes

Sometimes the requirement is to construct an xs:QName without using the default namespace. This can be achieved by writing:

 if (contains($qname, ":")) then fn:resolve-QName($qname, $element) else
            fn:QName("", $qname)

If the requirement is to construct an xs:QName using the namespaces in the static context, then the xs:QName constructor should be used.

Examples

Assume that the element bound to $element has a single namespace binding bound to the prefix eg.

fn:resolve-QName("hello", $element) returns a QName with local name "hello" that is in no namespace.

fn:resolve-QName("eg:myFunc", $element) returns an xs:QName whose namespace URI is specified by the namespace binding corresponding to the prefix "eg" and whose local name is "myFunc".

10.2 Functions and operators related to QNames

This section specifies functions on QNames as defined in [XML Schema Part 2: Datatypes Second Edition].

Function Meaning
op:QName-equal Returns true if two supplied QNames have the same namespace URI and the same local part.
fn:prefix-from-QName Returns the prefix component of the supplied QName.
fn:local-name-from-QName Returns the local part of the supplied QName.
fn:namespace-uri-from-QName Returns the namespace URI part of the supplied QName.
fn:expanded-QName Returns a string representation of an xs:QName in the format Q{uri}local.
fn:in-scope-namespaces Returns the in-scope namespaces of an element node, as a map.
fn:in-scope-prefixes Returns the prefixes of the in-scope namespaces for an element node.
fn:namespace-uri-for-prefix Returns the namespace URI of one of the in-scope namespaces for $element, identified by its namespace prefix.

10.2.1 op:QName-equal

Summary

Returns true if two supplied QNames have the same namespace URI and the same local part.

Operator Mapping

Defines the semantics of the "eq" and "ne" operators when applied to two values of type xs:QName.

Signature
op:QName-equal(
$arg1 as xs:QName,
$arg2 as xs:QName
) as xs:boolean
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns true if the namespace URIs of $arg1 and $arg2 are equal and the local names of $arg1 and $arg2 are equal.

Otherwise, the function returns false.

The namespace URI parts are considered equal if they are both absentDM40, or if they are both present and equal under the rules of the fn:codepoint-equal function.

The local parts are also compared under the rules of the fn:codepoint-equal function.

Notes

The prefix parts of $arg1 and $arg2, if any, are ignored.

10.2.2 fn:prefix-from-QName

Summary

Returns the prefix component of the supplied QName.

Signature
fn:prefix-from-QName(
$value as xs:QName?
) as xs:NCName?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence the function returns the empty sequence.

If $value has no prefix component the function returns the empty sequence.

Otherwise, the function returns an xs:NCName representing the prefix component of $value.

10.2.3 fn:local-name-from-QName

Summary

Returns the local part of the supplied QName.

Signature
fn:local-name-from-QName(
$value as xs:QName?
) as xs:NCName?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence the function returns the empty sequence.

Otherwise, the function returns an xs:NCName representing the local part of $value.

Examples

The expression fn:local-name-from-QName(fn:QName("http://www.example.com/example", "person")) returns "person".

10.2.4 fn:namespace-uri-from-QName

Summary

Returns the namespace URI part of the supplied QName.

Signature
fn:namespace-uri-from-QName(
$value as xs:QName?
) as xs:anyURI?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $value is the empty sequence the function returns the empty sequence.

Otherwise, the function returns an xs:anyURI representing the namespace URI part of $value.

If $value is in no namespace, the function returns the zero-length xs:anyURI.

Examples

The expression fn:namespace-uri-from-QName(fn:QName("http://www.example.com/example", "person")) returns xs:anyURI("http://www.example.com/example").

10.2.5 fn:expanded-QName

Summary

Returns a string representation of an xs:QName in the format Q{uri}local.

Signature
fn:expanded-QName(
$qname as xs:QName?
) as xs:string?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

If $qname is the empty sequence, returns the empty sequence.

The result is a string in the format Q{uri}local, where:

  • uri is the result of fn:string(fn:namespace-uri-from-QName($qname)) (which will be a zero-length string if the QName is in no namespace), and

  • local is the result of fn:local-name-from-QName($qname).

There is no escaping of special characters in the namespace URI. If the namespace URI contains curly braces, the resulting string will not be a valid BracedURILiteralXP40.

Examples

The expression fn:QName("http://www.example.com/example", "person") => fn:expandedQName() returns Q{http://www.example.com/example}person.

The expression fn:QName("", "person") => fn:expandedQName() returns Q{}person.

History

Accepted 2022-11-15.

10.2.6 fn:in-scope-namespaces

Summary

Returns the in-scope namespaces of an element node, as a map.

Signature
fn:in-scope-namespaces(
$element as element()
) as map(union(xs:NCName, enum('')), xs:anyURI)
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns a map representing the prefixes of the in-scope namespaces for $element. The map contains one entry for each in-scope namespace: the key of the entry is the namespace prefix or a zero-length string, and the corresponding value is the namespace URI.

For namespace bindings that have a prefix, the key represents the prefix as an instance of xs:NCName. For the default namespace, which has no prefix, the key is the zero-length string as an instance of xs:string.

Notes

The XML namespace is in scope for every element, so the result will always include an entry with key "xml" and corresponding value http://www.w3.org/XML/1998/namespace.

Examples
let $e := 
<z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two">
  <b xmlns=""/>
</z:a>

The expression fn:in-scope-namespaces($e) returns map{"": "http://example.org/one", "z": "http://example.org/two", "xml": "http://www.w3.org/XML/1998/namespace"}.

History

New in 4.0. Accepted 2022-09-20. Note that the function signature uses notation that is not yet accepted.

10.2.7 fn:in-scope-prefixes

Summary

Returns the prefixes of the in-scope namespaces for an element node.

Signature
fn:in-scope-prefixes(
$element as element()
) as xs:string*
Properties

This function is ·nondeterministic-wrt-ordering·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of the expression map:keys(fn:in-scope-namespaces($element)) (but in no defined order).

Notes

The XML namespace is in scope for every element, so the result will always include the string "xml".

History

Reformulated in 4.0, so it is now defined in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.

10.2.8 fn:namespace-uri-for-prefix

Summary

Returns the namespace URI of one of the in-scope namespaces for $element, identified by its namespace prefix.

Signature
fn:namespace-uri-for-prefix(
$prefix as union(xs:NCName, enum(''))?,
$element as element()
) as xs:anyURI?
Properties

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

Rules

The function returns the result of the expression map:get(fn:in-scope-namespaces($element), string($prefix)).

Examples
let $e := 
<z:a xmlns="http://example.org/one" xmlns:z="http://example.org/two">
  <b xmlns=""/>
</z:a>

The expression fn:namespace-uri-for-prefix("z", $e) returns "http://example.org/two".

The expression fn:namespace-uri-for-prefix("", $e) returns "http://example.org/one".

The expression fn:namespace-uri-for-prefix((), $e) returns "http://example.org/one".

The expression fn:namespace-uri-for-prefix("xml", $e) returns "http://www.w3.org/XML/1998/namespace".

History

Reformulated in 4.0, so it is now defined in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.