Please check the errata for any errors or issues reported since publication.
See also translations.
This document is also available in these non-normative formats: XML.
Copyright © 2000 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
XPath 4.0 is an expression language that allows the processing of values conforming to the data model defined in [XDM 4.0]. The name of the language derives from its most distinctive feature, the path expression, which provides a means of hierarchic addressing of the nodes in an XML tree. As well as modeling the tree structure of XML, the data model also includes atomic items, function items, maps, arrays, and sequences. This version of XPath supports JSON as well as XML, and adds many new functions in [Functions and Operators 4.0].
XPath 4.0 is a superset of XPath 3.1. A detailed list of changes made since XPath 3.1 can be found in I Change Log.
This is a draft prepared by the QT4CG (officially registered in W3C as the XSLT Extensions Community Group). Comments are invited.
The publications of this community group are dedicated to our co-chair, Michael Sperberg-McQueen (1954–2024).
Michael was central to the development of XML and many related technologies. He brought a polymathic breadth of knowledge and experience to everything he did. This, combined with his indefatigable curiosity and appetite for learning, made him an invaluable contributor to our project, along with many others. We have lost a brilliant thinker, a patient teacher, and a loyal friend.
This section discusses each of the basic kinds of expression. Each kind of expression has a name such as PathExpr, which is introduced on the left side of the grammar production that defines the expression. Since XPath 4.0 is a composable language, each kind of expression is defined in terms of other expressions whose operators have a higher precedence. In this way, the precedence of operators is represented explicitly in the grammar.
The order in which expressions are discussed in this document does not reflect the order of operator precedence. In general, this document introduces the simplest kinds of expressions first, followed by more complex expressions. For the complete grammar, see Appendix [A XPath 4.0 Grammar].
The highest-level symbol in the XPath grammar is XPath.
XPath | ::= | (DefaultElementNamespaceDecl ";")? (NamespaceDecl ";")* Expr |
DefaultElementNamespaceDecl | ::= | "declare" "default" "element" "namespace" URILiteral |
NamespaceDecl | ::= | "declare" "namespace" NCName "=" URILiteral |
Expr | ::= | (ExprSingle ++ ",") |
The effect of a DefaultElementNamespaceDecl or NamespaceDecl is described in 4.1 Namespace Declarations.
ExprSingle | ::= | ForExpr |
ForExpr | ::= | ForClauseForLetReturn |
LetExpr | ::= | LetClauseForLetReturn |
QuantifiedExpr | ::= | ("some" | "every") (QuantifierBinding ++ ",") "satisfies" ExprSingle |
IfExpr | ::= | "if" "(" Expr ")" (UnbracedActions | BracedAction) |
OrExpr | ::= | AndExpr ("or" AndExpr)* |
The XPath 4.0 operator that has lowest precedence is the comma operator, which is used to combine two operands to form a sequence. As shown in the grammar, a general expression (Expr) can consist of multiple ExprSingle operands, separated by commas.
The name ExprSingle denotes an expression that does not contain a top-level comma operator (despite its name, an ExprSingle may evaluate to a sequence containing more than one item.)
The symbol ExprSingle is used in various places in the grammar where an expression is not allowed to contain a top-level comma. For example, each of the arguments of a function call must be a ExprSingle, because commas are used to separate the arguments of a function call.
After the comma, the expressions that have next lowest precedence are ForExpr, LetExpr, QuantifiedExpr, IfExpr, and OrExpr. Each of these expressions is described in a separate section of this document.
XPath 4.0 allows an XPath expression to be preceded by namespace declarations, allowing namespace prefixes to be bound within the XPath expression, rather than relying entirely on the host language to declare namespace prefixes. [Issue 2179 4 September 2025]
An XPath 4.0 expression may be preceded by a set of namespace declarations: specifically, an optional default namespace declaration, followed by zero or more bindings of specific namespace prefixes to specific namespace URIs.
DefaultElementNamespaceDecl | ::= | "declare" "default" "element" "namespace" URILiteral |
URILiteral | ::= | StringLiteral |
StringLiteral | ::= | AposStringLiteral | QuotStringLiteral |
| /* ws: explicit */ | ||
NamespaceDecl | ::= | "declare" "namespace" NCName "=" URILiteral |
URILiteral | ::= | StringLiteral |
StringLiteral | ::= | AposStringLiteral | QuotStringLiteral |
| /* ws: explicit */ |
These namespace declarations are added to the static context of the expression, overriding any namespace bindings initialized by the host language.
Specifically, if there is a DefaultNamespaceDecl then the relevant URI is set in the static context as the default namespace for elements and types, while a NamespaceDecl establishes a namespace binding from the given prefix to the given URI in the statically known namespaces.
The namespace URI specified in a namespace declaration must not be http://www.w3.org/XML/1998/namespace or http://www.w3.org/2000/xmlns/, and the namespace prefix must not be xml or xmlns [err:XQST0070].
The namespace prefixes defined in namespace declarations must be distinct [err:XQST0033].
A default element namespace declaration declares how unprefixed element and type names are to be interpreted. The URILiteral may take one of the following forms:
A namespace URI. This namespace will typically be used for unprefixed names appearing where an element or type name is expected.
The empty string "". In this case unprefixed names appearing where an element or type name is expected are treated as being in no namespace: the default namespace for elements and types is set to absentDM.
The string "##any". In this case an unprefixed name appearing as a NameTest in an axis step whose principal node kind is element is interpreted as a wildcard (the unprefixed name N is treated as equivalent to the wildcard *:N); an unprefixed name used appearing where an item type name is expected is interpreted as a local name in namespace http://www.w3.org/2001/XMLSchema, while an unprefixed name appearing in any other context where an element or type name is expected is treated as being in no namespace.
Note:
To take an example, older versions of the internet index of RFCs (requests for comments) use the namespace URI http://www.rfc-editor.org/rfc-index, while newer versions use https://www.rfc-editor.org/rfc-index (note the change of URI scheme). XPath code that needs to work with either version can be simplified by setting the default namespace to ##any: but be aware that this might lead to spurious matching of names in an unrelated namespace.
The following example illustrates the declaration of a default namespace for elements and types:
declare default element namespace "http://example.org/names";
It is a static error if analysis of an expression relies on some component of the static context that is absentDM.
It is a type error if evaluation of an expression relies on some part of the dynamic context that is absentDM.
Note:
In version 4.0 this has been reclassified as a type error rather than a dynamic error. This change allows a processor to report the error during static analysis where possible; for example if the body of a user-defined function is written as fn($x) { @code }. The error code is prefixed XPDY rather than XPTY for backwards compatibility reasons.
It is a static error if an expression is not a valid instance of the grammar defined in A.1 EBNF.
It is a type error if, during the static analysis phase, an expression is found to have a static type that is not appropriate for the context in which the expression occurs, or during the dynamic evaluation phase, the dynamic type of a value does not match a required type as specified by the matching rules in 3.1.2 Sequence Type Matching.
During the analysis phase, an expression is classified as implausible if the inferred static typeS and the required type R are substantively disjoint; more specifically, if neither of the types is a subtype of the other, and if the only values that are instances of both types are one or more of: the empty sequence, the empty map, and the empty array.
It is a static error if an expression refers to an element name, attribute name, schema type name, or variable name that is not defined in the static context, except for an ElementName in an ElementTest or an AttributeName in an AttributeTest.
An implementation that does not support the namespace axis must raise a static error if it encounters a reference to the namespace axis and XPath 1.0 compatibility mode is false.
It is a static error if the expanded QName and number of arguments in a static function call do not match the name and arity range of a function definition in the static context, or if an argument keyword in the function call does not match a parameter name in that function definition, or if two arguments in the function call bind to the same parameter in the function definition.
It is a type error if the result of a path operator contains both nodes and non-nodes.
It is a type error if E1 in a path expression E1/E2 does not evaluate to a sequence of nodes.
It is a type error if, in an axis step, the context item is not a node.
It is a static error if two fields in a record declaration have the same name.
It is a static error if a recursive record type cannot be instantiated (typically because it contains a self-reference that is neither optional nor emptiable). Processors are not required to detect this error.
It is a static error if a module contains multiple bindings for the same namespace prefix.
It is a static error for an inline function expression to have more than one parameter with the same name.
An implementation MAY raise a static error if the value of a BracedURILiteral is of nonzero length and is neither an absolute URI nor a relative URI.
It is a dynamic error if the dynamic type of the operand of a treat expression does not match the sequence type designated by the treat expression. This error might also be raised by a path expression beginning with / or // if the context node is not in a tree that is rooted at a document node. This is because a leading / or // in a path expression is an abbreviation for an initial step that includes the clause treat as document-node().
It is a static error if an expanded QName used as an ItemType in a is not defined in the static context either as a named item type in the in-scope named item types, or as a generalized atomic type in the in-scope schema type.
The type named in a cast or castable expression must be the name of a type defined in the in-scope schema types, and the type must be simple.
A static error is raised if any of the following conditions is statically detected in any expression:
The prefix xml is bound to some namespace URI other than http://www.w3.org/XML/1998/namespace.
A prefix other than xml is bound to the namespace URI http://www.w3.org/XML/1998/namespace.
The prefix xmlns is bound to any namespace URI.
A prefix other than xmlns is bound to the namespace URI http://www.w3.org/2000/xmlns/.
A namespace declaration must not define a binding for the prefix xml or xmlns, nor for the URI http://www.w3.org/XML/1998/namespace or http://www.w3.org/2000/xmlns/.
It is a static error if the target type of a cast or castable expression is xs:NOTATION, xs:anySimpleType, or xs:anyAtomicType.
It is a static error if a QName used in an expression contains a namespace prefix that cannot be expanded into a namespace URI by using the statically known namespaces.
It is a static error if a variable bound in a for expression, and its associated positional variable, do not have distinct names (expanded QNames).
When applying the coercion rules, if an item is of type xs:untypedAtomic and the expected type is namespace-sensitive, a type error [err:XPTY0117] is raised.
An implementation-dependent limit has been exceeded.
The namespace axis is not supported.
No two keys in a map may have the same key value.
It is a static error if a named item type declaration is recursive, unless it satisfies the conditions defined in 3.2.8.3.1 Recursive Record Types.
In a forexpression, when the keyword member is present, the value of the binding collection must be a single array; and when either or both of the keywords key and value are present, the value of the binding collection must be a single map.
During the analysis phase, an axis step is classified as implausible if the combination of the inferred context item type, the choice of axis, and the supplied node test, is such that the axis step will always return an empty sequence.
During the analysis phase, a unary or postfix lookup expression is classified as implausible if the combination of the inferred type of the left-hand operand (or the context item type in the case of a unary expression) and the choice of key specifier is such that the lookup expression will always return an empty sequence.
It is a static error if a key type named in a is not a generalized atomic type.