See also translations.
This document is also available in these non-normative formats: XML and Change markings relative to previous Working Draft.
Copyright © 2013 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
XML is a versatile markup language, capable of labeling the information content of diverse data sources including structured and semi-structured documents, relational databases, and object repositories. A query language that uses the structure of XML intelligently can express queries across all these kinds of data, whether physically stored in XML or viewed as XML via middleware. This specification describes a query language called XQuery, which is designed to be broadly applicable across many types of XML data sources.
XQuery 3.0 is an extended version of the XQuery 1.0 Recommendation published on 23 January 2007. A list of changes made since XQuery 1.0 can be found in J Change Log. Here are some of the new features in XQuery 3.0:
group by
clause in FLWOR Expressions (3.10.7 Group By Clause).
tumbling window
and sliding window
in
FLWOR Expressions (3.10.4 Window
Clause).
count
clause in FLWOR Expressions (3.10.6 Count Clause).
allowing empty
in 3.10.2 For Clause, for
functionality similar to outer joins in SQL.
try
/catch
expressions (3.15 Try/Catch Expressions).
Dynamic function call (3.2.2 Dynamic Function Call ).
Inline function expressions (3.1.7 Inline Function Expressions).
Private functions (4.18 Function Declaration).
Switch expressions (3.13 Switch Expression).
Computed namespace constructors (<IP_ADDRESS> Computed Namespace Constructors).
Output declarations (2.2.4 Serialization).
Annotations (4.15 Annotations).
A string concatenation operator (3.6 String Concatenation Expressions).
A mapping operator (3.17 Simple map operator (!)).
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is one document in a set of seven documents that are being progressed to Recommendation together (XQuery 3.0, XQueryX 3.0, XSLT 3.0, Data Model 3.0, Functions and Operators 3.0, Serialization 3.0, XPath 3.0).
W3C publishes a Candidate Recommendation, as described in the Process Document, to indicate that the document is believed to be stable and to encourage implementation by the developer community. The publication of this document constitutes a call for implementations of this specification.
This document was developed by the W3C XML Query Working Group, which is part of the XML Activity. It will remain a Candidate Recommendation until at least 08 April 2013. The Working Group expects to advance this specification to Recommendation Status.
Once the entrance criteria for Proposed Recommendation have been achieved, the Director will be requested to advance this document to Proposed Recommendation status. Working closely with the developer community, we expect to show evidence of implementations by approximately 31 July 2013.
This Candidate Recommendation makes several substantive technical changes (as well as many editorial changes), including new features, adopted since the Last Call Working Draft was published. Please note that this Candidate Recommendation of XQuery 3.0 represents the second version of a previous W3C Recommendation.
In this Candidate Recommendation, referencing context-dependent functions in named function references and partial function applications is an error; future changes may permit such references in at least some cases.
No implementation report currently exists. However, a Test Suite for this document is under development. Implementors are encouraged to run this test suite and report their results. The Test Suite can be found at http://dev.w3.org/2011/QT3-test-suite/.
This document incorporates changes made against the Last Call Working Draft of 13 December 2011. Changes to this document since the Last Call Working Draft are detailed in J Change Log.
Please report errors in this document using W3C's public Bugzilla system (instructions can be found at http://www.w3.org/XML/2005/04/qt-bugzilla). If access to that system is not feasible, you may send your comments to the W3C XSLT/XPath/XQuery public comments mailing list<EMAIL_ADDRESS>It will be very helpful if you include the string “[XQuery30]” in the subject line of your report, whether made in Bugzilla or in email. Please use multiple Bugzilla entries (or, if necessary, multiple email messages) if you have more than one comment to make. Archives of the comments and responses are available at http://lists.w3.org/Archives/Public/public-qt-comments/.
Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1 Introduction
2 Basics
2.1 Module Context and
Expression Context
2.1.1 Static Context
2.1.2 Dynamic Context
2.2 Processing Model
2.2.1 Data Model Generation
2.2.2 Schema Import Processing
2.2.3 Expression Processing
<IP_ADDRESS>
Static Analysis Phase
<IP_ADDRESS>
Dynamic Evaluation Phase
2.2.4 Serialization
2.2.5 Consistency Constraints
2.3 Error
Handling
2.3.1 Kinds of Errors
2.3.2 Identifying and Reporting Errors
2.3.3 Handling Dynamic Errors
2.3.4 Errors and Optimization
2.4 Concepts
2.4.1 Document Order
2.4.2 Atomization
2.4.3 Effective Boolean Value
2.4.4 Input Sources
2.4.5 URI Literals
2.4.6 Resolving a Relative URI
Reference
2.5 Types
2.5.1 Predefined Schema Types
2.5.2 Namespace-sensitive Types
2.5.3 Typed Value and String Value
2.5.4 SequenceType Syntax
2.5.5 SequenceType Matching
<IP_ADDRESS>
Matching a SequenceType and a
Value
<IP_ADDRESS>
Matching an ItemType and an
Item
<IP_ADDRESS>
Element Test
<IP_ADDRESS>
Schema Element Test
<IP_ADDRESS>
Attribute Test
<IP_ADDRESS>
Schema Attribute Test
<IP_ADDRESS>
Function Test
2.5.6 SequenceType Subtype
Relationships
<IP_ADDRESS>
The judgement subtype(A, B)
<IP_ADDRESS>
The judgement subtype-itemtype(Ai,
Bi)
<IP_ADDRESS>
The judgement
subtype-assertions(AnnotationsA, AnnotationsB)
2.6 Comments
3 Expressions
3.1 Primary Expressions
3.1.1 Literals
3.1.2 Variable References
3.1.3 Parenthesized Expressions
3.1.4 Context Item Expression
3.1.5 Static Function Calls
<IP_ADDRESS>
Evaluating Static and Dynamic
Function Calls
<IP_ADDRESS>
Function Conversion
Rules
<IP_ADDRESS>
Function Coercion
3.1.6 Named Function References
3.1.7 Inline Function Expressions
3.2 Postfix Expressions
3.2.1 Filter Expressions
3.2.2 Dynamic Function Call
3.3 Path
Expressions
3.3.1 Relative Path Expressions
<IP_ADDRESS>
Path operator (/)
3.3.2 Steps
<IP_ADDRESS>
Axes
<IP_ADDRESS>
Node Tests
3.3.3 Predicates within Steps
3.3.4 Unabbreviated Syntax
3.3.5 Abbreviated Syntax
3.4 Sequence Expressions
3.4.1 Constructing Sequences
3.4.2 Combining Node Sequences
3.5 Arithmetic
Expressions
3.6 String
Concatenation Expressions
3.7 Comparison
Expressions
3.7.1 Value Comparisons
3.7.2 General Comparisons
3.7.3 Node Comparisons
3.8 Logical Expressions
3.9 Constructors
3.9.1 Direct Element Constructors
<IP_ADDRESS>
Attributes
<IP_ADDRESS>
Namespace Declaration Attributes
<IP_ADDRESS>
Content
<IP_ADDRESS>
Boundary Whitespace
3.9.2 Other Direct Constructors
3.9.3 Computed Constructors
<IP_ADDRESS>
Computed Element
Constructors
<IP_ADDRESS>
Computed Attribute
Constructors
<IP_ADDRESS>
Document Node
Constructors
<IP_ADDRESS>
Text Node Constructors
<IP_ADDRESS>
Computed Processing Instruction
Constructors
<IP_ADDRESS>
Computed Comment
Constructors
<IP_ADDRESS>
Computed Namespace
Constructors
3.9.4 In-scope Namespaces of a Constructed
Element
3.10 FLWOR
Expressions
3.10.1 Variable Bindings
3.10.2 For Clause
3.10.3 Let Clause
3.10.4 Window Clause
<IP_ADDRESS>
Tumbling Windows
<IP_ADDRESS>
Sliding Windows
<IP_ADDRESS>
Effects of Window Clauses
on the Tuple Stream
3.10.5 Where Clause
3.10.6 Count Clause
3.10.7 Group By Clause
3.10.8 Order By Clause
3.10.9 Return Clause
3.11 Ordered and Unordered
Expressions
3.12 Conditional
Expressions
3.13 Switch
Expression
3.14 Quantified Expressions
3.15 Try/Catch
Expressions
3.16 Expressions on
SequenceTypes
3.16.1 Instance Of
3.16.2 Typeswitch
3.16.3 Cast
3.16.4 Castable
3.16.5 Constructor Functions
3.16.6 Treat
3.17 Simple map
operator (!)
3.18 Validate
Expressions
3.19 Extension Expressions
4 Modules and Prologs
4.1 Version Declaration
4.2 Module
Declaration
4.3 Boundary-space Declaration
4.4 Default Collation
Declaration
4.5 Base URI
Declaration
4.6 Construction Declaration
4.7 Ordering Mode Declaration
4.8 Empty
Order Declaration
4.9 Copy-Namespaces Declaration
4.10 Decimal Format Declaration
4.11 Schema
Import
4.12 Module
Import
4.12.1 The Target Namespace of a
Module
4.12.2 Multiple Modules with the same
Target Namespace
4.12.3 Location URIs
4.12.4 Cycles
4.13 Namespace Declaration
4.14 Default Namespace Declaration
4.15 Annotations
4.16 Variable Declaration
4.17 Context Item Declaration
4.18 Function
Declaration
4.19 Option Declaration
4.20 require-feature and
prohibit-feature
5 Conformance
5.1 Minimal Conformance
5.2 Optional Features
5.2.3 Schema Aware Feature
5.2.4 Static Typing Feature
5.2.5 Module Feature
5.2.6 Serialization Feature
5.2.7 Higher-Order Function
Feature
5.3 Data Model Conformance
5.4 Syntax
Extensions
A XQuery 3.0 Grammar
A.1 EBNF
A.1.1 Notation
A.1.2 Extra-grammatical
Constraints
A.1.3 Grammar Notes
A.2 Lexical
structure
A.2.1 Terminal Symbols
A.2.2 Terminal Delimitation
A.2.3 End-of-Line Handling
A.2.3.1
XML 1.0 End-of-Line
Handling
A.2.3.2
XML 1.1 End-of-Line
Handling
A.2.4 Whitespace Rules
A.2.4.1
Default Whitespace
Handling
A.2.4.2
Explicit Whitespace
Handling
A.3 Reserved Function Names
A.4 Precedence Order (Non-Normative)
B Type Promotion
and Operator Mapping
B.1 Type
Promotion
B.2 Operator
Mapping
C Context Components
C.1 Static Context
Components
C.2 Dynamic Context
Components
D Implementation-Defined
Items
E References
E.1 Normative References
E.2 Non-normative References
E.3 Background Material
F Error Conditions
G The application/xquery Media
Type
G.1 Introduction
G.2 Registration of MIME Media Type
application/xquery
G.2.1 Interoperability
Considerations
G.2.2 Applications Using this Media
Type
G.2.3 File Extensions
G.2.4 Intended Usage
G.2.5 Author/Change Controller
G.3 Encoding Considerations
G.4 Recognizing XQuery Files
G.5 Charset Default Rules
G.6 Security Considerations
H Glossary (Non-Normative)
I Example Applications
(Non-Normative)
I.1 Joins
I.2 Queries on Sequence
I.3 Recursive Transformations
I.4 Selecting
Distinct Combinations
J Change Log (Non-Normative)
J.1 Incompatibilities
J.2 Changes introduced in this Working
Draft
J.2.1 Substantive Changes
J.2.2 Editorial Changes
J.3 Changes introduced in prior Working
Drafts
J.3.1 Substantive
Changes
J.3.2 Editorial
Changes
As increasing amounts of information are stored, exchanged, and presented using XML, the ability to intelligently query XML data sources becomes increasingly important. One of the great strengths of XML is its flexibility in representing many different kinds of information from diverse sources. To exploit this flexibility, an XML query language must provide features for retrieving and interpreting information from these diverse sources.
XQuery is designed to meet the requirements identified by the W3C XML Query Working Group [XQuery 3.0 Requirements] and the use cases in [XML Query Use Cases]. It is designed to be a language in which queries are concise and easily understood. It is also flexible enough to query a broad spectrum of XML information sources, including both databases and documents. The Query Working Group has identified a requirement for both a non-XML query syntax and an XML-based query syntax. XQuery is designed to meet the first of these requirements. XQuery is derived from an XML query language called Quilt [Quilt], which in turn borrowed features from several other languages, including XPath 1.0 [XML Path Language (XPath) Version 1.0], XQL [XQL], XML-QL [XML-QL], SQL [SQL], and OQL [ODMG].
[Definition: XQuery 3.0 operates on the abstract, logical structure of an XML document, rather than its surface syntax. This logical structure, known as the data model, is defined in [XQuery and XPath Data Model (XDM) 3.0].]
XQuery Version 3.0 is an extension of XPath Version 3.0. In general, any expression that is syntactically valid and executes successfully in both XPath 3.0 and XQuery 3.0 will return the same result in both languages. There are a few exceptions to this rule:
Because XQuery expands predefined entity references
and character references and XPath
does not, expressions containing these produce different results in
the two languages. For instance, the value of the string literal
"&"
is &
in XQuery, and
&
in XPath. (XPath is often embedded in other
languages, which may expand predefined entity references or
character references before the XPath expression is evaluated.)
If XPath 1.0 compatibility mode is enabled, XPath behaves differently from XQuery in a number of ways, which are discussed in [XML Path Language (XPath) 3.0].
Because these languages are so closely related, their grammars and language descriptions are generated from a common source to ensure consistency, and the editors of these specifications work together closely.
XQuery 3.0 also depends on and is closely related to the following specifications:
[XQuery and XPath Data Model (XDM) 3.0] defines the data model that underlies all XQuery 3.0 expressions.
The type system of XQuery 3.0 is based on XML Schema. It is implementation-defined whether the type system is based on [XML Schema 1.0] or [XML Schema 1.1].
The built-in function library and the operators supported by XQuery 3.0 are defined in [XQuery and XPath Functions and Operators 3.0].
One requirement in [XQuery 3.0 Requirements] is that an XML query language have both a human-readable syntax and an XML-based syntax. The XML-based syntax for XQuery is described in [XQueryX 3.0].
[Definition: An XQuery 3.0 Processor processes a query according to the XQuery 3.0 specification. ] [Definition: An XQuery 1.0 Processor processes a query according to the XQuery 1.0 specification. ]
[Definition: An XPath 3.0 Processor processes a query according to the XPath 3.0 specification.] [Definition: An XPath 2.0 Processor processes a query according to the XPath 2.0 specification.] [Definition: An XPath 1.0 Processor processes a query according to the XPath 1.0 specification.]
This document specifies a grammar for XQuery 3.0, using the same basic EBNF notation used in [XML 1.0]. Unless otherwise noted (see A.2 Lexical structure), whitespace is not significant in queries. Grammar productions are introduced together with the features that they describe, and a complete grammar is also presented in the appendix [A XQuery 3.0 Grammar]. The appendix is the normative version.
In the grammar productions in this document, named symbols are underlined and literal text is enclosed in double quotes. For example, the following productions describe the syntax of a static function call:
| [133] | FunctionCall |
::= | EQName ArgumentList |
| [121] | ArgumentList |
::= | "(" (Argument (","
Argument)*)? ")" |
The productions should be read as follows: A static function call consists of an EQName followed by an ArgumentList. The argument list consists of an opening parenthesis, an optional list of one or more arguments (separated by commas), and a closing parenthesis.
This document normatively defines the static and dynamic semantics of XQuery 3.0. In this document, examples and material labeled as "Note" are provided for explanatory purposes and are not normative.
Certain aspects of language processing are described in this specification as implementation-defined or implementation-dependent.
[Definition: Implementation-defined indicates an aspect that may differ between implementations, but must be specified by the implementor for each particular implementation.]
[Definition: Implementation-dependent indicates an aspect that may differ between implementations, is not specified by this or any W3C specification, and is not required to be specified by the implementor for any particular implementation.]
The basic building block of XQuery 3.0 is the expression, which is a string of [Unicode] characters; the version of Unicode to be used is implementation-defined. The language provides several kinds of expressions which may be constructed from keywords, symbols, and operands. In general, the operands of an expression are other expressions. XQuery 3.0 allows expressions to be nested with full generality. (However, unlike a pure functional language, it does not allow variable substitution if the variable declaration contains construction of new nodes.)
Note:
This specification contains no assumptions or requirements regarding the character set encoding of strings of [Unicode] characters.
Like XML, XQuery 3.0 is a case-sensitive language. Keywords in XQuery 3.0 use lower-case characters and are not reserved—that is, names in XQuery 3.0 expressions are allowed to be the same as language keywords, except for certain unprefixed function-names listed in A.3 Reserved Function Names.
[Definition:
In the data model, a
value is always a sequence.] [Definition: A sequence is
an ordered collection of zero or more items.] [Definition: An item is either an atomic value, a
node, or a functionDM30.]
[Definition: An atomic value is a value in
the value space of an atomic type, as defined in [XML Schema 1.0] or [XML
Schema 1.1].] [Definition: A node is an instance of one of the
node kinds defined in [XQuery
and XPath Data Model (XDM) 3.0].] Each node has a unique
node identity, a typed value, and a string
value. In addition, some nodes have a name. The typed
value of a node is a sequence of zero or more atomic values.
The string value of a node is a value of type
xs:string
. The name of a node is a value of
type xs:QName
.
[Definition: A sequence containing exactly one item is called a singleton.] An item is identical to a singleton sequence containing that item. Sequences are never nested—for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3). [Definition: A sequence containing zero items is called an empty sequence.]
[Definition: The term XDM instance is used, synonymously with the term value, to denote an unconstrained sequence of items in the data model.]
In the XQuery 3.0 grammar, most names are specified using the EQName production, which allows lexical QNames, and also allows a namespace URI to be specified as a literal:
| [196] | EQName |
::= | QName | URIQualifiedName |
| [212] | QName |
::= | [http://www.w3.org/TR/REC-xml-names/#NT-QName]Names |
| [213] | NCName |
::= | [http://www.w3.org/TR/REC-xml-names/#NT-NCName]Names |
| [195] | URILiteral |
::= | StringLiteral |
| [201] | URIQualifiedName |
::= | BracedURILiteral NCName |
| [202] | BracedURILiteral |
::= | "Q" "{" (PredefinedEntityRef |
CharRef | [^&{}])*
"}" |
Names in XQuery 3.0 can be bound to namespaces, and are based on the syntax and semantics defined in [XML Names]. [Definition: A lexical QName is a name that conforms to the syntax of [http://www.w3.org/TR/REC-xml-names/#NT-QName].] A lexical QName consists of an optional namespace prefix and a local name. If the namespace prefix is present, it is separated from the local name by a colon. A lexical QName with a prefix can be converted into an expanded QName by resolving its namespace prefix to a namespace URI, using the statically known namespaces. The semantics of a lexical QName without a prefix depend on the expression in which it is found.
[Definition: An expanded QName consists of an optional namespace URI and a local name. An expanded QName also retains its original namespace prefix (if any), to facilitate casting the expanded QName into a string.] Two expanded QNames are equal if their namespace URIs are equal and their local names are equal (even if their namespace prefixes are not equal). Namespace URIs and local names are compared on a codepoint basis, without further normalization.
The EQName production allows
expanded QNames to be specified using either a QName or a URIQualifiedName, which allows
the namespace URI to be specified as a literal. The namespace URI
value is whitespace normalized according to the rules for the
xs:anyURI
type in [XML Schema
1.0] or [XML Schema 1.1]. It is a
static error
[err:XQST0070] if
the namespace URI for an EQName is
http://www.w3.org/2000/xmlns/
.
Here are some examples of EQNames:
pi
is a lexical QName without a namespace prefix.
math:pi
is a lexical QName with a namespace prefix.
Q{http://www.w3.org/2005/xpath-functions/math}pi
specifies the namespace URI using a BracedURILiteral; it is not a
lexical QName.
Certain namespace prefixes are predeclared by XQuery and bound to fixed namespace URIs. These 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/2005/xpath-functions
local =
http://www.w3.org/2005/xquery-local-functions
(see 4.18 Function Declaration.)
In addition to the prefixes in the above list,
this document uses the prefix err
to represent the
namespace URI http://www.w3.org/2005/xqt-errors
(see
2.3.2 Identifying and Reporting
Errors). This namespace prefix is not predeclared and its
use in this document is not normative. It also uses the namespace
URI http://www.w3.org/2012/xquery
for which no prefix
is used in this document, which is reserved for use in this
specification. It is currently used for annotations and option
declarations that are defined by the XML Query Working
Group.
Element nodes have a property called in-scope namespaces. [Definition: The in-scope namespaces property of an element node is a set of namespace bindings, each of which associates a namespace prefix with a URI.] For a given element, one namespace binding may have an empty prefix; the URI of this namespace binding is the default namespace within the scope of the element.
Note:
In [XML Path Language (XPath) Version 1.0], the in-scope namespaces of an element node are represented by a collection of namespace nodes arranged on a namespace axis, which is optional and deprecated in [XML Path Language (XPath) 3.0]. XQuery does not support the namespace axis and does not represent namespace bindings in the form of nodes. However, where other specifications such as [XSLT and XQuery Serialization 3.0] refer to namespace nodes, these nodes may be synthesized from the in-scope namespaces of an element node by interpreting each namespace binding as a namespace node.
[Definition: Within this specification, the term URI refers to a Universal Resource Identifier as defined in [RFC3986] and extended in [RFC3987] with the new name IRI.] The term URI has been retained in preference to IRI to avoid introducing new names for concepts such as "Base URI" that are defined or referenced across the whole family of XML specifications.
Note:
In most contexts, processors are not required to raise errors if a URI is not lexically valid according to [RFC3986] and [RFC3987]. See 2.4.5 URI Literals and <IP_ADDRESS> Namespace Declaration Attributes for details.
[Definition: The expression context for a given expression consists of all the information that can affect the result of the expression.]
[Definition: The module context for a given module consists of all the information that is accessible to top-level expressions in the module.] The context of a top-level expression is defined based on the context of the module in which it is defined: the context of the QueryBody is the context of the main module, and the context for evaluating a function body or for a variable's initializing expression is defined based on the context of the module in which the function or variable is defined.
This information is organized into two categories called the static context and the dynamic context.
[Definition: The static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation.] This information can be used to decide whether the expression contains a static error.
The individual components of the static context are described below. Rules governing the initialization and alteration of these components can be found in C.1 Static Context Components.
[Definition: XPath 1.0
compatibility mode. This component must be
set by all host languages that include XPath 3.0 as a subset,
indicating whether rules for compatibility with XPath 1.0 are in
effect. XQuery sets the value of this component to
false
. ]
[Definition: Statically known
namespaces. This is a mapping from prefix to namespace
URI that defines all the namespaces that are known during
static processing of a given expression.] The URI value is
whitespace normalized according to the rules for the
xs:anyURI
type in [XML Schema
1.0] or [XML Schema 1.1]. Note the
difference between in-scope namespaces, which is a
dynamic property of an element node, and statically known namespaces, which is a
static property of an expression.
Some namespaces are predefined; additional namespaces can be added to the statically known namespaces by namespace declarations, schema imports, or module imports in a Prolog, by a module declaration , and by namespace declaration attributes in direct element constructors.
[Definition: Default
element/type namespace. This is a namespace URI or absentDM30.
The namespace URI, if present, is used for any unprefixed QName
appearing in a position where an element or type name is expected.]
The URI value is whitespace normalized according to the rules for
the xs:anyURI
type in [XML
Schema 1.0] or [XML Schema 1.1].
[Definition: Default function
namespace. This is a namespace URI or absentDM30.
The namespace URI, if present, is used for any unprefixed QName
appearing in a position where a function name is expected.] The URI
value is whitespace normalized according to the rules for the
xs:anyURI
type in [XML Schema
1.0] or [XML Schema 1.1].
[Definition: In-scope schema definitions. This is a generic term for all the element declarations, attribute declarations, and schema type definitions that are in scope during static analysis of an expression.] It includes the following three parts:
[Definition: In-scope schema types. Each schema type definition is identified either by an expanded QName (for a named type) or by an implementation-dependent type identifier (for an anonymous type). The in-scope schema types include the predefined schema types described in 2.5.1 Predefined Schema Types. If the Schema Aware Feature is supported, in-scope schema types also include all type definitions found in imported schemas. ]
[Definition: In-scope element declarations. Each element declaration is identified either by an expanded QName (for a top-level element declaration) or by an implementation-dependent element identifier (for a local element declaration). If the Schema Aware Feature is supported, in-scope element declarations include all element declarations found in imported schemas. ] An element declaration includes information about the element's substitution group affiliation.
[Definition: Substitution groups are defined in [XML Schema 1.0] and [XML Schema 1.1] Part 1. Informally, the substitution group headed by a given element (called the head element) consists of the set of elements that can be substituted for the head element without affecting the outcome of schema validation.]
[Definition: In-scope attribute declarations. Each attribute declaration is identified either by an expanded QName (for a top-level attribute declaration) or by an implementation-dependent attribute identifier (for a local attribute declaration). If the Schema Aware Feature is supported, in-scope attribute declarations include all attribute declarations found in imported schemas. ]
[Definition: In-scope variables. This is a mapping from expanded QName to type. It defines the set of variables that are available for reference within an expression. The expanded QName is the name of the variable, and the type is the static type of the variable.]
Variable declarations in a Prolog are added to in-scope variables. An expression that binds a variable extends the in-scope variables, within the scope of the variable, with the variable and its type. Within the body of an inline function expression or user-defined function , the in-scope variables are extended by the names and types of the function parameters.
The static type of a variable may either be declared in a query or inferred by static type inference as discussed in <IP_ADDRESS> Static Analysis Phase.
[Definition: Context item static type. This component defines the static type of the context item within the scope of a given expression.]
[Definition: Statically known function signatures. This is a mapping from (expanded QName, arity) to function signatureDM30. ] The entries in this mapping define the set of statically known functions — those functions that are available to be called from a static function call, or referenced from a named function reference. Each such function is uniquely identified by its expanded QName and arity (number of parameters). Given a statically known function's expanded QName and arity, this component supplies the function's signatureDM30, which specifies various static properties of the function, including typesand annotations.
The statically known function signatures include the signatures of functions from a variety of sources, including built-in functions described in [XQuery and XPath Functions and Operators 3.0], functions declared in the current module (see 4.18 Function Declaration), module imports (see 4.12 Module Import), constructor functions (see 3.16.5 Constructor Functions), and functions provided by an implementation or via an implementation-defined API (see C.1 Static Context Components). It is a static error [err:XQST0034] if two such functions have the same expanded QName and the same arity (even if the signatures are consistent).
[Definition: Statically known collations. This is an implementation-defined mapping from URI to collation. It defines the names of the collations that are available for use in processing queries and expressions.] [Definition: A collation is a specification of the manner in which strings and URIs are compared and, by extension, ordered. For a more complete definition of collation, see [XQuery and XPath Functions and Operators 3.0].]
[Definition: Default collation. This
identifies one of the collations in statically known collations as the
collation to be used by functions and operators for comparing and
ordering values of type xs:string
and
xs:anyURI
(and types derived from them) when no
explicit collation is specified.]
[Definition: Construction mode. 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
.]
[Definition: Ordering mode. Ordering
mode, which has the value ordered
or
unordered
, affects the ordering of the result sequence
returned by certain expressions, as discussed in 3.11 Ordered and Unordered
Expressions. ]
[Definition:
Default order for empty sequences. This component controls
the processing of empty sequences and NaN
values as
ordering keys in an order by
clause in a FLWOR
expression, as described in 3.10.8
Order By Clause.] Its value may be greatest
or
least
.
[Definition: Boundary-space
policy. This component controls the processing of boundary
whitespace by direct element constructors, as
described in <IP_ADDRESS> Boundary
Whitespace.] Its value may be preserve
or
strip
.
[Definition: Copy-namespaces
mode. This component controls the namespace bindings that are
assigned when an existing element node is copied by an element
constructor, as described in 3.9.1 Direct Element
Constructors. Its value consists of two parts:
preserve
or no-preserve
, and
inherit
or no-inherit
.]
[Definition: Static Base URI. This is
an absolute URI, used to resolve relative URIs
both during static analysis and during dynamic evaluation. ]
All expressions within a module have the same
static base URI. The Static Base URI can be set using a base URI
declaration. The Static Base URI is available during
dynamic evaluation by use of the fn:static-base-uri
function, and is used implicitly during dynamic evaluation by
functions such as fn:doc
. Relative URI references are
resolved as described in 2.4.6 Resolving a Relative URI
Reference.
If the value of the Static Base URI is based on
the location of the query module (in the terminology of [RFC3986], the URI used to retrieve the
encapsulating entity), then the implementation may
use different values for the Static Base URI during static analysis
and during dynamic evaluation. This might be necessary, for
example, if a query consisting of several modules is compiled, and
the resulting object code is distributed to a different location
for execution. It would then be inappropriate to use the same
location when resolving import module
declarations as
when retrieving source documents using the fn:doc
function. If an implementation uses different values for the Static
Base URI during static analysis and during dynamic evaluation, then
it is implementation-defined which of the two values is used for
particular operations that rely on the Static Base URI; for
example, it is implementation-defined which value is used for
resolving collation URIs.
[Definition: Statically known
documents. This is a mapping from strings to types. The string
represents the absolute URI of a resource that is potentially
available using the fn:doc
function. The type is the
static type of a
call to fn:doc
with the given URI as its literal
argument. ] If the argument to fn:doc
is a string
literal that is not present in statically known documents,
then the static
type of fn:doc
is
document-node()?
.
Note:
The purpose of the statically known documents is to
provide static type information, not to determine which documents
are available. A URI need not be found in the statically known
documents to be accessed using fn:doc
.
[Definition: Statically known
collections. This is a mapping from strings to types. The
string represents the absolute URI of a resource that is
potentially available using the fn:collection
function. The type is the type of the sequence of nodes that would
result from calling the fn:collection
function with
this URI as its argument.] If the argument to
fn:collection
is a string literal that is not present
in statically known collections, then the static type of
fn:collection
is node()*
.
Note:
The purpose of the statically known collections is to
provide static type information, not to determine which collections
are available. A URI need not be found in the statically known
collections to be accessed using
fn:collection
.
[Definition:
Statically known default collection type. This is the type
of the sequence of nodes that would result from calling the
fn:collection
function with no arguments.] Unless
initialized to some other value by an implementation, the value of
statically known default collection type is
node()*
.
[Definition: Statically
known decimal formats. This is a mapping from QName to
decimal format, with one default format that has no visible
name. Each format is used for serializing decimal numbers
using fn:format-number()
.]
Each decimal format contains three sets of properties,
which control the interpretation of characters in the
picture string supplied to the fn:format-number
function, and also specify characters that may appear in the result
of formatting the number.
The following attributes specify characters used to format the number per se:
[Definition: decimal-separator specifies the character used for the decimal-separator-symbol; the default value is the period character (.)]
[Definition: grouping-separator specifies the character used for the grouping-separator-symbol, which is typically used as a thousands separator; the default value is the comma character (,)]
[Definition: percent specifies the character used for the percent-symbol; the default value is the percent character (%)]
[Definition: per-mille specifies the character used for the per-mille-symbol; the default value is the Unicode per-mille character (#x2030)]
[Definition: zero-digit specifies the character used for the zero-digit-symbol; the default value is the digit zero (0). This character must be a digit (category Nd in the Unicode property database), and it must have the numeric value zero. This attribute implicitly defines the Unicode character that is used to represent each of the values 0 to 9 in the final result string: Unicode is organized so that each set of decimal digits forms a contiguous block of characters in numerical sequence.]
The following attributes control the interpretation of characters in the picture string supplied to the format-number function. In each case the value must be a single character.
[Definition: digit-sign specifies the character used for the digit-sign in the picture string; the default value is the number sign character (#)]
[Definition: pattern-separator specifies the character used for the pattern-separator-symbol, which separates positive and negative sub-pictures in a picture string; the default value is the semi-colon character (;)]
The following attributes specify characters or strings that may appear in the result of formatting the number:
[Definition: infinity specifies the string used for the infinity-symbol; the default value is the string "Infinity"]
[Definition: NaN specifies the string used for the NaN-symbol, which is used to represent the value NaN (not-a-number); the default value is the string "NaN"]
[Definition: minus-sign specifies the character used for the minus-sign-symbol; the default value is the hyphen-minus character (-, #x2D). The value must be a single character.]
[Definition: The dynamic context of an expression is defined as information that is available at the time the expression is evaluated.] If evaluation of an expression relies on some part of the dynamic context that is absentDM30 , a dynamic error is raised [err:XPDY0002].
The individual components of the dynamic context are described below. Rules governing the initialization and alteration of these components can be found in C.2 Dynamic Context Components.
The dynamic context consists of all the components of the static context, and the additional components listed below.
[Definition: The first three components of the dynamic context (context item, context position, and context size) are called the focus of the expression. ] The focus enables the processor to keep track of which items are being processed by the expression. [Definition: A singleton focus is a focus that refers to a single item; in a singleton focus, context item is set to the item, context position = 1 and context size = 1.]
Certain language constructs, notably the path operator
E1/E2
, the simple mapping operator, and the
predicate E1[E2]
,
create a new focus for the evaluation of a sub-expression. In these
constructs, E2
is evaluated once for each item in the
sequence that results from evaluating E1
. Each time
E2
is evaluated, it is evaluated with a different
focus. The focus for evaluating E2
is referred to
below as the inner focus, while the focus for evaluating
E1
is referred to as the outer focus. The inner
focus exists only while E2
is being evaluated. When
this evaluation is complete, evaluation of the containing
expression continues with its original focus unchanged.
[Definition: The context item is the
item currently being
processed.] [Definition: When the context item is a node, it
can also be referred to as the context node.] The context
item is returned by an expression consisting of a single dot
(.
). When an expression E1/E2
or
E1[E2]
is evaluated, each item in the sequence
obtained by evaluating E1
becomes the context item in
the inner focus for an evaluation of E2
.
[Definition: The initial context item is a context item that an implementation can set before processing a query begins. The query body and the prolog of every module in a query share the same initial context item.]
[Definition: The context position is
the position of the context item within the sequence of items
currently being processed.] It changes whenever the context item
changes. When the focus is defined, the value of the context
position is an integer greater than zero. The context position is
returned by the expression fn:position()
. When an
expression E1/E2
or E1[E2]
is evaluated,
the context position in the inner focus for an evaluation of
E2
is the position of the context item in the sequence
obtained by evaluating E1
. The position of the first
item in a sequence is always 1 (one). The context position is
always less than or equal to the context size.
[Definition: The context size is the
number of items in the sequence of items currently being
processed.] Its value is always an integer greater than zero. The
context size is returned by the expression fn:last()
.
When an expression E1/E2
or E1[E2]
is
evaluated, the context size in the inner focus for an evaluation of
E2
is the number of items in the sequence obtained by
evaluating E1
.
[Definition: Variable values. This is a mapping from expanded QName to value. It contains the same expanded QNames as the in-scope variables in the static context for the expression. The expanded QName is the name of the variable and the value is the dynamic value of the variable, which includes its dynamic type.]
[Definition: Named functions. This is a mapping from (expanded QName, arity) to functionDM30. ] It supplies a function for each signature in statically known function signatures and may supply other functions (see 2.2.5 Consistency Constraints). Named functions can include functions with implementation-dependent implementations; these functions do not have a static context or a dynamic context of their own.
[Definition: Current dateTime. This
information represents an implementation-dependent point
in time during the processing of a
query, and includes an explicit timezone. It can be
retrieved by the fn:current-dateTime
function. If
invoked multiple times during the execution of a query, this function always returns the same
result.]
[Definition: Implicit timezone. This
is the timezone to be used when a date, time, or dateTime value
that does not have a timezone is used in a comparison or arithmetic
operation. The implicit timezone is an implementation-defined value of
type xs:dayTimeDuration
. See [XML Schema 1.0] or [XML
Schema 1.1] for the range of valid values of a timezone.]
[Definition: Default language. This is
the natural language used when creating human-readable output (for
example, by the functions fn:format-date
and
fn:format-integer
) if no other language is requested.
The value is a language code as defined by the type
xs:language
.]
[Definition: Default calendar. This is
the calendar used when formatting dates in human-readable output
(for example, by the functions fn:format-date
and
fn:format-dateTime
) if no other calendar is requested.
The value is a string.]
[Definition: Default place. This is a
geographical location used to identify the place where events
happened (or will happen) when formatting dates and times using
functions such as fn:format-date
and
fn:format-dateTime
, if no other place is specified. It
is used when translating timezone offsets to civil timezone names,
and when using calendars where the translation from ISO dates/times
to a local representation is dependent on geographical location.
Possible representations of this information are an ISO country
code or an Olson timezone name, but implementations are free to use
other representations from which the above information can be
derived.]
[Definition: Available documents.
This is a mapping of strings to document nodes. Each string
represents the absolute URI of a resource. The document node is the
root of a tree that represents that resource using the data model. The document node
is returned by the fn:doc
function when applied to
that URI.] The set of available documents is not limited to the set
of statically known documents, and it may be
empty.
If there are one or more URIs in available documents that map to a
document node D
, then the document-uri property of
D
must either be absent, or must be one of these
URIs.
Note:
This means that given a document node $N
, the
result of fn:doc(fn:document-uri($N)) is $N
will
always be true
, unless
fn:document-uri($N)
is an empty sequence.
[Definition: Available text
resources. This is a mapping of strings to text resources. Each
string represents the absolute URI of a resource. The resource is
returned by the fn:unparsed-text
function when applied
to that URI.] The set of available text resources is not limited to
the set of statically known documents, and it may be
empty.
[Definition: Available node
collections. This is a mapping of strings to sequences of
nodes. Each string represents the absolute URI of a resource. The
sequence of nodes represents the result of the
fn:collection
function when that URI is supplied as
the argument. ] The set of available node collections is not
limited to the set of statically known collections, and it
may be empty.
For every document node D
that is in the target of
a mapping in available node collections, or that
is the root of a tree containing such a node, the document-uri
property of D
must either be absent, or must be a URI
U
such that available documents contains a mapping
from U
to D
.
Note:
This means that for any document node $N
retrieved
using the fn:collection
function, either directly or
by navigating to the root of a node that was returned, the result
of fn:doc(fn:document-uri($N)) is $N
will always be
true
, unless fn:document-uri($N)
is an
empty sequence. This implies a requirement for the
fn:doc
and fn:collection
functions to be
consistent in their effect. If the implementation uses catalogs or
user-supplied URI resolvers to dereference URIs supplied to the
fn:doc
function, the implementation of the
fn:collection
function must take these mechanisms into
account. For example, an implementation might achieve this by
mapping the collection URI to a set of document URIs, which are
then resolved using the same catalog or URI resolver that is used
by the fn:doc
function.
[Definition: Default node
collection. This is the sequence of nodes that would result
from calling the fn:collection
function with no
arguments.] The value of default collection may be
initialized by the implementation.
[Definition: Available
resource collections. This is a mapping of strings to sequences
of URIs. The string represents the absolute URI of a resource which
can be interpreted as an aggregation of a number of individual
resources each of which has its own URI. The sequence of URIs
represents the result of the fn:uri-collection
function when that URI is supplied as the argument. ] There is no
implication that the URIs in this sequence can be successfully
dereferenced, or that the resources they refer to have any
particular media type.
Note:
An implementation may maintain some consistent
relationship between the available node collections and the
available resource collections, for example by ensuring that the
result of fn:uri-collection(X)!fn:doc(.)
is the same
as the result of fn:collection(X)
. However, this is
not required. The fn:uri-collection
function is more
general than fn:collection
in that it allows access to
resources other than XML documents; at the same time,
fn:collection
allows access to nodes that might lack
individual URIs, for example nodes corresponding to XML fragments
stored in the rows of a relational database.
[Definition: Default resource
collection. This is the sequence of URIs that would result from
calling the fn:uri-collection
function with no
arguments.] The value of default resource collection may be
initialized by the implementation.
[Definition: Environment variables. This is a mapping from names to values. Both the names and the values are strings. The names are compared using an implementation-defined collation, and are unique under this collation. The set of environment variables is implementation-defined and may be empty.]
Note:
A possible implementation is to provide the set of POSIX environment variables (or their equivalent on other operating systems) appropriate to the process in which the query is initiated.
XQuery 3.0 is defined in terms of the data model and the expression context.
Figure 1: Processing Model Overview
Figure 1 provides a schematic overview of the processing steps that are discussed in detail below. Some of these steps are completely outside the domain of XQuery 3.0; in Figure 1, these are depicted outside the line that represents the boundaries of the language, an area labeled external processing. The external processing domain includes generation of an XDM instance that represents the data to be queried (see 2.2.1 Data Model Generation), schema import processing (see 2.2.2 Schema Import Processing) and serialization (see 2.2.4 Serialization). The area inside the boundaries of the language is known as the query processing domain , which includes the static analysis and dynamic evaluation phases (see 2.2.3 Expression Processing). Consistency constraints on the query processing domain are defined in 2.2.5 Consistency Constraints.
Before a query can be processed, its input data must be represented as an XDM instance. This process occurs outside the domain of XQuery 3.0, which is why Figure 1 represents it in the external processing domain. Here are some steps by which an XML document might be converted to an XDM instance:
A document may be parsed using an XML parser that generates an XML Information Set (see [XML Infoset]). The parsed document may then be validated against one or more schemas. This process, which is described in [XML Schema 1.0] or [XML Schema 1.1], results in an abstract information structure called the Post-Schema Validation Infoset (PSVI). If a document has no associated schema, its Information Set is preserved. (See DM1 in Fig. 1.)
The Information Set or PSVI may be transformed into an XDM instance by a process described in [XQuery and XPath Data Model (XDM) 3.0]. (See DM2 in Fig. 1.)
The above steps provide an example of how an XDM instance might be constructed. An XDM instance might also be synthesized directly from a relational database, or constructed in some other way (see DM3 in Fig. 1.) XQuery 3.0 is defined in terms of the data model, but it does not place any constraints on how XDM instances are constructed.
[Definition: Each element node and attribute
node in an XDM instance has a type
annotation ( described in [XQuery and XPath Data Model (XDM) 3.0].
) The type annotation of a node is a reference to an XML
Schema type. ] The type-name
of a node is
the name of the type referenced by its type annotation. If the
XDM
instance was derived from a validated XML document as described
in Section 3.3
Construction from a PSVI DM30, the
type annotations of the element and attribute nodes are derived
from schema validation. XQuery 3.0 does not provide a way to
directly access the type annotation of an element or attribute
node.
The value of an attribute is represented directly within the
attribute node. An attribute node whose type is unknown (such as
might occur in a schemaless document) is given the type annotation
xs:untypedAtomic
.
The value of an element is represented by the children of the
element node, which may include text nodes and other element nodes.
The type
annotation of an element node indicates how the values in its
child text nodes are to be interpreted. An element that has not
been validated (such as might occur in a schemaless document) is
annotated with the schema type xs:untyped
. An element
that has been validated and found to be partially valid is
annotated with the schema type xs:anyType
. If an
element node is annotated as xs:untyped
, all its
descendant element nodes are also annotated as
xs:untyped
. However, if an element node is annotated
as xs:anyType
, some of its descendant element nodes
may have a more specific type annotation.
The in-scope schema definitions in the static context may be extracted from actual XML schemas (see step SI1 in Figure 1) or may be generated by some other mechanism (see step SI2 in Figure 1). In either case, the result must satisfy the consistency constraints defined in 2.2.5 Consistency Constraints.
XQuery 3.0 defines two phases of processing called the static analysis phase and the dynamic evaluation phase (see Fig. 1). During the static analysis phase, static errors, dynamic errors, or type errors may be raised. During the dynamic evaluation phase, only dynamic errors or type errors may be raised. These kinds of errors are defined in 2.3.1 Kinds of Errors.
Within each phase, an implementation is free to use any strategy or algorithm whose result conforms to the specifications in this document.
[Definition: The static analysis phase depends on the expression itself and on the static context. The static analysis phase does not depend on input data (other than schemas).]
During the static analysis phase, the query is parsed into an internal representation called the operation tree (step SQ1 in Figure 1). A parse error is raised as a static error [err:XPST0003]. The static context is initialized by the implementation (step SQ2). The static context is then changed and augmented based on information in the prolog (step SQ3). If the Schema Aware Feature is supported, the in-scope schema definitions are populated with information from imported schemas. If the Module Feature is supported, the static context is extended with function declarations and variable declarations from imported modules. The static context is used to resolve schema type names, function names, namespace prefixes, and variable names (step SQ4). If a name of one of these kinds in the operation tree is not found in the static context, a static error ([err:XPST0008] or [err:XPST0017]) is raised (however, see exceptions to this rule in <IP_ADDRESS> Element Test and <IP_ADDRESS> Attribute Test.)
The operation tree is then normalized by making explicit the implicit operations such as atomization and extraction of Effective Boolean Values (step SQ5).
During the static analysis phase, a processor may perform type analysis. The effect of type analysis is to assign a static type to each expression in the operation tree. [Definition: The static type of an expression is the best inference that the processor is able to make statically about the type of the result of the expression.] This specification does not define the rules for type analysis nor the static types that are assigned to particular expressions: the only constraint is that the inferred type must match all possible values that the expression is capable of returning.
Examples of inferred static types might be:
For the expression concat(a,b)
the inferred static
type is xs:string
For the expression $a = $v
the inferred static type
is xs:boolean
For the expression $s[exp]
the inferred static type
has the same item type as the static type of $s
, but a
cardinality that allows the empty sequence even if the static type
of $s
does not allow an empty sequence.
The inferred static type of the expression data($x)
(whether written explicitly or inserted into the operation tree in
places where atomization is implicit) depends on the inferred
static type of $x
: for example, if $x
has
type element(*, xs:integer)
then data($x)
has static type xs:integer
.
In XQuery 1.0 and XPath 2.0, rules for static type inferencing were published normatively in [XQuery 1.0 and XPath 2.0 Formal Semantics], but implementations were allowed to refine these rules to infer a more precise type where possible. In XQuery 3.0 and XPath 3.0, the rules for static type inferencing are entirely implementation-defined.
Every kind of expression also imposes requirements on the type
of its operands. For example, with the expression
substring($a, $b, $c)
, $a
must be of type
xs:string
(or something that can be converted to
xs:string
by the function calling rules), while
$b
and $c
must be of type
xs:double
.
If the Static Typing Feature is in effect, a processor must
raise a type error during static analysis if the inferred static
type of an expression is not subsumed by the required type of the
context where the expression is used. For example, the call of
substring above would cause a type error if the inferred static
type of $a
is xs:integer
; equally, a type
error would be reported during static analysis if the inferred
static type is xs:anyAtomicType
.
If the Static Typing Feature is not in effect, a processor may
raise a type error during static analysis only if the inferred
static type of an expression has no overlap (intersection) with the
required type: so for the first argument of substring, the
processor may raise an error if the inferred type is
xs:integer
, but not if it is
xs:anyAtomicType
. Alternatively, if the Static Typing
Feature is not in effect, the processor may defer all type checking
until the dynamic evaluation phase.
[Definition: The dynamic evaluation phase is the phase during which the value of an expression is computed.] It occurs after completion of the static analysis phase.
The dynamic evaluation phase can occur only if no errors were detected during the static analysis phase. If the Static Typing Feature is in effect, all type errors are detected during static analysis and serve to inhibit the dynamic evaluation phase.
The dynamic evaluation phase depends on the operation tree of the expression being evaluated (step DQ1), on the input data (step DQ4), and on the dynamic context (step DQ5), which in turn draws information from the external environment (step DQ3) and the static context (step DQ2). The dynamic evaluation phase may create new data-model values (step DQ4) and it may extend the dynamic context (step DQ5)—for example, by binding values to variables.
[Definition: A dynamic type is associated
with each value as it is computed. The dynamic type of a value may
be more specific than the static type of the expression that computed
it (for example, the static type of an expression might be
xs:integer*
, denoting a sequence of zero or more
integers, but at evaluation time its value may have the dynamic
type xs:integer
, denoting exactly one integer.)]
If an operand of an expression is found to have a dynamic type that is not appropriate for that operand, a type error is raised [err:XPTY0004].
Even though static typing can catch many type errors before an expression is
executed, it is possible for an expression to raise an error during
evaluation that was not detected by static analysis. For example,
an expression may contain a cast of a string into an integer, which
is statically valid. However, if the actual value of the string at
run time cannot be cast into an integer, a dynamic error will result. Similarly,
an expression may apply an arithmetic operator to a value whose
static type is
xs:untypedAtomic
. This is not a static error, but at run
time, if the value cannot be successfully cast to a numeric type, a dynamic error will be
raised.
When the Static Typing Feature is in effect, it is also possible for static analysis of an expression to raise a type error, even though execution of the expression on certain inputs would be successful. For example, an expression might contain a function that requires an element as its parameter, and the static analysis phase might infer the static type of the function parameter to be an optional element. This case is treated as a type error and inhibits evaluation, even though the function call would have been successful for input data in which the optional element is present.
[Definition: Serialization is the process of converting an XDM instance to a sequence of octets (step DM4 in Figure 1.), as described in [XSLT and XQuery Serialization 3.0]. ]
Note:
This definition of serialization is the definition used in this specification. Any form of serialization that is not based on [XSLT and XQuery Serialization 3.0] is outside the scope of the XQuery 3.0 specification.
An XQuery implementation is not required to provide a serialization interface. For example, an implementation may provide only a DOM interface (see [Document Object Model]) or an interface based on an event stream.
[XSLT and XQuery Serialization 3.0] defines a set of serialization parameters that govern the serialization process. If an XQuery implementation provides a serialization interface, it may support (and may expose to users) any of the serialization parameters listed (with default values) in C.1 Static Context Components. If an implementation does not support one of these parameters, it must ignore it without raising an error.
[Definition:
An output declaration is an option declaration in the
namespace "http://www.w3.org/2010/xslt-xquery-serialization"; it is
used to declare serialization parameters.] Except for
parameter-document
, each option corresponds to a
serialization parameter element defined in
Section B Schema for Serialization Parameters
SER30. The name of each option is the
same as the name of the corresponding serialization parameter
element, and the values permitted for each option are the same as
the values allowed in the serialization parameter element. There is
no output declaration for use-character-maps
, it can
be set only by means of a parameter document. When the
application requests serialization of the output, the processor may
use these parameters to control the way in which the serialization
takes place. Processors may also allow external mechanisms for
specifying serialization parameters, which may or may not override
serialization parameters specified in the query prolog.
The following example illustrates the use of declaration options.
declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization"; declare option output:method "xml"; declare option output:encoding "iso-8859-1"; declare option output:indent "yes"; declare option output:parameter-document "file:///home/me/serialization-parameters.xml";
An output declaration may appear only in a
main module; it is a static error [err:XQST0108] if an output declaration appears
in a library
module. It is a static error [err:XQST0110] if the same serialization
parameter is declared more than once. It is a static error [err:XQST0109] if the local
name of an output declaration in the
http://www.w3.org/2010/xslt-xquery-serialization
namespace is not one of the serialization parameter names listed in
C.1 Static Context
Components or parameter-document
, or if
the name of an output declaration is
use-character-maps
. The default value for the
method
parameter is "xml"
. An
implementation may define additional implementation-defined
serialization parameters in its own namespaces.
If the local name of an output declaration in the
http://www.w3.org/2010/xslt-xquery-serialization
namespace is parameter-document
, the value of the
output declaration is treated as a URI literal. The value is a
location hint, and identifies an XDM instance in an
implementation-defined way. If a processor is performing
serialization, it is a static error [err:XQST0119] if the implementation is not able
to process the value of the output:parameter-document
declaration to produce an XDM instance.
If a processor is performing serialization, the
XDM instance identified by an
output:parameter-document
output declaration specifies
the values of serialization parameters in the manner defined by
Section 3.1 Setting Serialization Parameters by Means of a Data
Model Instance SER30. It is a static
error [err:XQST0115] if this yields a serialization
error. The value of any other output declaration overrides any
value that might have been specified for the same serialization
parameter using an output declaration in the
http://www.w3.org/2010/xslt-xquery-serialization
namespace with the local name parameter-document declaration.
A serialization parameter that is not applicable to the chosen output method must be ignored, except that if its value is not a valid value for that parameter, an error may be raised.
A processor that is performing serialization must raise a serialization error if the values of any serialization parameters (other than any that are ignored under the previous paragraph) are incorrect.
A processor that is not performing serialization may report errors if any serialization parameters are incorrect, or may ignore such parameters.
Specifying serialization parameters in a query does not by itself demand that the output be serialized. It merely defines the desired form of the serialized output for use in situations where the processor has been asked to perform serialization.
Note:
The data model permits an element node to have fewer in-scope namespaces than its parent. Correct serialization of such an element node would require "undeclaration" of namespaces, which is a feature of [XML Names 1.1]. An implementation that does not support [XML Names 1.1] is permitted to serialize such an element without "undeclaration" of namespaces, which effectively causes the element to inherit the in-scope namespaces of its parent.
In order for XQuery 3.0 to be well defined, the input XDM instance, the static context, and the dynamic context must be mutually consistent. The consistency constraints listed below are prerequisites for correct functioning of an XQuery 3.0 implementation. Enforcement of these consistency constraints is beyond the scope of this specification. This specification does not define the result of a query under any condition in which one or more of these constraints is not satisfied.
For every node that has a type annotation, if that type annotation is found in the in-scope schema definitions (ISSD), then its definition in the ISSD must be equivalent to its definition in the type annotation .
Every element name, attribute name, or schema type name referenced in in-scope variables or statically known function signatures must be in the in-scope schema definitions, unless it is an element name referenced as part of an ElementTest or an attribute name referenced as part of an AttributeTest.
Any reference to a global element, attribute, or type name in the in-scope schema definitions must have a corresponding element, attribute or type definition in the in-scope schema definitions.
For each mapping of a string to a document node in available documents, if there exists a mapping of the same string to a document type in statically known documents, the document node must match the document type, using the matching rules in 2.5.5 SequenceType Matching.
For each mapping of a string to a sequence of nodes in available node collections, if there exists a mapping of the same string to a type in statically known collections, the sequence of nodes must match the type, using the matching rules in 2.5.5 SequenceType Matching.
The sequence of nodes in the default collection must match the statically known default collection type, using the matching rules in 2.5.5 SequenceType Matching.
The value of the context item must match the context item static type, using the matching rules in 2.5.5 SequenceType Matching.
For each (variable, type) pair in in-scope variables and the corresponding (variable, value) pair in variable values such that the variable names are equal, the value must match the type, using the matching rules in 2.5.5 SequenceType Matching.
For each variable declared as external, if the variable declaration does not include a VarDefaultValue, the external environment must provide a value for the variable.
For each variable declared as external for which the external environment provides a value: If the variable declaration includes a declared type, the value provided by the external environment must match the declared type, using the matching rules in 2.5.5 SequenceType Matching. If the variable declaration does not include a declared type, the external environment must provide a type to accompany the value provided, using the same matching rules.
For each function declared as external: the function's implementationDM30 must either return a value that matches the declared result type, using the matching rules in 2.5.5 SequenceType Matching, or raise an implementation-defined error.
For a given query, define a participating ISSD as the in-scope schema definitions of a module that is used in evaluating the query. If two participating ISSDs contain a definition for the same schema type, element name, or attribute name, the definitions must be equivalent in both ISSDs. In this context, equivalence means that validating an instance against type T in one ISSD will always have the same effect as validating the same instance against type T in the other ISSD (that is, it will produce the same PSVI, insofar as the PSVI is used during subsequent processing). This means, for example, that the membership of the substitution group of an element declaration in one ISSD must be the same as that of the corresponding element declaration in the other ISSD; that the set of types derived by extension from a given type must be the same; and that in the presence of a strict or lax wildcard, the set of global element (or attribute) declarations capable of matching the wildcard must be the same.
In the statically known namespaces, the prefix
xml
must not be bound to any namespace URI other than
http://www.w3.org/XML/1998/namespace
, and no prefix
other than xml
may be bound to this namespace URI. The
prefix xmlns
must not be bound to any namespace URI,
and no prefix may be bound to the namespace URI
http://www.w3.org/2000/xmlns/
.
For each (expanded QName, arity) -> FunctionTest
entry in statically known function
signatures, there must exist an (expanded QName, arity)
-> function
entry in named functions such that the function's
signatureDM30
is FunctionTest
.
As described in 2.2.3 Expression Processing, XQuery 3.0 defines a static analysis phase, which does not depend on input data, and a dynamic evaluation phase, which does depend on input data. Errors may be raised during each phase.
[Definition: An error that can be detected during the static analysis phase, and is not a type error, is a static error.] A syntax error is an example of a static error.
[Definition: A dynamic error is an error that must be detected during the dynamic evaluation phase and may be detected during the static analysis phase. Numeric overflow is an example of a dynamic error. ]
[Definition: A type error may be raised during the static analysis phase or the dynamic evaluation phase. During the static analysis phase, a type error occurs when the static type of an expression does not match the expected type of the context in which the expression occurs. During the dynamic evaluation phase, a type error occurs when the dynamic type of a value does not match the expected type of the context in which the value occurs.]
The outcome of the static analysis phase is either success or one or more type errors, static errors, or statically-detected dynamic errors. The result of the dynamic evaluation phase is either a result value, a type error, or a dynamic error.
If more than one error is present, or if an error condition comes within the scope of more than one error defined in this specification, then any non-empty subset of these errors may be reported.
During the static analysis phase, if the Static
Typing Feature is in effect and the static type assigned to an expression
other than ()
or data(())
is
empty-sequence()
, a static error is raised [err:XPST0005]. This catches
cases in which a query refers to an element or attribute that is
not present in the in-scope schema definitions, possibly because of a
spelling error.
Independently of whether the Static Typing Feature is in effect, if an implementation can determine during the static analysis phase that a QueryBody , if evaluated, would necessarily raise a dynamic error or that an expression, if evaluated, would necessarily raise a type error, the implementation may (but is not required to) report that error during the static analysis phase.
An implementation can raise a dynamic error for a QueryBody statically only if the query can never execute without raising that error, as in the following example:
error()
The following example contains a type error, which can be reported statically even if the implementation can not prove that the expression will actually be evaluated.
if (empty($arg)) then "cat" * 2 else 0
[Definition: In addition to static errors, dynamic errors, and type errors, an XQuery 3.0 implementation may raise warnings, either during the static analysis phase or the dynamic evaluation phase. The circumstances in which warnings are raised, and the ways in which warnings are handled, are implementation-defined.]
In addition to the errors defined in this specification, an implementation may raise a dynamic error for a reason beyond the scope of this specification. For example, limitations may exist on the maximum numbers or sizes of various objects. An error must be raised if such a limitation is exceeded.
The errors defined in this specification are identified by
QNames that have the form err:XXYYnnnn
, where:
err
denotes the namespace for XPath and XQuery
errors, http://www.w3.org/2005/xqt-errors
. This
binding of the namespace prefix err
is used for
convenience in this document, and is not normative.
XX
denotes the language in which the error is
defined, using the following encoding:
XP
denotes an error defined by XPath. Such an error
may also occur XQuery since XQuery includes XPath as a subset.
XQ
denotes an error defined by XQuery (or an error
originally defined by XQuery and later added to XPath).
YY
denotes the error category, using the following
encoding:
ST
denotes a static error.
DY
denotes a dynamic error.
TY
denotes a type error.
nnnn
is a unique numeric code.
Note:
The namespace URI for XPath and XQuery errors is not expected to change from one version of XQuery to another. However, the contents of this namespace may be extended to include additional error definitions.
The method by which an XQuery 3.0 processor reports error information to the external environment is implementation-defined.
An error can be represented by a URI reference that is derived
from the error QName as follows: an error with namespace URI
NS
and local part LP
can be represented as the URI reference NS
#
LP
. For example, an error
whose QName is err:XPST0017
could be represented as
http://www.w3.org/2005/xqt-errors#XPST0017
.
Note:
Along with a code identifying an error, implementations may wish to return additional information, such as the location of the error or the processing phase in which it was detected. If an implementation chooses to do so, then the mechanism that it uses to return this information is implementation-defined.
Except as noted in this document, if any operand of an
expression raises a dynamic error, the expression also raises a
dynamic
error. If an expression can return a value or raise a dynamic
error, the implementation may choose to return the value or raise
the dynamic error (see 2.3.4
Errors and Optimization). For example, the logical
expression expr1 and expr2
may return the value
false
if either operand returns false
, or
may raise a dynamic error if either operand raises a dynamic
error.
If more than one operand of an expression raises an error, the implementation may choose which error is raised by the expression. For example, in this expression:
($x div $y) + xs:decimal($z)
both the sub-expressions ($x div $y)
and
xs:decimal($z)
may raise an error. The implementation
may choose which error is raised by the "+
"
expression. Once one operand raises an error, the implementation is
not required, but is permitted, to evaluate any other operands.
[Definition: In addition to its identifying QName, a dynamic error may also carry a descriptive string and one or more additional values called error values.] An implementation may provide a mechanism whereby an application-defined error handler can process error values and produce diagnostic messages, such as XQuery 3.0 Section 3.15 Try/Catch Expressions XQ30 .
A dynamic error may be raised by a built-in function or operator. For
example, the div
operator raises an error if its
operands are xs:decimal
values and its second operand
is equal to zero. Errors raised by built-in functions and operators
are defined in [XQuery and XPath
Functions and Operators 3.0].
A dynamic error can also be raised explicitly by calling the
fn:error
function, which always raises
a dynamic error and never returns a value. This
function is defined in [XQuery and
XPath Functions and Operators 3.0]. For example, the following
function call raises a dynamic error, providing a QName that
identifies the error, a descriptive string, and a diagnostic value
(assuming that the prefix app
is bound to a namespace
containing application-defined error codes):
fn:error(xs:QName("app:err057"), "Unexpected value", fn:string($v))
Because different implementations may choose to evaluate or optimize an expression in different ways, certain aspects of raising dynamic errors are implementation-dependent, as described in this section.
An implementation is always free to evaluate the operands of an operator in any order.
In some cases, a processor can determine the result of an
expression without accessing all the data that would be implied by
the formal expression semantics. For example, the formal
description of filter expressions suggests that
$s[1]
should be evaluated by examining all the items
in sequence $s
, and selecting all those that satisfy
the predicate position()=1
. In practice, many
implementations will recognize that they can evaluate this
expression by taking the first item in the sequence and then
exiting. If $s
is defined by an expression such as
//book[author eq 'Berners-Lee']
, then this strategy
may avoid a complete scan of a large document and may therefore
greatly improve performance. However, a consequence of this
strategy is that a dynamic error or type error that would be
detected if the expression semantics were followed literally might
not be detected at all if the evaluation exits early. In this
example, such an error might occur if there is a book
element in the input data with more than one author
subelement.
The extent to which a processor may optimize its access to data, at the cost of not raising errors, is defined by the following rules.
Consider an expression Q that has an operand (sub-expression) E. In general the value of E is a sequence. At an intermediate stage during evaluation of the sequence, some of its items will be known and others will be unknown. If, at such an intermediate stage of evaluation, a processor is able to establish that there are only two possible outcomes of evaluating Q, namely the value V or an error, then the processor may deliver the result V without evaluating further items in the operand E. For this purpose, two values are considered to represent the same outcome if their items are pairwise the same, where nodes are the same if they have the same identity, and values are the same if they are equal and have exactly the same type.
There is an exception to this rule: If a processor evaluates an
operand E (wholly or in part), then it is required to
establish that the actual value of the operand E does not
violate any constraints on its cardinality. For example, the
expression $e eq 0
results in a type error if the
value of $e
contains two or more items. A processor is
not allowed to decide, after evaluating the first item in the value
of $e
and finding it equal to zero, that the only
possible outcomes are the value true
or a type error
caused by the cardinality violation. It must establish that the
value of $e
contains no more than one item.
These rules apply to all the operands of an expression considered in combination: thus if an expression has two operands E1 and E2, it may be evaluated using any samples of the respective sequences that satisfy the above rules.
The rules cascade: if A is an operand of B and B is an operand of C, then the processor needs to evaluate only a sufficient sample of B to determine the value of C, and needs to evaluate only a sufficient sample of A to determine this sample of B.
The effect of these rules is that the processor is free to stop
examining further items in a sequence as soon as it can establish
that further items would not affect the result except possibly by
causing an error. For example, the processor may return
true
as the result of the expression S1 =
S2
as soon as it finds a pair of equal values from the two
sequences.
Another consequence of these rules is that where none of the items in a sequence contributes to the result of an expression, the processor is not obliged to evaluate any part of the sequence. Again, however, the processor cannot dispense with a required cardinality check: if an empty sequence is not permitted in the relevant context, then the processor must ensure that the operand is not an empty sequence.
Examples:
If an implementation can find (for example, by using an index)
that at least one item returned by $expr1
in the
following example has the value 47
, it is allowed to
return true
as the result of the some
expression, without searching for another item returned by
$expr1
that would raise an error if it were
evaluated.
some $x in $expr1 satisfies $x = 47
In the following example, if an implementation can find (for
example, by using an index) the product
element-nodes
that have an id
child with the value 47
,
it is allowed to return these nodes as the result of the path expression,
without searching for another product
node that would
raise an error because it has an id
child whose value
is not an integer.
//product[id = 47]
For a variety of reasons, including optimization, implementations may rewrite expressions into a different form. There are a number of rules that limit the extent of this freedom:
Other than the raising or not raising of errors, the result of evaluating a rewritten expression must conform to the semantics defined in this specification for the original expression.
Note:
This allows an implementation to return a result in cases where the original expression would have raised an error, or to raise an error in cases where the original expression would have returned a result. The main cases where this is likely to arise in practice are (a) where a rewrite changes the order of evaluation, such that a subexpression causing an error is evaluated when the expression is written one way and is not evaluated when the expression is written a different way, and (b) where intermediate results of the evaluation cause overflow or other out-of-range conditions.
Note:
This rule does not mean that the result of the expression will always be the same in non-error cases as if it had not been rewritten, because there are many cases where the result of an expression is to some degree implementation-dependent or implementation-defined.
Conditional and typeswitch expressions must not raise a dynamic
error in respect of subexpressions occurring in a branch that is
not selected, and must not return the value delivered by a branch
unless that branch is selected. Thus, the following example must
not raise a dynamic error if the document abc.xml
does
not exist:
if (doc-available('abc.xml')) then doc('abc.xml') else ()
As stated earlier, an expression must not be rewritten to
dispense with a required cardinality check: for example,
string-length(//title)
must raise an error if the
document contains more than one title element.
Expressions must not be rewritten in such a way as to create or remove static errors. The static errors in this specification are defined for the original expression, and must be preserved if the expression is rewritten.
Expression rewrite is illustrated by the following examples.
Consider the expression //part[color eq "Red"]
. An
implementation might choose to rewrite this expression as
//part[color = "Red"][color eq "Red"]
. The
implementation might then process the expression as follows: First
process the "=
" predicate by probing an index on parts
by color to quickly find all the parts that have a Red color; then
process the "eq
" predicate by checking each of these
parts to make sure it has only a single color. The result would be
as follows:
Parts that have exactly one color that is Red are returned.
If some part has color Red together with some other color, an error is raised.
The existence of some part that has no color Red but has multiple non-Red colors does not trigger an error.
The expression in the following example cannot raise a casting error if it is evaluated exactly as written (i.e., left to right). Since neither predicate depends on the context position, an implementation might choose to reorder the predicates to achieve better performance (for example, by taking advantage of an index). This reordering could cause the expression to raise an error.
$N[@x castable as xs:date][xs:date(@x) gt xs:date("2000-01-01")]
To avoid unexpected errors caused by expression rewrite, tests
that are designed to prevent dynamic errors should be expressed
using conditional or
typeswitch
expressions. For example, the above
expression can be written as follows:
$N[if (@x castable as xs:date) then xs:date(@x) gt xs:date("2000-01-01") else false()]
This section explains some concepts that are important to the processing of XQuery 3.0 expressions.
An ordering called document order is defined among all the nodes accessible during processing of a given query, which may consist of one or more trees (documents or fragments). Document order is defined in [XQuery and XPath Data Model (XDM) 3.0], and its definition is repeated here for convenience. Document order is a total ordering, although the relative order of some nodes is implementation-dependent. [Definition: Informally, document order is the order in which nodes appear in the XML serialization of a document.] [Definition: Document order is stable, which means that the relative order of two nodes will not change during the processing of a given query, even if this order is implementation-dependent.] [Definition: The node ordering that is the reverse of document order is called reverse document order.]
Within a tree, document order satisfies the following constraints:
The root node is the first node.
Every node occurs before all of its children and descendants.
Attribute nodes immediately follow the element node with which they are associated. The relative order of attribute nodes is stable but implementation-dependent.
The relative order of siblings is the order in which they occur
in the children
property of their parent node.
Children and descendants occur before following siblings.
The relative order of nodes in distinct trees is stable but implementation-dependent, subject to the following constraint: If any node in a given tree T1 is before any node in a different tree T2, then all nodes in tree T1 are before all nodes in tree T2.
The semantics of some XQuery 3.0 operators depend on a process
called atomization. Atomization is applied to a
value when the value is used in a context in which a sequence of
atomic values is required. The result of atomization is either a
sequence of atomic values or a type error [err:FOTY0012]. [Definition: Atomization of a sequence is
defined as the result of invoking the fn:data
function
on the sequence, as defined in [XQuery and XPath Functions and Operators
3.0].]
The semantics of fn:data
are repeated here for
convenience. The result of fn:data
is the sequence of
atomic values produced by applying the following rules to each item
in the input sequence:
If the item is an atomic value, it is returned.
If the item is a node, its typed value is returned ([err:FOTY0012] is raised if the node has no typed value.)
If the item is a functionDM30 [err:FOTY0012] is raised.
Atomization is used in processing the following types of expressions:
Arithmetic expressions
Comparison expressions
Function calls and returns
Cast expressions
Constructor expressions for various kinds of nodes
order by
clauses in FLWOR expressions
group by
clauses in FLWOR expressions
Switch expressions
Under certain circumstances (listed below), it is necessary to
find the effective boolean value of a value. [Definition: The
effective boolean value of a value is defined as the result
of applying the fn:boolean
function to the value, as
defined in [XQuery and XPath
Functions and Operators 3.0].]
The dynamic semantics of fn:boolean
are repeated
here for convenience:
If its operand is an empty sequence, fn:boolean
returns false
.
If its operand is a sequence whose first item is a node,
fn:boolean
returns true
.
If its operand is a singleton value of type xs:boolean
or derived from xs:boolean
, fn:boolean
returns the value of its operand unchanged.
If its operand is a singleton value of type xs:string
,
xs:anyURI
, xs:untypedAtomic
, or a type
derived from one of these, fn:boolean
returns
false
if the operand value has zero length; otherwise
it returns true
.
If its operand is a singleton value of any numeric type or derived from a numeric type,
fn:boolean
returns false
if the operand
value is NaN
or is numerically equal to zero;
otherwise it returns true
.
In all other cases, fn:boolean
raises a type error
[err:FORG0006].
Note:
The effective
boolean value of a sequence that contains at least one node and
at least one atomic value is implementation-dependent in
regions of a query where ordering mode is
unordered
.
The effective boolean value of a sequence is computed implicitly during processing of the following types of expressions:
Logical expressions (and
, or
)
The fn:not
function
The where
clause of a FLWOR expression
Certain types of predicates, such as a[b]
Conditional expressions (if
)
Quantified expressions (some
,
every
)
WindowStartCondition and
WindowEndCondition
in window
clauses.
Note:
The definition of effective boolean value is not used when
casting a value to the type xs:boolean
, for example in
a cast
expression or when passing a value to a
function whose expected parameter is of type
xs:boolean
.
XQuery 3.0 has a set of functions that provide access to input data. These functions are of particular importance because they provide a way in which an expression can reference a document or a collection of documents. The input functions are described informally here; they are defined in [XQuery and XPath Functions and Operators 3.0].
An expression can access input data either by calling one of the input functions or by referencing some part of the dynamic context that is initialized by the external environment, such as a variable or context item.
The input functions supported by XQuery 3.0 are as follows:
The fn:doc
function takes a string containing a
URI. If that URI is associated with a document in available
documents, fn:doc
returns a document node whose
content is the data
model representation of the given document; otherwise it raises
a dynamic
error.
The fn:unparsed-text
function takes a string
containing a URI, which must identify a resource that can be read
as text; otherwise it raises a dynamic error.
The fn:environment-variable
and
fn:available-environment-variables
identify
environment variables that are available in the dynamic
context.
The fn:collection
function with one argument takes
a string containing a URI. If that URI is associated with a
collection in available node collections,
fn:collection
returns the data model representation of
that collection; otherwise it raises a dynamic error. A collection may be any
sequence of nodes. For example, the expression
fn:collection("http://example.org")//customer
identifies all the customer
elements that are
descendants of nodes found in the collection whose URI is
http://example.org
.
The fn:collection
function with zero arguments
returns the default collection, an implementation-dependent
sequence of nodes.
The fn:uri-collection
function returns a sequence
of xs:anyURI
values representing the URIs in a
resource collection.
The fn:uri-collection
function with zero arguments
returns the URIs in the default resource
collection.
These input functions are all specified in [XQuery and XPath Functions and Operators 3.0], which specifies error conditions and other details not described here.
XQuery 3.0 requires a statically known, valid URI in a URILiteral or a BracedURILiteral. An implementation may raise a static error [err:XQST0046] if the value of a URI Literal or a Braced URI Literal is of nonzero length and is neither an absolute URI nor a relative URI.
As in a string literal, any predefined entity reference
(such as &
), character reference (such as
•
), or EscapeQuot or EscapeApos (for example,
""
) is replaced by its appropriate expansion. Certain
characters, notably the ampersand, can only be represented using a
predefined entity reference
or a character reference.
Note:
The xs:anyURI
type is designed to anticipate the
introduction of Internationalized Resource Identifiers (IRI's) as
defined in [RFC3987].
Whitespace is normalized using the whitespace normalization
rules of fn:normalize-space
. If the result of
whitespace normalization contains only whitespace, the
corresponding URI consists of the empty string. Whitespace normalization is done after the expansion of
character references, so writing a
newline (for example) as

does not prevent
its being normalized to a space character.
A Braced URI Literal or URI Literal is not subjected to percent-encoding or decoding as defined in [RFC3986].
[Definition: To resolve a relative URI
$rel
against a base URI $base
is to
expand it to an absolute URI, as if by calling the function
fn:resolve-uri($rel, $base)
.] During static analysis,
the base URI is the Static Base URI. During dynamic evaluation, the
base URI used to resolve a relative URI reference depends on the
semantics of the expression.
Any process that attempts to resolve URI against a base URI, or to dereference the URI, may apply percent-encoding or decoding as defined in the relevant RFCs.
The type system of XQuery 3.0 is based on [XML Schema 1.0] or [XML Schema 1.1].
[Definition: A sequence type is a type that can be expressed using the SequenceType syntax. Sequence types are used whenever it is necessary to refer to a type in an XQuery 3.0 expression. The term sequence type suggests that this syntax is used to describe the type of an XQuery 3.0 value, which is always a sequence.]
[Definition: A schema type is a type that
is (or could be) defined using the facilities of [XML Schema 1.0] or [XML
Schema 1.1] (including the built-in types of [XML Schema 1.0] or [XML
Schema 1.1]).] A schema type can be used as a type annotation
on an element or attribute node (unless it is a non-instantiable
type such as xs:NOTATION
or
xs:anyAtomicType
, in which case its derived types can
be so used). Every schema type is either a complex type or a
simple type; simple types are further subdivided into
list types, union types, and atomic types (see
[XML Schema 1.0] or [XML Schema 1.1] for definitions and
explanations of these terms.)
[Definition: A generalized atomic type is a type which is either (a) an atomic type or (b) a pure union type ].
[Definition: A pure union type is an
XML Schema union type that satisfies the following constraints: (1)
{variety}
is union
, (2) the
{facets}
property is empty, (3) no type in the
transitive membership of the union type has {variety}
list
, and (4) no type in the transitive membership of
the union type is a type with {variety}
union
having a non-empty {facets}
property].
Note:
The definition of pure union type excludes union types derived by non-trivial restriction from other union types, as well as union types that include list types in their membership. Pure union types have the property that every instance of an atomic type defined as one of the member types of the union is also a valid instance of the union type.
Note:
The current (second) edition of XML Schema 1.0 contains an error in respect of the substitutability of a union type by one of its members: it fails to recognize that this is unsafe if the union is derived by restriction from another union.
This problem is fixed in XSD 1.1, but the effect of the resolution is that an atomic value labeled with an atomic type cannot be treated as being substitutable for a union type without explicit validation. This specification therefore allows union types to be used as item types only if they are defined directly as the union of a number of atomic types.
Generalized atomic types
represent the intersection between the categories of sequence type and
schema type. A
generalized atomic type, such as xs:integer
or
my:hatsize
, is both a sequence type and a schema type.
The schema types defined in [XQuery and XPath Data Model (XDM) 3.0] are summarized below.
The in-scope schema types in the static context are
initialized with certain predefined schema types, including the
built-in schema types in the namespace
http://www.w3.org/2001/XMLSchema
, which has the
predefined namespace prefix xs
. The schema types in
this namespace are defined in [XML Schema
1.0] or [XML Schema 1.1] and
augmented by additional types defined in [XQuery and XPath Data Model (XDM) 3.0].
Element and attribute declarations in the xs
namespace
are not implicitly included in the static context. The schema types
defined in [XQuery and XPath Data
Model (XDM) 3.0] are summarized below.
[Definition: xs:untyped
is used as the
type
annotation of an element node that has not been validated, or
has been validated in skip
mode.] No predefined schema
types are derived from xs:untyped
.
[Definition: xs:untypedAtomic
is
an atomic type that is used to denote untyped atomic data, such as
text that has not been assigned a more specific type.] An attribute
that has been validated in skip
mode is represented in
the data model by an
attribute node with the type annotation
xs:untypedAtomic
. No predefined schema types are
derived from xs:untypedAtomic
.
[Definition:
xs:dayTimeDuration
is derived by restriction from
xs:duration
. The lexical representation of
xs:dayTimeDuration
is restricted to contain only day,
hour, minute, and second components.]
[Definition:
xs:yearMonthDuration
is derived by restriction from
xs:duration
. The lexical representation of
xs:yearMonthDuration
is restricted to contain only
year and month components.]
[Definition: xs:anyAtomicType
is
an atomic type that includes all atomic values (and no values that
are not atomic). Its base type is xs:anySimpleType
from which all simple types, including atomic, list, and union
types, are derived. All primitive atomic types, such as
xs:decimal
and xs:string
, have
xs:anyAtomicType
as their base type.]
Note:
xs:anyAtomicType
will not appear as the type of an
actual value in an XDM instance.
The relationships among the schema types in the xs
namespace are illustrated in Figure 2. A more complete description
of the XQuery 3.0 type hierarchy can be found in [XQuery and XPath Functions and Operators
3.0].
Figure 2: Hierarchy of Schema Types used in XQuery 3.0.
[Definition: The
namespace-sensitive types are xs:QName
,
xs:NOTATION
, types derived by restriction from
xs:QName
or xs:NOTATION
, list types that
have a namespace-sensitive item type, and union types with a
namespace-sensitive type in their transitive membership.]
It is not possible to preserve the type of a namespace-sensitive value without also preserving the namespace binding that defines the meaning of each namespace prefix used in the value. Therefore, XQuery 3.0 defines some error conditions that occur only with namespace-sensitive values. For instance, casting to a namespace-sensitive type raises a type error [err:XPTY0117] if the namespace bindings for the result cannot be determined.
Every node has a typed value and a string value
, except for nodes whose value is absentDM30.
[Definition: The typed value of a node is a
sequence of atomic values and can be extracted by applying the
fn:data
function to the node.] [Definition: The string value of a node is
a string and can be extracted by applying the
fn:string
function to the node.] Definitions of
fn:data
and fn:string
can be found in
[XQuery and XPath Functions and
Operators 3.0].
An implementation may store both the typed value and the string value of a node,
or it may store only one of these and derive the other as needed.
The string value of a node must be a valid lexical representation
of the typed value of the node, but the node is not required to
preserve the string representation from the original source
document. For example, if the typed value of a node is the
xs:integer
value 30
, its string value
might be "30
" or "0030
".
The typed value, string value, and type annotation of a node are closely related, and are defined by rules found in the following locations:
If the node was created by mapping from an Infoset or PSVI, see rules in [XQuery and XPath Data Model (XDM) 3.0].
If the node was created by an XQuery node constructor, see rules in 3.9.1 Direct Element Constructors, <IP_ADDRESS> Computed Element Constructors, or <IP_ADDRESS> Computed Attribute Constructors.
If the node was created by a validate
expression,
see rules in 3.18 Validate
Expressions.
As a convenience to the reader, the relationship between typed value and string value for various kinds of nodes is summarized and illustrated by examples below.
For text and document nodes, the typed value of the node is the
same as its string value, as an instance of the type
xs:untypedAtomic
. The string value of a document node
is formed by concatenating the string values of all its descendant
text nodes, in document order.
The typed value of a comment or processing instruction node is
the same as its string value. It is an instance of the type
xs:string
.
The typed value of an attribute node with the type annotation
xs:anySimpleType
or xs:untypedAtomic
is
the same as its string value, as an instance of
xs:untypedAtomic
. The typed value of an attribute node
with any other type annotation is derived from its string value and
type annotation using the lexical-to-value-space mapping defined in
[XML Schema 1.0] or [XML Schema 1.1] Part 2 for the relevant
type.
Example: A1 is an attribute having string value
"3.14E-2"
and type annotation xs:double
.
The typed value of A1 is the xs:double
value whose
lexical representation is 3.14E-2
.
Example: A2 is an attribute with type annotation
xs:IDREFS
, which is a list datatype whose item type is
the atomic datatype xs:IDREF
. Its string value is
"bar baz faz
". The typed value of A2 is a sequence of
three atomic values ("bar
", "baz
",
"faz
"), each of type xs:IDREF
. The typed
value of a node is never treated as an instance of a named list
type. Instead, if the type annotation of a node is a list type
(such as xs:IDREFS
), its typed value is treated as a
sequence of the generalized atomic type from
which it is derived (such as xs:IDREF
).
For an element node, the relationship between typed value and string value depends on the node's type annotation, as follows:
If the type annotation is xs:untyped
or
xs:anySimpleType
or denotes a complex type with mixed
content (including xs:anyType
), then the typed value
of the node is equal to its string value, as an instance of
xs:untypedAtomic
. However, if the nilled
property of the node is true
, then its typed value is
the empty sequence.
Example: E1 is an element node having type annotation
xs:untyped
and string value "1999-05-31
".
The typed value of E1 is "1999-05-31
", as an instance
of xs:untypedAtomic
.
Example: E2 is an element node with the type annotation
formula
, which is a complex type with mixed content.
The content of E2 consists of the character "H
", a
child element named subscript
with string value
"2
", and the character "O
". The typed
value of E2 is "H2O
" as an instance of
xs:untypedAtomic
.
If the type annotation denotes a simple type or a complex type
with simple content, then the typed value of the node is derived
from its string value and its type annotation in a way that is
consistent with schema validation. However, if the
nilled
property of the node is true
, then
its typed value is the empty sequence.
Example: E3 is an element node with the type annotation
cost
, which is a complex type that has several
attributes and a simple content type of xs:decimal
.
The string value of E3 is "74.95
". The typed value of
E3 is 74.95
, as an instance of
xs:decimal
.
Example: E4 is an element node with the type annotation
hatsizelist
, which is a simple type derived from the
atomic type hatsize
, which in turn is derived from
xs:integer
. The string value of E4 is "7 8
9
". The typed value of E4 is a sequence of three values
(7
, 8
, 9
), each of type
hatsize
.
Example: E5 is an element node with the type annotation
my:integer-or-string
which is a union type with member
types xs:integer
and xs:string
. The
string value of E5 is "47
". The typed value of E5 is
47
as an xs:integer
, since
xs:integer
is the member type that validated the
content of E5. In general, when the type annotation of a node is a
union type, the typed value of the node will be an instance of one
of the member types of the union.
Note:
If an implementation stores only the string value of a node, and the type annotation of the node is a union type, the implementation must be able to deliver the typed value of the node as an instance of the appropriate member type.
If the type annotation denotes a complex type with empty content, then the typed value of the node is the empty sequence and its string value is the zero-length string.
If the type annotation denotes a complex type with element-only
content, then the typed value of the node is absentDM30.
The fn:data
function raises a type error [err:FOTY0012] when applied to
such a node. The string value of such a node is equal to the
concatenated string values of all its text node descendants, in
document order.
Example: E6 is an element node with the type annotation
weather
, which is a complex type whose content type
specifies element-only
. E6 has two child elements
named temperature
and precipitation
. The
typed value of E6 is absentDM30,
and the fn:data
function applied to E6 raises an
error.
Whenever it is necessary to refer to a type in an XQuery 3.0 expression, the SequenceType syntax is used.
| [168] | SequenceType |
::= | ("empty-sequence" "(" ")") |
| [170] | ItemType |
::= | KindTest | ("item"
"(" ")") | FunctionTest |
AtomicOrUnionType |
ParenthesizedItemType |
| [169] | OccurrenceIndicator |
::= | "?" | "*" | "+" |
| [171] | AtomicOrUnionType |
::= | EQName |
| [172] | KindTest |
::= | DocumentTest |
| [174] | DocumentTest |
::= | "document-node" "(" (ElementTest | SchemaElementTest)?
")" |
| [183] | ElementTest |
::= | "element" "(" (ElementNameOrWildcard
("," TypeName "?"?)?)?
")" |
| [185] | SchemaElementTest |
::= | "schema-element" "(" ElementDeclaration
")" |
| [186] | ElementDeclaration |
::= | ElementName |
| [179] | AttributeTest |
::= | "attribute" "(" (AttribNameOrWildcard (","
TypeName)?)? ")" |
| [181] | SchemaAttributeTest |
::= | "schema-attribute" "(" AttributeDeclaration
")" |
| [182] | AttributeDeclaration |
::= | AttributeName |
| [184] | ElementNameOrWildcard |
::= | ElementName |
"*" |
| [188] | ElementName |
::= | EQName |
| [180] | AttribNameOrWildcard |
::= | AttributeName |
"*" |
| [187] | AttributeName |
::= | EQName |
| [190] | TypeName |
::= | EQName |
| [178] | PITest |
::= | "processing-instruction" "(" (NCName | StringLiteral)? ")" |
| [176] | CommentTest |
::= | "comment" "(" ")" |
| [177] | NamespaceNodeTest |
::= | "namespace-node" "(" ")" |
| [175] | TextTest |
::= | "text" "(" ")" |
| [173] | AnyKindTest |
::= | "node" "(" ")" |
| [191] | FunctionTest |
::= | Annotation*
(AnyFunctionTest |
| [192] | AnyFunctionTest |
::= | "function" "(" "*" ")" |
| [193] | TypedFunctionTest |
::= | "function" "(" (SequenceType ("," SequenceType)*)? ")" "as" SequenceType |
| [194] | ParenthesizedItemType |
::= | "(" ItemType
")" |
With the exception of the special type
empty-sequence()
, a sequence type consists of an item
type that constrains the type of each item in the sequence, and
a cardinality that constrains the number of items in the
sequence. Apart from the item type item()
, which
permits any kind of item, item types divide into node types
(such as element()
), generalized atomic types
(such as xs:integer
) and function types (such as
function() as item()*).
Lexical QNames
appearing in a sequence type have their prefixes expanded
to namespace URIs by means of the statically known namespaces and (where
applicable) the default element/type namespace . Equality
of QNames is defined by the eq
operator.
Item types representing element and attribute nodes may specify
the required type annotations of those nodes, in the
form of a schema
type. Thus the item type element(*, us:address)
denotes any element node whose type annotation is (or is derived
from) the schema type named us:address
.
Any occurrence of '+', '*', or '?' immediately following a sequence type is assumed to be an occurrence indicator, which binds to the last ItemType in the SequenceType, as described in occurrence-indicators constraint.
Here are some examples of sequence types that might be used in XQuery 3.0:
xs:date
refers to the built-in atomic schema type
named xs:date
attribute()?
refers to an optional attribute
node
element()
refers to any element node
element(po:shipto, po:address)
refers to an element
node that has the name po:shipto
and has the type
annotation po:address
(or a schema type derived from
po:address
)
element(*, po:address)
refers to an element node of
any name that has the type annotation po:address
(or a
type derived from po:address
)
element(customer)
refers to an element node named
customer
with any type annotation
schema-element(customer)
refers to an element node
whose name is customer
(or is in the substitution
group headed by customer
) and whose type annotation
matches the schema type declared for a customer
element in the in-scope element declarations
node()*
refers to a sequence of zero or more nodes
of any kind
item()+
refers to a sequence of one or more
items
function(*)
refers to any functionDM30,
regardless of arity or type
function(node()) as xs:string*
refers to a functionDM30
that takes a single argument whose value is a single node, and
returns a sequence of zero or more xs:string values
(function(node()) as xs:string)*
refers to a
sequence of zero or more functionsDM30,
each of which takes a single argument whose value is a single node,
and returns as its result a single xs:string value
[Definition: SequenceType
matching compares the dynamic type of a value with an expected
sequence
type. ] For example, an instance of
expression
returns true
if the dynamic type of a given value matches a
given sequence
type, or false
if it does not.
An XQuery 3.0 implementation must be able to determine relationships among the types in type annotations in an XDM instance and the types in the in-scope schema definitions (ISSD). An XQuery 3.0 implementation must be able to determine relationships among the types in ISSDs used in different modules of the same query.
[Definition: The use of a value
whose dynamic
type is derived from an expected type is known as subtype
substitution.] Subtype substitution does not change the actual
type of a value. For example, if an xs:integer
value
is used where an xs:decimal
value is expected, the
value retains its type as xs:integer
.
The definition of SequenceType matching relies on a
pseudo-function named derives-from(
AT,
ET )
, which takes an actual simple or complex
schema type AT and an expected simple or complex schema
type ET, and either returns a boolean value or raises a
type error
[err:XPTY0004].
This function is defined as follows:
derives-from(
AT, ET
)
raises a type error [err:XPTY0004] if ET is not present in
the in-scope schema definitions (ISSD).
derives-from(
AT, ET
)
returns true
if AT is derived
from ET by restriction or extension, or if ET is
a union type of which AT is a member type.
Formally, it returns true
if AT is validly
derived from ET given the empty set, as defined in
[XML Schema 1.0] or [XML Schema 1.1] Part 1 constraints Type
Derivation OK (Complex) (if AT is a complex type), or Type
Derivation OK (Simple) (if AT is a simple type). The
phrase "given the empty set" is used because the rules in the XML
Schema specification are parameterized: the parameter is a list of
the kinds of derivation that are not allowed, and in this case the
list is always empty.
Otherwise, derives-from(
AT, ET
)
returns false
The rules for SequenceType matching are given below, with examples (the examples are for purposes of illustration, and do not cover all possible cases).
The sequence
type empty-sequence()
matches a value that is the
empty sequence.
An ItemType with no OccurrenceIndicator matches any value that contains exactly one item if the ItemType matches that item (see <IP_ADDRESS> Matching an ItemType and an Item).
An ItemType with an OccurrenceIndicator matches a value if the number of items in the value matches the OccurrenceIndicator and the ItemType matches each of the items in the value.
An OccurrenceIndicator specifies the number of items in a sequence, as follows:
?
matches zero or one items
*
matches zero or more items
+
matches one or more items
As a consequence of these rules, any sequence type whose OccurrenceIndicator is
*
or ?
matches a value that is an empty
sequence.
An ItemType consisting
simply of an EQName is interpreted as an AtomicOrUnionType. The
expected type AtomicOrUnionType matches an atomic value
whose actual type is AT if derives-from(
AT, AtomicOrUnionType )
is
true
.
The name of an AtomicOrUnionType has its prefix expanded to a namespace URI by means of the statically known namespaces, or if unprefixed, the default element/type namespace. If the expanded QName of an AtomicOrUnionType is not defined as a generalized atomic type in the in-scope schema types, a static error is raised [err:XPST0051].
Example: The ItemType
xs:decimal
matches any value of type
xs:decimal
. It also matches any value of type
shoesize
, if shoesize
is an atomic type
derived by restriction from xs:decimal
.
Example: Suppose ItemType
dress-size
is a union type that allows either
xs:decimal
values for numeric sizes (e.g. 4, 6, 10,
12), or one of an enumerated set of xs:strings
(e.g.
"small", "medium", "large"). The ItemType dress-size
matches any of these values.
Note:
The names of non-atomic types such as xs:IDREFS
are
not accepted in this context, but can often be replaced by a
generalized atomic type with an
occurrence indicator, such as xs:IDREF+
.
item()
matches any single item.
Example: item()
matches the atomic value
1
, the element <a/>
, or the
function fn:concat#3
.
node()
matches any node.
text()
matches any text node.
processing-instruction()
matches any
processing-instruction node.
processing-instruction(
N )
matches any processing-instruction node whose PITarget is equal to
fn:normalize-space(N)
. If
fn:normalize-space(N)
is not in the lexical space of
NCName, a type error is raised [err:XPTY0004]
Example: processing-instruction(xml-stylesheet)
matches any processing instruction whose PITarget is
xml-stylesheet
.
For backward compatibility with XPath 1.0, the PITarget of a
processing instruction may also be expressed as a string literal,
as in this example:
processing-instruction("xml-stylesheet")
.
If the specified PITarget is not a syntactically valid NCName, a type error is raised [err:XPTY0004].
comment()
matches any comment node.
namespace-node()
matches any namespace node.
document-node()
matches any document node.
document-node(
E )
matches
any document node that contains exactly one element node,
optionally accompanied by one or more comment and processing
instruction nodes, if E is an ElementTest or SchemaElementTest that
matches the element node (see <IP_ADDRESS>
Element Test and <IP_ADDRESS> Schema Element
Test).
Example: document-node(element(book))
matches a
document node containing exactly one element node that is matched
by the ElementTest element(book)
.
A ParenthesizedItemType matches an item if and only if the item matches the ItemType that is in parentheses.
An ItemType that is an ElementTest, SchemaElementTest, AttributeTest, SchemaAttributeTest, or FunctionTest matches an item as described in the following sections.
| [183] | ElementTest |
::= | "element" "(" (ElementNameOrWildcard
("," TypeName "?"?)?)?
")" |
| [184] | ElementNameOrWildcard |
::= | ElementName |
"*" |
| [188] | ElementName |
::= | EQName |
| [190] | TypeName |
::= | EQName |
An ElementTest is used to match an element node by its name and/or type annotation.
The ElementName and TypeName of an ElementTest have their prefixes expanded to namespace URIs by means of the statically known namespaces, or if unprefixed, the default element/type namespace. The ElementName need not be present in the in-scope element declarations, but the TypeName must be present in the in-scope schema types [err:XPST0008]. Note that substitution groups do not affect the semantics of ElementTest.
An ElementTest may take any of the following forms:
element()
and element(*)
match any
single element node, regardless of its name or type annotation.
element(
ElementName )
matches
any element node whose name is ElementName, regardless of its type
annotation or nilled
property.
Example: element(person)
matches any element node
whose name is person
.
element(
ElementName ,
TypeName )
matches an
element node whose name is ElementName if
derives-from(
AT, TypeName )
is
true
, where AT is the type annotation of the
element node, and the nilled
property of the node is
false
.
Example: element(person, surgeon)
matches a
non-nilled element node whose name is person
and whose
type annotation is surgeon
(or is derived from
surgeon
).
element(
ElementName, TypeName ?)
matches an
element node whose name is ElementName if
derives-from(
AT, TypeName )
is
true
, where AT is the type annotation of the
element node. The nilled
property of the node may be
either true
or false
.
Example: element(person, surgeon?)
matches a nilled
or non-nilled element node whose name is person
and
whose type annotation is surgeon
(or is derived from
surgeon
).
element(*,
TypeName )
matches an
element node regardless of its name, if derives-from(
AT, TypeName
)
is true
, where AT is the type
annotation of the element node, and the nilled
property of the node is false
.
Example: element(*, surgeon)
matches any non-nilled
element node whose type annotation is surgeon
(or is
derived from surgeon
), regardless of its name.
element(*,
TypeName ?)
matches an
element node regardless of its name, if derives-from(
AT, TypeName
)
is true
, where AT is the type
annotation of the element node. The nilled
property of
the node may be either true
or false
.
Example: element(*, surgeon?)
matches any nilled or
non-nilled element node whose type annotation is
surgeon
(or is derived from surgeon
),
regardless of its name.
| [185] | SchemaElementTest |
::= | "schema-element" "(" ElementDeclaration
")" |
| [186] | ElementDeclaration |
::= | ElementName |
| [188] | ElementName |
::= | EQName |
A SchemaElementTest matches an element node against a corresponding element declaration found in the in-scope element declarations.
The ElementName of a SchemaElementTest has its prefixes expanded to a namespace URI by means of the statically known namespaces, or if unprefixed, the default element/type namespace. If the ElementName specified in the SchemaElementTest is not found in the in-scope element declarations, a static error is raised [err:XPST0008].
A SchemaElementTest matches a candidate element node if all of the following conditions are satisfied:
Either:
The name N of the candidate node matches the specified ElementName, or
The name N of the candidate node matches the name of an element declaration that is a member of the actual substitution group headed by the declaration of element ElementName.
Note:
The term "actual substitution group" is defined in [XML Schema 1.1]. The actual substitution group of an element declaration H includes those element declarations P that are declared to have H as their direct or indirect substitution group head, provided that P is not declared as abstract, and that P is validly substitutable for H, which means that there must be no blocking constraints that prevent substitution.
The schema element declaration named N is not abstract.
derives-from( AT, ET )
is true, where AT
is the type annotation of the candidate node and ET is the
schema type declared in the schema element declaration named
N.
If the schema element declaration named N is not nillable, then the nilled property of the candidate node is false.
Example: The SchemaElementTest
schema-element(customer)
matches a candidate element
node in the following two situations:
customer is a top-level element declaration in the in-scope element declarations; the name of the candidate node is customer; the element declaration of customer is not abstract; the type annotation of the candidate node is the same as or derived from the schema type declared in the customer element declaration; and either the candidate node is not nilled, or customer is declared to be nillable.
customer is a top-level element declaration in the in-scope element declarations; the name of the candidate node is client; client is an actual (non-abstract and non-blocked) member of the substitution group of customer; the type annotation of the candidate node is the same as or derived from the schema type declared for the client element; and either the candidate node is not nilled, or client is declared to be nillable.
| [179] | AttributeTest |
::= | "attribute" "(" (AttribNameOrWildcard (","
TypeName)?)? ")" |
| [180] | AttribNameOrWildcard |
::= | AttributeName |
"*" |
| [187] | AttributeName |
::= | EQName |
| [190] | TypeName |
::= | EQName |
An AttributeTest is used to match an attribute node by its name and/or type annotation.
The AttributeName and TypeName of an AttributeTest have their prefixes expanded to namespace URIs by means of the statically known namespaces. If unprefixed, the AttributeName is in no namespace, but an unprefixed TypeName is in the default element/type namespace. The AttributeName need not be present in the in-scope attribute declarations, but the TypeName must be present in the in-scope schema types [err:XPST0008].
An AttributeTest may take any of the following forms:
attribute()
and attribute(*)
match any
single attribute node, regardless of its name or type
annotation.
attribute(
AttributeName )
matches any attribute node whose name is AttributeName, regardless of its
type annotation.
Example: attribute(price)
matches any attribute
node whose name is price
.
attribute(
AttributeName, TypeName )
matches an
attribute node whose name is AttributeName if
derives-from(
AT, TypeName )
is
true
, where AT is the type annotation of the
attribute node.
Example: attribute(price, currency)
matches an
attribute node whose name is price
and whose type
annotation is currency
(or is derived from
currency
).
attribute(*,
TypeName )
matches an
attribute node regardless of its name, if
derives-from(
AT, TypeName )
is
true
, where AT is the type annotation of the
attribute node.
Example: attribute(*, currency)
matches any
attribute node whose type annotation is currency
(or
is derived from currency
), regardless of its name.
| [181] | SchemaAttributeTest |
::= | "schema-attribute" "(" AttributeDeclaration
")" |
| [182] | AttributeDeclaration |
::= | AttributeName |
| [187] | AttributeName |
::= | EQName |
A SchemaAttributeTest matches an attribute node against a corresponding attribute declaration found in the in-scope attribute declarations.
The AttributeName of a SchemaAttributeTest has its prefixes expanded to a namespace URI by means of the statically known namespaces. If unprefixed, an AttributeName is in no namespace. If the AttributeName specified in the SchemaAttributeTest is not found in the in-scope attribute declarations, a static error is raised [err:XPST0008].
A SchemaAttributeTest matches a candidate attribute node if both of the following conditions are satisfied:
The name of the candidate node matches the specified AttributeName.
derives-from(
AT, ET )
is
true
, where AT is the type annotation of the
candidate node and ET is the schema type declared for
attribute AttributeName
in the in-scope attribute declarations.
Example: The SchemaAttributeTest
schema-attribute(color)
matches a candidate attribute
node if color
is a top-level attribute declaration in
the in-scope attribute declarations, the name of the
candidate node is color
, and the type annotation of
the candidate node is the same as or derived from the schema type
declared for the color
attribute.
| [191] | FunctionTest |
::= | Annotation*
(AnyFunctionTest |
| [192] | AnyFunctionTest |
::= | "function" "(" "*" ")" |
| [193] | TypedFunctionTest |
::= | "function" "(" (SequenceType ("," SequenceType)*)? ")" "as" SequenceType |
A FunctionTest matches a functionDM30, potentially also checking its function signatureDM30 and annotations (see 4.15 Annotations).
[Definition: A function assertion is a predicate that restricts the set of functions matched by a FunctionTest. It uses the same syntax as 4.15 Annotations.] XQuery 3.0 does not currently define any function assertions, but future versions may. Other specifications in the XQuery family may also use function assertions in the future.
Implementations are free to define their own function assertions, whose behavior is completely implementation-defined. Implementations may also provide a way for users to create their own function assertions.
An implementation may raise implementation-defined errors or warnings for function assertions, e.g. if the parameters are not correct for a given assertion. If a function assertion is not recognized by an implementation, it is ignored, and has no effect on the semantics of the function test.
Note:
An implementation is free to raise warnings for function assertions that it does not recognize.
Note:
Although function assertions use the same syntax as annotations,