5 Modules and Prologs

[1]    Module    ::=    VersionDecl? (LibraryModule | MainModule)
[3]    MainModule    ::=    Prolog QueryBody
[4]    LibraryModule    ::=    ModuleDecl Prolog
[6]    Prolog    ::=    ((DefaultNamespaceDecl | Setter | NamespaceDecl | Import) Separator)* ((ContextItemDecl | AnnotatedDecl | OptionDecl) Separator)*
[8]    Setter    ::=    BoundarySpaceDecl | DefaultCollationDecl | BaseURIDecl | ConstructionDecl | OrderingModeDecl | EmptyOrderDecl | CopyNamespacesDecl | DecimalFormatDecl
[20]    Import    ::=    SchemaImport | ModuleImport
[7]    Separator    ::=    ";"
[43]    QueryBody    ::=    Expr

A query can be assembled from one or more fragments called modules. [Definition: A module is a fragment of XQuery code that conforms to the Module grammar and can independently undergo the static analysis phase described in 2.3.3 Expression Processing. Each module is either a main module or a library module.]

[Definition: A main module consists of a Prolog followed by a Query Body.] A query has exactly one main module. In a main module, the Query Body is evaluated with respect to the static and dynamic contexts of the main module in which it is found, and its value is the result of the query.

[Definition: A module that does not contain a Query Body is called a library module. A library module consists of a module declaration followed by a Prolog.] A library module cannot be evaluated directly; instead, it provides function and variable declarations that can be imported into other modules.

The XQuery syntax does not allow a module to contain both a module declaration and a Query Body.

[Definition: A Prolog is a series of declarations and imports that define the processing environment for the module that contains the Prolog.] Each declaration or import is followed by a semicolon. A Prolog is organized into two parts.

The first part of the Prolog consists of setters, imports, namespace declarations, and default namespace declarations. [Definition: Setters are declarations that set the value of some property that affects query processing, such as construction mode, ordering mode, or default collation.] Namespace declarations and default namespace declarations affect the interpretation of lexical QNames within the query. Imports are used to import definitions from schemas and modules. [Definition: The target namespace of a module is the namespace of the objects (such as elements or functions) that it defines. ]

The second part of the Prolog consists of declarations of variables, functions, and options. These declarations appear at the end of the Prolog because they may be affected by declarations and imports in the first part of the Prolog.

[Definition: The Query Body, if present, consists of an expression that defines the result of the query.] Evaluation of expressions is described in 4 Expressions. A module can be evaluated only if it has a Query Body.

5.1 Version Declaration

[2]    VersionDecl    ::=    "xquery" (("encoding" StringLiteral) | ("version" StringLiteral ("encoding" StringLiteral)?)) Separator

[Definition: A version declaration can identify the applicable XQuery syntax and semantics for a module, as well as its encoding.] [Definition: An XQuery version number consists of two integers separated by a dot. The first integer is referred to as the major version number; the second as the minor version number.] Any XQuery processor that implements any version of XQuery with a given major number must accept any query with the same major version number. The processor may reject queries labeled with a different major version number. The processor may reject queries with the same major version number and a greater minor version number than the processor recognizes. If a query is rejected because of a version mismatch with the processor, a static error [err:XQST0031] must be raised.

Note:

The processor is allowed to provide an option to require that minor versions also match, or that the minor number of the version in the query is not larger than the largest minor version understood by the processor in this major release of XQuery, or to allow more permissive version matching, perhaps with warnings, but the behaviour is then outside the scope of this specification.

The version number "1.0" indicates the intent that the module be processed by an XQuery 1.0 processor, the version number "3.0" indicates the intent that the module be processed by an XQuery 3.0 processor, the version number "3.1" indicates the intent that the module be processed by an XQuery 3.1 processor. If the version declaration is not present or the version is not included in the declaration, an XQuery 3.1 processor assumes a version of "3.1".

[Definition: If present, a version declaration may optionally include an encoding declaration. The value of the string literal following the keyword encoding is an encoding name, and must conform to the definition of EncName specified in [XML 1.0] [err:XQST0087]. The purpose of an encoding declaration is to allow the writer of a query to provide a string that indicates how the query is encoded, such as "UTF-8", "UTF-16", or "US-ASCII".] Since the encoding of a query may change as the query moves from one environment to another, there can be no guarantee that the encoding declaration is correct.

The handling of an encoding declaration is implementation-dependent. If an implementation has a priori knowledge of the encoding of a query, it may use this knowledge and disregard the encoding declaration. The semantics of a query are not affected by the presence or absence of an encoding declaration.

If a version declaration is present, no Comment may occur before the end of the version declaration. If such a Comment is present, the result is implementation-dependent; an implementation may raise an implementation-dependent static error, or ignore the comment.

Note:

The effect of a Comment before the end of a version declaration is implementation-dependent because it may suppress query processing by interfering with detection of the encoding declaration.

The following examples illustrate version declarations:

xquery version "1.0";
xquery version "3.0" encoding "utf-8";

5.2 Module Declaration

[5]    ModuleDecl    ::=    "module" "namespace" NCName "=" URILiteral Separator

[Definition: A module declaration serves to identify a module as a library module. A module declaration begins with the keyword module and contains a namespace prefix and a URILiteral.] The URILiteral must be of nonzero length [err:XQST0088]. The URILiteral identifies the target namespace of the library module, which is the namespace for all variables and functions exported by the library module. The name of every variable and function declared in a library module must have a namespace URI that is the same as the target namespace of the module; otherwise a static error is raised [err:XQST0048]. The (prefix,URI) pair is added to the set of statically known namespaces.

The namespace prefix specified in a module declaration must not be xml or xmlns [err:XQST0070], and must not be the same as any namespace prefix bound in the same module by a schema import, by a namespace declaration, or by a module import with a different target namespace [err:XQST0033].

Any module may import one or more library modules by means of a module import that specifies the target namespace of the library modules to be imported. When a module imports one or more library modules, the variables and functions declared in the imported modules are added to the static context and (where applicable) to the dynamic context of the importing module.

The following is an example of a module declaration:

module namespace gis =
      "http://example.org/gis-functions";

5.3 Boundary-space Declaration

[9]    BoundarySpaceDecl    ::=    "declare" "boundary-space" ("preserve" | "strip")

[Definition: A boundary-space declaration sets the boundary-space policy in the static context, overriding any implementation-defined default. Boundary-space policy controls whether boundary whitespace is preserved by element constructors during processing of the query.] If boundary-space policy is preserve, boundary whitespace is preserved. If boundary-space policy is strip, boundary whitespace is stripped (deleted). A further discussion of whitespace in constructed elements can be found in 4.12.1.4 Boundary Whitespace.

The following example illustrates a boundary-space declaration:

declare boundary-space preserve;

If a Prolog contains more than one boundary-space declaration, a static error is raised [err:XQST0068].

5.4 Default Collation Declaration

[10]    DefaultCollationDecl    ::=    "declare" "default" "collation" URILiteral

[Definition: A default collation declaration sets the value of the default collation in the static context, overriding any implementation-defined default.] The default collation is the collation that is used by 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.

If neither the implementation nor the Prolog specifies a default collation, the Unicode codepoint collation (http://www.w3.org/2005/xpath-functions/collation/codepoint) is used.

The following example illustrates a default collation declaration:

declare default collation "http://example.org/languages/Icelandic";

If a default collation declaration specifies a collation by a relative URI, that relative URI is resolved to an absolute URI using the Static Base URI. If a Prolog contains more than one default collation declaration, or the value specified by a default collation declaration (after resolution of a relative URI, if necessary) is not present in statically known collations, a static error is raised [err:XQST0038].

5.5 Base URI Declaration

[11]    BaseURIDecl    ::=    "declare" "base-uri" URILiteral

[Definition: A base URI declaration specifies the Static Base URI property. The Static Base URI property is used when resolving relative URI references.] For example, the Static Base URI property is used when resolving relative references for module import and for the fn:doc function.

Note:

As discussed in the definition of Static Base URI, if there is no base URI declaration, or if the value of the declaration is a relative URI reference, then the value of the Static Base URI may depend on the location of the query, and it is permissible for this to vary between the static analysis phase and the dynamic evaluation phase.

The following is an example of a base URI declaration:

declare base-uri "http://example.org";

If a Prolog contains more than one base URI declaration, a static error is raised [err:XQST0032].

In the terminology of [RFC3986] Section 5.1, the URILiteral of the base URI declaration is considered to be a "base URI embedded in content". If no base URI declaration is present, Static Base URI property is established according to the principles outlined in [RFC3986] Section 5.1—that is, it defaults first to the base URI of the encapsulating entity, then to the URI used to retrieve the entity, and finally to an implementation-defined default. If the URILiteral in the base URI declaration is a relative URI, then it is made absolute by resolving it with respect to this same hierarchy. For example, if the URILiteral in the base URI declaration is ../data/, and the query is contained in a file whose URI is file:///C:/temp/queries/query.xq, then the Static Base URI property is file:///C:/temp/data/.

It is not intrinsically an error if this process fails to establish an absolute base URI; however, the Static Base URI property is then absentDM31 [err:XPST0001]. When the Static Base URI property is absentDM31, any attempt to use its value to resolve a relative URI reference will result in an error [err:XPST0001].

5.6 Construction Declaration

[12]    ConstructionDecl    ::=    "declare" "construction" ("strip" | "preserve")

[Definition: A construction declaration sets the construction mode in the static context, overriding any implementation-defined default.] The construction mode governs the behavior of element and document node constructors. If construction mode is preserve, the type of a constructed element node is xs:anyType, and all attribute and element nodes copied during node construction retain their original types. If construction mode is strip, the type of a constructed element node is xs:untyped; all element nodes copied during node construction receive the type xs:untyped, and all attribute nodes copied during node construction receive the type xs:untypedAtomic.

The following example illustrates a construction declaration:

declare construction strip;

If a Prolog specifies more than one construction declaration, a static error is raised [err:XQST0067].

5.7 Ordering Mode Declaration

[13]    OrderingModeDecl    ::=    "declare" "ordering" ("ordered" | "unordered")

[Definition: An ordering mode declaration sets the ordering mode in the static context, overriding any implementation-defined default.] This ordering mode applies to all expressions in a module (including both the Prolog and the Query Body, if any), unless overridden by an ordered or unordered expression.

The following example illustrates an ordering mode declaration:

declare ordering unordered;

If a Prolog contains more than one ordering mode declaration, a static error is raised [err:XQST0065].

5.8 Empty Order Declaration

[14]    EmptyOrderDecl    ::=    "declare" "default" "order" "empty" ("greatest" | "least")

[Definition: An empty order declaration sets the default order for empty sequences in the static context, overriding any implementation-defined default. This declaration controls the processing of empty sequences and NaN values as ordering keys in an order by clause in a FLWOR expression.] An individual order by clause may override the default order for empty sequences by specifying empty greatest or empty least.

The following example illustrates an empty order declaration:

declare default order empty least;

If a Prolog contains more than one empty order declaration, a static error is raised [err:XQST0069].

Note:

It is important to distinguish an empty order declaration from an ordering mode declaration. An empty order declaration applies only when an order by clause is present, and specifies how empty sequences are treated by the order by clause (unless overridden). An ordering mode declaration, on the other hand, applies only in the absence of an order by clause.

5.9 Copy-Namespaces Declaration

[15]    CopyNamespacesDecl    ::=    "declare" "copy-namespaces" PreserveMode "," InheritMode
[16]    PreserveMode    ::=    "preserve" | "no-preserve"
[17]    InheritMode    ::=    "inherit" | "no-inherit"

[Definition: A copy-namespaces declaration sets the value of copy-namespaces mode in the static context, overriding any implementation-defined default. Copy-namespaces mode controls the namespace bindings that are assigned when an existing element node is copied by an element constructor or document constructor.] Handling of namespace bindings by element constructors is described in 4.12.1 Direct Element Constructors.

The following example illustrates a copy-namespaces declaration:

declare copy-namespaces preserve, no-inherit;

If a Prolog contains more than one copy-namespaces declaration, a static error is raised [err:XQST0055].

5.10 Decimal Format Declaration

[18]    DecimalFormatDecl    ::=    "declare" (("decimal-format" EQName) | ("default" "decimal-format")) (DFPropertyName "=" StringLiteral)*
[19]    DFPropertyName    ::=    "decimal-separator" | "grouping-separator" | "infinity" | "minus-sign" | "NaN" | "percent" | "per-mille" | "zero-digit" | "digit" | "pattern-separator" | "exponent-separator"

[Definition: A decimal format declaration adds a decimal format to the statically known decimal formats, which define the properties used to format numbers using the fn:format-number() function], as described in [XQuery and XPath Functions and Operators 4.0]. If the form decimal-format EQName is used, then the declaration defines the properties of the decimal format whose name is EQName, while the form default decimal-format defines the properties of the unnamed decimal format. The declaration contains a set of (DFPropertyName, StringLiteral) pairs, where the DFPropertyName is the name of the property and the StringLiteral is its value. The valid values and default values for each property are defined in statically known decimal formats.

If a format declares no properties, default values are used for all properties.

Error conditions are defined as follows:

The following query formats numbers using two different decimal format declarations:

declare decimal-format local:de 
  decimal-separator = "," grouping-separator = "."; 
declare decimal-format local:en 
  decimal-separator = "." grouping-separator = ","; 
       
let $numbers := (1234.567, 789, 1234567.765) 
for $i in $numbers
return ( 
  format-number($i, "#.###,##", "local:de"), 
  format-number($i, "#,###.##", "local:en") 
)

The output of this query is:

1.234,57 1,234.57 789 789 1.234.567,76 1,234,567.76

5.11 Schema Import

[21]    SchemaImport    ::=    "import" "schema" SchemaPrefix? URILiteral ("at" URILiteral ("," URILiteral)*)?
[22]    SchemaPrefix    ::=    ("namespace" NCName "=") | ("default" "element" "namespace")

[Definition: A schema import imports the element declarations, attribute declarations, and type definitions from a schema into the in-scope schema definitions. For each named user-defined simple type in the schema, schema import also adds a corresponding constructor function. ] The schema to be imported is identified by its target namespace. The schema import may bind a namespace prefix to the target namespace of the imported schema, adding the (prefix, URI) pair to the statically known namespaces, or it may declare that target namespace to be the default element namespace and the default type namespace . The schema import may also provide optional hints for locating the schema.

The namespace prefix specified in a schema import must not be xml or xmlns [err:XQST0070], and must not be the same as any namespace prefix bound in the same module by another schema import, a module import, a namespace declaration, or a module declaration [err:XQST0033].

If the schema import declaration specifies default element namespace then the prolog must not contain a namespace declaration that specifies default element namespace or default type namespace.

The first URILiteral in a schema import specifies the target namespace of the schema to be imported. The URILiterals that follow the at keyword are optional location hints, and can be interpreted or disregarded in an implementation-dependent way. Multiple location hints might be used to indicate more than one possible place to look for the schema or multiple physical resources to be assembled to form the schema.

If the target namespace is http://www.w3.org/2005/xpath-functions then the schema described in Section C Schemas FO31 is imported; any location hints are ignored.

A schema import that specifies a zero-length string as target namespace is considered to import a schema that has no target namespace. Such a schema import must not bind a namespace prefix [err:XQST0057], but it may set the default element and/or type namespace to a zero-length string (representing "no namespace"), thus enabling the definitions in the imported namespace to be referenced. If the default element and/or type namespace is not set to "no namespace", the only way to reference the definitions in an imported schema that has no target namespace is using the EQName syntax Q{}local-name .

It is a static error [err:XQST0058] if more than one schema import in the same Prolog specifies the same target namespace. It is a static error [err:XQST0059] if the implementation is not able to process a schema import by finding a valid schema with the specified target namespace. It is a static error [err:XQST0035] if multiple imported schemas, or multiple physical resources within one schema, contain definitions for the same name in the same symbol space (for example, two definitions for the same element name, even if the definitions are consistent). However, it is not an error to import the schema with target namespace http://www.w3.org/2001/XMLSchema (predeclared prefix xs), even though the built-in types defined in this schema are implicitly included in the in-scope schema types.

It is a static error [err:XQST0012] if the set of definitions contained in all schemas imported by a Prolog do not satisfy the conditions for schema validity specified in Sections 3 and 5 of [XML Schema 1.0] or [XML Schema 1.1] Part 1--i.e., each definition must be valid, complete, and unique.

The following example imports a schema, specifying both its target namespace and its location, and binding the prefix soap to the target namespace:

import schema namespace soap="http://www.w3.org/2003/05/soap-envelope" 
    at "http://www.w3.org/2003/05/soap-envelope/";

The following example imports a schema by specifying only its target namespace, and makes it the default namespace for elements and types:

import schema default element namespace "http://example.org/abc";

The following example imports a schema that has no target namespace, providing a location hint, and sets the default namespace for elements and types to "no namespace" so that the definitions in the imported schema can be referenced:

import schema default element namespace "" at "http://example.org/xyz.xsd";

The following example imports a schema that has no target namespace and sets the default namespace for elements and types to "no namespace". Since no location hint is provided, it is up to the implementation to find the schema to be imported.

import schema default element namespace "";

5.12 Module Import

[23]    ModuleImport    ::=    "import" "module" ("namespace" NCName "=")? URILiteral ("at" URILiteral ("," URILiteral)*)?

[Definition: A module import imports the public variable declarations, public function declarations, and public item type declarations from one or more library modules into the statically known function definitions, in-scope variables , or item type aliases of the importing module.] Each module import names a target namespace and imports an implementation-defined set of modules that share this target namespace. The module import may bind a namespace prefix to the target namespace, adding the (prefix, URI) pair to the statically known namespaces, and it may provide optional hints for locating the modules to be imported.

If a module A imports module B, the static context of module A will contain the in-scope schema definitions and statically known function definitions of module B, and the dynamic context of module A will contain the variable values and dynamically known function definitions of module B, with the exception of non-public functions and variables, and of the functions and variables not declared directly in B.

The following example illustrates a module import:

import module namespace gis="http://example.org/gis-functions";

If a query imports the same module via multiple paths, only one instance of the module is imported. Because only one instance of a module is imported, there is only one instance of each variable declared in a module's prolog.

A module may import its own target namespace (this is interpreted as importing an implementation-defined set of other modules that share its target namespace.)

The namespace prefix specified in a module import must not be xml or xmlns [err:XQST0070], and must not be the same as any namespace prefix bound in the same module by another module import, a schema import, a namespace declaration, or a module declaration with a different target namespace [err:XQST0033].

The first URILiteral in a module import must be of nonzero length [err:XQST0088], and specifies the target namespace of the modules to be imported. The URILiterals that follow the at keyword are optional location hints, and can be interpreted or disregarded in an implementation-defined way.

It is a static error [err:XQST0047] if more than one module import in a Prolog specifies the same target namespace. It is a static error [err:XQST0059] if the implementation is not able to process a module import by finding a valid module definition with the specified target namespace. It is a static error if two or more variables declared or imported by a module have equal expanded QNames (as defined by the eq operator) [err:XQST0049].

Each module has its own static context. A module import imports only functions, variable declarations, and item type declaratons; it does not import other objects from the imported modules, such as in-scope schema definitions or statically known namespaces. Module imports are not transitive—that is, importing a module provides access only to declarations 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 declared in module C.

Example: Schema Information and Module Import

A module import does not import schema definitions from the imported module. In the following query, the type geometry:triangle is not defined, even if it is known in the imported module, so the variable declaration raises an error [err:XPST0051]:

(: Error - geometry:triangle is not defined :) 
import module namespace geo = "http://example.org/geo-functions"; 
declare variable $t as geometry:triangle := geo:make-triangle(); 
$t

Without the type declaration for the variable, the variable declaration succeeds:

import module namespace geo = "http://example.org/geo-functions";
declare variable $t := geo:make-triangle(); $t

Importing the schema that defines the type of the variable, the variable declaration succeeds:

import schema namespace geometry = "http://example.org/geo-schema-declarations"; 
import module namespace geo = "http://example.org/geo-functions"; 
declare variable $t as geometry:triangle := geo:make-triangle(); $t

5.12.1 The Target Namespace of a Module

The target namespace of a module should be treated in the same way as other namespace URIs.

To maximize interoperability, query authors should use a string that is a valid absolute IRI.

Implementions must accept any string of Unicode characters. Target namespace URIs are compared using the Unicode codepoint collation rather than any concept of semantic equivalence.

Implementations may provide mechanisms allowing the target namespace URI to be used as input to a process that delivers the module as a resource, for example a catalog, module repository, or URI resolver. For interoperability, such mechanisms should not prevent the user from choosing an arbitrary URI for naming a module.

Similarly, implementations may perform syntactic transformations on the target namespace URI to obtain the names of related resources, for example to implement a convention relating the name or location of compiled code to the target namespace URI; but again, such mechanisms should not prevent the user from choosing an arbitrary target namespace URI.

As with other namespace URIs, it is common practice to use target namespace URIs whose scheme is "http" and whose authority part uses a DNS domain name under the control of the user.

The specifications allow, and some users might consider it good practice, for the target namespace URI of a function library to be the same as the namespace URI of the XML vocabulary manipulated by the functions in that library.

5.12.2 Multiple Modules with the same Namespace

Several different modules with the same target namespace can be used in the same query. The names of public variables and public functions must be unique within the module contexts of a query: that is, if two modules with the same target namespace URI are used in the same query, the names of the public variables and functions in their module contexts must not overlap.

If one module contains an "import module" declaration with the target namespace M, then all public variables and public functions in the contexts of modules whose target namespace is M must be accessible in the importing module, regardless whether the participation of the imported module was directly due to this "import module" declaration.

5.12.3 Location URIs

The term "location URIs" refers to the URIs in the "at" clause of an "import module" declaration.

Products should (by default or at user option) take account of all the location URIs in an "import module" declaration, treating each location URI as a reference to a module with the specified target namespace URI. Location URIs should be made absolute with respect to the static base URI of the module containing the "import module" declaration where they appear. The mapping from location URIs to module source code or compiled code MAY be done in any way convenient to the implementation. If possible given the product's architecture, security requirements, etc, the product should allow this to fetch the source code of the module to use the standard web mechanisms for dereferencing URIs in standard schemes such as the "http" URI scheme.

When the same absolutized location URI is used more than once, either in the same "import module" declaration or in different "import module" declarations within the same query, a single copy of the resource containing the module is loaded. When different absolutized location URIs are used, each results in a single module being loaded, unless the implementation is able to determine that the different URIs are references to the same resource. No error due to duplicate variable or functions names should arise from the same module being imported more than once, so long as the absolute location URI is the same in each case.

Implementations must report a static error if a location URI cannot be resolved after all available recovery strategies have been exhausted.

5.12.4 Cycles

Implementations must resolve cycles in the import graph, either at the level of target namespace URIs or at the level of location URIs, and ensure that each module is imported only once.

5.13 Namespace Declaration

[24]    NamespaceDecl    ::=    "declare" "namespace" NCName "=" URILiteral

[Definition: A namespace declaration declares a namespace prefix and associates it with a namespace URI, adding the (prefix, URI) pair to the set of statically known namespaces.] The namespace declaration is in scope throughout the query in which it is declared, unless it is overridden by a namespace declaration attribute in a direct element constructor.

If the URILiteral part of a namespace declaration is a zero-length string, any existing namespace binding for the given prefix is removed from the statically known namespaces. This feature provides a way to remove predeclared namespace prefixes such as local.

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.

The namespace prefix specified in a namespace declaration must not be xml or xmlns [err:XQST0070]. The namespace URI specified in a namespace declaration must not be http://www.w3.org/XML/1998/namespace or http://www.w3.org/2000/xmlns/ [err:XQST0070]. The namespace prefix specified in a namespace declaration must not be the same as any namespace prefix bound in the same module by a module import, schema import, module declaration, or another namespace declaration [err:XQST0033].

It is a static error [err:XPST0081] if an expression contains a lexical QName with a namespace prefix that is not in the statically known namespaces.

XQuery has several predeclared namespace prefixes that are present in the statically known namespaces before each query is processed. These prefixes may be used without an explicit declaration. They may be overridden by namespace declarations in a Prolog or by namespace declaration attributes on constructed elements (however, the prefix xml must not be redeclared, and no other prefix may be bound to the namespace URI associated with the prefix xml [err:XQST0070]). The predeclared namespace prefixes are as follows:

Additional predeclared namespace prefixes may be added to the statically known namespaces by an implementation.

When element or attribute names are compared, they are considered identical if the local parts and namespace URIs match on a codepoint basis. 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 xmlns:foo = "http://example.org"> Lentils </foo:bing>
    

5.14 Default Namespace Declaration

[25]    DefaultNamespaceDecl    ::=    "declare" "default" ("element" | "type" | "function") "namespace" URILiteral

Default namespace declarations can be used in a Prolog to facilitate the use of unprefixed QNames.

The namespace URI specified in a default namespace declaration must not be http://www.w3.org/XML/1998/namespace or http://www.w3.org/2000/xmlns/ [err:XQST0070].

The following kinds of default namespace declarations are supported:

Unprefixed attribute names and variable names are in no namespace.

5.15 Annotations

[26]    AnnotatedDecl    ::=    "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl)
[188]    InlineFunctionExpr    ::=    Annotation* (("function" FunctionSignature) | ("->" FunctionSignature?)) FunctionBody
[27]    Annotation    ::=    "%" EQName ("(" Literal ("," Literal)* ")")?

XQuery uses annotations to declare properties associated with functions (inline or declared in the prolog) and variables. For instance, a function may be declared %public or %private. The semantics associated with these properties are described in 5.18 Function Declaration.

Annotations are (QName, value) pairs. If the EQName of the annotation is a lexical QName, the prefix of the QName is resolved using the statically known namespaces; if no prefix is present, the name is in the http://www.w3.org/2012/xquery namespace.

Implementations may define further annotations, whose behaviour is implementation-defined. For instance, if the eg prefix is bound to a namespace associated with a particular implementation, it could define an annotation like eg:sequential. If the namespace URI of an annotation is not recognized by the implementation, then the annotation is ignored. Implementations may also provide a way for users to define their own annotations. Implementations must not define annotations in reserved namespaces; it is a static error [err:XQST0045] for a user to define an annotation in a reserved namespace.

An annotation can provide values explicitly using a parenthesized list of literals. For instance, the annotation %java:method("java.lang.Math.sin") sets the value of the java:method annotation to the string value java.lang.Math.sin.

5.16 Variable Declaration

[26]    AnnotatedDecl    ::=    "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl)
[27]    Annotation    ::=    "%" EQName ("(" Literal ("," Literal)* ")")?
[28]    VarDecl    ::=    "variable" "$" VarName TypeDeclaration? ((":=" VarValue) | ("external" (":=" VarDefaultValue)?))
[151]    VarName    ::=    EQName
[202]    TypeDeclaration    ::=    "as" SequenceType
[29]    VarValue    ::=    ExprSingle
[30]    VarDefaultValue    ::=    ExprSingle

A variable declaration adds the static type of a variable to the in-scope variables, and may also add a value for the variable to the variable values.

Note:

A variable declaration always refers to a declaration 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.

During static analysis, a variable declaration causes a pair (expanded QName N, type T) to be added to the in-scope variables. The expanded QName N is the VarName. If N is equal (as defined by the eq operator) to the expanded QName of another variable in in-scope variables, a static error is raised [err:XQST0049]. The type T of the declared variable is as follows:

All variable names declared in a library module must (when expanded) be in the target namespace of the library module [err:XQST0048]. A variable declaration may use annotations to specify that the variable is %private or %public (which is the default). [Definition: A private variable is a variable with a %private annotation. A private variable is hidden from module import, which can not import it into the in-scope variables of another module.] [Definition: A public variable is a variable without a %private annotation. A public variable is accessible to module import, which can import it into the in-scope variables of another module. Using %public and %private annotations in a main module is not an error, but it does not affect module imports, since a main module cannot be imported. It is a static error [err:XQST0116] if a variable declaration contains both a %private and a %public annotation, more than one %private annotation, or more than one %public annotation.]

Variable names that have no namespace prefix are in no namespace. Variable declarations that have no namespace prefix may appear only in a main module.

Here are some examples of variable declarations:

An implementation can provide annotations it needs. For instance, an implementation that supports volatile external variables might allow them to be declared using an annotation:

declare %eg:volatile variable $time as xs:time external;

[Definition: If a variable declaration includes an expression (VarValue or VarDefaultValue), the expression is called an initializing expression. The static context for an initializing expression includes all functions, variables, and namespaces that are declared or imported anywhere in the Prolog, other than the variable being declared.]

If a required type is defined, then the value obtained by evaluating the initializing expression is converted to the required type by applying the coercion rules. A type error occurs if this is not possible. In invoking the coercion rules, XPath 1.0 compatibility mode does not apply.

In a module's dynamic context, a variable value (or the context item) may depend on another variable value (or the context item). [Definition: A variable value (or the context item) depends on another variable value (or the context item) if, during the evaluation of the initializing expression of the former, the latter is accessed through the module context.]

In the following example, the value of variable $a depends on the value of variable $b because the evaluation of $a's initializing expression accesses the value of $b during the evaluation of local:f().

declare variable $a := local:f(); 
declare variable $b := 1;
declare function local:f() { $b }; 

A directed graph can be built with all variable values and the context item as nodes, and with the depend on relation as edges. This graph must not contain cycles, as it makes the population of the dynamic context impossible. If it is discovered, during static analysis or during dynamic evaluation, that such a cycle exists, error [err:XQDY0054] must be raised.

During query evaluation, each variable declaration causes a pair (expanded QName N, value V) to be added to the variable values. The expanded QName N is the VarName. The value V is as follows:

In all cases the value V must match the type T according to the rules for SequenceType matching; otherwise a type error is raised [err:XPTY0004].

5.17 Context Item Declaration

[31]    ContextItemDecl    ::=    "declare" "context" "item" ("as" ItemType)? ((":=" VarValue) | ("external" (":=" VarDefaultValue)?))

A context item declaration allows a query to specify the static type, value, or default value for the initial context item.

Only the main module can set the value of the initial context item. In a library module, a context item declaration must be external, and specifies only the static type. Specifying a VarValue or VarDefaultValue for a context item declaration in a library module is a static error [err:XQST0113].

In every module that does not contain a context item declaration, the effect is as if the declaration

declare context item as item() external;

appeared in that module.

During static analysis, the context item declaration has the effect of setting the context item static type T in the static context. The context item static type is set to ItemType if specified, or to item() otherwise.

If a module contains more than one context item declaration, a static error is raised [err:XQST0099].

The static context for an initializing expression includes all functions, variables, and namespaces that are declared or imported anywhere in the Prolog.

During query evaluation, a singleton focus is created in the dynamic context for the evaluation of the QueryBody in the main module, and for the initializing expression of every variable declaration in every module. The context item of this singleton focus is called the initial context item, which is selected as follows:

In all cases where the context item has a value, that value must match the type T according to the rules for SequenceType matching; otherwise a type error is raised [err:XPTY0004]. If more than one module contains a context item declaration, the context item must match the type declared in each one.

If VarValue or VarDefaultValue is evaluated, the static and dynamic contexts for the evaluation are the current module's static and dynamic context.

If a required type is defined, then the value obtained by evaluating VarValue or VarDefaultValue is converted to the required type by applying the coercion rules. A type error occurs if this is not possible. In invoking the coercion rules, XPath 1.0 compatibility mode does not apply.

Here are some examples of context item declarations.

5.18 Function Declaration

In addition to the built-in functions, XQuery allows users to declare functions of their own. A function declaration declares a family of functions having the same name and similar parameters. The declaration 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 3 Types.

Including a function declaration in the query causes a corresponding function definition to be added to the statically known function definitions of the static context. The associated functions also become available in the dynamically known function definitions of the dynamic context.

[26]    AnnotatedDecl    ::=    "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl)
[27]    Annotation    ::=    "%" EQName ("(" Literal ("," Literal)* ")")?
[32]    FunctionDecl    ::=    "function" EQName FunctionSignatureWithDefaults (FunctionBody | "external") /* xgc: reserved-function-names */
[33]    FunctionSignatureWithDefaults    ::=    "(" ParamListWithDefaults? ")" TypeDeclaration?
[35]    ParamListWithDefaults    ::=    ParamWithDefault ("," ParamWithDefault)*
[36]    ParamWithDefault    ::=    "$" EQName TypeDeclaration? (":=" ExprSingle)?
[39]    FunctionBody    ::=    EnclosedExpr
[202]    TypeDeclaration    ::=    "as" SequenceType
[40]    EnclosedExpr    ::=    "{" Expr? "}"

A function declaration specifies whether the implementation of the function is user-defined or external.

[Definition: User defined functions are functions that contain a function body, which provides the implementation of the function as a content expression.] The static context for a function body includes all functions, variables, and namespaces that are declared or imported anywhere in the Prolog, including the function being declared. Its in-scope variables component also includes the parameters of the function being declared. However, its context item static type component is absentDM31, and an implementation should raise a static error [err:XPST0008] if an expression depends on the context item.

The function declaration includes a list of zero or more function parameters. A parameter is optional if a default value is supplied using the construct := ExprSingle; otherwise it is required. If a parameter is optional, then all subsequent parameters in the list must also be optional. In other words, the parameter list includes zero or more required parameters followed by zero or more optional parameters.

The number of arguments that may be supplied in a call to this family of functions is this in the range M to N, where M is the number of required parameters, and N is the total number of parameters (whether required or optional). This is refered to as the arity range of the function definition.

The properties of the function definition F are derived from the syntax of the function declaration as follows:

The static context may include more than one declared function with the same name, but their arity ranges must not overlap [err:XQST0034].

In function declarations, external functions are identified by the keyword external. The purpose of a function declaration 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.

In addition to user-defined functions and external functions, XQuery 4.0 allows anonymous functions to be declared in the body of a query using inline function expressions.

A function declaration may use the %private or %public annotations to specify that a function is public or private; if neither of these annotations is used, the function is public. [Definition: A private function is a function with a %private annotation. A private function is hidden from module import, which can not import it into the statically known function definitions of another module. ] [Definition: A public function is a function without a %private annotation. A public function is accessible to module import, which can import it into the statically known function definitions of another module. ] Using %public and %private annotations in a main module is not an error, but it does not affect module imports, since a main module cannot be imported. It is a static error [err:XQST0106] if a function declaration contains both a %private and a %public annotation, more than one %private annotation, or more than one %public annotation.

An XQuery implementation may provide a facility whereby external functions can be implemented, 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 and XPath Data Model (XDM) 3.1] with additional types that are designed to facilitate exchange of data, or it may provide mechanism 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. These additional types, if defined, are considered to be derived by restriction from xs:anyAtomicType.

An implementation can define annotations, in its own namespace, to support functionality beyond the scope of this specification. For instance, an implementation that supports external Java functions might use an annotation to associate a Java function with an XQuery external function:

declare 
   %java:method("java.lang.StrictMath.copySign") 
   function smath:copySign($magnitude, $sign) 
   external;

Every declared function must be in a namespace; that is, every declared function name must (when expanded) have a non-null namespace URI [err:XQST0060]. If the function name in a function declaration has no namespace prefix, it is considered to be in the default function namespace. Every function name declared in a library module must (when expanded) be in the target namespace of the library module [err:XQST0048].

[Definition: A reserved namespace is a namespace that must not be used in the name of a function declaration.] It is a static error [err:XQST0045] if the function name in a function declaration (when expanded) is in a reserved namespace. The following namespaces are reserved namespaces:

In order to allow main modules to declare functions for local use within the module without defining a new namespace, XQuery predefines the namespace prefix local to the namespace http://www.w3.org/2005/xquery-local-functions. It is suggested (but not required) that this namespace be used for defining local functions.

If a function parameter is declared using a name but no type, its default type is item()*. If the result type is omitted from a function declaration, its default result type is item()*.

The function body defines the implementation of the function definition. The rules for static function calls (see 4.4.1.2 Evaluating Static Function Calls) ensure that a value is available for each parameter, whether required or optional.

The parameters of a function declaration are considered to be variables whose scope is the function body. It is an static error [err:XQST0039] for a function declaration 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 sequence type.

The following example illustrates the declaration and use of a local function that accepts a sequence of employee elements, summarizes them by department, and returns a sequence of dept elements.

A function declaration may be recursive—that is, it may reference itself. Mutually recursive functions, whose bodies reference each other, are also allowed. The following example declares 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. The function local:depth calls the built-in functions empty and max, which are in the default function namespace.

[TODO: add an example of a function with an optional parameter.]

5.19 Item Type Declarations

An item type declaration defines a name for an item type. Defining a name for an item type allows it to be referenced (using the syntax item-type(name) rather than repeating the item type definition in full.

[26]    AnnotatedDecl    ::=    "declare" Annotation* (VarDecl | FunctionDecl | ItemTypeDecl)
[27]    Annotation    ::=    "%" EQName ("(" Literal ("," Literal)* ")")?
[41]    ItemTypeDecl    ::=    "item-type" EQName "as" ItemType

An item-type declaration adds a named item type to the item type aliases of the containing module. This enables the item type to be referred to using a simple name.

For example, given the declaration:

declare item-type app:invoice as map("xs:string", element(inv:paid-invoice))

It becomes possible to declare a variable containing a sequence of such items as:

declare variable $invoices as app:invoice*

The definition can also be used within another item-type declaration:

declare item-type app:overdue-invoices as map("xs:date", app:invoice*)

If the name of the item type is written as an (unprefixed) NCName, then it is interpreted as being in no namespace.

All item type names declared in a library module must (when expanded) be in the target namespace of the library module [err:XQST0048].

An item type declaration may use the %private or %public annotations to specify that an item type name is public or private; if neither of these annotations is used, the declaration is public. [Definition: A private item type is a named item type with a %private annotation. A private item type is hidden from module import, which can not import it into the item type aliases of another module. ] [Definition: A public item type is an item type declaration without a %private annotation. A public item type is accessible to module import, which can import it into the item type aliases of another module. ] Using %public and %private annotations in a main module is not an error, but it does not affect module imports, since a main module cannot be imported. It is a static error [err:XQST0106] if an item type declaration contains both a %private and a %public annotation, more than one %private annotation, or more than one %public annotation.

A static error must be reported if the definition of item types is cyclic: that is, if the definition of an item type depends directly or indirectly on itself. [TODO: ERROR CODE]

5.20 Option Declaration

[Definition: An option declaration declares an option that affects the behavior of a particular implementation. Each option consists of an identifying EQName and a StringLiteral.]

[42]    OptionDecl    ::=    "declare" "option" EQName StringLiteral

Typically, a particular option will be recognized by some implementations and not by others. The syntax is designed so that option declarations can be successfully parsed by all implementations.

If the EQName of an option is a lexical QName with a prefix, it must resolve to a namespace URI and local name, using the statically known namespaces [err:XPST0081].

If the EQName of an option is a lexical QName that does not have a prefix, the expanded QName is in the http://www.w3.org/2012/xquery namespace, which is reserved for option declarations defined by the XQuery family of specifications. XQuery does not currently define declaration options in this namespace.

Each implementation recognizes the http://www.w3.org/2012/xquery namespace URI and and all options defined in this namespace in this specification. In addition, each implementation recognizes an implementation-defined set of namespace URIs and an implementation-defined set of option names defined in those namespaces. If the namespace part of an option declaration's name is not recognized, the option declaration is ignored.

Otherwise, the effect of the option declaration, including its error behavior, is implementation-defined. For example, if the local part of the QName is not recognized, or if the StringLiteral does not conform to the rules defined by the implementation for the particular option declaration, the implementation may choose whether to raise an error, ignore the option declaration, or take some other action.

Implementations may impose rules on where particular option declarations may appear relative to variable declarations and function declarations, and the interpretation of an option declaration may depend on its position.

An option declaration must not be used to change the syntax accepted by the processor, or to suppress the detection of static errors. However, it may be used without restriction to modify the semantics of the query. The scope of the option declaration is implementation-defined—for example, an option declaration might apply to the whole query, to the current module, or to the immediately following function declaration.

The following examples illustrate several possible uses for option declarations: