A module is a piece of XQuery code that can
independently undergo the analysis phase described
in 2.4.2 Type
Checking. A module that contains a Prolog
followed by a Query Body is called a main
module. A query consists of exactly one main module.
In a main module, the Query Body can be evaluated, and
its value is the result of the query. A module that
contains a Module Declaration followed by a
Prolog is called a library module. A
library module cannot be evaluated directly; instead, it
provides function and variable definitions that can be
imported into other modules. No module may contain both a
Module Declaration and a Query Body.
The Module Declaration, if present, consists of
the keyword module followed by a URI that
serves as the target namespace of the module. The
target namespace is the default namespace for variable
definitions in the module, and is also the default
function namespace for the module unless the module's
Prolog explicitly declares a different default function
namespace.
All variables and functions defined in a library
module must be, explicitly or implicitly, in the target
namespace of the library module. If a library module
declares a default function namespace that is different
from its target namespace (for example, in order to use
the functions in [XQuery
1.0 and XPath 2.0 Functions and Operators] without a
prefix), then the names of functions defined in the
library module must have explicit prefixes that are bound
to the target namespace of the library module.
Any module may import a library module by means of a
module import that specifies the target namespace
of the library module to be imported. When a module
imports one or more library modules, the variables and
functions defined in the imported modules are added to
the static context and (where applicable) to the
dynamic context of the importing module.
The Prolog is a series of declarations and
definitions that create the environment for query
processing. The Prolog may contain a version
declaration that specifies the version of the XQuery
language that is used in the module. The Prolog may also
include namespace declarations, schema imports, module
imports, variable definitions, and declarations that
control various processing options. In addition, the
Prolog may contain some function definitions.
The Query Body, if present, consists of an
expression that defines the result of the query, as
described in 3
Expressions. A module can be evaluated only if it
has a Query Body.
4.1 Version
Declaration
A version declaration specifies the
applicable XQuery syntax and semantics for a module.
The version number "1.0" indicates the requirement that
the query must be processed by an XQuery Version 1.0
processor. If the version declaration is not present,
the version is presumed to be "1.0". An XQuery
implementation must raise a static error when
processing a query labeled with a version that the
implementation does not support. It is the intent of
the XQuery working group to give later versions of this
specification numbers other than "1.0", but this intent
does not indicate a commitment to produce any future
versions of XQuery, nor if any are produced, to use any
particular numbering scheme.
The following is an example of a version
declaration:
4.2 Namespace
Declarations
A Namespace Declaration defines a namespace
prefix and associates it with a namespace URI, adding
the (prefix, URI) pair to the set of in-scope
namespaces. The string literal used in a namespace
declaration must be a valid URI, and may not be a
zero-length string. The namespace declaration is in
scope throughout the query in which it is declared,
unless it is overridden by a namespace declaration
attribute in an element constructor.
The following query illustrates a namespace
declaration:
declare namespace foo = "http://example.org"
<foo:bar> Lentils </foo:bar>
In the query result, the newly created node is in
the namespace associated with the namespace URI
http://example.org.
Multiple declarations of the same namespace prefix
in the Prolog result in a static error. However, a
declaration of a namespace in the Prolog can override a
prefix that has been predeclared in the static
context.
(: Error: multiple declarations of namespace 'xx' :)
declare namespace xx = "http://example.org/foo"
declare namespace xx = "http://example.org/bar"
<xx:bing/>
It is a static error to use a QName with a namespace
prefix that has not been declared.
In an element constructor, a namespace
declaration attribute can be used to bind a prefix
to a namespace, adding a (prefix, URI) pair to the set
of in-scope namespaces for the element in which it
occurs and for nested expressions. The binding of a
prefix by a namespace declaration attribute overrides
any binding of the same prefix by a higher-level
element or by the Prolog. The value of a namespace
declaration attribute must be a valid URI. In the Data
Model, a namespace declaration attribute generates a
namespace node rather than an attribute node. Namespace
nodes are not retrieved by queries that return the
attributes of an element. The following query
illustrates a namespace declaration attribute that
binds the prefix foo within the scope of a
constructed element:
<foo:bar xmlns:foo="http://example.org">{ //foo:bing }</foo:bar>
When element or attribute names are compared, they
are considered identical if the local part and
namespace URI match. Namespace prefixes need not be
identical for two names to match, as illustrated by the
following example:
declare namespace xx = "http://example.org"
let $i := <foo:bar xmlns:foo = "http://example.org">
<foo:bing> Lentils </foo:bing>
</foo:bar>
return $i/xx:bing
Although the namespace prefixes xx and
foo differ, both are bound to the
namespace URI "http://example.org". Since
xx:bing and foo:bing have the
same local name and the same namespace URI, they match.
The output of the above query is as follows.
<foo:bing> Lentils </foo:bing>
XQuery has five predefined namespace prefixes that
are present in the in-scope namespaces before
each query is processed. These prefixes may be used
without an explicit declaration. Their definitions may
be overridden by namespace declarations in the Prolog
or by namespace declaration attributes on constructed
elements (except for the prefix xml, which
may not be redefined.) The five predefined namespace
prefixes are as follows:
-
xml =
http://www.w3.org/XML/1998/namespace
-
xs =
http://www.w3.org/2001/XMLSchema
-
xsi =
http://www.w3.org/2001/XMLSchema-instance
-
fn =
http://www.w3.org/2003/05/xpath-functions
-
xdt =
http://www.w3.org/2003/05/xpath-datatypes
Additional predefined namespace prefixes may be
added to the in-scope namespaces by an
implementation.
The namespace prefix xmlns also has a
special significance (it identifies a namespace
declaration attribute), and it may not be
redefined.
4.3 Default Namespace
Declarations
Default Namespace Declarations can be used in
a Prolog to facilitate the use of unprefixed QNames.
The string literal used in a default namespace
declaration must be a valid URI, and may be a
zero-length string. The following kinds of default
namespace declarations are supported:
-
Declaration of a default element
namespace defines a namespace URI that is
associated with unprefixed names of elements and
types. If no default element namespace is declared,
unqualified names of elements and types are in no
namespace. The following example illustrates the
declaration of a default namespace for elements and
types:
default element namespace = "http://example.org/names"
If a direct element constructor includes
an attribute named xmlns, it is
considered to be a namespace declaration
attribute that specifies a new default
element namespace within the scope of the
constructed element and its descendants. For
example, within the scope of the following
constructed element, the default element namespace
is http://example.org/altnames.
<abc xmlns="http://example.org/altnames">Content goes here.</abc>
-
A Prolog may contain a declaration for a
default function namespace. If no default
function namespace is declared in the Prolog of a
library module, the default function
namespace for that module is the target
namespace of the module. If no default function
namespace is declared in the Prolog of a main
module, the default function namespace for that
module is the namespace of XPath/XQuery functions,
http://www.w3.org/2003/05/xpath-functions.
The following example illustrates the declaration
of a default function namespace:
default function namespace = "http://example.com/functions"
The effect of declaring a default function
namespace is that all functions in the default
function namespace, including implicitly-defined
constructor functions, are aliased with a name that
has the original local name, but no namespace URI.
It is a static error if this results in two
functions having the same name and arity. The
function may be referred to using either its
original name or its alias--that is, the namespace
prefix becomes optional.
When a function call uses a function name with
no prefix, the local name of the function must
match a function in one of the following
categories:
-
Functions (including implicitly-defined
constructor functions) in the default function
namespace.
-
Functions defined in the Prolog of the
current module or an imported module, without a
namespace prefix.
-
Constructor functions for atomic types in
the in-scope type definitions whose
names are in no namespace.
Unqualified attribute names and variable names are
never in a namespace, with one exception: in a
variable definition in a library module,
if the name of the variable being defined has no
prefix, it is considered to be in the target
namespace of the library module.
4.4 Schema Imports
A schema import imports the element,
attribute, and type definitions from a named schema
into the in-scope schema definitions. The string
literals in a schema import must be valid URIs. The
schema import specifies the target namespace of the
schema to be imported, and optionally the location of
the schema. A schema import may also bind a namespace
prefix to the target namespace of the imported schema,
or may declare that target namespace to be the default
element namespace. The optional location indication can
be disregarded by an implementation if it has another
way to locate the given schema.
The following example imports the schema for an
XHTML document, specifying both its target namespace
and its location, and binding the prefix
xhtml to this namespace:
import schema namespace xhtml="http://www.w3.org/1999/xhtml"
at "http://example.org/xhtml/xhtml.xsd"
The following example imports a schema by specifying
only its target namespace, and makes it the default
element namespace for the query:
import schema default element namespace="http://example.org/abc"
It is a static error to import two schemas that both
define the same name in the same symbol space and in
the same scope. For instance, a query may not import
two schemas that include top-level element declarations
for two elements with the same expanded name.
Note:
XQuery 1.0 supports querying of DTD-validated
documents only if the Static Typing Feature is not
enabled. Since XQuery 1.0 does not provide a means
for importing Document Type Definitions (DTDs),
implementations supporting the Static Typing Feature
level are not required to recognize or support type
information in DTDs.
If static typing of queries that access
DTD-validated documents is required, the DTD should
be converted to an XML Schema and the resulting
schema should be imported into the query. We request
public comment on this restriction.
4.5 Module
Imports
A module import imports the function
definitions and variable definitions from the Prolog of
a library module into the in-scope
functions and in-scope variables of the
importing module. The string literals in a module
import must be valid URIs. The module import
identifies the module to be imported by its target
namespace, and may also specify its location by
using an at clause. Implementations may
locate modules in any manner that is convenient, and
are free to ignore the specified location if they have
another way to find a module. By means of an optional
namespace clause, a module import may bind
a namespace prefix to the target namespace of the
imported module.
Each module has its own static context. A
module import imports only functions and
variable definitions; it does not import other
declarations from the imported module, such as
in-scope schema definitions or in-scope
namespaces. Module imports are not transitive--that
is, importing a module provides access only to function
and variable definitions contained directly in the
imported module. For example, if module A imports
module B, and module B imports module C, module A does
not have access to the functions and variables defined
in module C. Two modules may import each other.
It is a type error to import a module if the
importing module's in-scope type definitions do
not include definitions for the type names that appear
in variable definitions, function parameters, or
function returns found in the imported module. It is a
static error to import a module that contains function
definitions or variable definitions whose names are
already defined in the static context of the importing
module.
To illustrate the above rules, suppose that a
certain schema defines a type named
triangle. Suppose that a library module
imports the schema, binds its target namespace to the
prefix geo, and defines a function with
the signature area($t as geo:triangle) as
xs:double. If a query wishes to use this
function, it must import both the library
module and the schema on which it is based. Importing
the library module alone would not provide access to
the type definition on which the area
function is defined.
4.6 Variable
Definitions
A variable definition adds the static type of
a variable to the static context, and may also
add a value for the variable to the evaluation
context.
If a variable definition includes a type, that type
is added to the static context as the type of the
variable. If a variable definition includes an
expression but not an explicit type, the static type of
the variable is inferred from the static type of the
expression. If a variable definition includes both a
type and an expression, the static type of the
expression must be compatible with the declared static
type; otherwise a type error is raised.
If a variable definition includes an expression, the
value of the expression is bound to the variable in the
evaluation context. If the variable definition includes
the keyword external, a value must be
provided for the variable by the external environment
before the query can be evaluated. If the value
provided by the external environment is not compatible
with the declared type of the variable, a type error is
raised.
If a variable definition contains neither a type nor
an expression, the type and value of the variable must
both be provided by the external environment at
evaluation time. The static type of such a variable is
considered to be xs:anyType.
A variable or function may appear in the expression
part of a variable definition only if that variable or
function is defined before the variable definition
(that is, its definition must be declared or imported
earlier in the Prolog than the variable definition in
which it is used.)
All variables defined in a library module
must be implicitly or explicitly in the target
namespace of the library module. When a library
module is imported, variables in the imported module
are added to the in-scope variables of the importing
module.
The term variable definition always refers to
a definition of a variable in a Prolog. The
binding of a variable to a value in a query expression,
such as a FLWOR expression, is known as a variable
binding, and does not make the variable visible to
an importing module.
Here are some examples of variable definitions:
-
The following definition specifies both the type
and the value of a variable. This definition causes
the type xs:integer to be associated
with variable $x in the static
context, and the value 7 to be
associated with variable $x in the
evaluation context.
define variable $x as xs:integer {7}
-
The following definition specifies a value but
not a type. The static type of the variable is
inferred from the static type of its value. In this
case, the variable $x has a static
type of xs:decimal, inferred from its
value which is 7.5.
-
The following definition specifies a type but
not a value. The keyword external
indicates that the value of the variable will be
provided by the external environment. At evaluation
time, if the variable $x in the
evaluation context does not have a value of
type xs:integer, a type error is
raised.
define variable $x as xs:integer external
-
The following definition specifies neither a
type nor a value. It simply declares that the query
depends on the existence of a variable named
$x, whose type and value will be
provided by the external environment. During query
analysis, the type of $x is considered
to be xs:anyType. During query
evaluation, the evaluation context must
include a type and a value for $x, and
its value must be compatible with its type.
define variable $x external
4.7 Validation
Declaration
| [134] |
ValidationDecl |
::= |
"validation" "lax" | "validation"
"strict" | "validation" "skip" |
The validation declaration in the Prolog sets
the validation mode in the static context
to strict, lax, or
skip. This establishes a default
validation mode for the query. The default
validation context for the query is always set
to global. The default validation mode and
validation context can be overridden by
validate expressions within the body of
the query. The significance of validation mode and
validation context are described in 3.13 Validate
Expressions.
4.8 Xmlspace
Declaration
| [108] |
XMLSpaceDecl |
::= |
"declare" "xmlspace" "=" ("preserve" |
"strip") |
The xmlspace declaration in a Prolog controls
whether boundary whitespace is preserved by
element and attribute constructors during execution of
the query, as described in 3.7.1.4 Whitespace in Element
Content. If xmlspace = preserve is
specified, boundary whitespace is preserved. If
xmlspace = strip is specified or if no
xmlspace declaration is present, boundary whitespace is
stripped (deleted).
The following example illustrates an xmlspace
declaration:
declare xmlspace = preserve
4.9 Default
Collation
A Prolog may declare a default collation,
which is the name of the collation to be used by all
functions and operators that require a collation if no
other collation is specified. For example, the
gt operator on strings is defined by a
call to the fn:compare function, which
takes an optional collation parameter. Since the
gt operator does not specify a collation,
the fn:compare function implements
gt by using the default collation
specified in the Prolog. The default collation is
identified by a literal string containing a URI.
The following example illustrates a declaration of a
default collation:
default collation = "http://example.org/languages/Icelandic"
If a Prolog specifies no default collation, the
system provided default collation is chosen. If the
system does not provide a default collation, the
Unicode codepoint collation
(http://www.w3.org/2003/05/xpath-functions/collation/codepoint)
is used. If a Prolog specifies more than one default
collation, or value specified does not identify a
collation known to the implementation, a static error
is raised.
4.10
Function Definitions
In addition to the built-in functions described in
[XQuery 1.0 and XPath
2.0 Functions and Operators], XQuery allows users
to define functions of their own. A function definition
specifies the name of the function, the names and
datatypes of the parameters, and the datatype of the
result. All datatypes are specified using the syntax
described in 2.4.3
SequenceType. A function definition also
includes either an expression called the function
body that defines how the result of the function is
computed from its parameters, or the keyword
external, indicating that the function is
an external function.
External functions are implemented outside
the query environment. For example, an XQuery
implementation might provide a set of external
functions in addition to the core function library
described in [XQuery
1.0 and XPath 2.0 Functions and Operators]. The
purpose of a function definition for an external
function is to declare the datatypes of the function
parameters and result, for use in type checking of the
query that contains or imports the function
declaration.
An XQuery implementation may provide a facility
whereby external functions can be implemented using a
host programming language, but it is not required to do
so. If such a facility is provided, the protocols by
which parameters are passed to an external function,
and the result of the function is returned to the
invoking query, are implementation-defined. An XQuery
implementation may augment the type system of [XQuery 1.0 and XPath 2.0 Data
Model] with additional types that are designed to
facilitate exchange of data with host programming
languages, or it may provide mechanisms for the user to
define such types. For example, a type might be
provided that encapsulates an object returned by an
external function, such as an SQL database
connection.
The name of a function may be qualified with a
namespace prefix. If no namespace prefix is specified,
the function is in no namespace. To avoid the risk of
name collisions, authors of general-purpose or
long-lived function libraries are encouraged to define
their functions in an explicit namespace.
If a function parameter is declared using a name but
no type, its default type is item*. If the
returns clause is omitted from a function
definition, its default return type is
item*.
The parameters of a function definition are
considered to be variables whose scope is the function
body. It is an error for a function definition to have
more than one parameter with the same name. The type of
a function parameter can be any type that can be
expressed as a SequenceType (see 2.4.3
SequenceType).
The following example illustrates the definition and
use of a function that accepts a sequence of valid
employee elements (as defined in the
in-scope element declarations), summarizes them
by department, and returns a sequence of valid
dept elements (again, as defined in the
in-scope element declarations).
Rules for converting function arguments to their
declared parameter types, and for converting the result
of a function to its declared result type, are
described in 3.1.4
Function Calls
A function may be defined recursively--that is, it
may reference its own definition. Mutually recursive
functions, whose bodies reference each other, are also
allowed. The following example defines a recursive
function that computes the maximum depth of a node
hierarchy, and calls the function to find the maximum
depth of a particular document. In its definition, the
user-defined function depth calls the
built-in functions empty and
max.
In XQuery 1.0, user-defined functions may not be
overloaded. Only one function definition may have a
given name. However, some of the built-in functions in
the XQuery core library are overloaded--for example,
the fn:string function can be called with
either zero arguments or one argument.
Since a constructor function is effectively
defined for every user-defined atomic type in the
in-scope type definitions, a static error is
raised if the Prolog attempts to define a function with
the same name as any of these types.
Note:
If a future version of XQuery supports overloading
of user-defined functions, an ambiguity may arise
between a function that takes a node as parameter and
a function with the same name that takes an atomic
value as parameter (since a function call
automatically extracts the atomic value of a node
when necessary). The designers of such a future
version of XQuery can avoid this ambiguity by writing
suitable rules to govern function overloading.
Nevertheless, users who are concerned about this
possibility may choose to explicitly extract atomic
values from nodes when calling functions that expect
atomic values.