Please refer to theerrata for this document, which may include somenormative corrections.
See alsotranslations.
This document is also available in these non-normative formats:XML and Changemarkings relative to first edition.
Copyright © 2010 W3C®(MIT,ERCIM,Keio), All Rights Reserved.W3Cliability,trademarkanddocumentuse rules apply.
XPath 2.0 is an expression language that allowsthe processing of values conforming to the data model defined in[XQuery 1.0 and XPath 2.0 Data Model (SecondEdition)]. The data model provides a tree representation of XMLdocuments as well as atomic values such as integers, strings, andbooleans, and sequences that may contain both references to nodesin an XML document and atomic values. The result of an XPathexpression may be a selection of nodes from the input documents, oran atomic value, or more generally, any sequence allowed by thedata model. The name of the language derives from its mostdistinctive feature, the path expression, which provides a means ofhierarchic addressing of the nodes in an XML tree. XPath 2.0 is asuperset of[XPath 1.0], with the addedcapability to support a richer set of data types, and to takeadvantage of the type information that becomes available whendocuments are validated using XML Schema. A backwards compatibilitymode is provided to ensure that nearly all XPath 1.0 expressionscontinue to deliver the same result with XPath 2.0; exceptions tothis policy are noted in [I Backwards Compatibility withXPath 1.0].
Status Update (October 2016): Although XPath 2.0 remains widely used, and is referenced normatively from other W3C specifications, readers are advised that later versions exist, and that no further maintenance (including correction of reported errors) is planned for this document. Readers interested in the most recent version of the XPath specification are encouraged to refer tohttps://www.w3.org/TR/xpath-3/.
This section describes the status of this document at thetime of its publication. Other documents may supersede thisdocument. A list of current W3C publications and the latestrevision of this technical report can be found in theW3C technical reports index athttp://www.w3.org/TR/.
This is one document in a set of eight documents that are beingprogressed to Edited Recommendation together (XPath 2.0, XQuery1.0, XQueryX 1.0, XSLT 2.0, Data Model (XDM), Functions andOperators, Formal Semantics, Serialization).
This document, published on 14 December 2010, is an EditedRecommendationof the W3C. It supersedes the previous W3C Recommendation of 23January 2007. This second edition is not a new version of thisspecification; its purpose is to clarify a number of issues thathave become apparent since the first edition was published. All ofthese clarifications (excepting trivial editorial fixes) have beenpublished in a separate errata document, and published in aProposed Edited Recommendation in April 2009. The changes aresummarized in an appendix. On 3 January 2011, the originalpublication of this Recommendation was replaced by this version inwhich two HTML anchors that were omitted by the originalpublication have been restored; the W3C Team has retained a copy ofthe original publication. This documenthas been jointly developed by the W3CXSL Working Group andthe W3CXML Query WorkingGroup, each of which is part of theXMLActivity.
This document has been reviewed by W3C Members, by softwaredevelopers, and by other W3C groups and interested parties, and isendorsed by the Director as a W3C Recommendation. It is a stabledocument and may be used as reference material or cited fromanother document. W3C's role in making the Recommendation is todraw attention to the specification and to promote its widespreaddeployment. This enhances the functionality and interoperability ofthe Web.
This documentincorporates changes made against theRecommendationof 23 January 2007 that resolve all errata known at the date ofpublication. Changes to this document since the first edition aredetailed in theJ Changes since theFirst Edition. This document supersedes thefirstedition.
This specification is designed to be referencednormatively from other specifications defining a host language forit; it is not intended to be implemented outside a host language.The implementability of this specification has been tested in thecontext of its normative inclusion in host languages defined by theXQuery 1.0 andXSLT 2.0 specifications; see theXQuery 1.0implementation report and theXSLT 2.0 implementation report (member-only) for details.
This document was produced bygroups operating under the5 February2004 W3C Patent Policy. W3C maintains apubliclist of any patent disclosures made in connection with thedeliverables of theXMLQuery Working Groupand also maintains apubliclist of any patent disclosures made in connection with thedeliverables of the XSL Working Group; those pages alsoinclude instructions for disclosing a patent. Anindividual who has actual knowledge of a patent which theindividual believes containsEssential Claim(s) must disclose the information in accordancewithsection 6 of the W3C Patent Policy.
1Introduction
2Basics
2.1ExpressionContext
2.1.1Static Context
2.1.2Dynamic Context
2.2Processing Model
2.2.1Data Model Generation
2.2.2Schema Import Processing
2.2.3Expression Processing
2.2.3.1Static Analysis Phase
2.2.3.2Dynamic Evaluation Phase
2.2.4Serialization
2.2.5Consistency Constraints
2.3ErrorHandling
2.3.1Kinds of Errors
2.3.2Identifying and Reporting Errors
2.3.3Handling Dynamic Errors
2.3.4Errors and Optimization
2.4Concepts
2.4.1Document Order
2.4.2Atomization
2.4.3Effective Boolean Value
2.4.4Input Sources
2.5Types
2.5.1Predefined Schema Types
2.5.2Typed Value and String Value
2.5.3SequenceType Syntax
2.5.4SequenceType Matching
2.5.4.1Matching a SequenceType and aValue
2.5.4.2Matching an ItemType and anItem
2.5.4.3Element Test
2.5.4.4Schema Element Test
2.5.4.5Attribute Test
2.5.4.6Schema Attribute Test
2.6Comments
3Expressions
3.1Primary Expressions
3.1.1Literals
3.1.2Variable References
3.1.3Parenthesized Expressions
3.1.4Context Item Expression
3.1.5Function Calls
3.2PathExpressions
3.2.1Steps
3.2.1.1Axes
3.2.1.2Node Tests
3.2.2Predicates
3.2.3Unabbreviated Syntax
3.2.4Abbreviated Syntax
3.3Sequence Expressions
3.3.1Constructing Sequences
3.3.2Filter Expressions
3.3.3Combining Node Sequences
3.4ArithmeticExpressions
3.5ComparisonExpressions
3.5.1Value Comparisons
3.5.2General Comparisons
3.5.3Node Comparisons
3.6Logical Expressions
3.7ForExpressions
3.8ConditionalExpressions
3.9Quantified Expressions
3.10Expressions onSequenceTypes
3.10.1Instance Of
3.10.2Cast
3.10.3Castable
3.10.4Constructor Functions
3.10.5Treat
AXPath Grammar
A.1EBNF
A.1.1Notation
A.1.2Extra-grammaticalConstraints
A.1.3Grammar Notes
A.2Lexicalstructure
A.2.1Terminal Symbols
A.2.2Terminal Delimitation
A.2.3End-of-Line Handling
A.2.3.1XML 1.0 End-of-LineHandling
A.2.3.2XML 1.1 End-of-LineHandling
A.2.4Whitespace Rules
A.2.4.1Default WhitespaceHandling
A.2.4.2Explicit WhitespaceHandling
A.3Reserved Function Names
A.4Precedence Order
BType Promotionand Operator Mapping
B.1TypePromotion
B.2OperatorMapping
CContext Components
C.1Static ContextComponents
C.2Dynamic ContextComponents
DImplementation-DefinedItems
EReferences
E.1Normative References
E.2Non-normative References
E.3Background Material
FConformance
F.1Static Typing Feature
F.1.1Static Typing Extensions
GError Conditions
HGlossary (Non-Normative)
IBackwards Compatibilitywith XPath 1.0 (Non-Normative)
I.1Incompatibilities when CompatibilityMode is true
I.2Incompatibilities when CompatibilityMode is false
I.3Incompatibilities when using aSchema
JChanges since the First Edition(Non-Normative)
The primary purpose of XPath is to address thenodes of[XML 1.0] or[XML1.1] trees. XPath gets its name from its use of a path notationfor navigating through the hierarchical structure of an XMLdocument. XPath uses a compact, non-XML syntax to facilitate use ofXPath within URIs and XML attribute values.
[Definition: XPath operates on the abstract,logical structure of an XML document, rather than its surfacesyntax. This logical structure, known as thedata model, isdefined in[XQuery 1.0 and XPath 2.0 DataModel (Second Edition)].]
XPath is designed to be embedded in ahostlanguage such as[XSL Transformations (XSLT)Version 2.0 (Second Edition)] or[XQuery 1.0:An XML Query Language (Second Edition)]. XPath has a naturalsubset that can be used for matching (testing whether or not a nodematches a pattern); this use of XPath is described in[XSL Transformations (XSLT) Version 2.0 (SecondEdition)].
XQuery Version 1.0 is an extension of XPath Version 2.0. Anyexpression that is syntactically valid and executes successfully inboth XPath 2.0 and XQuery 1.0 will return the same result in bothlanguages. Since these languages are so closely related, theirgrammars and language descriptions are generated from a commonsource to ensure consistency, and the editors of thesespecifications work together closely.
XPath also depends on and is closely related to the followingspecifications:
[XQuery 1.0 and XPath 2.0 Data Model(Second Edition)] defines the data model that underlies allXPath expressions.
[XQuery 1.0 and XPath 2.0Formal Semantics (Second Edition)] defines the static semanticsof XPath and also contains a formal but non-normative descriptionof the dynamic semantics that may be useful for implementors andothers who require a formal definition.
The type system of XPath is based on[XMLSchema].
The built-in function library and the operators supported byXPath are defined in[XQuery 1.0and XPath 2.0 Functions and Operators (Second Edition)].
This document specifies a grammar for XPath, using the samebasic EBNF notation used in[XML 1.0]. Unlessotherwise noted (seeA.2 Lexicalstructure), whitespace is not significant inexpressions. Grammarproductions are introduced together with the features that theydescribe, and a complete grammar is also presented in the appendix[A XPath Grammar]. The appendix is thenormative version.
In the grammar productions in this document, named symbols areunderlined and literal text is enclosed in double quotes. Forexample, the following production describes the syntax of afunction call:
[48] | FunctionCall | ::= | QName "(" (ExprSingle (","ExprSingle)*)? ")" |
The production should be read as follows: A function callconsists of a QName followed by an open-parenthesis. Theopen-parenthesis is followed by an optional argument list. Theargument list (if present) consists of one or more expressions,separated by commas. The optional argument list is followed by aclose-parenthesis.
Certain aspects of language processing are described in thisspecification asimplementation-defined orimplementation-dependent.
[Definition:Implementation-defined indicates an aspect that may differbetween implementations, but must be specified by the implementorfor each particular implementation.]
[Definition:Implementation-dependent indicates an aspect that may differbetween implementations, is not specified by this or any W3Cspecification, and is not required to be specified by theimplementor for any particular implementation.]
A language aspect described in this specificationasimplementation-defined orimplementation dependentmay be further constrained by the specifications of a host languagein which XPath is embedded.
This document normatively defines the dynamic semantics ofXPath. The static semantics of XPath are normatively defined in[XQuery 1.0 and XPath 2.0 FormalSemantics (Second Edition)]. In this document, examples andmaterial labeled as "Note" are provided for explanatory purposesand are not normative.
The basic building block of XPath is theexpression,which is a string of[Unicode] characters(the version of Unicode to be used isimplementation-defined.) Thelanguage provides several kinds of expressions which may beconstructed from keywords, symbols, and operands. In general, theoperands of an expression are other expressions. XPath allowsexpressions to be nested with full generality.
Note:
This specification contains no assumptions or requirementsregarding the character set encoding of strings of[Unicode] characters.
Like XML, XPath is a case-sensitive language. Keywords in XPathuse lower-case characters and are not reserved—that is, names inXPath expressions are allowed to be the same as language keywords,except for certain unprefixed function-names listed inA.3 Reserved Function Names.
[Definition:In thedata model, avalue is always asequence.] [Definition: Asequence isan ordered collection of zero or moreitems.] [Definition: Anitem is either anatomic value or anode.] [Definition: Anatomic value is a value inthe value space of anatomic type, as defined in[XML Schema].] [Definition: Anode is an instance of one ofthenode kinds defined in[XQuery 1.0and XPath 2.0 Data Model (Second Edition)].] Each node has auniquenode identity, atyped value, and astringvalue. In addition, some nodes have aname. Thetypedvalue of a node is a sequence of zero or more atomic values.Thestring value of a node is a value of typexs:string
. Thename of a node is a value oftypexs:QName
. [Definition: In certainsituations a value is said to beundefined (for example, thevalue of the context item, or the typed value of an element node).This term indicates that the property in question has no value andthat any attempt to use its value results in an error.]
[Definition: A sequence containing exactly one itemis called asingleton.] An item is identical to a singletonsequence containing that item. Sequences are never nested—forexample, combining the values 1, (2, 3), and ( ) into a singlesequence results in the sequence (1, 2, 3). [Definition: A sequence containing zero itemsis called anempty sequence.]
[Definition: The termXDM instanceis used, synonymously with the termvalue, to denote anunconstrained sequence ofnodesand/oratomicvalues in thedatamodel.]
Names in XPath are calledQNames, and conform to thesyntax in[XML Names]. [Definition: Lexically, aQName consists of an optional namespace prefix and a localname. If the namespace prefix is present, it is separated from thelocal name by a colon.] A lexical QName can be converted into anexpanded QName by resolving its namespace prefix to anamespace URI, using thestatically known namespaces[err:XPST0081].[Definition: Anexpanded QName consistsof an optional namespace URI and a local name. An expanded QNamealso retains its original namespace prefix (if any), to facilitatecasting the expanded QName into a string.] The namespace URI valueis whitespace normalized according to the rules for thexs:anyURI
type in[XMLSchema]. Two expanded QNames are equal if their namespace URIsare equal and their local names are equal (even if their namespaceprefixes are not equal). Namespace URIs and local names arecompared on a codepoint basis, without further normalization.
This document uses thefollowing namespace prefixes to represent the namespace URIs withwhich they are listed. Use of these namespace prefix bindings inthis document is not normative.
xs = http://www.w3.org/2001/XMLSchema
fn = http://www.w3.org/2005/xpath-functions
err = http://www.w3.org/2005/xqt-errors
(see2.3.2 Identifying and ReportingErrors).
Element nodes have a property calledin-scope namespaces.[Definition: Thein-scopenamespaces property of an element node is a set ofnamespacebindings, each of which associates a namespace prefix with aURI, thus defining the set of namespace prefixes that are availablefor interpreting QNames within the scope of the element. For agiven element, one namespace binding may have an empty prefix; theURI of this namespace binding is the default namespace within thescope of the element.]
In[XPath 1.0], the in-scopenamespaces of an element node are represented by a collection ofnamespace nodes arranged on anamespace axis. InXPath Version 2.0, the namespace axis is deprecated and need not besupported by a host language. A host language that does not supportthe namespace axis need not represent namespace bindings in theform of nodes.
[Definition: Withinthis specification, the termURI refers to a UniversalResource Identifier as defined in[RFC3986]and extended in[RFC3987] with the new nameIRI.] The term URI has been retained in preference to IRI toavoid introducing new names for concepts such as "Base URI" thatare defined or referenced across the whole family of XMLspecifications.
[Definition: Theexpressioncontext for a given expression consists of all the informationthat can affect the result of the expression.] This information isorganized into two categories called thestatic context and thedynamiccontext.
[Definition: Thestatic context of anexpression is the information that is available during staticanalysis of the expression, prior to its evaluation.] Thisinformation can be used to decide whether the expression contains astatic error.If analysis of an expression relies on some component of thestaticcontext that has not been assigned a value, astatic error is raised[err:XPST0001].
The individual components of thestatic context are summarized below.A default initial value foreach component may be specified by the host language. The scope ofeach component is specified inC.1 Static ContextComponents.
[Definition:XPath 1.0compatibility mode.This value istrue
if rules for backwardcompatibility with XPath Version 1.0 are in effect; otherwise it isfalse
.]
[Definition:Statically knownnamespaces. This is a set of (prefix, URI) pairs that defineall the namespaces that are known during static processing of agiven expression.] The URI value is whitespace normalized accordingto the rules for thexs:anyURI
type in[XML Schema]. Note the difference betweenin-scope namespaces, which is adynamic property of an element node, andstatically known namespaces, which is astatic property of an expression.
[Definition:Defaultelement/type namespace. This is a namespace URI or "none". Thenamespace URI, if present, is used for any unprefixed QNameappearing in a position where an element or type name is expected.]The URI value is whitespace normalized according to the rules forthexs:anyURI
type in[XMLSchema].
[Definition:Default functionnamespace. This is a namespace URI or "none". The namespaceURI, if present, is used for any unprefixed QName appearing in aposition where a function name is expected.] The URI value iswhitespace normalized according to the rules for thexs:anyURI
type in[XMLSchema].
[Definition:In-scope schemadefinitions. This is a generic term for all the elementdeclarations, attribute declarations, and schema type definitionsthat are in scope during processing of an expression.] It includesthe following three parts:
[Definition:In-scope schematypes. Each schema type definition is identified either by anexpandedQName (for anamed type) or by animplementation-dependent typeidentifier (for ananonymous type). The in-scope schematypes include the predefined schema types described in2.5.1 Predefined Schema Types.]
[Definition:In-scope elementdeclarations. Each element declaration is identified either byanexpandedQName (for a top-level element declaration) or by animplementation-dependent elementidentifier (for a local element declaration). ] An elementdeclaration includes information about the element'ssubstitutiongroup affiliation.
[Definition:Substitutiongroups are defined in[XML Schema]Part 1, Section 2.2.2.2. Informally, the substitution group headedby a given element (called thehead element) consists of theset of elements that can be substituted for the head elementwithout affecting the outcome of schema validation.]
[Definition:In-scopeattribute declarations. Each attribute declaration isidentified either by anexpanded QName (for a top-level attributedeclaration) or by animplementation-dependentattribute identifier (for a local attribute declaration). ]
[Definition:In-scopevariables. This is a set of (expanded QName, type) pairs. Itdefines the set of variables that are available for referencewithin an expression. Theexpanded QName is the name of thevariable, and the type is thestatic type of the variable.]
An expression that binds a variable (such as afor
,some
, orevery
expression) extends thein-scope variables of itssubexpressions with the new bound variable and its type.
[Definition:Context item statictype. This component defines thestatic type of the context item within thescope of a given expression.]
[Definition:Functionsignatures. This component defines the set of functions thatare available to be called from within an expression. Each functionis uniquely identified by itsexpanded QName and its arity (number ofparameters).] In addition to the name and arity, each functionsignature specifies thestatic types of the function parameters andresult.
Thefunction signatures include thesignatures ofconstructor functions, which arediscussed in3.10.4Constructor Functions.
[Definition:Statically knowncollations. This is animplementation-defined set of(URI, collation) pairs. It defines the names of the collations thatare available for use in processing expressions.] [Definition:Acollation is a specification of the manner in whichstrings and URIs are compared and, by extension, ordered. For amore complete definition of collation, see[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].]
[Definition:Default collation. Thisidentifies one of the collations instatically known collations as thecollation to be used by functions and operators for comparing andordering values of typexs:string
andxs:anyURI
(and types derived from them) when noexplicit collation is specified.]
[Definition:Base URI. This is an absoluteURI, used when necessary in the resolution of relative URIs (forexample, by thefn:resolve-uri
function.)] The URIvalue is whitespace normalized according to the rules for thexs:anyURI
type in[XMLSchema].
[Definition:Statically knowndocuments. This is a mapping from strings onto types. Thestring represents the absolute URI of a resource that ispotentially available using thefn:doc
function. Thetype is thestatictype of a call tofn:doc
with the given URI as itsliteral argument. ] If the argument tofn:doc
is astring literal that is not present instatically knowndocuments, then thestatic type offn:doc
isdocument-node()?
.
Note:
The purpose of thestatically known documents is toprovide static type information, not to determine which documentsare available. A URI need not be found in thestatically knowndocuments to be accessed usingfn:doc
.
[Definition:Statically knowncollections. This is a mapping from strings onto types. Thestring represents the absolute URI of a resource that ispotentially available using thefn:collection
function. The type is the type of the sequence of nodes that wouldresult from calling thefn:collection
function withthis URI as its argument.] If the argument tofn:collection
is a string literal that is not presentinstatically known collections, then thestatic type offn:collection
isnode()*
.
Note:
The purpose of thestatically known collections is toprovide static type information, not to determine which collectionsare available. A URI need not be found in thestatically knowncollections to be accessed usingfn:collection
.
[Definition:Statically known default collection type. This is the typeof the sequence of nodes that would result from calling thefn:collection
function with no arguments.] Unlessinitialized to some other value by an implementation, the value ofstatically known default collection type isnode()*
.
[Definition: Thedynamic context of anexpression is defined as information that is available at the timethe expression is evaluated.] If evaluation of an expression relieson some part of thedynamic context that has not beenassigned a value, adynamic error is raised [err:XPDY0002].
The individual components of thedynamic context are summarizedbelow. Further rules governing the semantics of these componentscan be found inC.2 Dynamic ContextComponents.
Thedynamic context consists of all thecomponents of thestatic context, and the additionalcomponents listed below.
[Definition:The first three components of thedynamic context (context item, contextposition, and context size) are called thefocus of theexpression. ] The focus enables the processor to keep track ofwhich items are being processed by the expression.
Certain language constructs, notably thepath expressionE1/E2
and thepredicateE1[E2]
, create a newfocus for the evaluation of a sub-expression. In these constructs,E2
is evaluated once for each item in the sequencethat results from evaluatingE1
. Each timeE2
is evaluated, it is evaluated with a differentfocus. The focus for evaluatingE2
is referred tobelow as theinner focus, while the focus for evaluatingE1
is referred to as theouter focus. The innerfocus exists only whileE2
is being evaluated. Whenthis evaluation is complete, evaluation of the containingexpression continues with its original focus unchanged.
[Definition: Thecontext item is the itemcurrently being processed. An item is either an atomic value or anode.][Definition: When the context item is a node, itcan also be referred to as thecontext node.] The contextitem is returned by an expression consisting of a single dot(.
). When an expressionE1/E2
orE1[E2]
is evaluated, each item in the sequenceobtained by evaluatingE1
becomes the context item inthe inner focus for an evaluation ofE2
.
[Definition: Thecontext position isthe position of the context item within the sequence of itemscurrently being processed.] It changes whenever the context itemchanges. When the focus is defined, the value of the contextposition is an integer greater than zero. The context position isreturned by the expressionfn:position()
. When anexpressionE1/E2
orE1[E2]
is evaluated,the context position in the inner focus for an evaluation ofE2
is the position of the context item in the sequenceobtained by evaluatingE1
. The position of the firstitem in a sequence is always 1 (one). The context position isalways less than or equal to the context size.
[Definition: Thecontext size is thenumber of items in the sequence of items currently beingprocessed.] Its value is always an integer greater than zero. Thecontext size is returned by the expressionfn:last()
.When an expressionE1/E2
orE1[E2]
isevaluated, the context size in the inner focus for an evaluation ofE2
is the number of items in the sequence obtained byevaluatingE1
.
[Definition:Variable values. This is aset of (expanded QName, value) pairs. It contains the sameexpandedQNames as thein-scope variables in thestatic context forthe expression. The expanded QName is the name of the variable andthe value is the dynamic value of the variable, which includes itsdynamictype.]
[Definition:Functionimplementations. Each function infunction signatures has afunction implementation that enables the function to map instancesof its parameter types into an instance of its result type. ]
[Definition:Current dateTime. Thisinformation represents animplementation-dependent pointin time during the processing ofan expression, and includes an explicittimezone. It can be retrieved by thefn:current-dateTime
function. If invoked multipletimes during the execution ofan expression, this function always returnsthe same result.]
[Definition:Implicit timezone. Thisis the timezone to be used when a date, time, or dateTime valuethat does not have a timezone is used in a comparison or arithmeticoperation. The implicit timezone is animplementation-defined value oftypexs:dayTimeDuration
. See[XMLSchema] for the range of legal values of a timezone.]
[Definition:Available documents.This is a mapping of strings onto document nodes. The stringrepresents the absolute URI of a resource. The document node is theroot of a tree that represents that resource using thedata model. The document nodeis returned by thefn:doc
function when applied tothat URI.] The set of available documents is not limited to the setofstatically known documents, and it may beempty.
If there are one or more URIs inavailable documents that map to adocument nodeD
, then the document-uri property ofD
must either be absent, or must be one of theseURIs.
Note:
This means that given a document node$N
, theresult offn:doc(fn:document-uri($N)) is $N
willalways be True, unlessfn:document-uri($N)
is an emptysequence.
[Definition:Availablecollections. This is a mapping of strings onto sequences ofnodes. The string represents the absolute URI of a resource. Thesequence of nodes represents the result of thefn:collection
function when that URI is supplied asthe argument. ] The set of available collections is not limited tothe set ofstatically known collections, and itmay be empty.
For every document nodeD
that is in the target ofa mapping inavailable collections, or that isthe root of a tree containing such a node, the document-uriproperty ofD
must either be absent, or must be a URIU
such thatavailable documents contains a mappingfromU
toD
."
Note:
This means that for any document node$N
retrievedusing thefn:collection
function, either directly orby navigating to the root of a node that was returned, the resultoffn:doc(fn:document-uri($N)) is $N
will always beTrue, unlessfn:document-uri($N)
is an empty sequence.This implies a requirement for thefn:doc
andfn:collection
functions to be consistent in theireffect. If the implementation uses catalogs or user-supplied URIresolvers to dereference URIs supplied to thefn:doc
function, the implementation of thefn:collection
function must take these mechanisms into account. For example, animplementation might achieve this by mapping the collection URI toa set of document URIs, which are then resolved using the samecatalog or URI resolver that is used by thefn:doc
function.
[Definition:Defaultcollection. This is the sequence of nodes that would resultfrom calling thefn:collection
function with noarguments.] The value ofdefault collection may beinitialized by the implementation.
XPath is defined in terms of thedata model and theexpressioncontext.
Figure 1: Processing Model Overview
Figure 1 provides a schematic overview of the processing stepsthat are discussed in detail below. Some of these steps arecompletely outside the domain of XPath; in Figure 1, these aredepicted outside the line that represents the boundaries of thelanguage, an area labeledexternal processing. The externalprocessing domain includes generation of anXDM instance that represents thedata to be queried (see2.2.1 Data ModelGeneration), schema import processing (see2.2.2 Schema ImportProcessing) and serialization (see2.2.4 Serialization). The areainside the boundaries of the language is known as theXPath processingdomain, which includes the static analysis anddynamic evaluation phases (see2.2.3 ExpressionProcessing). Consistency constraints on theXPath processing domainare defined in2.2.5Consistency Constraints.
Beforeanexpression can be processed, its input data must berepresented as anXDM instance. This process occursoutside the domain of XPath, which is why Figure 1 represents it inthe external processing domain. Here are some steps by which an XMLdocument might be converted to anXDM instance:
A document may be parsed using an XML parser that generates anXML Information Set (see[XMLInfoset]). The parsed document may then be validated againstone or more schemas. This process, which is described in[XML Schema], results in an abstract informationstructure called thePost-Schema Validation Infoset (PSVI).If a document has no associated schema, its Information Set ispreserved. (See DM1 in Fig. 1.)
The Information Set or PSVI may be transformed into anXDM instance by aprocess described in[XQuery 1.0 and XPath 2.0Data Model (Second Edition)]. (See DM2 in Fig. 1.)
The above steps provide an example of how anXDM instancemight be constructed. An XDM instance might also be synthesizeddirectly from a relational database, or constructed in some otherway (see DM3 in Fig. 1.) XPath is defined in terms of thedata model, but it does notplace any constraints on how XDM instances are constructed.
[Definition: Each element node and attributenode in anXDM instance has atypeannotation (referred to in[XQuery 1.0 andXPath 2.0 Data Model (Second Edition)] as itstype-name
property.) The type annotation of a node isaschema typethat describes the relationship between thestring value of the node and itstyped value.] IftheXDMinstance was derived from a validated XML document as describedinSection 3.3Construction from a PSVIDM, the typeannotations of the element and attribute nodes are derived fromschema validation. XPath does not provide a way to directly accessthe type annotation of an element or attribute node.
The value of an attribute is represented directly within theattribute node. An attribute node whose type is unknown (such asmight occur in a schemaless document) is given thetype annotationxs:untypedAtomic
.
The value of an element is represented by the children of theelement node, which may include text nodes and other element nodes.Thetypeannotation of an element node indicates how the values in itschild text nodes are to be interpreted. An element that has notbeen validated (such as might occur in a schemaless document) isannotated with the schema typexs:untyped
. An elementthat has been validated and found to be partially valid isannotated with the schema typexs:anyType
. If anelement node is annotated asxs:untyped
, all itsdescendant element nodes are also annotated asxs:untyped
. However, if an element node is annotatedasxs:anyType
, some of its descendant element nodesmay have a more specifictype annotation.
Thein-scope schema definitions in thestatic context areprovided by the host language (see step SI1 in Figure 1) and mustsatisfy the consistency constraints defined in2.2.5 ConsistencyConstraints.
XPath defines two phases of processing called thestatic analysisphase and thedynamic evaluation phase (see Fig. 1).During the static analysis phase,static errors,dynamic errors, ortype errors may be raised.During the dynamic evaluation phase, onlydynamic errors ortype errors may be raised.These kinds of errors are defined in2.3.1 Kinds of Errors.
Within each phase, an implementation is free to use any strategyor algorithm whose result conforms to the specifications in thisdocument.
[Definition: Thestatic analysisphase depends on the expression itself and on thestatic context. Thestatic analysis phase does not depend on input data (otherthan schemas).]
During the static analysis phase, theXPath expression isparsed into an internal representation called theoperationtree (step SQ1 in Figure 1). A parse error is raised as astatic error[err:XPST0003]. Thestaticcontext is initialized by the implementation (step SQ2). Thestaticcontext is used to resolve schema type names, function names,namespace prefixes, and variable names (step SQ4). If a name of oneof these kinds in theoperation tree is not found in thestaticcontext, astatic error ([err:XPST0008] or [err:XPST0017]) is raised (however, seeexceptions to this rule in2.5.4.3Element Test and2.5.4.5Attribute Test.)
Theoperation tree is thennormalized by makingexplicit the implicit operations such asatomization and extraction ofEffective BooleanValues (step SQ5). The normalization process is described in[XQuery 1.0 and XPath 2.0 FormalSemantics (Second Edition)].
Each expression is then assigned astatic type (step SQ6). [Definition: Thestatic type of anexpression is a type such that, when the expression is evaluated,the resulting value will always conform to the static type.] If theStatic Typing Feature issupported, thestatictypes of various expressions are inferred according to therules described in[XQuery 1.0 andXPath 2.0 Formal Semantics (Second Edition)]. If theStatic Typing Feature is notsupported, the static types that are assigned areimplementation-dependent.
During thestatic analysis phase, if theStatic Typing Feature is ineffect and an operand of an expression is found to have astatic type that is notappropriate for that operand, atype error is raised [err:XPTY0004]. If static type checkingraises no errors and assigns astatic type T to an expression, thenexecution of the expression on valid input data is guaranteedeither to produce a value of type T or to raise adynamic error.
The purpose of theStatic Typing Feature is toprovide early detection oftype errors and to infer type information thatmay be useful in optimizing the evaluation of an expression.
[Definition: Thedynamicevaluation phase is the phase during which the value of anexpression is computed.] It occurs after completion of thestaticanalysis phase.
The dynamic evaluation phase can occur only if no errors weredetected during thestatic analysis phase. If theStatic Typing Feature is ineffect, alltypeerrors are detected during static analysis and serve to inhibitthe dynamic evaluation phase.
The dynamic evaluation phase depends on theoperationtree of the expression being evaluated (step DQ1), on the inputdata (step DQ4), and on thedynamic context (step DQ5), which in turndraws information from the external environment (step DQ3) and thestaticcontext (step DQ2). The dynamic evaluation phase may create newdata-model values (step DQ4) and it may extend thedynamic context(step DQ5)—for example, by binding values to variables.
[Definition: Adynamic type is associatedwith each value as it is computed. The dynamic type of a value maybe more specific than thestatic type of the expression that computedit (for example, the static type of an expression might bexs:integer*
, denoting a sequence of zero or moreintegers, but at evaluation time its value may have the dynamictypexs:integer
, denoting exactly one integer.)]
If an operand of an expression is found to have adynamic type that is notappropriate for that operand, atype error is raised [err:XPTY0004].
Even though static typing can catch manytype errors before an expression isexecuted, it is possible for an expression to raise an error duringevaluation that was not detected by static analysis. For example,an expression may contain a cast of a string into an integer, whichis statically valid. However, if the actual value of the string atrun time cannot be cast into an integer, adynamic error will result. Similarly,an expression may apply an arithmetic operator to a value whosestatic type isxs:untypedAtomic
. This is not astatic error, but at runtime, if the value cannot be successfully cast to anumeric type, adynamic error will beraised.
When theStatic Typing Feature is ineffect, it is also possible for static analysis of an expression toraise atype error,even though execution of the expression on certain inputs would besuccessful. For example, an expression might contain a functionthat requires an element as its parameter, and the static analysisphase might infer thestatic type of the function parameter to bean optional element. This case is treated as atype error and inhibitsevaluation, even though the function call would have beensuccessful for input data in which the optional element ispresent.
[Definition:Serialization is the processof converting anXDM instance into a sequence ofoctets (step DM4 in Figure 1.) ] The general framework forserialization is described in[XSLT 2.0and XQuery 1.0 Serialization (Second Edition)].
The host language may provide a serializationoption.
In order for XPath to be well defined, the inputXDM instance, thestaticcontext, and thedynamic context must be mutuallyconsistent. The consistency constraints listed below areprerequisites for correct functioning of an XPath implementation.Enforcement of these consistency constraints is beyond the scope ofthis specification. This specification does not define the resultofanexpression under any condition in which one or moreof these constraints is not satisfied.
Some of the consistency constraints use the termdata modelschema. [Definition:For a given node in anXDM instance, thedata modelschema is defined as the schema from which thetype annotation ofthat node was derived.] For a node that was constructed by someprocess other than schema validation, thedata model schemaconsists simply of the schema type definition that is representedby thetypeannotation of the node.
For every node that has a type annotation, if that typeannotation is found in thein-scope schema definitions (ISSD), then itsdefinition in the ISSD must be equivalent to its definition in thedatamodel schema. Furthermore, all types that are derived byextension from the given type in thedata model schema must also beknown by equivalent definitions in the ISSD.
For every element nameEN that is found both in anXDMinstance and in thein-scope schema definitions (ISSD), allelements that are known in thedata model schema to be in thesubstitution group headed byEN must also be known in the ISSD to be in thesubstitutiongroup headed byEN.
Every element name, attribute name, or schema type namereferenced inin-scope variables orfunctionsignatures must be in thein-scope schemadefinitions, unless it is an element name referenced as part ofanElementTest or an attributename referenced as part of anAttributeTest.
Any reference to a global element, attribute, or type name inthein-scopeschema definitions must have a corresponding element, attributeor type definition in thein-scope schema definitions.
For each mapping of a string to a document node inavailabledocuments, if there exists a mapping of the same string to adocument type instatically known documents, the document nodemust match the document type, using the matching rules in2.5.4 SequenceTypeMatching.
For each mapping of a string to a sequence of nodes inavailablecollections, if there exists a mapping of the same string to atype instatically known collections, thesequence of nodes must match the type, using the matching rules in2.5.4 SequenceTypeMatching.
The sequence of nodes in thedefault collection must match thestatically known default collectiontype, using the matching rules in2.5.4 SequenceTypeMatching.
The value of thecontext item must match thecontext item static type, usingthe matching rules in2.5.4SequenceType Matching.
For each (variable, type) pair inin-scope variables and thecorresponding (variable, value) pair invariable values such that thevariable names are equal, the value must match the type, using thematching rules in2.5.4SequenceType Matching.
In thestatically known namespaces, the prefixxml
must not be bound to any namespace URI other thanhttp://www.w3.org/XML/1998/namespace
, and no prefixother thanxml
may be bound to this namespace URI.
As described in2.2.3Expression Processing, XPath defines astatic analysisphase, which does not depend on input data, and adynamicevaluation phase, which does depend on input data. Errors maybe raised during each phase.
[Definition: Astatic error is an errorthat must be detected during the static analysis phase. A syntaxerror is an example of astatic error.]
[Definition: Adynamic error is an errorthat must be detected during the dynamic evaluation phase and maybe detected during the static analysis phase. Numeric overflow isan example of a dynamic error. ]
[Definition: Atype error may be raisedduring the static analysis phase or the dynamic evaluation phase.During the static analysis phase, atype error occurs when thestatic type of anexpression does not match the expected type of the context in whichthe expression occurs. During the dynamic evaluation phase, atype error occurswhen thedynamictype of a value does not match the expected type of the contextin which the value occurs.]
The outcome of thestatic analysis phase is either successor one or moretypeerrors,staticerrors, or statically-detecteddynamic errors. The result of thedynamicevaluation phase is either a result value, atype error, or adynamic error.
If more than one error is present, or if an error conditioncomes within the scope of more than one error defined in thisspecification, then any non-empty subset of these errors may bereported.
During thestatic analysis phase, if theStatic Typing Feature is ineffect and thestatictype assigned to an expression other than()
ordata(())
isempty-sequence()
, astatic error is raised[err:XPST0005].This catches cases in which a query refers to an element orattribute that is not present in thein-scope schemadefinitions, possibly because of a spelling error.
Independently of whether theStatic Typing Feature isin effect, if an implementation can determine during thestatic analysisphase that an expression, if evaluated, would necessarily raiseatype error or adynamicerror, the implementation may (but is not required to) reportthat error during thestatic analysis phase. However, thefn:error()
function must not be evaluated during thestaticanalysis phase.
[Definition: In addition tostatic errors,dynamic errors, andtype errors, an XPathimplementation may raisewarnings, either during thestaticanalysis phase or thedynamic evaluation phase. Thecircumstances in which warnings are raised, and the ways in whichwarnings are handled, areimplementation-defined.]
In addition to the errors defined in this specification, animplementation may raise adynamic error for a reason beyond the scopeof this specification. For example, limitations may exist on themaximum numbers or sizes of various objects. Any such limitations,and the consequences of exceeding them, areimplementation-dependent.
The errors defined in this specification are identified byQNames that have the formerr:XPYYnnnn
, where:
err
denotes the namespace for XPath and XQueryerrors,http://www.w3.org/2005/xqt-errors
. Thisbinding of the namespace prefixerr
is used forconvenience in this document, and is not normative.
XP
identifies the error as an XPath error.
YY
denotes the error category, using the followingencoding:
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 tochange from one version of XPath to another. However, the contentsof this namespace may be extended to include additional errordefinitions.
The method by which an XPath processor reports error informationto the external environment isimplementation-defined.
An error can be represented by a URI reference that is derivedfrom the error QName as follows: an error with namespace URINS
and local partLP
can be represented as the URI referenceNS
#
LP
. Forexample, an error whose QName iserr:XPST0017
could berepresented ashttp://www.w3.org/2005/xqt-errors#XPST0017
.
Note:
Along with a code identifying an error, implementations may wishto return additional information, such as the location of the erroror the processing phase in which it was detected. If animplementation chooses to do so, then the mechanism that it uses toreturn this information isimplementation-defined.
Except as noted in this document, if any operand of anexpression raises adynamic error, the expression also raises adynamicerror. If an expression can validly return a value or raise adynamic error, the implementation may choose to return the value orraise the dynamic error. For example, the logical expressionexpr1 and expr2
may return the valuefalse
if either operand returnsfalse
, ormay raise a dynamic error if either operand raises a dynamicerror.
If more than one operand of an expression raises an error, theimplementation 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)
andxs:decimal($z)
may raise an error. The implementationmay choose which error is raised by the "+
"expression. Once one operand raises an error, the implementation isnot 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 moreadditional values callederror values.] An implementationmay provide a mechanism whereby an application-defined errorhandler can process error values and produce diagnosticmessages.
A dynamic error may be raised by abuilt-in function or operator. Forexample, thediv
operator raises an error if itsoperands arexs:decimal
values and its second operandis equal to zero. Errors raised by built-in functions and operatorsare defined in[XQuery 1.0 andXPath 2.0 Functions and Operators (Second Edition)].
A dynamic error can also be raised explicitly by calling thefn:error
function, which only raises an error andnever returns a value. This function is defined in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)]. For example, the followingfunction call raises a dynamic error, providing a QName thatidentifies the error, a descriptive string, and a diagnostic value(assuming that the prefixapp
is bound to a namespacecontaining application-defined error codes):
fn:error(xs:QName("app:err057"), "Unexpected value", fn:string($v))
Because different implementations may choose to evaluate oroptimize an expression in different ways, certain aspects of thedetection and reporting ofdynamic errors areimplementation-dependent, asdescribed in this section.
An implementation is always free to evaluate the operands of anoperator in any order.
In some cases, a processor can determine the result of anexpression without accessing all the data that would be implied bythe formal expression semantics. For example, the formaldescription offilter expressions suggests that$s[1]
should be evaluated by examining all the itemsin sequence$s
, and selecting all those that satisfythe predicateposition()=1
. In practice, manyimplementations will recognize that they can evaluate thisexpression by taking the first item in the sequence and thenexiting. If$s
is defined by an expression such as//book[author eq 'Berners-Lee']
, then this strategymay avoid a complete scan of a large document and may thereforegreatly improve performance. However, a consequence of thisstrategy is that a dynamic error or type error that would bedetected if the expression semantics were followed literally mightnot be detected at all if the evaluation exits early. In thisexample, such an error might occur if there is abook
element in the input data with more than oneauthor
subelement.
The extent to which a processor may optimize its access to data,at the cost of not detecting errors, is defined by the followingrules.
Consider an expressionQ that has an operand(sub-expression)E. In general the value ofE isa sequence. At an intermediate stage during evaluation of thesequence, some of its items will be known and others will beunknown. If, at such an intermediate stage of evaluation, aprocessor is able to establish that there are only two possibleoutcomes of evaluatingQ, namely the valueV oran error, then the processor may deliver the resultVwithout evaluating further items in the operandE. Forthis purpose, two values are considered to represent the sameoutcome if their items are pairwise the same, where nodes are thesame if they have the same identity, and values are the same ifthey are equal and have exactly the same type.
There is an exception to this rule: If a processor evaluates anoperandE (wholly or in part), then it is required toestablish that the actual value of the operandE does notviolate any constraints on its cardinality. For example, theexpression$e eq 0
results in a type error if thevalue of$e
contains two or more items. A processor isnot allowed to decide, after evaluating the first item in the valueof$e
and finding it equal to zero, that the onlypossible outcomes are the valuetrue
or a type errorcaused by the cardinality violation. It must establish that thevalue of$e
contains no more than one item.
These rules apply to all the operands of an expressionconsidered in combination: thus if an expression has two operandsE1 andE2, it may be evaluated using any samplesof the respective sequences that satisfy the above rules.
The rules cascade: ifA is an operand ofB andB is an operand ofC, then the processor needs toevaluate only a sufficient sample ofB to determine thevalue ofC, and needs to evaluate only a sufficient sampleofA to determine this sample ofB.
The effect of these rules is that the processor is free to stopexamining further items in a sequence as soon as it can establishthat further items would not affect the result except possibly bycausing an error. For example, the processor may returntrue
as the result of the expressionS1 =S2
as soon as it finds a pair of equal values from the twosequences.
Another consequence of these rules is that where none of theitems in a sequence contributes to the result of an expression, theprocessor is not obliged to evaluate any part of the sequence.Again, however, the processor cannot dispense with a requiredcardinality check: if an empty sequence is not permitted in therelevant context, then the processor must ensure that the operandis 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 thefollowing example has the value47
, it is allowed toreturntrue
as the result of thesome
expression, without searching for another item returned by$expr1
that would raise an error if it wereevaluated.
some $x in $expr1 satisfies $x = 47
In the following example, if an implementation can find (forexample, by using an index) theproduct
element-nodesthat have anid
child with the value47
,it is allowed to return these nodes as the result of thepath expression,without searching for anotherproduct
node that wouldraise an error because it has anid
child whose valueis 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 thisfreedom:
Other than the raising or not raising of errors, the result ofevaluating a rewritten expression must conform to the semanticsdefined in this specification for the original expression.
Note:
This allows an implementation to return a result in cases wherethe original expression would have raised an error, or to raise anerror in cases where the original expression would have returned aresult. The main cases where this is likely to arise in practiceare (a) where a rewrite changes the order of evaluation, such thata subexpression causing an error is evaluated when the expressionis written one way and is not evaluated when the expression iswritten a different way, and (b) where intermediate results of theevaluation cause overflow or other out-of-range conditions.
Note:
This rule does not mean that the result of the expression willalways be the same in non-error cases as if it had not beenrewritten, because there are many cases where the result of anexpression is to some degreeimplementation-dependent orimplementation-defined.
Conditional and typeswitch expressions must not raise a dynamicerror in respect of subexpressions occurring in a branch that isnot selected, and must not return the value delivered by a branchunless that branch is selected. Thus, the following example mustnot raise a dynamic error if the documentabc.xml
doesnot exist:
if (doc-available('abc.xml')) then doc('abc.xml') else ()
As stated earlier, an expression must not be rewritten todispense with a required cardinality check: for example,string-length(//title)
must raise an error if thedocument contains more than one title element.
Expressions must not be rewritten in such a way as to create orremove static errors. For example, there is a rule that in castinga string to a QName the operand must be a string literal. This ruleapplies to the original expression and not to any rewritten form ofthe expression.
Expression rewrite is illustrated by the following examples.
Consider the expression//part[color eq "Red"]
. Animplementation might choose to rewrite this expression as//part[color = "Red"][color eq "Red"]
. Theimplementation might then process the expression as follows: Firstprocess the "=
" predicate by probing an index on partsby color to quickly find all the parts that have a Red color; thenprocess the "eq
" predicate by checking each of theseparts to make sure it has only a single color. The result would beas follows:
Parts that have exactly one color that is Red are returned.
If some part has color Red together with some other color, anerror is raised.
The existence of some part that has no color Red but hasmultiple non-Red colors does not trigger an error.
The expression in the following example cannot raise a castingerror if it is evaluated exactly as written (i.e., left to right).Since neither predicate depends on the context position, animplementation might choose to reorder the predicates to achievebetter 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, teststhat are designed to prevent dynamic errors should be expressedusing conditional expressions. For example, the above expressioncan 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 theprocessing of XPath expressions.
An ordering calleddocument order is defined among allthe nodes accessible during processing of a givenexpression, which mayconsist of one or moretrees (documents or fragments).Document order is defined in[XQuery 1.0 andXPath 2.0 Data Model (Second Edition)], and its definition isrepeated here for convenience. [Definition: The node ordering that isthe reverse of document order is calledreverse documentorder.]
Document order is a total ordering, although the relative orderof some nodes isimplementation-dependent.[Definition: Informally,document orderis the order in which nodes appear in the XML serialization of adocument.] [Definition: Document order isstable, whichmeans that the relative order of two nodes will not change duringthe processing of a givenexpression, even if this order isimplementation-dependent.]
Within a tree, document order satisfies the followingconstraints:
The root node is the first node.
Every node occurs before all of its children anddescendants.
Namespace nodes immediately follow the element node with whichthey are associated. The relative order of namespace nodes isstable butimplementation-dependent.
Attribute nodes immediately follow thenamespace nodes of theelement node with which they are associated. The relative order ofattribute nodes is stable butimplementation-dependent.
The relative order of siblings is the order in which they occurin thechildren
property of their parent node.
Children and descendants occur before following siblings.
The relative order of nodes in distinct trees is stable butimplementation-dependent,subject to the following constraint: If any node in a given tree T1is before any node in a different tree T2, then all nodes in treeT1 are before all nodes in tree T2.
The semantics of some XPath operators depend on a process calledatomization.Atomization is applied to a value when the value is used in acontext in which a sequence of atomic values is required. Theresult of atomization is either a sequence of atomic values or atype error[err:FOTY0012]. [Definition:Atomization of asequence is defined as the result of invoking thefn:data
function on the sequence, as defined in[XQuery 1.0 and XPath 2.0Functions and Operators (Second Edition)].]
The semantics offn:data
are repeated here forconvenience. The result offn:data
is the sequence ofatomic values produced by applying the following rules to each itemin the input sequence:
If the item is an atomic value, it is returned.
If the item is a node, itstyped value is returned (err:FOTY0012 israised if the node has no typed value.)
Atomization is used in processing the following types ofexpressions:
Arithmetic expressions
Comparison expressions
Function calls and returns
Cast expressions
Under certain circumstances (listed below), it is necessary tofind theeffective boolean value of a value. [Definition: Theeffective boolean value of a value is defined as the resultof applying thefn:boolean
function to the value, asdefined in[XQuery 1.0 and XPath2.0 Functions and Operators (Second Edition)].]
The dynamic semantics offn:boolean
are repeatedhere for convenience:
If its operand is an empty sequence,fn:boolean
returnsfalse
.
If its operand is a sequence whose first item is a node,fn:boolean
returnstrue
.
If its operand is asingleton value of typexs:boolean
or derived fromxs:boolean
,fn:boolean
returns the value of its operand unchanged.
If its operand is asingleton value of typexs:string
,xs:anyURI
,xs:untypedAtomic
, or a typederived from one of these,fn:boolean
returnsfalse
if the operand value has zero length; otherwiseit returnstrue
.
If its operand is asingleton value of anynumeric type or derived from a numeric type,fn:boolean
returnsfalse
if the operandvalue isNaN
or is numerically equal to zero;otherwise it returnstrue
.
In all other cases,fn:boolean
raises a type error[err:FORG0006].
Note:
The static semantics offn:boolean
are defined inSection7.2.4 The fn:boolean and fn:notfunctionsFS.
Theeffectiveboolean value of a sequence is computed implicitly duringprocessing of the following types of expressions:
Logical expressions (and
,or
)
Thefn:not
function
Certain types ofpredicates, such asa[b]
Conditional expressions (if
)
Quantified expressions (some
,every
)
General comparisons, inXPath 1.0 compatibility mode.
Note:
The definition ofeffective boolean value isnot used whencasting a value to the typexs:boolean
, for example inacast
expression or when passing a value to afunction whose expected parameter is of typexs:boolean
.
XPath has a set of functions that provide access to input data.These functions are of particular importance because they provide away in which an expression can reference a document or a collectionof documents. The input functions are described informally here;they are defined in[XQuery 1.0and XPath 2.0 Functions and Operators (Second Edition)].
An expression can access input data either by calling one of theinput functions or by referencing some part of thedynamic contextthat is initialized by the external environment, such as avariableorcontextitem.
The input functions supported by XPath are as follows:
Thefn:doc
function takes a string containing aURI. If that URI is associated with a document inavailabledocuments,fn:doc
returns a document node whosecontent is thedatamodel representation of the given document; otherwise it raisesadynamicerror (see[XQuery 1.0 andXPath 2.0 Functions and Operators (Second Edition)] fordetails).
Thefn:collection
function with one argument takesa string containing a URI. If that URI is associated with acollection inavailable collections,fn:collection
returns the data model representation ofthat collection; otherwise it raises adynamic error (see[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)] for details). A collection may beany sequence of nodes. For example, the expressionfn:collection("http://example.org")//customer
identifies all thecustomer
elements that aredescendants of nodes found in the collection whose URI ishttp://example.org
.
Thefn:collection
function with zero argumentsreturns thedefault collection, animplementation-dependentsequence of nodes.
The type system of XPath is based on[XMLSchema], and is formally defined in[XQuery 1.0 and XPath 2.0 Formal Semantics(Second Edition)].
[Definition: Asequence type is a typethat can be expressed using theSequenceType syntax. Sequence typesare used whenever it is necessary to refer to a type in an XPathexpression. The termsequence type suggests that this syntaxis used to describe the type of an XPath value, which is always asequence.]
[Definition: Aschema type is a type thatis (or could be) defined using the facilities of[XML Schema] (including the built-in types of[XML Schema]).] A schema type can be usedas a type annotation on an element or attribute node (unless it isa non-instantiable type such asxs:NOTATION
orxs:anyAtomicType
, in which case its derived types canbe so used). Every schema type is either acomplex type or asimple type; simple types are further subdivided intolist types,union types, andatomic types (see[XML Schema] for definitions andexplanations of these terms.)
Atomic types represent the intersection between the categoriesofsequencetype andschematype. An atomic type, such asxs:integer
ormy:hatsize
, is both asequence type and aschema type.
Thein-scope schema types in thestatic context areinitialized with a set of predefined schema types that isdetermined by the host language. This set may include some or allof the schema types in the namespacehttp://www.w3.org/2001/XMLSchema
, represented in thisdocument by the namespace prefixxs
. The schema typesin this namespace are defined in[XMLSchema] and augmented by additional types defined in[XQuery 1.0 and XPath 2.0 Data Model (SecondEdition)]. The schema types defined in[XQuery 1.0 and XPath 2.0 Data Model (SecondEdition)] are summarized below.
[Definition:xs:untyped
is used as thetypeannotation of an element node that has not been validated, orhas been validated inskip
mode.] No predefined schematypes are derived fromxs:untyped
.
[Definition:xs:untypedAtomic
isan atomic type that is used to denote untyped atomic data, such astext that has not been assigned a more specific type.] An attributethat has been validated inskip
mode is represented inthedata model by anattribute node with thetype annotationxs:untypedAtomic
. No predefined schema types arederived fromxs:untypedAtomic
.
[Definition:xs:dayTimeDuration
is derived by restriction fromxs:duration
. The lexical representation ofxs:dayTimeDuration
is restricted to contain only day,hour, minute, and second components.]
[Definition:xs:yearMonthDuration
is derived by restriction fromxs:duration
. The lexical representation ofxs:yearMonthDuration
is restricted to contain onlyyear and month components.]
[Definition:xs:anyAtomicType
isan atomic type that includes all atomic values (and no values thatare not atomic). Its base type isxs:anySimpleType
from which all simple types, including atomic, list, and uniontypes, are derived. All primitive atomic types, such asxs:decimal
andxs:string
, havexs:anyAtomicType
as their base type.]
Note:
xs:anyAtomicType
will not appear as the type of anactual value in anXDM instance.
The relationships among the schema types in thexs
namespace are illustrated in Figure 2. A more complete descriptionof the XPath type hierarchy can be found in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
Figure 2: Hierarchy of Schema Types used in XPath
Every node has atyped value and astring value.[Definition: Thetyped value of a node is asequence of atomic values and can be extracted by applying thefn:data
function to the node.] [Definition: Thestring value of a node isa string and can be extracted by applying thefn:string
function to the node.] Definitions offn:data
andfn:string
can be found in[XQuery 1.0 and XPath 2.0Functions and Operators (Second Edition)].
An implementation may store both thetyped value and thestring 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 representationof the typed value of the node, but the node is not required topreserve the string representation from the original sourcedocument. For example, if the typed value of a node is thexs:integer
value30
, its string valuemight be "30
" or "0030
".
Thetyped value,string value, andtype annotation of a node areclosely related. If the node was created by mapping from an Infosetor PSVI, the relationships among these properties are defined byrules in[XQuery 1.0 and XPath 2.0 Data Model(Second Edition)].
As a convenience to the reader, the relationship betweentyped value andstring valuefor various kinds of nodes is summarized and illustrated byexamples below.
For text and document nodes, the typed value of the node is thesame as its string value, as an instance of the typexs:untypedAtomic
. The string value of a document nodeis formed by concatenating the string values of all its descendanttext nodes, indocument order.
The typed value of a comment, namespace, or processing instruction nodeis the same as its string value. It is an instance of the typexs:string
.
The typed value of an attribute node with thetype annotationxs:anySimpleType
orxs:untypedAtomic
isthe same as its string value, as an instance ofxs:untypedAtomic
. The typed value of an attribute nodewith any other type annotation is derived from its string value andtype annotation using the lexical-to-value-space mapping defined in[XML Schema] Part 2 for the relevanttype.
Example: A1 is an attribute having string value"3.14E-2"
and type annotationxs:double
.The typed value of A1 is thexs:double
value whoselexical representation is3.14E-2
.
Example: A2 is an attribute with type annotationxs:IDREFS
, which is a list datatype whose item type isthe atomic datatypexs:IDREF
. Its string value is"bar baz faz
". The typed value of A2 is a sequence ofthree atomic values ("bar
", "baz
","faz
"), each of typexs:IDREF
. The typedvalue of a node is never treated as an instance of a named listtype. Instead, if the type annotation of a node is a list type(such asxs:IDREFS
), its typed value is treated as asequence of the atomic type from which it is derived (such asxs:IDREF
).
For an element node, the relationship between typed value andstring value depends on the node'stype annotation, as follows:
If the type annotation isxs:untyped
orxs:anySimpleType
or denotes a complex type with mixedcontent (includingxs:anyType
), then the typed valueof the node is equal to its string value, as an instance ofxs:untypedAtomic
. However, if thenilled
property of the node istrue
, then its typed value isthe empty sequence.
Example: E1 is an element node having type annotationxs:untyped
and string value "1999-05-31
".The typed value of E1 is "1999-05-31
", as an instanceofxs:untypedAtomic
.
Example: E2 is an element node with the type annotationformula
, which is a complex type with mixed content.The content of E2 consists of the character "H
", achild element namedsubscript
with string value"2
", and the character "O
". The typedvalue of E2 is "H2O
" as an instance ofxs:untypedAtomic
.
If the type annotation denotes a simple type or a complex typewith simple content, then the typed value of the node is derivedfrom its string value and its type annotation in a way that isconsistent with schema validation. However, if thenilled
property of the node istrue
, thenits typed value is the empty sequence.
Example: E3 is an element node with the type annotationcost
, which is a complex type that has severalattributes and a simple content type ofxs:decimal
.The string value of E3 is "74.95
". The typed value ofE3 is74.95
, as an instance ofxs:decimal
.
Example: E4 is an element node with the type annotationhatsizelist
, which is a simple type derived from theatomic typehatsize
, which in turn is derived fromxs:integer
. The string value of E4 is "7 89
". The typed value of E4 is a sequence of three values(7
,8
,9
), each of typehatsize
.
Example: E5 is an element node with the type annotationmy:integer-or-string
which is a union type with membertypesxs:integer
andxs:string
. Thestring value of E5 is "47
". The typed value of E5 is47
as anxs:integer
, sincexs:integer
is the member type that validated thecontent of E5. In general, when the type annotation of a node is aunion type, the typed value of the node will be an instance of oneof the member types of the union.
Note:
If an implementation stores only the string value of a node, andthe type annotation of the node is a union type, the implementationmust be able to deliver the typed value of the node as an instanceof the appropriate member type.
If the type annotation denotes a complex type with emptycontent, then the typed value of the node is the empty sequence andits string value is the zero-length string.
If the type annotation denotes a complex type with element-onlycontent, then the typed value of the node isundefined. Thefn:data
function raises atypeerror [err:FOTY0012] when applied to such a node. The stringvalue of such a node is equal to the concatenated string values ofall its text node descendants, in document order.
Example: E6 is an element node with the type annotationweather
, which is a complex type whose content typespecifieselement-only
. E6 has two child elementsnamedtemperature
andprecipitation
. Thetyped value of E6 isundefined, and thefn:data
function applied to E6 raises an error.
Whenever it is necessary to refer to a type in an XPathexpression, theSequenceTypesyntax is used.
With the exception of the special typeempty-sequence()
, asequence type consists of anitemtype that constrains the type of each item in the sequence, andacardinality that constrains the number of items in thesequence. Apart from the item typeitem()
, whichpermits any kind of item, item types divide intonode types(such aselement()
) andatomic types (such asxs:integer
).
Item types representing element and attribute nodes may specifythe requiredtype annotations of those nodes, in theform of aschematype. Thus the item typeelement(*, us:address)
denotes any element node whose type annotation is (or is derivedfrom) the schema type namedus:address
.
Here are some examples ofsequence types that might be used in XPathexpressions:
xs:date
refers to the built-in atomic schema typenamedxs:date
attribute()?
refers to an optional attributenode
element()
refers to any element node
element(po:shipto, po:address)
refers to an elementnode that has the namepo:shipto
and has the typeannotationpo:address
(or a schema type derived frompo:address
)
element(*, po:address)
refers to an element node ofany name that has the type annotationpo:address
(or atype derived frompo:address
)
element(customer)
refers to an element node namedcustomer
with any type annotation
schema-element(customer)
refers to an element nodewhose name iscustomer
(or is in the substitutiongroup headed bycustomer
) and whose type annotationmatches the schema type declared for acustomer
element in thein-scope element declarations
node()*
refers to a sequence of zero or more nodesof any kind
item()+
refers to a sequence of one or more nodesor atomic values
[Definition: During evaluation of anexpression, it is sometimes necessary to determine whether a valuewith a knowndynamic type "matches" an expectedsequence type. Thisprocess is known asSequenceType matching.] For example, aninstance of
expression returnstrue
ifthedynamictype of a given value matches a givensequence type, orfalse
if it does not.
QNames appearing in asequence type have their prefixes expandedto namespace URIs by means of thestatically known namespaces and (whereapplicable) thedefault element/type namespace. Anunprefixed attribute QName is in no namespace. Equality of QNamesis defined by theeq
operator.
The rules forSequenceType matching compare thedynamic type ofa value with an expectedsequence type. These rules are a subset ofthe formal rules that match a value with an expected type definedin[XQuery 1.0 and XPath 2.0Formal Semantics (Second Edition)], because the FormalSemantics must be able to match values against types that are notexpressible using theSequenceType syntax.
Some of the rules forSequenceType matching requiredetermining whether a given schema type is the same as or derivedfrom an expected schema type. The given schema type may be "known"(defined in thein-scope schema definitions), or "unknown" (notdefined in thein-scope schema definitions). An unknown schema typemight be encountered, for example, if a source document has beenvalidated using a schema that was not imported into thestatic context. Inthis case, an implementation is allowed (but is not required) toprovide animplementation-dependentmechanism for determining whether the unknown schema type isderived from the expected schema type. For example, animplementation might maintain a data dictionary containinginformation about type hierarchies.
[Definition: The use of a valuewhosedynamictype is derived from an expected type is known assubtypesubstitution.] Subtype substitution does not change the actualtype of a value. For example, if anxs:integer
valueis used where anxs:decimal
value is expected, thevalue retains its type asxs:integer
.
The definition ofSequenceType matching relies on apseudo-function namedderives-from(
AT,ET)
, which takes an actual simple or complexschema typeAT and an expected simple or complex schematypeET, and either returns a boolean value or raises atype error[err:XPTY0004]. Thepseudo-functionderives-from
is defined below and isdefined formally in[XQuery 1.0and XPath 2.0 Formal Semantics (Second Edition)].
derives-from(
AT,ET)
returnstrue
ifET is a known type and any ofthe following three conditions is true:
AT is a schema type found in thein-scope schemadefinitions, and is the same asET or is derived byrestriction or extension fromET
AT is a schema type not found in thein-scope schemadefinitions, and animplementation-dependentmechanism is able to determine thatAT is derived byrestriction fromET
There exists some schema typeIT such thatderives-from(
IT, ET)
andderives-from(
AT, IT)
aretrue.
derives-from(
AT,ET)
returnsfalse
ifET is a known type andeither the first and third or the second and third of the followingconditions are true:
AT is a schema type found in thein-scope schemadefinitions, and is not the same asET, and is notderived by restriction or extension fromET
AT is a schema type not found in thein-scope schemadefinitions, and animplementation-dependentmechanism is able to determine thatAT is not derived byrestriction fromET
No schema typeIT exists such thatderives-from(
IT, ET)
andderives-from(
AT, IT)
aretrue.
derives-from(
AT,ET)
raises atype error[err:XPTY0004]if:
ET is an unknown type, or
AT is an unknown type, and the implementation is notable to determine whetherAT is derived by restrictionfromET.
The rules forSequenceType matching are givenbelow, with examples (the examples are for purposes ofillustration, and do not cover all possible cases).
Thesequencetypeempty-sequence()
matches a value that is theempty sequence.
AnItemType with noOccurrenceIndicator matchesany value that contains exactly one item if theItemType matches that item (see2.5.4.2 Matching an ItemType and anItem).
AnItemType with anOccurrenceIndicator matches avalue if the number of items in the value matches theOccurrenceIndicator and theItemType matches each of theitems in the value.
AnOccurrenceIndicator specifiesthe 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, anysequence type whoseOccurrenceIndicator is*
or?
matches a value that is an emptysequence.
AnItemType consisting simplyof a QName is interpreted as anAtomicType. An AtomicTypeAtomicType matches an atomic value whose actual type isAT ifderives-from(
AT,AtomicType)
istrue
. If a QName thatis used as anAtomicType is notdefined as an atomic type in thein-scope schema types, astatic error is raised[err:XPST0051].
Example: TheAtomicTypexs:decimal
matches the value12.34
(adecimal literal).xs:decimal
also matches a valuewhose type isshoesize
, ifshoesize
is anatomic type derived by restriction fromxs:decimal
.
Note:
The names of non-atomic types such asxs:IDREFS
arenot accepted in this context, but can often be replaced by anatomic type with an occurrence indicator, such asxs:IDREF+
.
item()
matches any single item.
Example:item()
matches the atomic value1
or the element<a/>
.
node()
matches any node.
text()
matches any text node.
processing-instruction()
matches anyprocessing-instruction node.
processing-instruction(
N)
matches any processing-instruction node whose PITarget is equal tofn:normalize-space(N)
. Iffn:normalize-space(N)
is not in the lexical space ofNCName, a type error is raised [err:XPTY0004]
Example:processing-instruction(xml-stylesheet)
matches any processing instruction whose PITarget isxml-stylesheet
.
For backward compatibility with XPath 1.0, the PITarget of aprocessing instruction may also be expressed as a string literal,as in this example:processing-instruction("xml-stylesheet")
.
comment()
matches any comment node.
document-node()
matches any document node.
document-node(
E)
matches anydocument node that contains exactly one element node, optionallyaccompanied by one or more comment and processing instructionnodes, ifE is anElementTest orSchemaElementTest that matchesthe element node (see2.5.4.3 ElementTest and2.5.4.4Schema Element Test).
Example:document-node(element(book))
matches adocument node containing exactly one element node that is matchedby the ElementTestelement(book)
.
AnItemType that is anElementTest,SchemaElementTest,AttributeTest, orSchemaAttributeTest matches anelement or attribute node as described in the followingsections.
AnElementTest is used tomatch an element node by its name and/ortype annotation. AnElementTest may take any of thefollowing forms. In these forms,ElementName need not be present in thein-scope element declarations, butTypeName must be present in thein-scope schematypes [err:XPST0008]. Note thatsubstitutiongroups do not affect the semantics ofElementTest.
element()
andelement(*)
match anysingle element node, regardless of its name or type annotation.
element(
ElementName)
matches anyelement node whose name isElementName, regardless of its typeannotation ornilled
property.
Example:element(person)
matches any element nodewhose name isperson
.
element(
ElementName,
TypeName)
matches an elementnode whose name isElementNameifderives-from(
AT,TypeName)
istrue
, whereAT is the type annotation of theelement node, and thenilled
property of the node isfalse
.
Example:element(person, surgeon)
matches anon-nilled element node whose name isperson
and whosetype annotation issurgeon
(or is derived fromsurgeon
).
element(
ElementName,TypeName?)
matches anelement node whose name isElementName ifderives-from(
AT,TypeName)
istrue
, whereAT is the type annotation of theelement node. Thenilled
property of the node may beeithertrue
orfalse
.
Example:element(person, surgeon?)
matches a nilledor non-nilled element node whose name isperson
andwhose type annotation issurgeon
(or is derived fromsurgeon
).
element(*,
TypeName)
matches an elementnode regardless of its name, ifderives-from(
AT,TypeName)
istrue
, whereAT is the type annotation of theelement node, and thenilled
property of the node isfalse
.
Example:element(*, surgeon)
matches any non-nilledelement node whose type annotation issurgeon
(or isderived fromsurgeon
), regardless of its name.
element(*,
TypeName?)
matches anelement node regardless of its name, ifderives-from(
AT,TypeName)
istrue
, whereAT is the type annotation of theelement node. Thenilled
property of the node may beeithertrue
orfalse
.
Example:element(*, surgeon?)
matches any nilled ornon-nilled element node whose type annotation issurgeon
(or is derived fromsurgeon
),regardless of its name.
ASchemaElementTestmatches an element node against a corresponding element declarationfound in thein-scope element declarations. It takes thefollowing form:
schema-element(
ElementName)
If theElementNamespecified in theSchemaElementTest is not foundin thein-scope element declarations, astatic error is raised[err:XPST0008].
ASchemaElementTestmatches a candidate element node if all three of the followingconditions are satisfied:
The name of the candidate node matches the specifiedElementName or matches the name of anelement in asubstitution group headed by anelement namedElementName.
derives-from(
AT, ET)
istrue
, whereAT is the type annotation of thecandidate node andET is the schema type declared forelementElementName in thein-scope element declarations.
If the element declaration forElementName in thein-scopeelement declarations is notnillable
, then thenilled
property of the candidate node isfalse
.
Example: TheSchemaElementTestschema-element(customer)
matches a candidate elementnode ifcustomer
is a top-level element declaration inthein-scope element declarations, the name of thecandidate node iscustomer
or is in asubstitutiongroup headed bycustomer
, the type annotation ofthe candidate node is the same as or derived from the schema typedeclared for thecustomer
element, and either thecandidate node is notnilled
orcustomer
is declared to benillable
.
AnAttributeTest is usedto match an attribute node by its name and/ortype annotation.AnAttributeTest any takeany of the following forms. In these forms,AttributeName need not be present inthein-scope attribute declarations, butTypeName must be present in thein-scope schematypes [err:XPST0008].
attribute()
andattribute(*)
match anysingle attribute node, regardless of its name or typeannotation.
attribute(
AttributeName)
matchesany attribute node whose name isAttributeName, regardless of itstype annotation.
Example:attribute(price)
matches any attributenode whose name isprice
.
attribute(
AttributeName,TypeName)
matches anattribute node whose name isAttributeName ifderives-from(
AT,TypeName)
istrue
, whereAT is the type annotation of theattribute node.
Example:attribute(price, currency)
matches anattribute node whose name isprice
and whose typeannotation iscurrency
(or is derived fromcurrency
).
attribute(*,
TypeName)
matches anattribute node regardless of its name, ifderives-from(
AT,TypeName)
istrue
, whereAT is the type annotation of theattribute node.
Example:attribute(*, currency)
matches anyattribute node whose type annotation iscurrency
(oris derived fromcurrency
), regardless of its name.
ASchemaAttributeTest matches anattribute node against a corresponding attribute declaration foundin thein-scope attribute declarations. It takes thefollowing form:
schema-attribute(
AttributeName)
If theAttributeNamespecified in theSchemaAttributeTest is notfound in thein-scope attribute declarations, astatic error is raised[err:XPST0008].
ASchemaAttributeTest matches acandidate attribute node if both of the following conditions aresatisfied:
The name of the candidate node matches the specifiedAttributeName.
derives-from(
AT, ET)
istrue
, whereAT is the type annotation of thecandidate node andET is the schema type declared forattributeAttributeName inthein-scope attribute declarations.
Example: TheSchemaAttributeTestschema-attribute(color)
matches a candidate attributenode ifcolor
is a top-level attribute declaration inthein-scope attribute declarations, the name of thecandidate node iscolor
, and the type annotation ofthe candidate node is the same as or derived from the schema typedeclared for thecolor
attribute.
[77] | Comment | ::= | "(:" (CommentContents |Comment)* ":)" |
[82] | CommentContents | ::= | (Char+ - (Char* ('(:' |':)') Char*)) |
Comments may be used to provide informative annotation foranexpression. Comments are lexical constructs only, anddo not affectexpression processing.
Comments are strings, delimited by the symbols(:
and:)
. Comments may be nested.
A comment may be used anywhereignorable whitespace is allowed(seeA.2.4.1 DefaultWhitespace Handling).
The following is an example of a comment:
(: Houston, we have a problem :)
This section discusses each of the basic kinds of expression.Each kind of expression has a name such asPathExpr
,which is introduced on the left side of the grammar production thatdefines the expression. Since XPath is a composable language, eachkind of expression is defined in terms of other expressions whoseoperators have a higher precedence. In this way, the precedence ofoperators is represented explicitly in the grammar.
The order in which expressions are discussed in this documentdoes not reflect the order of operator precedence. In general, thisdocument introduces the simplest kinds of expressions first,followed by more complex expressions. For the complete grammar, seeAppendix [A XPath Grammar].
The highest-level symbolin the XPath grammar is XPath.
[1] | XPath | ::= | Expr |
[2] | Expr | ::= | ExprSingle (","ExprSingle)* |
[3] | ExprSingle | ::= | ForExpr |
The XPath operator that has lowest precedence is thecomma operator,which is used to combine two operands to form a sequence. As shownin the grammar, a general expression (Expr) can consist of multipleExprSingle operands, separated bycommas. The nameExprSingledenotes an expression that does not contain a top-levelcomma operator(despite its name, anExprSingle may evaluate to a sequencecontaining more than one item.)
The symbolExprSingle isused in various places in the grammar where an expression is notallowed to contain a top-level comma. For example, each of thearguments of a function call must be anExprSingle, because commas are used toseparate the arguments of a function call.
After the comma, the expressions that have next lowestprecedence areForExpr,QuantifiedExpr,IfExpr, andOrExpr. Each of these expressions isdescribed in a separate section of this document.
[Definition:Primaryexpressions are the basic primitives of the language. Theyinclude literals, variable references, context item expressions,and function calls. A primary expression may also be created byenclosing any expression in parentheses, which is sometimes helpfulin controlling the precedence of operators.]
[41] | PrimaryExpr | ::= | Literal |VarRef |ParenthesizedExpr |ContextItemExpr |FunctionCall |
[Definition: Aliteral is a direct syntacticrepresentation of an atomic value.] XPath supports two kinds ofliterals: numeric literals and string literals.
[42] | Literal | ::= | NumericLiteral |StringLiteral |
[43] | NumericLiteral | ::= | IntegerLiteral |DecimalLiteral |DoubleLiteral |
[71] | IntegerLiteral | ::= | Digits |
[72] | DecimalLiteral | ::= | ("."Digits) | (Digits "." [0-9]*) |
[73] | DoubleLiteral | ::= | (("."Digits) | (Digits ("." [0-9]*)?)) [eE] [+-]?Digits |
[74] | StringLiteral | ::= | ('"' (EscapeQuot |[^"])* '"') | ("'" (EscapeApos| [^'])* "'") |
[75] | EscapeQuot | ::= | '""' |
[76] | EscapeApos | ::= | "''" |
[81] | Digits | ::= | [0-9]+ |
The value of anumeric literal containing no".
" and noe
orE
characteris an atomic value of typexs:integer
. The value of anumeric literal containing ".
" but noe
orE
character is an atomic value of typexs:decimal
. The value of a numeric literal containingane
orE
character is an atomic value oftypexs:double
. The value of the numeric literal isdetermined by casting it to the appropriate type according to therules for casting fromxs:untypedAtomic
to a numerictype as specified inSection17.1.1 Casting from xs:string andxs:untypedAtomicFO.
The value of astring literal is an atomic value whosetype isxs:string
and whose value is the stringdenoted by the characters between the delimiting apostrophes orquotation marks. If the literal is delimited by apostrophes, twoadjacent apostrophes within the literal are interpreted as a singleapostrophe. Similarly, if the literal is delimited by quotationmarks, two adjacent quotation marks within the literal areinterpreted as one quotation mark.
Here are some examples of literal expressions:
"12.5"
denotes the string containing the characters'1', '2', '.', and '5'.
12
denotes thexs:integer
valuetwelve.
12.5
denotes thexs:decimal
valuetwelve and one half.
125E2
denotes thexs:double
valuetwelve thousand, five hundred.
"He said, ""I don't like it."""
denotes a stringcontaining two quotation marks and one apostrophe.
Note:
When XPath expressions are embedded in contexts where quotationmarks have special significance, such as inside XML attributes,additional escaping may be needed.
Thexs:boolean
valuestrue
andfalse
can be represented by calls to thebuilt-infunctionsfn:true()
andfn:false()
,respectively.
Values of other atomic types can be constructed by calling theconstructor function for the giventype. The constructor functions for XML Schema built-in types aredefined in[XQuery 1.0 and XPath2.0 Functions and Operators (Second Edition)]. In general, thename of a constructor function for a given type is the same as thename of the type (including its namespace). For example:
xs:integer("12")
returns the integer valuetwelve.
xs:date("2001-08-25")
returns an item whose type isxs:date
and whose value represents the date 25thAugust 2001.
xs:dayTimeDuration("PT5H")
returns an item whosetype isxs:dayTimeDuration
and whose value representsa duration of five hours.
Constructor functions can also be used to create special valuesthat have no literal representation, as in the followingexamples:
xs:float("NaN")
returns the special floating-pointvalue, "Not a Number."
xs:double("INF")
returns the specialdouble-precision value, "positive infinity."
It is also possible to construct values of various types byusing acast
expression. For example:
9 cast as hatsize
returns the atomic value9
whose type ishatsize
.
[44] | VarRef | ::= | "$"VarName |
[45] | VarName | ::= | QName |
[Definition: Avariablereference is a QName preceded by a $-sign.] Two variablereferences are equivalent if their local names are the same andtheir namespace prefixes are bound to the same namespace URI in thestatically known namespaces. Anunprefixed variable reference is in no namespace.
Every variable reference must match a name in thein-scopevariables, which include variables from the followingsources:
Thein-scope variables may be augmented byimplementation-definedvariables.
A variable may be bound by an XPath expression.The kinds of expressions that can bindvariables arefor
expressions (3.7 For Expressions) andquantified expressions (3.9Quantified Expressions).
Every variable binding has a static scope. The scope defineswhere references to the variable can validly occur. It is astatic error[err:XPST0008] toreference a variable that is not in scope. If a variable is boundin thestaticcontext for an expression, that variable is in scope for theentire expression.
If a variable reference matches two or more variable bindingsthat are in scope, then the reference is taken as referring to theinner binding, that is, the one whose scope is smaller. Atevaluation time, the value of a variable reference is the value ofthe expression to which the relevant variable is bound. The scopeof a variable binding is defined separately for each kind ofexpression that can bind variables.
[46] | ParenthesizedExpr | ::= | "("Expr? ")" |
Parentheses may be used to enforce a particular evaluation orderin expressions that contain multiple operators. For example, theexpression(2 + 4) * 5
evaluates to thirty, since theparenthesized expression(2 + 4)
is evaluated firstand its result is multiplied by five. Without parentheses, theexpression2 + 4 * 5
evaluates to twenty-two, becausethe multiplication operator has higher precedence than the additionoperator.
Empty parentheses are used to denote an empty sequence, asdescribed in3.3.1 ConstructingSequences.
[47] | ContextItemExpr | ::= | "." |
Acontext item expression evaluates to thecontext item, which maybe either a node (as in the expressionfn:doc("bib.xml")/books/book[fn:count(./author)>1]
)or an atomic value (as in the expression(1 to 100)[. mod 5eq 0]
).
If thecontextitem isundefined, a context item expression raises adynamic error [err:XPDY0002].
[Definition: Thebuilt-in functionssupported by XPath are defined in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].]Additional functions may be provided in thestatic context.XPath per se does not provide a way to declare functions, but ahost language may provide such a mechanism.
[48] | FunctionCall | ::= | QName "(" (ExprSingle (","ExprSingle)*)? ")" |
Afunction call consists of a QName followed by aparenthesized list of zero or more expressions, calledarguments. If the QName in the function call has nonamespace prefix, it is considered to be in thedefault functionnamespace.
If theexpanded QName and number of arguments ina function call do not match the name and arity of afunctionsignature in thestatic context, astatic error is raised [err:XPST0017].
A function call is evaluated as follows:
Argument expressions are evaluated, producing argument values.The order of argument evaluation isimplementation-dependent and afunction need not evaluate an argument if the function can evaluateits body without evaluating that argument.
Each argument value is converted by applying the functionconversion rules listed below.
The function is evaluated using the converted argument values.The result is either an instance of the function's declared returntype or a dynamic error. Thedynamic type of a function result may be atype that is derived from the declared return type. Errors raisedby functions are defined in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
Thefunction conversion rules are used to convert anargument value to its expected type; that is, to the declared typeof the functionparameter. The expected type is expressed asasequencetype. The function conversion rules are applied to a givenvalue as follows:
IfXPath 1.0 compatibility mode istrue
and an argument is not of the expected type, thenthe following conversions are applied sequentially to the argumentvalue V:
If the expected type calls for a single item or optional singleitem (examples:xs:string
,xs:string?
,xs:untypedAtomic
,xs:untypedAtomic?
,node()
,node()?
,item()
,item()?
), then the value V is effectively replaced byV[1].
If the expected type isxs:string
orxs:string?
, then the valueV
iseffectively replaced byfn:string(V)
.
If the expected type isxs:double
orxs:double?
, then the valueV
iseffectively replaced byfn:number(V)
.
If the expected type is a sequence of an atomic type (possiblywith an occurrence indicator*
,+
, or?
), the following conversions are applied:
Atomization isapplied to the given value, resulting in a sequence of atomicvalues.
Each item in the atomic sequence that is of typexs:untypedAtomic
is cast to the expected atomic type.Forbuilt-in functions where the expectedtype is specified asnumeric, arguments of typexs:untypedAtomic
are cast toxs:double
.
For eachnumeric itemin the atomic sequence that can bepromoted to the expected atomic type usingnumeric promotion as described inB.1 TypePromotion, the promotion is done.
For each item of typexs:anyURI
in the atomicsequence that can bepromoted to the expected atomic type usingURI promotion as described inB.1 TypePromotion, the promotion is done.
If, after the above conversions, the resulting value does notmatch the expected type according to the rules forSequenceType Matching, atype error is raised[err:XPTY0004].Note that the rules forSequenceType Matching permit avalue of a derived type to be substituted for a value of its basetype.
Since the arguments of a function call are separated by commas,any argument expression that contains a top-levelcomma operator mustbe enclosed in parentheses. Here are some illustrative examples offunction calls:
my:three-argument-function(1, 2, 3)
denotes afunction call with three arguments.
my:two-argument-function((1, 2), 3)
denotes afunction call with two arguments, the first of which is a sequenceof two values.
my:two-argument-function(1, ())
denotes a functioncall with two arguments, the second of which is an emptysequence.
my:one-argument-function((1, 2, 3))
denotes afunction call with one argument that is a sequence of threevalues.
my:one-argument-function(( ))
denotes a functioncall with one argument that is an empty sequence.
my:zero-argument-function( )
denotes a functioncall with zero arguments.
[25] | PathExpr | ::= | ("/"RelativePathExpr?) |
[26] | RelativePathExpr | ::= | StepExpr (("/" | "//")StepExpr)* |
[Definition: Apath expression can beused to locate nodes within trees. A path expression consists of aseries of one or moresteps,separated by "/
" or "//
", and optionallybeginning with "/
" or "//
".] An initial"/
" or "//
" is an abbreviation for one ormore initial steps that are implicitly added to the beginning ofthe path expression, as described below.
A path expression consisting of a single step is evaluated asdescribed in3.2.1 Steps.
A "/
" at the beginning of a path expression is anabbreviation for the initial step(fn:root(self::node()) treat asdocument-node())/
(however, if the "/
"is the entire path expression, the trailing "/
" isomitted from the expansion.) The effect of this initial step is tobegin the path at the root node of the tree that contains thecontext node. If the context item is not a node, atype error is raised[err:XPTY0020]. Atevaluation time, if the root node above the context node is not adocument node, adynamic error is raised [err:XPDY0050].
A "//
" at the beginning of a path expression is anabbreviation for the initial steps(fn:root(self::node()) treat asdocument-node())/descendant-or-self::node()/
(however, "//
" by itself is not a valid pathexpression [err:XPST0003].) The effect of these initialsteps is to establish an initial node sequence that contains theroot of the tree in which the context node is found, plus all nodesdescended from this root. This node sequence is used as the inputto subsequent steps in the path expression. If the context item isnot a node, atypeerror is raised [err:XPTY0020]. At evaluation time, if the rootnode above the context node is not a document node, adynamic error israised [err:XPDY0050].
Note:
The descendants of a node do not include attribute nodesor namespacenodes.
Each non-initial occurrence of "//
" in a pathexpression is expanded as described in3.2.4Abbreviated Syntax, leaving a sequence of steps separatedby "/
". This sequence of steps is then evaluated fromleft to right. Each operationE1/E2
is evaluated asfollows: ExpressionE1
is evaluated, and if the resultis not a (possibly empty) sequence of nodes, atype error is raised[err:XPTY0019].Each node resulting from the evaluation ofE1
thenserves in turn to provide aninner focus for an evaluationofE2
, as described in2.1.2 Dynamic Context. The sequencesresulting from all the evaluations ofE2
are combinedas follows:
If every evaluation ofE2
returns a (possiblyempty) sequence of nodes, these sequences are combined, andduplicate nodes are eliminated based on node identity.The resulting node sequence is returnedindocumentorder.
If every evaluation ofE2
returns a (possiblyempty) sequence of atomic values, these sequences areconcatenated, inorder, and returned.
If the multiple evaluations ofE2
return at leastone node and at least one atomic value, atype error is raised [err:XPTY0018].
Note:
Since each step in a path provides context nodes for thefollowing step, in effect, only the last step in a path is allowedto return a sequence of atomic values.
As an example of a path expression,child::div1/child::para
selects thepara
element children of thediv1
element children of thecontext node, or, in other words, thepara
elementgrandchildren of the context node that havediv1
parents.
Note:
The "/
" character can be usedeither as a complete path expression or as the beginning of alonger path expression such as "/*
". Also,"*
" is both the multiply operator and a wildcard inpath expressions. This can cause parsing difficulties when"/
" appears on the left hand side of "*
".This is resolved using theleading-lone-slash constraint.For example, "/*
" and "/ *
" are validpath expressions containing wildcards, but "/*5
" and"/ * 5
" raise syntax errors. Parentheses must be usedwhen "/
" is used on the left hand side of an operator,as in "(/) * 5
". Similarly, "4 + / * 5
"raises a syntax error, but "4 + (/) * 5
" is a validexpression. The expression "4 + /
" is also valid,because/
does not occur on the left hand side of theoperator.
[27] | StepExpr | ::= | FilterExpr |AxisStep |
[28] | AxisStep | ::= | (ReverseStep |ForwardStep)PredicateList |
[29] | ForwardStep | ::= | (ForwardAxisNodeTest) |AbbrevForwardStep |
[32] | ReverseStep | ::= | (ReverseAxisNodeTest) |AbbrevReverseStep |
[39] | PredicateList | ::= | Predicate* |
[Definition: Astep is a part of apath expression that generates a sequenceof items and then filters the sequence by zero or morepredicates. The value of thestep consists of those items that satisfy the predicates, workingfrom left to right. A step may be either anaxis step or afilterexpression.] Filter expressions are described in3.3.2 Filter Expressions.
[Definition: Anaxis step returns a sequenceof nodes that are reachable from the context node via a specifiedaxis. Such a step has two parts: anaxis, which defines the"direction of movement" for the step, and anode test, which selects nodes based ontheir kind, name, and/ortype annotation.] If the context item isa node, an axis step returns a sequence of zero or more nodes;otherwise, atypeerror is raised [err:XPTY0020].The resulting node sequence is returned indocumentorder. An axis step may be either aforwardstep or areverse step, followed by zero or morepredicates.
In theabbreviated syntax for a step, the axis can beomitted and other shorthand notations can be used as described in3.2.4 Abbreviated Syntax.
The unabbreviated syntax for an axis step consists of the axisname and node test separated by a double colon. The result of thestep consists of the nodes reachable from the context node via thespecified axis that have the node kind, name, and/ortype annotationspecified by the node test. For example, the stepchild::para
selects thepara
elementchildren of the context node:child
is the name of theaxis, andpara
is the name of the element nodes to beselected on this axis. The available axes are described in3.2.1.1 Axes. The available node tests aredescribed in3.2.1.2 Node Tests.Examples of steps are provided in3.2.3Unabbreviated Syntax and3.2.4Abbreviated Syntax.
[30] | ForwardAxis | ::= | ("child" "::") |
[33] | ReverseAxis | ::= | ("parent" "::") |
XPath defines a full set ofaxes fortraversing documents, but ahost language may define asubset of these axes. The following axes are defined:
Thechild
axis contains the children of the contextnode, which are the nodes returned by thedm:children
accessor in[XQuery 1.0 and XPath 2.0 DataModel (Second Edition)].
Note:
Only document nodes and element nodes have children. If thecontext node is any other kind of node, or if the context node isan empty document or element node, then the child axis is an emptysequence. The children of a document node or element node may beelement, processing instruction, comment, or text nodes.Attribute,namespace, and document nodes can never appear aschildren.
thedescendant
axis is defined as the transitiveclosure of the child axis; it contains the descendants of thecontext node (the children, the children of the children, and soon)
theparent
axis contains the sequence returned bythedm:parent
accessor in[XQuery1.0 and XPath 2.0 Data Model (Second Edition)], which returnsthe parent of the context node, or an empty sequence if the contextnode has no parent
Note:
An attribute node may have an element node as its parent, eventhough the attribute node is not a child of the element node.
theancestor
axis is defined as the transitiveclosure of the parent axis; it contains the ancestors of thecontext node (the parent, the parent of the parent, and so on)
Note:
The ancestor axis includes the root node of the tree in whichthe context node is found, unless the context node is the rootnode.
thefollowing-sibling
axis contains the contextnode's following siblings, those children of the context node'sparent that occur after the context node indocument order; ifthe context node is an attributeor namespace node, thefollowing-sibling
axis is empty
thepreceding-sibling
axis contains the contextnode's preceding siblings, those children of the context node'sparent that occur before the context node indocument order; ifthe context node is an attributeor namespace node, thepreceding-sibling
axis is empty
thefollowing
axis contains all nodes that aredescendants of the root of the tree in which the context node isfound, are not descendants of the context node, and occur after thecontext node indocument order
thepreceding
axis contains all nodes that aredescendants of the root of the tree in which the context node isfound, are not ancestors of the context node, and occur before thecontext node indocument order
theattribute
axis contains the attributes of thecontext node, which are the nodes returned by thedm:attributes
accessor in[XQuery1.0 and XPath 2.0 Data Model (Second Edition)]; the axis willbe empty unless the context node is an element
theself
axis contains just the context nodeitself
thedescendant-or-self
axis contains the contextnode and the descendants of the context node
theancestor-or-self
axis contains the context nodeand the ancestors of the context node; thus, the ancestor-or-selfaxis will always include the root node
thenamespace
axis contains the namespace nodes ofthe context node, which are the nodes returned by thedm:namespace-nodes
accessor in[XQuery 1.0 and XPath 2.0 Data Model (SecondEdition)]; this axis is empty unless the context node is anelement node. Thenamespace
axis is deprecated inXPath 2.0. IfXPath 1.0 compatibility mode istrue
, thenamespace
axis must besupported. IfXPath 1.0 compatibility mode isfalse
, then support for thenamespace
axis isimplementation-defined. Animplementation that does not support thenamespace
axis whenXPath 1.0 compatibility mode isfalse
must raise astatic error [err:XPST0010] if it is used. Applicationsneeding information about thein-scope namespaces of an elementshould use the functionsfn:in-scope-prefixes
andfn:namespace-uri-for-prefix
defined in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
Axes can be categorized asforward axes andreverseaxes. An axis that only ever contains the context node or nodesthat are after the context node indocument order is a forward axis. An axisthat only ever contains the context node or nodes that are beforethe context node indocument order is a reverse axis.
Theparent
,ancestor
,ancestor-or-self
,preceding
, andpreceding-sibling
axes are reverse axes; all otheraxes are forward axes. Theancestor
,descendant
,following
,preceding
andself
axes partition adocument (ignoring attributeand namespace nodes): they do not overlap andtogether they contain all the nodes in the document.
[Definition: Every axis has aprincipal node kind. If an axis can contain elements, thenthe principal node kind is element; otherwise, it is the kind ofnodes that the axis can contain.] Thus:
For the attribute axis, the principal node kind isattribute.
For the namespace axis, the principal node kind isnamespace.
For all other axes, the principal node kind is element.
[Definition: Anode test is a condition thatmust be true for each node selected by astep.] The condition may be based on the kind of thenode (element, attribute, text, document, comment, or processinginstruction), the name of the node, or (in the case of element,attribute, and document nodes), thetype annotation of the node.
[35] | NodeTest | ::= | KindTest |NameTest |
[36] | NameTest | ::= | QName |Wildcard |
[37] | Wildcard | ::= | "*" |
[Definition: A node test that consists only of aQName or a Wildcard is called aname test.] A name test istrue if and only if thekind of the node is theprincipal nodekind for the step axis and theexpanded QName of the node is equal (asdefined by theeq
operator) to theexpanded QNamespecified by the name test. For example,child::para
selects thepara
element children of the context node;if the context node has nopara
children, it selectsan empty set of nodes.attribute::abc:href
selects theattribute of the context node with the QNameabc:href
;if the context node has no such attribute, it selects an empty setof nodes.
A QName in a name test is resolved into anexpanded QName usingthestatically known namespaces in theexpression context. It is astatic error [err:XPST0081] if the QName has a prefix thatdoes not correspond to any statically known namespace. Anunprefixed QName, when used as a name test on an axis whoseprincipal node kind is element, hasthe namespace URI of thedefault element/type namespace inthe expression context; otherwise, it has no namespace URI.
A name test is not satisfied by an element node whose name doesnot match theexpanded QName of the name test, even ifit is in asubstitution group whose head is thenamed element.
A node test*
is true for any node of theprincipal nodekind of the step axis. For example,child::*
willselect all element children of the context node, andattribute::*
will select all attributes of the contextnode.
A node test can have the formNCName:*
. In thiscase, the prefix is expanded in the same way as with a QName, usingthestatically known namespaces in thestaticcontext. If the prefix is not found in the statically knownnamespaces, astatic error is raised [err:XPST0081]. The nodetest is true for any node of theprincipal node kind of the stepaxis whoseexpanded QName has the namespace URI towhich the prefix is bound, regardless of the local part of thename.
A node test can also have the form*:NCName
. Inthis case, the node test is true for any node of theprincipal nodekind of the step axis whose local name matches the givenNCName, regardless of its namespace or lack of a namespace.
[Definition: An alternative form of a node testcalled akind test can select nodes based on their kind,name, andtype annotation.] The syntax andsemantics of a kind test are described in2.5.3 SequenceType Syntax and2.5.4 SequenceTypeMatching. When a kind test is used in anode test, only those nodes onthe designated axis that match the kind test are selected. Shownbelow are several examples of kind tests that might be used in pathexpressions:
node()
matches any node.
text()
matches any text node.
comment()
matches any comment node.
element()
matches any element node.
schema-element(person)
matches any element nodewhose name isperson
(or is in thesubstitutiongroup headed byperson
), and whose type annotationis the same as (or is derived from) the declared type of theperson
element in thein-scopeelement declarations.
element(person)
matches any element node whose nameisperson
, regardless of its type annotation.
element(person, surgeon)
matches any non-nilledelement node whose name isperson
, and whose typeannotation issurgeon
or is derived fromsurgeon
.
element(*, surgeon)
matches any non-nilled elementnode whose type annotation issurgeon
(or is derivedfromsurgeon
), regardless of its name.
attribute()
matches any attribute node.
attribute(price)
matches any attribute whose nameisprice
, regardless of its type annotation.
attribute(*, xs:decimal)
matches any attributewhose type annotation isxs:decimal
(or is derivedfromxs:decimal
), regardless of its name.
document-node()
matches any document node.
document-node(element(book))
matches any documentnode whose content consists of a single element node that satisfiesthekind testelement(book)
, interleaved with zero or more commentsand processing instructions.
[40] | Predicate | ::= | "["Expr "]" |
[Definition: Apredicate consists of anexpression, called apredicate expression, enclosed insquare brackets. A predicate serves to filter a sequence, retainingsome items and discarding others.] In the case of multiple adjacentpredicates, the predicates are applied from left to right, and theresult of applying each predicate serves as the input sequence forthe following predicate.
For each item in the input sequence, the predicate expression isevaluated using aninner focus, defined as follows: Thecontext item is the item currently being tested against thepredicate. The context size is the number of items in the inputsequence. The context position is the position of the context itemwithin the input sequence. For the purpose of evaluating thecontext position within a predicate, the input sequence isconsidered to be sorted as follows: into document order if thepredicate is in a forward-axis step, into reverse document order ifthe predicate is in a reverse-axis step, or in its original orderif the predicate is not in a step.
For each item in the input sequence, the result of the predicateexpression is coerced to anxs:boolean
value, calledthepredicate truth value, as described below. Those itemsfor which the predicate truth value istrue
areretained, and those for which the predicate truth value isfalse
are discarded.
The predicate truth value is derived by applying the followingrules, in order:
If the value of the predicate expression is asingleton atomic value of anumeric type or derivedfrom anumeric type, thepredicate truth value istrue
if the value of thepredicate expression is equal (by theeq
operator) tothecontext position, and isfalse
otherwise.[Definition: A predicate whose predicateexpression returns a numeric type is called anumericpredicate.]
Otherwise, the predicate truth value is theeffective booleanvalue of the predicate expression.
Here are some examples ofaxis steps that contain predicates:
This example selects the secondchapter
elementthat is a child of the context node:
child::chapter[2]
This example selects all the descendants of the context nodethat are elements named"toy"
and whosecolor
attribute has the value"red"
:
descendant::toy[attribute::color = "red"]
This example selects all theemployee
children ofthe context node that have both asecretary
childelement and anassistant
child element:
child::employee[secretary][assistant]
Note:
When usingpredicates with a sequence of nodes selectedusing areverse axis, it is important to remember that thethe context positions for such a sequence are assigned inreversedocument order. For example,preceding::foo[1]
returns the first qualifyingfoo
element inreversedocument order, because the predicate is part of anaxis step using a reverseaxis. By contrast,(preceding::foo)[1]
returns thefirst qualifyingfoo
element indocument order,because the parentheses cause(preceding::foo)
to beparsed as aprimary expression in which contextpositions are assigned in document order. Similarly,ancestor::*[1]
returns the nearest ancestor element,because theancestor
axis is a reverse axis, whereas(ancestor::*)[1]
returns the root element (firstancestor in document order).
The fact that a reverse-axis step assigns context positions inreverse document order for the purpose of evaluating predicatesdoes not alter the fact that the final result of the step is alwaysin document order.
This section provides a number of examples of path expressionsin which the axis is explicitly specified in eachstep. The syntax used in these examples iscalled theunabbreviated syntax. In many common cases, it ispossible to write path expressions more concisely using anabbreviated syntax, as explained in3.2.4 Abbreviated Syntax.
child::para
selects thepara
elementchildren of the context node
child::*
selects all element children of thecontext node
child::text()
selects all text node children of thecontext node
child::node()
selects all the children of thecontext node. Note that no attribute nodes are returned, becauseattributes are not children.
attribute::name
selects thename
attribute of the context node
attribute::*
selects all the attributes of thecontext node
parent::node()
selects the parent of the contextnode. If the context node is an attribute node, this expressionreturns the element node (if any) to which the attribute node isattached.
descendant::para
selects thepara
element descendants of the context node
ancestor::div
selects alldiv
ancestors of the context node
ancestor-or-self::div
selects thediv
ancestors of the context node and, if the context node is adiv
element, the context node as well
descendant-or-self::para
selects thepara
element descendants of the context node and, ifthe context node is apara
element, the context nodeas well
self::para
selects the context node if it is apara
element, and otherwise returns an emptysequence
child::chapter/descendant::para
selects thepara
element descendants of thechapter
element children of the context node
child::*/child::para
selects allpara
grandchildren of the context node
/
selects the root of the tree that contains thecontext node, but raises a dynamic error if this root is not adocument node
/descendant::para
selects all thepara
elements in the same document as the context node
/descendant::list/child::member
selects all themember
elements that have alist
parentand that are in the same document as the context node
child::para[fn:position() = 1]
selects the firstpara
child of the context node
child::para[fn:position() = fn:last()]
selects thelastpara
child of the context node
child::para[fn:position() = fn:last()-1]
selectsthe last but onepara
child of the context node
child::para[fn:position() > 1]
selects all thepara
children of the context node other than the firstpara
child of the context node
following-sibling::chapter[fn:position() =1]
selects the nextchapter
sibling of thecontext node
preceding-sibling::chapter[fn:position() =1]
selects the previouschapter
sibling of thecontext node
/descendant::figure[fn:position() = 42]
selects theforty-secondfigure
element in the document containingthe context node
/child::book/child::chapter[fn:position() =5]/child::section[fn:position() = 2]
selects the secondsection
of the fifthchapter
of thebook
whose parent is the document node that containsthe context node
child::para[attribute::type eq "warning"]
selectsallpara
children of the context node that have atype
attribute with valuewarning
child::para[attribute::type eq 'warning'][fn:position() =5]
selects the fifthpara
child of the contextnode that has atype
attribute with valuewarning
child::para[fn:position() = 5][attribute::type eq"warning"]
selects the fifthpara
child of thecontext node if that child has atype
attribute withvaluewarning
child::chapter[child::title ='Introduction']
selects thechapter
children ofthe context node that have one or moretitle
childrenwhosetyped valueis equal to the stringIntroduction
child::chapter[child::title]
selects thechapter
children of the context node that have one ormoretitle
children
child::*[self::chapter or self::appendix]
selectsthechapter
andappendix
children of thecontext node
child::*[self::chapter or self::appendix][fn:position() =fn:last()]
selects the lastchapter
orappendix
child of the context node
[31] | AbbrevForwardStep | ::= | "@"?NodeTest |
[34] | AbbrevReverseStep | ::= | ".." |
The abbreviated syntax permits the following abbreviations:
The attribute axisattribute::
can be abbreviatedby@
. For example, a path expressionpara[@type="warning"]
is short forchild::para[attribute::type="warning"]
and so selectspara
children with atype
attribute withvalue equal towarning
.
If the axis name is omitted from anaxis step, the default axis ischild
unless the axis step contains anAttributeTest orSchemaAttributeTest; in thatcase, the default axis isattribute
. For example, thepath expressionsection/para
is an abbreviation forchild::section/child::para
, and the path expressionsection/@id
is an abbreviation forchild::section/attribute::id
. Similarly,section/attribute(id)
is an abbreviation forchild::section/attribute::attribute(id)
. Note that thelatter expression contains both an axis specification and anode test.
Each non-initial occurrence of//
is effectivelyreplaced by/descendant-or-self::node()/
duringprocessing of a path expression. For example,div1//para
is short forchild::div1/descendant-or-self::node()/child::para
andso will select allpara
descendants ofdiv1
children.
Note:
The path expression//para[1]
doesnotmean the same as the path expression/descendant::para[1]
. The latter selects the firstdescendantpara
element; the former selects alldescendantpara
elements that are the firstpara
children of their respective parents.
A step consisting of..
is short forparent::node()
. For example,../title
isshort forparent::node()/child::title
and so willselect thetitle
children of the parent of the contextnode.
Note:
The expression.
, known as acontext itemexpression, is aprimary expression, and is describedin3.1.4 Context ItemExpression.
Here are some examples of path expressions that use theabbreviated syntax:
para
selects thepara
element childrenof the context node
*
selects all element children of the contextnode
text()
selects all text node children of thecontext node
@name
selects thename
attribute ofthe context node
@*
selects all the attributes of the contextnode
para[1]
selects the firstpara
childof the context node
para[fn:last()]
selects the lastpara
child of the context node
*/para
selects allpara
grandchildrenof the context node
/book/chapter[5]/section[2]
selects the secondsection
of the fifthchapter
of thebook
whose parent is the document node that containsthe context node
chapter//para
selects thepara
elementdescendants of thechapter
element children of thecontext node
//para
selects all thepara
descendants of the root document node and thus selects allpara
elements in the same document as the contextnode
//@version
selects all theversion
attribute nodes that are in the same document as the contextnode
//list/member
selects all themember
elements in the same document as the context node that have alist
parent
.//para
selects thepara
elementdescendants of the context node
..
selects the parent of the context node
../@lang
selects thelang
attribute ofthe parent of the context node
para[@type="warning"]
selects allpara
children of the context node that have atype
attribute with valuewarning
para[@type="warning"][5]
selects the fifthpara
child of the context node that has atype
attribute with valuewarning
para[5][@type="warning"]
selects the fifthpara
child of the context node if that child has atype
attribute with valuewarning
chapter[title="Introduction"]
selects thechapter
children of the context node that have one ormoretitle
children whosetyped value is equal to the stringIntroduction
chapter[title]
selects thechapter
children of the context node that have one or moretitle
children
employee[@secretary and @assistant]
selects all theemployee
children of the context node that have both asecretary
attribute and anassistant
attribute
book/(chapter|appendix)/section
selects everysection
element that has a parent that is either achapter
or anappendix
element, that inturn is a child of abook
element that is a child ofthe context node.
IfE
is any expression that returns a sequence ofnodes, then the expressionE/.
returns the same nodesindocumentorder, with duplicates eliminated based on node identity.
XPath supports operators to construct, filter, and combinesequences ofitems. Sequences are never nested—forexample, combining the values1
,(2, 3)
,and( )
into a single sequence results in the sequence(1, 2, 3)
.
[2] | Expr | ::= | ExprSingle (","ExprSingle)* |
[11] | RangeExpr | ::= | AdditiveExpr ( "to"AdditiveExpr )? |
[Definition: One way to construct a sequence isby using thecomma operator, which evaluates each of itsoperands and concatenates the resulting sequences, in order, into asingle result sequence.] Empty parentheses can be used to denote anempty sequence.
A sequence may contain duplicate atomic values or nodes, but asequence is never an item in another sequence. When a new sequenceis created by concatenating two or more input sequences, the newsequence contains all the items of the input sequences and itslength is the sum of the lengths of the input sequences.
Note:
In places where the grammar calls forExprSingle, such as the arguments of afunction call, any expression that contains a top-level commaoperator must be enclosed in parentheses.
Here are some examples of expressions that constructsequences:
The result of this expression is a sequence of fiveintegers:
(10, 1, 2, 3, 4)
This expression combines four sequences of length one, two,zero, and two, respectively, into a single sequence of length five.The result of this expression is the sequence10, 1, 2, 3,4
.
(10, (1, 2), (), (3, 4))
The result of this expression is a sequence containing allsalary
children of the context node followed by allbonus
children.
(salary, bonus)
Assuming that$price
is bound to the value10.50
, the result of this expression is the sequence10.50, 10.50
.
($price, $price)
Arange expression can be used to construct a sequence ofconsecutive integers. Each of the operands of theto
operator is converted as though it was an argument of a functionwith the expected parameter typexs:integer?
. Ifeither operand is an empty sequence, or if the integer derived fromthe first operand is greater than the integer derived from thesecond operand, the result of the range expression is an emptysequence. If the two operands convert to the same integer, theresult of the range expression is that integer. Otherwise, theresult is a sequence containing the two integer operands and everyinteger between the two operands, in increasing order.
This example uses a range expression as one operand inconstructing a sequence. It evaluates to the sequence10, 1,2, 3, 4
.
(10, 1 to 4)
This example constructs a sequence of length one containing thesingle integer10
.
10 to 10
The result of this example is a sequence of length zero.
15 to 10
This example uses thefn:reverse
function toconstruct a sequence of six integers in decreasing order. Itevaluates to the sequence15, 14, 13, 12, 11, 10
.
fn:reverse(10 to 15)
[38] | FilterExpr | ::= | PrimaryExprPredicateList |
[39] | PredicateList | ::= | Predicate* |
[Definition: Afilter expressionconsists simply of aprimary expression followed by zero ormorepredicates. Theresult of the filter expression consists of the items returned bythe primary expression, filtered by applying each predicate inturn, working from left to right.] If no predicates are specified,the result is simply the result of the primary expression. Theordering of the items returned by a filter expression is the sameas their order in the result of the primary expression. Contextpositions are assigned to items based on their ordinal position inthe result sequence. The first context position is 1.
Here are some examples of filter expressions:
Given a sequence of products in a variable, return only thoseproducts whose price is greater than 100.
$products[price gt 100]
List all the integers from 1 to 100 that are divisible by 5.(See3.3.1 ConstructingSequences for an explanation of theto
operator.)
(1 to 100)[. mod 5 eq 0]
The result of the following expression is the integer 25:
(21 to 29)[5]
The following example returns the fifth through ninth items inthe sequence bound to variable$orders
.
$orders[fn:position() = (5 to 9)]
The following example illustrates the use of a filter expressionas astep in apath expression.It returns the last chapter or appendix within the book bound tovariable$book
:
$book/(chapter | appendix)[fn:last()]
The following example also illustrates the use of a filterexpression as astep in apathexpression. It returns the element node within the specifieddocument whose ID value istiger
:
fn:doc("zoo.xml")/fn:id('tiger')
[14] | UnionExpr | ::= | IntersectExceptExpr ( ("union"| "|")IntersectExceptExpr)* |
[15] | IntersectExceptExpr | ::= | InstanceofExpr (("intersect" | "except")InstanceofExpr )* |
XPath provides the following operators for combining sequencesof nodes:
Theunion
and|
operators areequivalent. They take two node sequences as operands and return asequence containing all the nodes that occur in either of theoperands.
Theintersect
operator takes two node sequences asoperands and returns a sequence containing all the nodes that occurin both operands.
Theexcept
operator takes two node sequences asoperands and returns a sequence containing all the nodes that occurin the first operand but not in the second operand.
All these operators eliminate duplicate nodes from their resultsequences based on node identity.The resulting sequence is returned indocumentorder.
If an operand ofunion
,intersect
, orexcept
contains an item that is not a node, atype error israised [err:XPTY0004].
Here are some examples of expressions that combine sequences.Assume the existence of three element nodes that we will refer toby symbolic names A, B, and C. Assume that the variables$seq1
,$seq2
and$seq3
arebound to the following sequences of these nodes:
$seq1
is bound to (A, B)
$seq2
is bound to (A, B)
$seq3
is bound to (B, C)
Then:
$seq1 union $seq2
evaluates to the sequence (A,B).
$seq2 union $seq3
evaluates to the sequence (A, B,C).
$seq1 intersect $seq2
evaluates to the sequence (A,B).
$seq2 intersect $seq3
evaluates to the sequencecontaining B only.
$seq1 except $seq2
evaluates to the emptysequence.
$seq2 except $seq3
evaluates to the sequencecontaining A only.
In addition to the sequence operators described here,[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)] includes functions for indexedaccess to items or sub-sequences of a sequence, for indexedinsertion or removal of items in a sequence, and for removingduplicate items from a sequence.
XPath provides arithmetic operators for addition, subtraction,multiplication, division, and modulus, in their usual binary andunary forms.
[12] | AdditiveExpr | ::= | MultiplicativeExpr ( ("+" |"-")MultiplicativeExpr)* |
[13] | MultiplicativeExpr | ::= | UnionExpr ( ("*" |"div" | "idiv" | "mod")UnionExpr )* |
[20] | UnaryExpr | ::= | ("-" | "+")*ValueExpr |
[21] | ValueExpr | ::= | PathExpr |
A subtraction operator must be preceded by whitespace if itcould otherwise be interpreted as part of the previous token. Forexample,a-b
will be interpreted as a name, buta - b
anda -b
will be interpreted asarithmetic expressions. (SeeA.2.4Whitespace Rules for further details on whitespacehandling.)
The first step in evaluating an arithmetic expression is toevaluate its operands. The order in which the operands areevaluated isimplementation-dependent.
IfXPath 1.0 compatibility mode istrue
, each operand is evaluated by applying thefollowing steps, in order:
Atomization isapplied to the operand. The result of this operation is called theatomized operand.
If the atomized operand is an empty sequence, the result of thearithmetic expression is thexs:double
valueNaN
, and the implementation need not evaluate theother operand or apply the operator. However, an implementation maychoose to evaluate the other operand in order to determine whetherit raises an error.
If the atomized operand is a sequence of length greater thanone, any items after the first item in the sequence arediscarded.
If the atomized operand is now an instance of typexs:boolean
,xs:string
,xs:decimal
(includingxs:integer
),xs:float
, orxs:untypedAtomic
, then it isconverted to the typexs:double
by applying thefn:number
function. (Note thatfn:number
returns the valueNaN
if its operand cannot beconverted to a number.)
IfXPath1.0 compatibility mode isfalse
,each operand is evaluated by applying the followingsteps, in order:
Atomization isapplied to the operand. The result of this operation is called theatomized operand.
If the atomized operand is an empty sequence, the result of thearithmetic expression is an empty sequence, and the implementationneed not evaluate the other operand or apply the operator. However,an implementation may choose to evaluate the other operand in orderto determine whether it raises an error.
If the atomized operand is a sequence of length greater thanone, atype erroris raised [err:XPTY0004].
If the atomized operand is of typexs:untypedAtomic
, it is cast toxs:double
. If the cast fails, adynamic error israised. [err:FORG0001]
After evaluation of the operands, if the types of the operandsare a valid combination for the given arithmetic operator, theoperator is applied to the operands, resulting in an atomic valueor adynamicerror (for example, an error might result from dividing byzero.) The combinations of atomic types that are accepted by thevarious arithmetic operators, and their respective result types,are listed inB.2 Operator Mappingtogether with theoperator functions that define thesemantics of the operator for each type combination, including thedynamic errors that can be raised by the operator. The definitionsof the operator functions are found in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
If the types of the operands, after evaluation, are not a validcombination for the given operator, according to the rules inB.2 Operator Mapping, atype error is raised[err:XPTY0004].
XPath supports two division operators nameddiv
andidiv
. Each of these operators accepts two operands ofanynumeric type. Asdescribed in[XQuery 1.0 and XPath2.0 Functions and Operators (Second Edition)],$arg1 idiv$arg2
is equivalent to($arg1 div $arg2) cast asxs:integer?
except for error cases.
Here are some examples of arithmetic expressions:
The first expression below returns thexs:decimal
value-1.5
, and the second expression returns thexs:integer
value-1
:
-3 div 2-3 idiv 2
Subtraction of two date values results in a value of typexs:dayTimeDuration
:
$emp/hiredate - $emp/birthdate
This example illustrates the difference between a subtractionoperator and a hyphen:
$unit-price - $unit-discount
Unary operators have higher precedence than binary operators,subject of course to the use of parentheses. Therefore, thefollowing two examples have different meanings:
-$bellcost + $whistlecost-($bellcost + $whistlecost)
Note:
Multiple consecutive unaryarithmetic operators are permitted by XPath for compatibility with[XPath 1.0].
Comparison expressions allow two values to be compared. XPathprovides three kinds of comparison expressions, called valuecomparisons, general comparisons, and node comparisons.
[10] | ComparisonExpr | ::= | RangeExpr ( (ValueComp |
[23] | ValueComp | ::= | "eq" | "ne" | "lt" | "le" | "gt" | "ge" |
[22] | GeneralComp | ::= | "=" | "!=" | "<" | "<=" | ">" |">=" |
[24] | NodeComp | ::= | "is" | "<<" | ">>" |
Note:
When an XPath expression is written within an XMLdocument, the XML escaping rules for special characters must befollowed; thus "<
" must be written as"<
".
The value comparison operators areeq
,ne
,lt
,le
,gt
,andge
. Value comparisons are used for comparingsingle values.
The first step in evaluating a value comparison is to evaluateits operands. The order in which the operands are evaluated isimplementation-dependent. Eachoperand is evaluated by applying the following steps, in order:
Atomization isapplied to the operand. The result of this operation is called theatomized operand.
If the atomized operand is an empty sequence, the result of thevalue comparison is an empty sequence, and the implementation neednot evaluate the other operand or apply the operator. However, animplementation may choose to evaluate the other operand in order todetermine whether it raises an error.
If the atomized operand is a sequence of length greater thanone, atype erroris raised [err:XPTY0004].
If the atomized operand is of typexs:untypedAtomic
, it is cast toxs:string
.
Note:
The purpose of this rule is to make value comparisonstransitive. Users should be aware that the general comparisonoperators have a different rule for casting ofxs:untypedAtomic
operands. Users should also be awarethat transitivity of value comparisons may be compromised by lossof precision during type conversion (for example, twoxs:integer
values that differ slightly may both beconsidered equal to the samexs:float
value becausexs:float
has less precision thanxs:integer
).
Next, if possible, the two operands are converted to their leastcommon type by a combination oftype promotion andsubtypesubstitution. For example, if the operands are of typehatsize
(derived fromxs:integer
) andshoesize
(derived fromxs:float
), theirleast common type isxs:float
.
Finally, if the types of the operands are a valid combinationfor the given operator, the operator is applied to the operands.The combinations of atomic types that are accepted by the variousvalue comparison operators, and their respective result types, arelisted inB.2 Operator Mappingtogether with theoperator functions that define thesemantics of the operator for each type combination. Thedefinitions of the operator functions are found in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
Informally, if both atomized operands consist of exactly oneatomic value, then the result of the comparison istrue
if the value of the first operand is (equal, notequal, less than, less than or equal, greater than, greater than orequal) to the value of the second operand; otherwise the result ofthe comparison isfalse
.
If the types of the operands, after evaluation, are not a validcombination for the given operator, according to the rules inB.2 Operator Mapping, atype error is raised[err:XPTY0004].
Here are some examples of value comparisons:
The following comparison atomizes the node(s) that are returnedby the expression$book/author
. The comparison is trueonly if the result of atomization is the value "Kennedy" as aninstance ofxs:string
orxs:untypedAtomic
. If the result of atomization is anempty sequence, the result of the comparison is an empty sequence.If the result of atomization is a sequence containing more than onevalue, atype erroris raised [err:XPTY0004].
$book1/author eq "Kennedy"
The followingpath expression contains a predicate thatselects products whose weight is greater than 100. For any productthat does not have aweight
subelement, the value ofthe predicate is the empty sequence, and the product is notselected. This example assumes thatweight
is avalidated element with a numeric type.
//product[weight gt 100]
The following comparison is true ifmy:hatsize
andmy:shoesize
are both user-defined types that arederived by restriction from a primitivenumeric type:
my:hatsize(5) eq my:shoesize(5)
The following comparison is true. Theeq
operatorcompares two QNames by performing codepoint-comparisons of theirnamespace URIs and their local names, ignoring their namespaceprefixes.
fn:QName("http://example.com/ns1", "this:color") eq fn:QName("http://example.com/ns1", "that:color")
The general comparison operators are=
,!=
,<
,<=
,>
, and>=
. General comparisons areexistentially quantified comparisons that may be applied to operandsequences of any length. The result of a general comparison thatdoes not raise an error is alwaystrue
orfalse
.
IfXPath 1.0 compatibility mode istrue
, a general comparison is evaluated by applyingthe following rules, in order:
If either operand is a single atomic value that is an instanceofxs:boolean
, then the other operand is converted toxs:boolean
by taking itseffective booleanvalue.
Atomization isapplied to each operand. After atomization, each operand is asequence of atomic values.
If the comparison operator is<
,<=
,>
, or>=
, theneach item in both of the operand sequences is converted to the typexs:double
by applying thefn:number
function. (Note thatfn:number
returns the valueNaN
if its operand cannot be converted to anumber.)
The result of the comparison istrue
if and only ifthere is a pair of atomic values, one in the first operand sequenceand the other in the second operand sequence, that have therequiredmagnitude relationship. Otherwise the result of thecomparison isfalse
. Themagnitude relationshipbetween two atomic values is determined by applying the followingrules. If acast
operation called for by these rulesis not successful, a dynamic error is raised. [err:FORG0001]
If at least one of the two atomic values is an instance of anumeric type, then bothatomic values are converted to the typexs:double
byapplying thefn:number
function.
If both atomic values are instances ofxs:untypedAtomic
, then the values are cast to the typexs:string
.
If exactly one of the atomic values is an instance ofxs:untypedAtomic
, and the previous rule does not apply(that is, the other value is not numeric), then it is cast to atype depending on the other value's dynamic type T according to thefollowing rules, in which V denotes the value to be cast:
If T isxs:dayTimeDuration
or is derived fromxs:dayTimeDuration
, then V is cast toxs:dayTimeDuration
.
If T isxs:yearMonthDuration
or is derived fromxs:yearMonthDuration
, then V is cast toxs:yearMonthDuration
.
In all other cases, V is cast to the primitive base type ofT.
Note:
The special treatment of the duration types is required to avoiderrors that may arise when comparing the primitive typexs:duration
with any duration type.
After performing the conversions described above, the atomicvalues are compared using one of the value comparison operatorseq
,ne
,lt
,le
,gt
, orge
, depending on whether thegeneral comparison operator was=
,!=
,<
,<=
,>
, or>=
. The values have the requiredmagnituderelationship if and only if the result of this value comparisonistrue
.
IfXPath1.0 compatibility mode isfalse
, ageneral comparison is evaluated by applying the following rules, inorder:
Atomization isapplied to each operand. After atomization, each operand is asequence of atomic values.
The result of the comparison istrue
if and only ifthere is a pair of atomic values, one in the first operand sequenceand the other in the second operand sequence, that have therequiredmagnitude relationship. Otherwise the result of thecomparison isfalse
. Themagnitude relationshipbetween two atomic values is determined by applying the followingrules. If acast
operation called for by these rulesis not successful, a dynamic error is raised. [err:FORG0001]
If both atomic values are instances ofxs:untypedAtomic
, then the values are cast to the typexs:string
.
If exactly one of the atomic values is an instance ofxs:untypedAtomic
, it is cast to a type depending onthe other value's dynamic type T according to the following rules,in which V denotes the value to be cast:
If T is a numeric type or is derived from a numeric type, then Vis cast toxs:double
.
If T isxs:dayTimeDuration
or is derived fromxs:dayTimeDuration
, then V is cast toxs:dayTimeDuration
.
If T isxs:yearMonthDuration
or is derived fromxs:yearMonthDuration
, then V is cast toxs:yearMonthDuration
.
In all other cases, V is cast to the primitive base type ofT.
Note:
The special treatment of the duration types is required to avoiderrors that may arise when comparing the primitive typexs:duration
with any duration type.
After performing the conversions described above, the atomicvalues are compared using one of the value comparison operatorseq
,ne
,lt
,le
,gt
, orge
, depending on whether thegeneral comparison operator was=
,!=
,<
,<=
,>
, or>=
. The values have the requiredmagnituderelationship if and only if the result of this value comparisonistrue
.
When evaluating a general comparison in which either operand isa sequence of items, an implementation may returntrue
as soon as it finds an item in the first operand and an item in thesecond operand that have the requiredmagnituderelationship. Similarly, a general comparison may raise adynamic erroras soon as it encounters an error in evaluating either operand, orin comparing a pair of items from the two operands. As a result ofthese rules, the result of a general comparison is notdeterministic in the presence of errors.
Here are some examples of general comparisons:
The following comparison is true if thetyped value of anyauthor
subelement of$book1
is "Kennedy" as an instance ofxs:string
orxs:untypedAtomic
:
$book1/author = "Kennedy"
The following example contains three general comparisons. Thevalue of the first two comparisons istrue
, and thevalue of the third comparison isfalse
. This exampleillustrates the fact that general comparisons are nottransitive.
(1, 2) = (2, 3)(2, 3) = (3, 4)(1, 2) = (3, 4)
The following example contains two general comparisons, both ofwhich aretrue
. This example illustrates the fact thatthe=
and!=
operators are not inversesof each other.
(1, 2) = (2, 3)(1, 2) != (2, 3)
Suppose that$a
,$b
, and$c
are bound to element nodes with type annotationxs:untypedAtomic
, withstring values "1
","2
", and "2.0
" respectively. Then($a, $b) = ($c, 3.0)
returnsfalse
,because$b
and$c
are compared asstrings. However,($a, $b) = ($c, 2.0)
returnstrue
, because$b
and2.0
arecompared as numbers.
Node comparisons are used to compare two nodes, by theiridentity or by theirdocument order. The result of a nodecomparison is defined by the following rules:
The operands of a node comparison are evaluated inimplementation-dependentorder.
If either operand is an empty sequence, the result of thecomparison is an empty sequence, and the implementation need notevaluate the other operand or apply the operator. However, animplementation may choose to evaluate the other operand in order todetermine whether it raises an error.
Each operand must be either a single node or an empty sequence;otherwise atypeerror is raised [err:XPTY0004].
A comparison with theis
operator istrue
if the two operand nodes have the same identity,and are thus the same node; otherwise it isfalse
. See[XQuery 1.0 and XPath 2.0 Data Model (SecondEdition)] for a definition of node identity.
A comparison with the<<
operator returnstrue
if the left operand node precedes the rightoperand node indocument order; otherwise it returnsfalse
.
A comparison with the>>
operator returnstrue
if the left operand node follows the rightoperand node indocument order; otherwise it returnsfalse
.
Here are some examples of node comparisons:
The following comparison is true only if the left and rightsides each evaluate to exactly the same single node:
/books/book[isbn="1558604820"] is /books/book[call="QA76.9 C3845"]
The following comparison is true only if the node identified bythe left side occurs before the node identified by the right sidein document order:
/transactions/purchase[parcel="28-451"] << /transactions/sale[parcel="33-870"]
Alogical expression is either anand-expressionor anor-expression. If a logical expression does not raisean error, its value is always one of the boolean valuestrue
orfalse
.
[8] | OrExpr | ::= | AndExpr ( "or"AndExpr )* |
[9] | AndExpr | ::= | ComparisonExpr ("and"ComparisonExpr)* |
The first step in evaluating a logical expression is to find theeffective booleanvalue of each of its operands (see2.4.3Effective Boolean Value).
The value of an and-expression is determined by the effectiveboolean values (EBV's) of its operands, as shown in the followingtable:
AND: | EBV2 =true | EBV2 =false | error in EBV2 |
EBV1 =true | true | false | error |
EBV1 =false | false | false | ifXPath1.0 compatibility mode istrue , thenfalse ; otherwise eitherfalse orerror. |
error in EBV1 | error | ifXPath1.0 compatibility mode istrue , then error;otherwise eitherfalse or error. | error |
The value of an or-expression is determined by the effectiveboolean values (EBV's) of its operands, as shown in the followingtable:
OR: | EBV2 =true | EBV2 =false | error in EBV2 |
EBV1 =true | true | true | ifXPath1.0 compatibility mode istrue , thentrue ; otherwise eithertrue orerror. |
EBV1 =false | true | false | error |
error in EBV1 | ifXPath1.0 compatibility mode istrue , then error;otherwise eithertrue or error. | error | error |
IfXPath 1.0 compatibility mode istrue
, the order in which the operands of a logicalexpression are evaluated is effectively prescribed. Specifically,it is defined that when there is no need to evaluate the secondoperand in order to determine the result, then no error can occuras a result of evaluating the second operand.
IfXPath1.0 compatibility mode isfalse
, the order inwhich the operands of a logical expression are evaluated isimplementation-dependent. Inthis case, an or-expression can returntrue
if the first expression evaluated is true, and itcan raise an error if evaluation of the first expression raises anerror. Similarly, an and-expression can returnfalse
if the first expression evaluated is false, and it can raise anerror if evaluation of the first expression raises an error. As aresult of these rules, a logical expression is not deterministic inthe presence of errors, as illustrated in the examples below.
Here are some examples of logical expressions:
The following expressions returntrue
:
1 eq 1 and 2 eq 2
1 eq 1 or 2 eq 3
The following expression may return eitherfalse
orraise adynamicerror(inXPath1.0 compatibility mode, the result must befalse
):
1 eq 2 and 3 idiv 0 = 1
The following expression may return eithertrue
orraise adynamicerror(inXPath1.0 compatibility mode, the result must betrue
):
1 eq 1 or 3 idiv 0 = 1
The following expression must raise adynamic error:
1 eq 1 and 3 idiv 0 = 1
In addition to and- and or-expressions, XPath provides afunction namedfn:not
that takes a general sequence asparameter and returns a boolean value. Thefn:not
function is defined in[XQuery 1.0and XPath 2.0 Functions and Operators (Second Edition)]. Thefn:not
function reduces its parameter to aneffective booleanvalue. It then returnstrue
if the effectiveboolean value of its parameter isfalse
, andfalse
if the effective boolean value of its parameteristrue
. If an error is encountered in finding theeffective boolean value of its operand,fn:not
raisesthe same error.
XPath provides an iteration facility called aforexpression.
[4] | ForExpr | ::= | SimpleForClause"return"ExprSingle |
[5] | SimpleForClause | ::= | "for" "$"VarName "in"ExprSingle ("," "$"VarName "in"ExprSingle)* |
Afor
expression is evaluated as follows:
If thefor
expression uses multiple variables, itis first expanded to a set of nestedfor
expressions,each of which uses only one variable. For example, the expressionfor $x in X, $y in Y return $x + $y
is expanded tofor $x in X return for $y in Y return $x + $y
.
In a single-variablefor
expression, the variableis called therange variable, the value of the expressionthat follows thein
keyword is called thebindingsequence, and the expression that follows thereturn
keyword is called thereturn expression.The result of thefor
expression is obtained byevaluating thereturn
expression once for each item inthe binding sequence, with the range variable bound to that item.The resulting sequences are concatenated (as if by thecomma operator) inthe order of the items in the binding sequence from which they werederived.
The following example illustrates the use of afor
expression in restructuring an input document. Theexample is based on the following input:
<bib> <book> <title>TCP/IP Illustrated</title> <author>Stevens</author> <publisher>Addison-Wesley</publisher> </book> <book> <title>Advanced Programming in the Unix Environment</title> <author>Stevens</author> <publisher>Addison-Wesley</publisher> </book> <book> <title>Data on the Web</title> <author>Abiteboul</author> <author>Buneman</author> <author>Suciu</author> </book></bib>
The following example transforms the input document into a listin which each author's name appears only once, followed by a listof titles of books written by that author. This example assumesthat the context item is thebib
element in the inputdocument.
for $a in fn:distinct-values(book/author)return (book/author[. = $a][1], book[author = $a]/title)
The result of the above expression consists of the followingsequence of elements. The titles of books written by a given authorare listed after the name of the author. The ordering ofauthor
elements in the result isimplementation-dependent due tothe semantics of thefn:distinct-values
function.
<author>Stevens</author> <title>TCP/IP Illustrated</title><title>Advanced Programming in the Unix environment</title><author>Abiteboul</author><title>Data on the Web</title><author>Buneman</author><title>Data on the Web</title><author>Suciu</author><title>Data on the Web</title>
The following example illustrates afor
expressioncontaining more than one variable:
for $i in (10, 20), $j in (1, 2)return ($i + $j)
The result of the above expression, expressed as a sequence ofnumbers, is as follows:11, 12, 21, 22
The scope of a variable bound in afor
expressioncomprises all subexpressions of thefor
expressionthat appear after the variable binding. The scope does not includethe expression to which the variable is bound. The followingexample illustrates how a variable binding may reference anothervariable bound earlier in the samefor
expression:
for $x in $z, $y in f($x)return g($x, $y)
Note:
The focus for evaluation of thereturn
clause of afor
expression is the same as the focus for evaluationof thefor
expression itself. The following example,which attempts to find the total value of a set of order-items, istherefore incorrect:
fn:sum(for $i in order-item return @price *@qty)
Instead, the expression must be written to use the variablebound in thefor
clause:
fn:sum(for $i in order-item return $i/@price * $i/@qty)
XPath supports a conditional expression based on the keywordsif
,then
, andelse
.
[7] | IfExpr | ::= | "if" "("Expr ")" "then"ExprSingle "else"ExprSingle |
The expression following theif
keyword is calledthetest expression, and the expressions following thethen
andelse
keywords are called thethen-expression andelse-expression,respectively.
The first step in processing a conditional expression is to findtheeffectiveboolean value of the test expression, as defined in2.4.3 Effective Boolean Value.
The value of a conditional expression is defined as follows: Ifthe effective boolean value of the test expression istrue
, the value of the then-expression is returned. Ifthe effective boolean value of the test expression isfalse
, the value of the else-expression isreturned.
Conditional expressions have a special rule for propagatingdynamicerrors. If the effective value of the test expression istrue
, the conditional expression ignores (does notraise) any dynamic errors encountered in the else-expression. Inthis case, since the else-expression can have no observable effect,it need not be evaluated. Similarly, if the effective value of thetest expression isfalse
, the conditional expressionignores anydynamic errors encountered in thethen-expression, and the then-expression need not be evaluated.
Here are some examples of conditional expressions:
In this example, the test expression is a comparisonexpression:
if ($widget1/unit-cost < $widget2/unit-cost) then $widget1 else $widget2
In this example, the test expression tests for the existence ofan attribute nameddiscounted
, independently of itsvalue:
if ($part/@discounted) then $part/wholesale else $part/retail
Quantified expressions support existential and universalquantification. The value of a quantified expression is alwaystrue
orfalse
.
[6] | QuantifiedExpr | ::= | ("some" | "every") "$"VarName "in"ExprSingle ("," "$"VarName "in"ExprSingle)* "satisfies"ExprSingle |
Aquantified expression begins with aquantifier,which is the keywordsome
orevery
,followed by one or more in-clauses that are used to bind variables,followed by the keywordsatisfies
and a testexpression. Each in-clause associates a variable with an expressionthat returns a sequence of items, called thebindingsequence for that variable. The in-clauses generate tuples ofvariable bindings, including a tuple for each combination of itemsin the binding sequences of the respective variables. Conceptually,the test expression is evaluated for each tuple of variablebindings. Results depend on theeffective boolean value of the test expressions,as defined in2.4.3 Effective BooleanValue. The value of the quantified expression is defined bythe following rules:
If the quantifier issome
, the quantifiedexpression istrue
if at least one evaluation of thetest expression has theeffective boolean valuetrue
; otherwisethe quantified expression isfalse
. This rule impliesthat, if the in-clauses generate zero binding tuples, the value ofthe quantified expression isfalse
.
If the quantifier isevery
, the quantifiedexpression istrue
if every evaluation of the testexpression has theeffective boolean valuetrue
; otherwisethe quantified expression isfalse
. This rule impliesthat, if the in-clauses generate zero binding tuples, the value ofthe quantified expression istrue
.
The scope of a variable bound in a quantified expressioncomprises all subexpressions of the quantified expression thatappear after the variable binding. The scope does not include theexpression to which the variable is bound.
The order in which test expressions are evaluated for thevarious binding tuples isimplementation-dependent. If thequantifier issome
, an implementation may returntrue
as soon as it finds one binding tuple for whichthe test expression has aneffective boolean value oftrue
, and itmay raise adynamic error as soon as it finds onebinding tuple for which the test expression raises an error.Similarly, if the quantifier isevery
, animplementation may returnfalse
as soon as it findsone binding tuple for which the test expression has aneffective booleanvalue offalse
, and it may raise adynamic error as soonas it finds one binding tuple for which the test expression raisesan error. As a result of these rules, the value of a quantifiedexpression is not deterministic in the presence of errors, asillustrated in the examples below.
Here are some examples of quantified expressions:
This expression istrue
if everypart
element has adiscounted
attribute (regardless of thevalues of these attributes):
every $part in /parts/part satisfies $part/@discounted
This expression istrue
if at least oneemployee
element satisfies the given comparisonexpression:
some $emp in /emps/employee satisfies ($emp/bonus > 0.25 * $emp/salary)
In the following examples, each quantified expression evaluatesits test expression over nine tuples of variable bindings, formedfrom the Cartesian product of the sequences(1, 2, 3)
and(2, 3, 4)
. The expression beginning withsome
evaluates totrue
, and theexpression beginning withevery
evaluates tofalse
.
some $x in (1, 2, 3), $y in (2, 3, 4) satisfies $x + $y = 4
every $x in (1, 2, 3), $y in (2, 3, 4) satisfies $x + $y = 4
This quantified expression may either returntrue
or raise atypeerror, since its test expression returnstrue
forone variable binding and raises atype error for another:
some $x in (1, 2, "cat") satisfies $x * 2 = 4
This quantified expression may either returnfalse
or raise atypeerror, since its test expression returnsfalse
forone variable binding and raises atype error for another:
every $x in (1, 2, "cat") satisfies $x * 2 = 4
sequencetypes are used ininstance of
,cast
,castable
, andtreat
expressions.
[16] | InstanceofExpr | ::= | TreatExpr ( "instance""of"SequenceType)? |
The boolean operatorinstance of
returnstrue
if the value of its first operand matches theSequenceType in its secondoperand, according to the rules forSequenceType matching; otherwise itreturnsfalse
. For example:
5 instance of xs:integer
This example returnstrue
because the given valueis an instance of the given type.
5 instance of xs:decimal
This example returnstrue
because the given valueis an integer literal, andxs:integer
is derived byrestriction fromxs:decimal
.
(5, 6) instance of xs:integer+
This example returnstrue
because the givensequence contains two integers, and is a valid instance of thespecified type.
. instance of element()
This example returnstrue
if the context item is anelement node orfalse
if the context item is definedbut is not an element node. If the context item isundefined, adynamic error israised [err:XPDY0002].
[19] | CastExpr | ::= | UnaryExpr ( "cast""as"SingleType )? |
[49] | SingleType | ::= | AtomicType"?"? |
Occasionally it is necessary to convert a value to a specificdatatype. For this purpose, XPath provides acast
expression that creates a new value of a specific type based on anexisting value. Acast
expression takes two operands:aninput expression and atarget type. The type ofthe input expression is called theinput type. The targettype must be an atomic type that is in thein-scope schematypes [err:XPST0051]. In addition, the target typecannot bexs:NOTATION
orxs:anyAtomicType
[err:XPST0080]. Theoptional occurrence indicator "?
" denotes that anempty sequence is permitted. If the target type has no namespaceprefix, it is considered to be in thedefaultelement/type namespace. The semantics of thecast
expression are as follows:
Atomization isperformed on the input expression.
If the result of atomization is a sequence of more than oneatomic value, atypeerror is raised [err:XPTY0004].
If the result of atomization is an empty sequence:
If?
is specified after the target type, the resultof thecast
expression is an empty sequence.
If?
is not specified after the target type, atype error israised [err:XPTY0004].
If the result of atomization is a single atomic value, theresult of the cast expression depends on the input type and thetarget type. In general, the cast expression attempts to create anew value of the target type based on the input value. Only certaincombinations of input type and target type are supported. A summaryof the rules are listed below— the normative definition of theserules is given in[XQuery 1.0 andXPath 2.0 Functions and Operators (Second Edition)]. For thepurpose of these rules, an implementation may determine that onetype is derived by restriction from another type either byexamining thein-scope schema definitions or by using analternative,implementation-dependentmechanism such as a data dictionary.
cast
is supported for the combinations of inputtype and target type listed inSection 17.1 Casting from primitive types to primitivetypesFO. For each of thesecombinations, both the input type and the target type are primitiveschema types. Forexample, a value of typexs:string
can be cast intothe schema typexs:decimal
. For each of these built-incombinations, the semantics of casting are specified in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
If the target type of acast
expression isxs:QName
, or is a type that is derived fromxs:QName
orxs:NOTATION
, and if the basetype of the input is not the same as the base type of the targettype, then the input expression must be a string literal [err:XPTY0004].
Note:
The reason for this rule is that construction of an instance ofone of these target types from a string requires knowledge aboutnamespace bindings. If the input expression is a non-literalstring, it might be derived from an input document whose namespacebindings are different from thestatically known namespaces.
cast
is supported if the input type is anon-primitive atomic type that is derived by restriction from thetarget type. In this case, the input value is mapped into the valuespace of the target type, unchanged except for its type. Forexample, ifshoesize
is derived by restriction fromxs:integer
, a value of typeshoesize
canbe cast into the schema typexs:integer
.
cast
is supported if the target type is anon-primitive atomic type and the input type isxs:string
orxs:untypedAtomic
. The inputvalue is first converted to a value in the lexical space of thetarget type by applying the whitespace normalization rules for thetarget type (as defined in[XML Schema]).The lexical value is then converted to the value space of thetarget type using the schema-defined rules for the target type. Ifthe input value fails to satisfy some facet of the target type, adynamic errormay be raised as specified in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
cast
is supported if the target type is anon-primitive atomic type that is derived by restriction from theinput type. The input value must satisfy all the facets of thetarget type (in the case of the pattern facet, this is checked bygenerating a string representation of the input value, using therules for casting toxs:string
). The resulting valueis the same as the input value, but with a differentdynamic type.
If a primitive type P1 can be cast into a primitive type P2,then any type derived by restriction from P1 can be cast into anytype derived by restriction from P2, provided that the facets ofthe target type are satisfied. First the input value is cast to P1using rule (b) above. Next, the value of type P1 is cast to thetype P2, using rule (a) above. Finally, the value of type P2 iscast to the target type, using rule (d) above.
For any combination of input type and target type that is not inthe above list, acast
expression raises atype error [err:XPTY0004].
If casting from the input type to the target type is supportedbut nevertheless it is not possible to cast the input value intothe value space of the target type, adynamic error is raised.[err:FORG0001] This includes the case when any facet of the targettype is not satisfied. For example, the expression"2003-02-31" cast as xs:date
would raise adynamic error.
[18] | CastableExpr | ::= | CastExpr ( "castable""as"SingleType )? |
[49] | SingleType | ::= | AtomicType"?"? |
XPath provides an expression that tests whether a given value iscastable into a given target type. The target type must be anatomic type that is in thein-scope schema types [err:XPST0051]. In addition, the targettype cannot bexs:NOTATION
orxs:anyAtomicType
[err:XPST0080]. The optional occurrence indicator"?
" denotes that an empty sequence is permitted.
The expressionE castable as T
returnstrue
if the result of evaluatingE
can besuccessfully cast into the target typeT
by using acast
expression; otherwise it returnsfalse
. If evaluation ofE
fails with adynamic error, thecastable
expression as a wholefails. Thecastable
expression can be used as apredicate to avoiderrors at evaluation time. It can also be used to select anappropriate type for processing of a given value, as illustrated inthe following example:
if ($x castable as hatsize) then $x cast as hatsize else if ($x castable as IQ) then $x cast as IQ else $x cast as xs:string
Note:
If the target type of acastable
expression isxs:QName
, or is a type that is derived fromxs:QName
orxs:NOTATION
, and the inputargument of the expression is of typexs:string
but itis not a literal string, the result of thecastable
expression isfalse
.
For every atomic type in thein-scope schema types (exceptxs:NOTATION
andxs:anyAtomicType
, whichare not instantiable), aconstructor function is implicitlydefined. In each case, the name of the constructor function is thesame as the name of its target type (including namespace). Thesignature of the constructor function for typeT is asfollows:
T($arg as xs:anyAtomicType?) asT?
[Definition: Theconstructorfunction for a given type is used to convert instances of otheratomic types into the given type. The semantics of the constructorfunction callT($arg)
are defined to be equivalent tothe expression(($arg) cast as T?)
.]
The constructor functions forxs:QName
and fortypes derived fromxs:QName
andxs:NOTATION
require their arguments to be stringliterals or to have a base type that is the same as the base typeof the target type; otherwise a type error [err:XPTY0004] is raised. This rule isconsistent with the semantics ofcast
expressions forthese types, as defined in3.10.2Cast.
The following examples illustrate the use of constructorfunctions:
This example is equivalent to("2000-01-01" cast asxs:date?)
.
xs:date("2000-01-01")
This example is equivalent to(($floatvalue * 0.2E-5) castas xs:decimal?)
.
xs:decimal($floatvalue * 0.2E-5)
This example returns axs:dayTimeDuration
valueequal to 21 days. It is equivalent to("P21D" cast asxs:dayTimeDuration?)
.
xs:dayTimeDuration("P21D")
Ifusa:zipcode
is a user-defined atomic type in thein-scope schematypes, then the following expression is equivalent to theexpression("12345" cast as usa:zipcode?)
.
usa:zipcode("12345")
Note:
An instance of an atomic type that is not in a namespace can beconstructed in either of the following ways:
By using acast
expression, if thedefaultelement/type namespace is "none".
17 cast as apple
By using a constructor function, if thedefault functionnamespace is "none".
apple(17)
[17] | TreatExpr | ::= | CastableExpr ("treat" "as"SequenceType)? |
XPath provides an expression calledtreat
that canbe used to modify thestatic type of its operand.
Likecast
, thetreat
expression takestwo operands: an expression and aSequenceType. Unlikecast
, however,treat
does not change thedynamic type orvalue of its operand. Instead, the purpose oftreat
isto ensure that an expression has an expected dynamic type atevaluation time.
The semantics ofexpr1
treatas
type1
are as follows:
During static analysis:
Thestatictype of thetreat
expression istype1
. This enables the expression to be usedas an argument of a function that requires a parameter oftype1
.
During expression evaluation:
Ifexpr1
matchestype1
, using the rules forSequenceType matching, thetreat
expression returns the value ofexpr1
; otherwise, it raises adynamic error[err:XPDY0050]. Ifthe value ofexpr1
is returned, its identityis preserved. Thetreat
expression ensures that thevalue of its expression operand conforms to the expected type atrun-time.
Example:
$myaddress treat as element(*, USAddress)
Thestatictype of$myaddress
may beelement(*,Address)
, a less specific type thanelement(*,USAddress)
. However, at run-time, the value of$myaddress
must match the typeelement(*,USAddress)
using rules forSequenceType matching;otherwise adynamic error is raised [err:XPDY0050].
The grammar of XPath uses the same simple Extended Backus-NaurForm (EBNF) notation as[XML 1.0] with thefollowing minor differences.
All named symbols have a name that begins with an uppercaseletter.
It adds a notation for referring to productions in externalspecs.
Comments or extra-grammatical constraints on grammar productionsare between '/*' and '*/' symbols.
A 'xgc:' prefix is an extra-grammatical constraint, the detailsof which are explained inA.1.2 Extra-grammaticalConstraints
A 'ws:' prefix explains the whitespace rules for the production,the details of which are explained inA.2.4 Whitespace Rules
A 'gn:' prefix means a 'Grammar Note', and is meant as aclarification for parsing rules, and is explained inA.1.3 Grammar Notes. These notes arenot normative.
The terminal symbols for this grammar include the quoted stringsused in the production rules below, and the terminal symbolsdefined in sectionA.2.1 TerminalSymbols.
The EBNF notation is described in more detail inA.1.1 Notation.
To increase readability, the EBNF in the main body of thisdocument omits some of these notational features. This appendix isthe normative version of the EBNF.
The following definitions will be helpful in defining preciselythis exposition.
[Definition:Each rule in the grammar defines onesymbol, using thefollowing format:
symbol ::= expression
]
[Definition: Aterminal is a symbol or stringor pattern that can appear in the right-hand side of a rule, butnever appears on the left hand side in the main grammar, althoughit may appear on the left-hand side of a rule in the grammar forterminals.] The following constructs are used to match strings ofone or more characters in a terminal:
matches anyChar with a value inthe range(s) indicated (inclusive).
matches anyChar with a valueamong the characters enumerated.
matches anyChar with a value notamong the characters given.
matches the sequence of characters that appear inside the doublequotes.
matches the sequence of characters that appear inside the singlequotes.
matches any string matched by the production defined in theexternal specification as per the provided reference.
Patterns (including the above constructs) can be combined withgrammatical operators to form more complex patterns, matching morecomplex sets of character strings. In the examples that follow, Aand B represent (sub-)patterns.
A
is treated as a unit and may be combined asdescribed in this list.
matchesA
or nothing; optionalA
.
matchesA
followed byB
. This operatorhas higher precedence than alternation; thusA B | C D
is identical to(A B) | (C D)
.
matchesA
orB
but not both.
matches any string that matchesA
but does notmatchB
.
matches one or more occurrences ofA
. Concatenationhas higher precedence than alternation; thusA+ | B+
is identical to(A+) | (B+)
.
matches zero or more occurrences ofA
.Concatenation has higher precedence than alternation; thusA*| B*
is identical to(A*) | (B*)
This section contains constraints on the EBNF productions, whichare required to parse legal sentences. The notes below arereferenced from the right side of the production, with thenotation:/* xgc: <id> */.
A single slash may appear either as a complete path expressionor as the first part of a path expression in which it is followedby aRelativePathExpr. Insome cases, the next token after the slash is insufficient to allowa parser to distinguish these two possibilities: the*
token and keywords likeunion
could be either anoperator or aNameTest . Forexample, without lookahead the first part of the expression/* 5
is easily taken to be a complete expression,/*
, which has a very different interpretation (the childnodes of/
).
Therefore to reduce the need for lookahead, if the tokenimmediately following a slash can form the start of aRelativePathExpr, then the slashmust be the beginning of aPathExpr, not the entirety of it.
A single slash may be used as the left-hand argument of anoperator by parenthesizing it:(/) * 5
. The expression5 * /
, on the other hand, is legal withoutparentheses.
An implementation's choice to support the[XML1.0] and[XML Names], or[XML 1.1] and[XML Names1.1] lexical specification determines the external documentfrom which to obtain the definition for this production. The EBNFonly has references to the 1.0 versions. In some cases, the XML 1.0and XML 1.1 definitions may be exactly the same. Also please notethat these external productions follow the whitespace rules oftheir respective specifications, and not the rules of thisspecification, in particularA.2.4.1 Default WhitespaceHandling. Thusprefix : localname
is not avalid QName for purposes of this specification, just as it is notpermitted in a XML document. Also, comments are not permissible oneither side of the colon. Also extra-grammatical constraints suchas well-formedness constraints must be taken into account.
Constraint:reserved-function-names
Unprefixed function names spelled the same way as languagekeywords could make the language harder to recognize. For instance,if(foo)
could be taken either as aFunctionCall or as the beginning ofanIfExpr. Therefore it is notlegal syntax for a user to invoke functions with unprefixed nameswhich match any of the names inA.3 Reserved Function Names.
A function named "if" can be called by binding its namespace toa prefix and using the prefixed form: "library:if(foo)" instead of"if(foo)".
Constraint:occurrence-indicators
As written, the grammar inA XPathGrammar is ambiguous for some forms using the '+' and '*'Kleene operators. The ambiguity is resolved as follows: theseoperators are tightly bound to theSequenceType expression, and havehigher precedence than other uses of these symbols. Any occurrenceof '+' and '*', as well as '?', following a sequence type isassumed to be an occurrence indicator. That is, a "+", "*", or "?"immediately following anItemTypemust be anOccurrenceIndicator. Thus,4 treat as item() + - 5
must be interpreted as(4 treat as item()+) - 5
, taking the '+' as anOccurrenceIndicator and the '-' as a subtraction operator. To forcethe interpretation of "+" as an addition operator (and thecorresponding interpretation of the "-" as a unary minus),parentheses may be used: the form(4 treat as item()) +-5
surrounds theSequenceType expression withparentheses and leads to the desired interpretation.
This rule has as a consequence that certain forms which wouldotherwise be legal and unambiguous are not recognized: in "4 treatas item() + 5", the "+" is taken as anOccurrenceIndicator, and notas an operator, which means this is not a legal expression.
This section contains general notes on the EBNF productions,which may be helpful in understanding how to interpret andimplement the EBNF. These notes are not normative. The notes beloware referenced from the right side of the production, with thenotation:/* gn: <id> */.
Note:
Look-ahead is required to distinguishFunctionCall from a QName or keywordfollowed by aComment. Forexample:address (: this may be empty :)
may bemistaken for a call to a function named "address" unless thislookahead is employed. Another example isfor (: whom thebell :) $tolls in 3 return $tolls
, where the keyword "for"must not be mistaken for a function name.
Comments are allowed everywhere thatignorablewhitespace is allowed, and theComment symbol does not explicitly appearon the right-hand side of the grammar (except in its ownproduction). SeeA.2.4.1Default Whitespace Handling.
A comment can contain nested comments, as long as all "(:" and":)" patterns are balanced, no matter where they occur within theouter comment.
Note:
Lexical analysis may typically handle nested comments byincrementing a counter for each "(:" pattern, and decrementing thecounter for each ":)" pattern. The comment does not terminate untilthe counter is back to zero.
Some illustrative examples:
(: commenting out a (: comment :) may be confusing, butoften helpful :)
is a legal Comment, since balanced nestingof comments is allowed.
"this is just a string :)"
is a legal expression.However,(: "this is just a string :)" :)
will cause asyntax error. Likewise,"this is another string (:"
isa legal expression, but(: "this is another string (:":)
will cause a syntax error. It is a limitation of nestedcomments that literal content can cause unbalanced nesting ofcomments.
for (: set up loop :) $i in $x return $i
issyntactically legal, ignoring the comment.
5 instance (: strange place for a comment :) ofxs:integer
is also syntactically valid.
The terminal symbols assumed by the grammar above are describedin this section.
Quoted strings appearing in production rules are terminalsymbols.
Other terminal symbols are defined inA.2.1 Terminal Symbols.
Ahost language may choose whether thelexical rules of[XML 1.0] and[XML Names] are followed, or alternatively, thelexical rules of[XML 1.1] and[XML Names 1.1] are followed.
When tokenizing, the longest possible match that is valid in thecurrent context is used.
All keywords are case sensitive. Keywords are not reserved—thatis, any QName may duplicate a keyword except as noted inA.3 Reserved Function Names.
[71] | IntegerLiteral | ::= | Digits | |
[72] | DecimalLiteral | ::= | ("."Digits) | (Digits "." [0-9]*) | /*ws: explicit */ |
[73] | DoubleLiteral | ::= | (("."Digits) |(Digits ("." [0-9]*)?)) [eE] [+-]?Digits | /*ws: explicit */ |
[74] | StringLiteral | ::= | ('"' (EscapeQuot |[^"])* '"') | ("'" (EscapeApos| [^'])* "'") | /*ws: explicit */ |
[75] | EscapeQuot | ::= | '""' | |
[76] | EscapeApos | ::= | "''" | |
[77] | Comment | ::= | "(:" (CommentContents |Comment)* ":)" | /*ws: explicit */ |
/*gn: comments*/ | ||||
[78] | QName | ::= | [http://www.w3.org/TR/REC-xml-names/#NT-QName]Names | /*xgs: xml-version*/ |
[79] | NCName | ::= | [http://www.w3.org/TR/REC-xml-names/#NT-NCName]Names | /*xgs: xml-version*/ |
[80] | Char | ::= | [http://www.w3.org/TR/REC-xml#NT-Char]XML | /*xgs: xml-version*/ |
The following symbols are used only in the definition ofterminal symbols; they are not terminal symbols in the grammar ofA.1 EBNF.
[81] | Digits | ::= | [0-9]+ |
[82] | CommentContents | ::= | (Char+ - (Char* ('(:' |':)') Char*)) |
XPath 2.0 expressions consist ofterminal symbols andsymbolseparators.
Terminal symbols that are not used exclusively in/* ws: explicit */ productions are of two kinds:delimiting and non-delimiting.
[Definition: Thedelimitingterminal symbols are: "!=",StringLiteral, "$", "(", ")", "*","+", (comma), "-", (dot), "..", "/", "//", (colon), "::", "<","<<", "<=", "=", ">", ">=", ">>", "?", "@","[", "]", "|"]
[Definition: Thenon-delimiting terminal symbols are:IntegerLiteral,NCName,DecimalLiteral,DoubleLiteral,QName, "ancestor", "ancestor-or-self","and", "as", "attribute", "cast", "castable", "child", "comment","descendant", "descendant-or-self", "div", "document-node","element", "else", "empty-sequence", "eq", "every", "except","external", "following", "following-sibling", "for", "ge", "gt","idiv", "if", "in", "instance", "intersect", "is", "item", "le","lt", "mod", "namespace", "ne", "node", "of", "or", "parent","preceding", "preceding-sibling", "processing-instruction","return", "satisfies", "schema-attribute", "schema-element","self", "some", "text", "then", "to", "treat", "union"]
[Definition:Whitespace andComments function assymbolseparators. For the most part, they are not mentioned in thegrammar, and may occur between any two terminal symbols mentionedin the grammar, except where that is forbidden by the/* ws: explicit */ annotation in the EBNF, or bythe/* xgs: xml-version */annotation. ]
It is customary to separate consecutive terminal symbols bywhitespace andComments, but this is requiredonly when otherwise two non-delimiting symbols would be adjacent toeach other. There are two exceptions to this, that of "." and "-",which do require asymbol separator if they follow a QName orNCName. Also, "." requires a separator if it precedes or follows anumeric literal.
The XPath processor must behave as if it normalized all linebreaks on input, before parsing. The normalization should be doneaccording to the choice to support either[XML1.0] or[XML 1.1] lexical processing.
For[XML 1.0] processing, all of thefollowing must be translated to a single #xA character:
the two-character sequence #xD #xA
any #xD character that is not immediately followed by #xA.
For[XML 1.1] processing, all of thefollowing must be translated to a single #xA character:
the two-character sequence #xD #xA
the two-character sequence #xD #x85
the single character #x85
the single character #x2028
any #xD character that is not immediately followed by #xA or#x85.
[Definition: Awhitespace character is anyof the characters defined by[http://www.w3.org/TR/REC-xml/#NT-S].]
[Definition:Ignorable whitespaceconsists of anywhitespace characters that may occur betweenterminals, unless thesecharacters occur in the context of a production marked with aws:explicit annotation,in which case they can occur only where explicitly specified (seeA.2.4.2 ExplicitWhitespace Handling).] Ignorable whitespace characters arenot significant to the semantics of an expression. Whitespace isallowed before the first terminal and after the last terminal of amodule. Whitespace is allowed between any twoterminals.Comments may also act as "whitespace" toprevent two adjacent terminals from being recognized as one. Someillustrative examples are as follows:
foo- foo
results in a syntax error. "foo-" would berecognized as a QName.
foo -foo
is syntactically equivalent tofoo -foo
, two QNames separated by a subtraction operator.
foo(: This is a comment :)- foo
is syntacticallyequivalent tofoo - foo
. This is because the commentprevents the two adjacent terminals from being recognized asone.
foo-foo
is syntactically equivalent to singleQName. This is because "-" is a valid character in a QName. Whenused as an operator after the characters of a name, the "-" must beseparated from the name, e.g. by using whitespace orparentheses.
10div 3
results in a syntax error.
10 div3
also results in a syntax error.
10div3
also results in a syntax error.
Explicit whitespace notation is specified with the EBNFproductions, when it is different from the default rules, using thenotation shown below. This notation is not inherited. In otherwords, if an EBNF rule is marked as /* ws: explicit */, thenotation does not automatically apply to all the 'child' EBNFproductions of that rule.
/* ws: explicit */ means that the EBNF notation explicitlynotates, withS
or otherwise, wherewhitespace characters areallowed. In productions with the /* ws: explicit */ annotation,A.2.4.1 Default WhitespaceHandling does not apply.Comments are also not allowed in theseproductions.
The following names are not allowed as function names in anunprefixed form because expression syntax takes precedence.
attribute
comment
document-node
element
empty-sequence
if
item
node
processing-instruction
schema-attribute
schema-element
text
typeswitch
Note:
Although the keywordtypeswitch
is not used inXPath, it is considered a reserved function name for compatibilitywith XQuery.
The grammar inA.1 EBNFnormatively defines built-in precedence among the operators ofXPath. These operators are summarized here to make clear the orderof their precedence from lowest to highest. The associativitycolumn indicates the order in which operators of equal precedencein an expression are applied.
# | Operator | Associativity |
---|---|---|
1 | , (comma) | left-to-right |
3 | for,some, every,if | left-to-right |
4 | or | left-to-right |
5 | and | left-to-right |
6 | eq, ne, lt, le, gt, ge,=, !=, <, <=, >,>=,is,<<, >> | left-to-right |
7 | to | left-to-right |
8 | +, - | left-to-right |
9 | *, div, idiv,mod | left-to-right |
10 | union, | | left-to-right |
11 | intersect,except | left-to-right |
12 | instance of | left-to-right |
13 | treat | left-to-right |
14 | castable | left-to-right |
15 | cast | left-to-right |
16 | -(unary), +(unary) | right-to-left |
17 | ?,*(OccurrenceIndicator), +(OccurrenceIndicator) | left-to-right |
18 | /, // | left-to-right |
19 | [ ] | left-to-right |
Note:
Parentheses can be used to override the operator precedence inthe usual way. Square brackets in an expression such as A[B] servetwo roles: they act as an operator causing B to be evaluated oncefor each item in the value of A, and they act as parenthesesenclosing the expression B.
[Definition: Under certain circumstances, anatomic value can be promoted from one type to another.Typepromotion is used in evaluating function calls (see3.1.5 Function Calls) and operatorsthat accept numeric or string operands (seeB.2 Operator Mapping).] The following typepromotions are permitted:
Numeric type promotion:
A value of typexs:float
(or any type derived byrestriction fromxs:float
) can be promoted to the typexs:double
. The result is thexs:double
value that is the same as the original value.
A value of typexs:decimal
(or any type derived byrestriction fromxs:decimal
) can be promoted to eitherof the typesxs:float
orxs:double
. Theresult of this promotion is created by casting the original valueto the required type. This kind of promotion may cause loss ofprecision.
URI type promotion: A value of typexs:anyURI
(orany type derived by restriction fromxs:anyURI
) can bepromoted to the typexs:string
. The result of thispromotion is created by casting the original value to the typexs:string
.
Note:
Sincexs:anyURI
values can be promoted toxs:string
, functions and operators that comparestrings using thedefault collation also comparexs:anyURI
values using thedefault collation.This ensures that orderings that include strings,xs:anyURI
values, or any combination of the two typesare consistent and well-defined.
Note thattype promotion is different fromsubtypesubstitution. For example:
A function that expects a parameter$p
of typexs:float
can be invoked with a value of typexs:decimal
. This is an example oftype promotion. Thevalue is actually converted to the expected type. Within the bodyof the function,$p instance of xs:decimal
returnsfalse
.
A function that expects a parameter$p
of typexs:decimal
can be invoked with a value of typexs:integer
. This is an example ofsubtypesubstitution. The value retains its original type. Within thebody of the function,$p instance of xs:integer
returnstrue
.
The operator mapping tables in this section list thecombinations of types for which the various operators of XPath aredefined. [Definition: For each operator andvalid combination of operand types, the operator mapping tablesspecify a result type and anoperator function thatimplements the semantics of the operator for the given types.] Thedefinitions of the operator functions are given in[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)]. The result of an operator may bethe raising of an error by its operator function, as defined in[XQuery 1.0 and XPath 2.0Functions and Operators (Second Edition)]. In some cases, theoperator function does not implement the full semantics of a givenoperator. For the definition of each operator (including itsbehavior for empty sequences or sequences of length greater thanone), see the descriptive material in the main part of thisdocument.
Theand
andor
operators are defineddirectly in the main body of this document, and do not occur in theoperator mapping tables.
If an operator in the operator mapping tables expects an operandof typeET, that operator can be applied to an operand oftypeAT if typeAT can be converted to typeET by a combination oftype promotion andsubtypesubstitution. For example, a table entry indicates that thegt
operator may be applied to twoxs:date
operands, returningxs:boolean
. Therefore, thegt
operator may also be applied to two (possiblydifferent) subtypes ofxs:date
, also returningxs:boolean
.
[Definition: When referring to a type, the termnumeric denotes the typesxs:integer
,xs:decimal
,xs:float
, andxs:double
.] An operator whose operands and result aredesignated asnumericmight be thought of as representing four operators, one for each ofthe numeric types. For example, the numeric+
operatormight be thought of as representing the following fouroperators:
Operator | First operand type | Second operand type | Result type |
+ | xs:integer | xs:integer | xs:integer |
+ | xs:decimal | xs:decimal | xs:decimal |
+ | xs:float | xs:float | xs:float |
+ | xs:double | xs:double | xs:double |
A numeric operator may be validly applied to an operand of typeAT if typeAT can be converted to any of the fournumeric types by a combination oftype promotion andsubtypesubstitution. If the result type of an operator is listed asnumeric, it means "the first type in the ordered list(xs:integer, xs:decimal, xs:float, xs:double)
intowhich all operands can be converted bysubtypesubstitution andtype promotion." As an example, supposethat the typehatsize
is derived fromxs:integer
and the typeshoesize
isderived fromxs:float
. Then if the+
operator is invoked with operands of typehatsize
andshoesize
, it returns a result of typexs:float
. Similarly, if+
is invoked withtwo operands of typehatsize
it returns a result oftypexs:integer
.
[Definition: In the operator mapping tables, thetermGregorian refers to the typesxs:gYearMonth
,xs:gYear
,xs:gMonthDay
,xs:gDay
, andxs:gMonth
.] For binary operators that accept twoGregorian-type operands, both operands must have the same type (forexample, if one operand is of typexs:gDay
, the otheroperand must be of typexs:gDay
.)
Operator | Type(A) | Type(B) | Function | Result type |
---|---|---|---|---|
A + B | numeric | numeric | op:numeric-add(A, B) | numeric |
A + B | xs:date | xs:yearMonthDuration | op:add-yearMonthDuration-to-date(A, B) | xs:date |
A + B | xs:yearMonthDuration | xs:date | op:add-yearMonthDuration-to-date(B, A) | xs:date |
A + B | xs:date | xs:dayTimeDuration | op:add-dayTimeDuration-to-date(A, B) | xs:date |
A + B | xs:dayTimeDuration | xs:date | op:add-dayTimeDuration-to-date(B, A) | xs:date |
A + B | xs:time | xs:dayTimeDuration | op:add-dayTimeDuration-to-time(A, B) | xs:time |
A + B | xs:dayTimeDuration | xs:time | op:add-dayTimeDuration-to-time(B, A) | xs:time |
A + B | xs:dateTime | xs:yearMonthDuration | op:add-yearMonthDuration-to-dateTime(A, B) | xs:dateTime |
A + B | xs:yearMonthDuration | xs:dateTime | op:add-yearMonthDuration-to-dateTime(B, A) | xs:dateTime |
A + B | xs:dateTime | xs:dayTimeDuration | op:add-dayTimeDuration-to-dateTime(A, B) | xs:dateTime |
A + B | xs:dayTimeDuration | xs:dateTime | op:add-dayTimeDuration-to-dateTime(B, A) | xs:dateTime |
A + B | xs:yearMonthDuration | xs:yearMonthDuration | op:add-yearMonthDurations(A, B) | xs:yearMonthDuration |
A + B | xs:dayTimeDuration | xs:dayTimeDuration | op:add-dayTimeDurations(A, B) | xs:dayTimeDuration |
A - B | numeric | numeric | op:numeric-subtract(A, B) | numeric |
A - B | xs:date | xs:date | op:subtract-dates(A, B) | xs:dayTimeDuration |
A - B | xs:date | xs:yearMonthDuration | op:subtract-yearMonthDuration-from-date(A, B) | xs:date |
A - B | xs:date | xs:dayTimeDuration | op:subtract-dayTimeDuration-from-date(A, B) | xs:date |
A - B | xs:time | xs:time | op:subtract-times(A, B) | xs:dayTimeDuration |
A - B | xs:time | xs:dayTimeDuration | op:subtract-dayTimeDuration-from-time(A, B) | xs:time |
A - B | xs:dateTime | xs:dateTime | op:subtract-dateTimes(A, B) | xs:dayTimeDuration |
A - B | xs:dateTime | xs:yearMonthDuration | op:subtract-yearMonthDuration-from-dateTime(A, B) | xs:dateTime |
A - B | xs:dateTime | xs:dayTimeDuration | op:subtract-dayTimeDuration-from-dateTime(A, B) | xs:dateTime |
A - B | xs:yearMonthDuration | xs:yearMonthDuration | op:subtract-yearMonthDurations(A, B) | xs:yearMonthDuration |
A - B | xs:dayTimeDuration | xs:dayTimeDuration | op:subtract-dayTimeDurations(A, B) | xs:dayTimeDuration |
A * B | numeric | numeric | op:numeric-multiply(A, B) | numeric |
A * B | xs:yearMonthDuration | numeric | op:multiply-yearMonthDuration(A, B) | xs:yearMonthDuration |
A * B | numeric | xs:yearMonthDuration | op:multiply-yearMonthDuration(B, A) | xs:yearMonthDuration |
A * B | xs:dayTimeDuration | numeric | op:multiply-dayTimeDuration(A, B) | xs:dayTimeDuration |
A * B | numeric | xs:dayTimeDuration | op:multiply-dayTimeDuration(B, A) | xs:dayTimeDuration |
A idiv B | numeric | numeric | op:numeric-integer-divide(A, B) | xs:integer |
A div B | numeric | numeric | op:numeric-divide(A, B) | numeric; but xs:decimal if both operands are xs:integer |
A div B | xs:yearMonthDuration | numeric | op:divide-yearMonthDuration(A, B) | xs:yearMonthDuration |
A div B | xs:dayTimeDuration | numeric | op:divide-dayTimeDuration(A, B) | xs:dayTimeDuration |
A div B | xs:yearMonthDuration | xs:yearMonthDuration | op:divide-yearMonthDuration-by-yearMonthDuration (A, B) | xs:decimal |
A div B | xs:dayTimeDuration | xs:dayTimeDuration | op:divide-dayTimeDuration-by-dayTimeDuration (A, B) | xs:decimal |
A mod B | numeric | numeric | op:numeric-mod(A, B) | numeric |
A eq B | numeric | numeric | op:numeric-equal(A, B) | xs:boolean |
A eq B | xs:boolean | xs:boolean | op:boolean-equal(A, B) | xs:boolean |
A eq B | xs:string | xs:string | op:numeric-equal(fn:compare(A, B), 0) | xs:boolean |
A eq B | xs:date | xs:date | op:date-equal(A, B) | xs:boolean |
A eq B | xs:time | xs:time | op:time-equal(A, B) | xs:boolean |
A eq B | xs:dateTime | xs:dateTime | op:dateTime-equal(A, B) | xs:boolean |
A eq B | xs:duration | xs:duration | op:duration-equal(A, B) | xs:boolean |
A eq B | Gregorian | Gregorian | op:gYear-equal(A, B) etc. | xs:boolean |
A eq B | xs:hexBinary | xs:hexBinary | op:hex-binary-equal(A, B) | xs:boolean |
A eq B | xs:base64Binary | xs:base64Binary | op:base64-binary-equal(A, B) | xs:boolean |
A eq B | xs:anyURI | xs:anyURI | op:numeric-equal(fn:compare(A, B), 0) | xs:boolean |
A eq B | xs:QName | xs:QName | op:QName-equal(A, B) | xs:boolean |
A eq B | xs:NOTATION | xs:NOTATION | op:NOTATION-equal(A, B) | xs:boolean |
A ne B | numeric | numeric | fn:not(op:numeric-equal(A, B)) | xs:boolean |
A ne B | xs:boolean | xs:boolean | fn:not(op:boolean-equal(A, B)) | xs:boolean |
A ne B | xs:string | xs:string | fn:not(op:numeric-equal(fn:compare(A, B), 0)) | xs:boolean |
A ne B | xs:date | xs:date | fn:not(op:date-equal(A, B)) | xs:boolean |
A ne B | xs:time | xs:time | fn:not(op:time-equal(A, B)) | xs:boolean |
A ne B | xs:dateTime | xs:dateTime | fn:not(op:dateTime-equal(A, B)) | xs:boolean |
A ne B | xs:duration | xs:duration | fn:not(op:duration-equal(A, B)) | xs:boolean |
A ne B | Gregorian | Gregorian | fn:not(op:gYear-equal(A, B)) etc. | xs:boolean |
A ne B | xs:hexBinary | xs:hexBinary | fn:not(op:hex-binary-equal(A, B)) | xs:boolean |
A ne B | xs:base64Binary | xs:base64Binary | fn:not(op:base64-binary-equal(A, B)) | xs:boolean |
A ne B | xs:anyURI | xs:anyURI | fn:not(op:numeric-equal(fn:compare(A, B), 0)) | xs:boolean |
A ne B | xs:QName | xs:QName | fn:not(op:QName-equal(A, B)) | xs:boolean |
A ne B | xs:NOTATION | xs:NOTATION | fn:not(op:NOTATION-equal(A, B)) | xs:boolean |
A gt B | numeric | numeric | op:numeric-greater-than(A, B) | xs:boolean |
A gt B | xs:boolean | xs:boolean | op:boolean-greater-than(A, B) | xs:boolean |
A gt B | xs:string | xs:string | op:numeric-greater-than(fn:compare(A, B), 0) | xs:boolean |
A gt B | xs:date | xs:date | op:date-greater-than(A, B) | xs:boolean |
A gt B | xs:time | xs:time | op:time-greater-than(A, B) | xs:boolean |
A gt B | xs:dateTime | xs:dateTime | op:dateTime-greater-than(A, B) | xs:boolean |
A gt B | xs:yearMonthDuration | xs:yearMonthDuration | op:yearMonthDuration-greater-than(A, B) | xs:boolean |
A gt B | xs:dayTimeDuration | xs:dayTimeDuration | op:dayTimeDuration-greater-than(A, B) | xs:boolean |
A gt B | xs:anyURI | xs:anyURI | op:numeric-greater-than(fn:compare(A, B), 0) | xs:boolean |
A lt B | numeric | numeric | op:numeric-less-than(A, B) | xs:boolean |
A lt B | xs:boolean | xs:boolean | op:boolean-less-than(A, B) | xs:boolean |
A lt B | xs:string | xs:string | op:numeric-less-than(fn:compare(A, B), 0) | xs:boolean |
A lt B | xs:date | xs:date | op:date-less-than(A, B) | xs:boolean |
A lt B | xs:time | xs:time | op:time-less-than(A, B) | xs:boolean |
A lt B | xs:dateTime | xs:dateTime | op:dateTime-less-than(A, B) | xs:boolean |
A lt B | xs:yearMonthDuration | xs:yearMonthDuration | op:yearMonthDuration-less-than(A, B) | xs:boolean |
A lt B | xs:dayTimeDuration | xs:dayTimeDuration | op:dayTimeDuration-less-than(A, B) | xs:boolean |
A lt B | xs:anyURI | xs:anyURI | op:numeric-less-than(fn:compare(A, B), 0) | xs:boolean |
A ge B | numeric | numeric | op:numeric-greater-than(A, B) or op:numeric-equal(A, B) | xs:boolean |
A ge B | xs:boolean | xs:boolean | fn:not(op:boolean-less-than(A, B)) | xs:boolean |
A ge B | xs:string | xs:string | op:numeric-greater-than(fn:compare(A, B), -1) | xs:boolean |
A ge B | xs:date | xs:date | fn:not(op:date-less-than(A, B)) | xs:boolean |
A ge B | xs:time | xs:time | fn:not(op:time-less-than(A, B)) | xs:boolean |
A ge B | xs:dateTime | xs:dateTime | fn:not(op:dateTime-less-than(A, B)) | xs:boolean |
A ge B | xs:yearMonthDuration | xs:yearMonthDuration | fn:not(op:yearMonthDuration-less-than(A, B)) | xs:boolean |
A ge B | xs:dayTimeDuration | xs:dayTimeDuration | fn:not(op:dayTimeDuration-less-than(A, B)) | xs:boolean |
A ge B | xs:anyURI | xs:anyURI | op:numeric-greater-than(fn:compare(A, B), -1) | xs:boolean |
A le B | numeric | numeric | op:numeric-less-than(A, B) or op:numeric-equal(A, B) | xs:boolean |
A le B | xs:boolean | xs:boolean | fn:not(op:boolean-greater-than(A, B)) | xs:boolean |
A le B | xs:string | xs:string | op:numeric-less-than(fn:compare(A, B), 1) | xs:boolean |
A le B | xs:date | xs:date | fn:not(op:date-greater-than(A, B)) | xs:boolean |
A le B | xs:time | xs:time | fn:not(op:time-greater-than(A, B)) | xs:boolean |
A le B | xs:dateTime | xs:dateTime | fn:not(op:dateTime-greater-than(A, B)) | xs:boolean |
A le B | xs:yearMonthDuration | xs:yearMonthDuration | fn:not(op:yearMonthDuration-greater-than(A, B)) | xs:boolean |
A le B | xs:dayTimeDuration | xs:dayTimeDuration | fn:not(op:dayTimeDuration-greater-than(A, B)) | xs:boolean |
A le B | xs:anyURI | xs:anyURI | op:numeric-less-than(fn:compare(A, B), 1) | xs:boolean |
A is B | node() | node() | op:is-same-node(A, B) | xs:boolean |
A << B | node() | node() | op:node-before(A, B) | xs:boolean |
A >> B | node() | node() | op:node-after(A, B) | xs:boolean |
A union B | node()* | node()* | op:union(A, B) | node()* |
A | B | node()* | node()* | op:union(A, B) | node()* |
A intersect B | node()* | node()* | op:intersect(A, B) | node()* |
A except B | node()* | node()* | op:except(A, B) | node()* |
A to B | xs:integer | xs:integer | op:to(A, B) | xs:integer* |
A , B | item()* | item()* | op:concatenate(A, B) | item()* |
Operator | Operand type | Function | Result type |
---|---|---|---|
+ A | numeric | op:numeric-unary-plus(A) | numeric |
- A | numeric | op:numeric-unary-minus(A) | numeric |
The tables in this section describe the scope (range ofapplicability) of the various components in the static context anddynamic context.
The following table describes the components of thestaticcontext. For each component, "global" indicates that the valueof the component applies throughout an XPath expression, whereas"lexical" indicates that the value of the component applies onlywithin the subexpression in which it is defined.
Component | Scope |
---|---|
XPath 1.0 Compatibility Mode | global |
Statically known namespaces | global |
Default element/type namespace | global |
Default function namespace | global |
In-scope schema types | global |
In-scope element declarations | global |
In-scope attribute declarations | global |
In-scope variables | lexical; for-expressions and quantified expressions can bindnew variables |
Context item static type | lexical |
Function signatures | global |
Statically known collations | global |
Default collation | global |
Base URI | global |
Statically known documents | global |
Statically known collections | global |
Statically known default collection type | global |
The following table describes how values are assigned to thevarious components of thedynamic context. All thesecomponents are initialized by mechanisms defined by the hostlanguage. For each component, "global" indicates that the value ofthe component remains constant throughout evaluation of the XPathexpression, whereas "dynamic" indicates that the value of thecomponent can be modified by the evaluation of subexpressions.
Component | Scope |
---|---|
Context item | dynamic; changes during evaluation of path expressions andpredicates |
Context position | dynamic; changes during evaluation of path expressions andpredicates |
Context size | dynamic; changes during evaluation of path expressions andpredicates |
Variable values | dynamic; for-expressions and quantified expressions can bindnew variables |
Current date and time | global; must be initialized by implementation |
Implicit timezone | global; must be initialized by implementation |
Available documents | global; must be initialized by implementation |
Available collections | global; must be initialized by implementation |
Default collection | global; overwriteable by implementation |
The following items in this specification areimplementation-defined:
The version of Unicode that is used to constructexpressions.
Theimplicittimezone.
The circumstances in whichwarnings are raised, and the ways in whichwarnings are handled.
The method by which errors are reported to the externalprocessing environment.
Whether the implementation is based on the rules of[XML 1.0] and[XML Names] or therules of[XML 1.1] and[XML Names 1.1]. One of these sets of rules mustbe applied consistently by all aspects of the implementation. Ifthe implementation is based on the rules of[XML1.0], the edition used must be at least Third Edition; theedition used isimplementation-defined, but werecommend that implementations use the latest version.
Whether the implementation supports the namespace axis.
Anystatic typing extensionssupported by the implementation, if theStatic Typing Feature issupported.
Note:
Additionalimplementation-defined items arelisted in[XQuery 1.0 and XPath 2.0 Data Model(Second Edition)] and[XQuery1.0 and XPath 2.0 Functions and Operators (SecondEdition)].
XPath is intended primarily as a component that can be used byother specifications. Therefore, XPath relies on specificationsthat use it (such as[XPointer] and[XSL Transformations (XSLT) Version 2.0 (SecondEdition)]) to specify conformance criteria for XPath in theirrespective environments. Specifications that set conformancecriteria for their use of XPath must not change the syntactic orsemantic definitions of XPath as given in this specification,except by subsetting and/or compatible extensions.
The specification of such a language may describe it as anextension of XPath provided that every expression that conforms tothe XPath grammar behaves as described in this specification.
[Definition: TheStatic TypingFeature is an optional feature of XPath that provides supportfor the static semantics defined in[XQuery 1.0 and XPath 2.0 Formal Semantics(Second Edition)], and requires implementations to detect andreporttype errorsduring thestatic analysis phase.] Specificationsthat use XPath may specify conformance criteria for use of theStatic Typing Feature.
If an implementation does not support theStatic Typing Feature, butcan nevertheless determine during the static analysis phase that anexpression will necessarily raise a type error if evaluated at runtime, the implementation may raise that error during the staticanalysis phase. The choice of whether to raise such an error atanalysis time isimplementation dependent.
In some cases, the static typing rules defined in[XQuery 1.0 and XPath 2.0 Formal Semantics(Second Edition)] are not very precise (see, for example, thetype inference rules for the ancestor axes—parent, ancestor, andancestor-or-self—and for the functionfn:root
). Someimplementations may wish to support more precise static typingrules.
A conforming implementation that implements theStatic Typing Feature mayalso provide one or morestatic typing extensions. [Definition: Astatic typingextension is animplementation-defined typeinference rule that infers a more precise static type than thatinferred by the type inference rules in[XQuery 1.0 and XPath 2.0 Formal Semantics(Second Edition)].] SeeSection6.1.1 Static Typing ExtensionsFS fora formal definition of the constraints on static typingextensions.
It is astaticerror if analysis of an expression relies on some component ofthestaticcontext that has not been assigned a value.
It is adynamic error if evaluation of anexpression relies on some part of thedynamic context that has not beenassigned a value.
It is astaticerror if an expression is not a valid instance of the grammardefined inA.1 EBNF.
It is atypeerror if, during thestatic analysis phase, an expression isfound to have astatic type that is not appropriate for thecontext in which the expression occurs, or during thedynamicevaluation phase, thedynamic type of a value does not match arequired type as specified by the matching rules in2.5.4 SequenceTypeMatching.
During the analysis phase, it is astatic error if thestatic type assigned to an expressionother than the expression()
ordata(())
isempty-sequence()
.
(Not currently used.)
(Not currently used.)
It is astaticerror if an expression refers to an element name, attributename, schema type name, namespace prefix, or variable name that isnot defined in thestatic context, except for an ElementNamein anElementTest or anAttributeName in anAttributeTest.
An implementation must raise astatic error if it encounters a reference toan axis that it does not support.
It is astaticerror if the expanded QName and number of arguments in afunction call do not match the name and arity of afunctionsignature in thestatic context.
It is atypeerror if the result of the last step in a path expressioncontains both nodes and atomic values.
It is atypeerror if the result of a step (other than the last step) in apath expression contains an atomic value.
It is atypeerror if, in an axis step, the context item is not a node.
(Not currently used.)
It is adynamic error if thedynamic type of theoperand of atreat
expression does not match thesequence typespecified by thetreat
expression. This error mightalso be raised by a path expression beginning with "/
"or "//
" if the context node is not in a tree that isrooted at a document node. This is because a leading"/
" or "//
" in a path expression is anabbreviation for an initial step that includes the clausetreat as document-node()
.
It is astaticerror if a QName that is used as anAtomicType in aSequenceType is not defined in thein-scope schematypes as an atomic type.
It is astaticerror if the target type of acast
orcastable
expression isxs:NOTATION
orxs:anyAtomicType
.
It is astaticerror if a QName used inan expression contains a namespace prefixthat cannot be expanded into a namespace URI by using thestatically known namespaces.
(Not currently used.)
In the operator mapping tables, the termGregorian refersto the typesxs:gYearMonth
,xs:gYear
,xs:gMonthDay
,xs:gDay
, andxs:gMonth
.
Lexically, aQName consists of an optional namespaceprefix and a local name. If the namespace prefix is present, it isseparated from the local name by a colon.
During evaluation of an expression, it is sometimes necessary todetermine whether a value with a knowndynamic type "matches" an expectedsequencetype. This process is known asSequenceTypematching.
Within this specification, the termURI refers to aUniversal Resource Identifier as defined in[RFC3986] and extended in[RFC3987] with the new nameIRI.
The termXDM instance is used, synonymously with the termvalue, to denote an unconstrained sequence ofnodes and/oratomic values in thedata model.
XPath 1.0 compatibility mode.This value istrue
ifrules for backward compatibility with XPath Version 1.0 are ineffect; otherwise it isfalse
.
Anatomic value is a value in the value space of anatomic type, as defined in[XMLSchema].
Atomization of a sequence is defined as the result ofinvoking thefn:data
function on the sequence, asdefined in[XQuery 1.0 and XPath2.0 Functions and Operators (Second Edition)].
Available collections. This is a mapping of strings ontosequences of nodes. The string represents the absolute URI of aresource. The sequence of nodes represents the result of thefn:collection
function when that URI is supplied asthe argument.
Available documents. This is a mapping of strings ontodocument nodes. The string represents the absolute URI of aresource. The document node is the root of a tree that representsthat resource using thedata model. The document node is returned bythefn:doc
function when applied to that URI.
Anaxis step returns a sequence of nodes that arereachable from the context node via a specified axis. Such a stephas two parts: anaxis, which defines the "direction ofmovement" for the step, and anode test, which selects nodes based on theirkind, name, and/ortype annotation.
Base URI. This is an absolute URI, used when necessary inthe resolution of relative URIs (for example, by thefn:resolve-uri
function.)
Thebuilt-in functions supported by XPath are defined in[XQuery 1.0 and XPath 2.0Functions and Operators (Second Edition)].
Acollation is a specification of the manner in whichstrings and URIs are compared and, by extension, ordered. For amore complete definition of collation, see[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
One way to construct a sequence is by using thecommaoperator, which evaluates each of its operands and concatenatesthe resulting sequences, in order, into a single resultsequence.
Theconstructor function for a given type is used toconvert instances of other atomic types into the given type. Thesemantics of the constructor function callT($arg)
aredefined to be equivalent to the expression(($arg) cast asT?)
.
Thecontext item is the item currently being processed.An item is either an atomic value or a node.
Context item static type. This component defines thestatic type ofthe context item within the scope of a given expression.
When the context item is a node, it can also be referred to asthecontext node.
Thecontext position is the position of the context itemwithin the sequence of items currently being processed.
Thecontext size is the number of items in the sequenceof items currently being processed.
Current dateTime. This information represents animplementation-dependent pointin time during the processing ofan expression, and includes an explicittimezone. It can be retrieved by thefn:current-dateTime
function. If invoked multipletimes during the execution ofan expression, this function always returnsthe same result.
XPath operates on the abstract, logical structure of an XMLdocument, rather than its surface syntax. This logical structure,known as thedata model, is defined in[XQuery 1.0 and XPath 2.0 Data Model (SecondEdition)].
For a given node in anXDM instance, thedata modelschema is defined as the schema from which thetype annotation ofthat node was derived.
Default collation. This identifies one of the collationsinstatically known collations as thecollation to be used by functions and operators for comparing andordering values of typexs:string
andxs:anyURI
(and types derived from them) when noexplicit collation is specified.
Default collection. This is the sequence of nodes thatwould result from calling thefn:collection
functionwith no arguments.
Default element/type namespace. This is a namespace URIor "none". The namespace URI, if present, is used for anyunprefixed QName appearing in a position where an element or typename is expected.
Default function namespace. This is a namespace URI or"none". The namespace URI, if present, is used for any unprefixedQName appearing in a position where a function name isexpected.
Thedelimiting terminal symbols are: "!=",StringLiteral, "$", "(", ")", "*","+", (comma), "-", (dot), "..", "/", "//", (colon), "::", "<","<<", "<=", "=", ">", ">=", ">>", "?", "@","[", "]", "|"
Informally,document order is the order in which nodesappear in the XML serialization of a document.
Thedynamic context of an expression is defined asinformation that is available at the time the expression isevaluated.
Adynamic error is an error that must be detected duringthe dynamic evaluation phase and may be detected during the staticanalysis phase. Numeric overflow is an example of a dynamicerror.
Thedynamic evaluation phase is the phase during whichthe value of an expression is computed.
Adynamic type is associated with each value as it iscomputed. The dynamic type of a value may be more specific than thestatic type ofthe expression that computed it (for example, the static type of anexpression might bexs:integer*
, denoting a sequenceof zero or more integers, but at evaluation time its value may havethe dynamic typexs:integer
, denoting exactly oneinteger.)
Theeffective boolean value of a value is defined as theresult of applying thefn:boolean
function to thevalue, as defined in[XQuery 1.0and XPath 2.0 Functions and Operators (Second Edition)].
A sequence containing zero items is called anemptysequence.
In addition to its identifying QName, a dynamic error may alsocarry a descriptive string and one or more additional values callederror values.
Anexpanded QName consists of an optional namespace URIand a local name. An expanded QName also retains its originalnamespace prefix (if any), to facilitate casting the expanded QNameinto a string.
Theexpression context for a given expression consists ofall the information that can affect the result of theexpression.
Afilter expression consists simply of aprimaryexpression followed by zero or morepredicates. The result of the filter expressionconsists of the items returned by the primary expression, filteredby applying each predicate in turn, working from left to right.
The first three components of thedynamic context (context item,context position, and context size) are called thefocus ofthe expression.
Function implementations. Each function infunctionsignatures has a function implementation that enables thefunction to map instances of its parameter types into an instanceof its result type.
Function signatures. This component defines the set offunctions that are available to be called from within anexpression. Each function is uniquely identified by itsexpanded QName andits arity (number of parameters).
Ignorable whitespace consists of anywhitespace characters that mayoccur betweenterminals,unless these characters occur in the context of a production markedwith aws:explicitannotation, in which case they can occur only where explicitlyspecified (seeA.2.4.2Explicit Whitespace Handling).
Implementation-dependent indicates an aspect that maydiffer between implementations, is not specified by this or any W3Cspecification, and is not required to be specified by theimplementor for any particular implementation.
Implementation-defined indicates an aspect that maydiffer between implementations, but must be specified by theimplementor for each particular implementation.
Implicit timezone. This is the timezone to be used when adate, time, or dateTime value that does not have a timezone is usedin a comparison or arithmetic operation. The implicit timezone isanimplementation-defined value oftypexs:dayTimeDuration
. See[XMLSchema] for the range of legal values of a timezone.
In-scope attribute declarations. Each attributedeclaration is identified either by anexpanded QName (for a top-levelattribute declaration) or by animplementation-dependentattribute identifier (for a local attribute declaration).
In-scope element declarations. Each element declarationis identified either by anexpanded QName (for a top-level elementdeclaration) or by animplementation-dependent elementidentifier (for a local element declaration).
Thein-scope namespaces property of an element node is aset ofnamespace bindings, each of which associates anamespace prefix with a URI, thus defining the set of namespaceprefixes that are available for interpreting QNames within thescope of the element. For a given element, one namespace bindingmay have an empty prefix; the URI of this namespace binding is thedefault namespace within the scope of the element.
In-scope schema definitions. This is a generic term forall the element declarations, attribute declarations, and schematype definitions that are in scope during processing of anexpression.
In-scope schema types. Each schema type definition isidentified either by anexpanded QName (for anamed type)or by animplementation-dependent typeidentifier (for ananonymous type). The in-scope schematypes include the predefined schema types described in2.5.1 Predefined SchemaTypes.
In-scope variables. This is a set of (expanded QName,type) pairs. It defines the set of variables that are available forreference within an expression. Theexpanded QName is the name of thevariable, and the type is thestatic type of the variable.
Anitem is either anatomic value or anode.
An alternative form of a node test called akind test canselect nodes based on their kind, name, andtypeannotation.
Aliteral is a direct syntactic representation of anatomic value.
A node test that consists only of a QName or a Wildcard iscalled aname test.
Anode is an instance of one of thenode kindsdefined in[XQuery 1.0 and XPath 2.0 DataModel (Second Edition)].
Anode test is a condition that must be true for eachnode selected by astep.
Thenon-delimiting terminal symbols are:IntegerLiteral,NCName,DecimalLiteral,DoubleLiteral,QName, "ancestor", "ancestor-or-self","and", "as", "attribute", "cast", "castable", "child", "comment","descendant", "descendant-or-self", "div", "document-node","element", "else", "empty-sequence", "eq", "every", "except","external", "following", "following-sibling", "for", "ge", "gt","idiv", "if", "in", "instance", "intersect", "is", "item", "le","lt", "mod", "namespace", "ne", "node", "of", "or", "parent","preceding", "preceding-sibling", "processing-instruction","return", "satisfies", "schema-attribute", "schema-element","self", "some", "text", "then", "to", "treat", "union"
When referring to a type, the termnumeric denotes thetypesxs:integer
,xs:decimal
,xs:float
, andxs:double
.
A predicate whose predicate expression returns a numeric type iscalled anumeric predicate.
For each operator and valid combination of operand types, theoperator mapping tables specify a result type and anoperatorfunction that implements the semantics of the operator for thegiven types.
Apath expression can be used to locate nodes withintrees. A path expression consists of a series of one or moresteps, separated by"/
" or "//
", and optionally beginningwith "/
" or "//
".
Apredicate consists of an expression, called apredicate expression, enclosed in square brackets. Apredicate serves to filter a sequence, retaining some items anddiscarding others.
Primary expressions are the basic primitives of thelanguage. They include literals, variable references, context itemexpressions, and function calls. A primary expression may also becreated by enclosing any expression in parentheses, which issometimes helpful in controlling the precedence of operators.
Every axis has aprincipal node kind. If an axis cancontain elements, then the principal node kind is element;otherwise, it is the kind of nodes that the axis can contain.
The node ordering that is the reverse of document order iscalledreverse document order.
Aschema type is a type that is (or could be) definedusing the facilities of[XML Schema](including the built-in types of[XMLSchema]).
Asequence is an ordered collection of zero or moreitems.
Asequence type is a type that can be expressed using theSequenceType syntax. Sequencetypes are used whenever it is necessary to refer to a type in anXPath expression. The termsequence type suggests that thissyntax is used to describe the type of an XPath value, which isalways a sequence.
Serialization is the process of converting anXDM instance intoa sequence of octets (step DM4 in Figure 1.)
A sequence containing exactly one item is called asingleton.
Document order isstable, which means that the relativeorder of two nodes will not change during the processing of a givenexpression,even if this order isimplementation-dependent.
Thestatic analysis phase depends on the expressionitself and on thestatic context. Thestatic analysisphase does not depend on input data (other than schemas).
Thestatic context of an expression is the informationthat is available during static analysis of the expression, priorto its evaluation.
Astatic error is an error that must be detected duringthe static analysis phase. A syntax error is an example of astaticerror.
Thestatic type of an expression is a type such that,when the expression is evaluated, the resulting value will alwaysconform to the static type.
Astatic typing extension is animplementation-defined typeinference rule that infers a more precise static type than thatinferred by the type inference rules in[XQuery 1.0 and XPath 2.0 Formal Semantics(Second Edition)].
TheStatic Typing Feature is an optional feature of XPaththat provides support for the static semantics defined in[XQuery 1.0 and XPath 2.0 Formal Semantics(Second Edition)], and requires implementations to detect andreporttype errorsduring thestatic analysis phase.
Statically known collections. This is a mapping fromstrings onto types. The string represents the absolute URI of aresource that is potentially available using thefn:collection
function. The type is the type of thesequence of nodes that would result from calling thefn:collection
function with this URI as itsargument.
Statically known documents. This is a mapping fromstrings onto types. The string represents the absolute URI of aresource that is potentially available using thefn:doc
function. The type is thestatic type of a call tofn:doc
with the given URI as its literal argument.
Statically known collations. This is animplementation-defined set of(URI, collation) pairs. It defines the names of the collations thatare available for use in processing expressions.
Statically known default collection type. This is thetype of the sequence of nodes that would result from calling thefn:collection
function with no arguments.
Statically known namespaces. This is a set of (prefix,URI) pairs that define all the namespaces that are known duringstatic processing of a given expression.
Astep is a part of apath expression that generates a sequenceof items and then filters the sequence by zero or morepredicates. The value of thestep consists of those items that satisfy the predicates, workingfrom left to right. A step may be either anaxis step or afilterexpression.
Thestring value of a node is a string and can beextracted by applying thefn:string
function to thenode.
Substitution groups are defined in[XML Schema] Part 1, Section 2.2.2.2. Informally,the substitution group headed by a given element (called thehead element) consists of the set of elements that can besubstituted for the head element without affecting the outcome ofschema validation.
The use of a value whosedynamic type is derived from an expectedtype is known assubtype substitution.
Each rule in the grammar defines onesymbol, using thefollowing format:
symbol ::= expression
Whitespace andComments function assymbolseparators. For the most part, they are not mentioned in thegrammar, and may occur between any two terminal symbols mentionedin the grammar, except where that is forbidden by the/* ws: explicit */ annotation in the EBNF, or bythe/* xgs: xml-version */annotation.
Aterminal is a symbol or string or pattern that canappear in the right-hand side of a rule, but never appears on theleft hand side in the main grammar, although it may appear on theleft-hand side of a rule in the grammar for terminals.
Each element node and attribute node in anXDM instance hasatype annotation (referred to in[XQuery 1.0 and XPath 2.0 Data Model (SecondEdition)] as itstype-name
property.) The typeannotation of a node is aschema type that describes the relationshipbetween thestringvalue of the node and itstyped value.
Atype error may be raised during the static analysisphase or the dynamic evaluation phase. During the static analysisphase, atype erroroccurs when thestatic type of an expression does not matchthe expected type of the context in which the expression occurs.During the dynamic evaluation phase, atype error occurs when thedynamic type of a valuedoes not match the expected type of the context in which the valueoccurs.
Under certain circumstances, an atomic value can be promotedfrom one type to another.Type promotion is used inevaluating function calls (see3.1.5 Function Calls) and operatorsthat accept numeric or string operands (seeB.2 Operator Mapping).
Thetyped value of a node is a sequence of atomic valuesand can be extracted by applying thefn:data
functionto the node.
In certain situations a value is said to beundefined(for example, the value of the context item, or the typed value ofan element node). This term indicates that the property in questionhas no value and that any attempt to use its value results in anerror.
Avariable reference is a QName preceded by a $-sign.
Variable values. This is a set of (expanded QName, value)pairs. It contains the sameexpanded QNames as thein-scopevariables in thestatic context for the expression. Theexpanded QName is the name of the variable and the value is thedynamic value of the variable, which includes itsdynamic type.
In addition tostatic errors,dynamic errors, andtype errors, an XPathimplementation may raisewarnings, either during thestaticanalysis phase or thedynamic evaluation phase. Thecircumstances in which warnings are raised, and the ways in whichwarnings are handled, areimplementation-defined.
Awhitespace character is any of the characters definedby[http://www.w3.org/TR/REC-xml/#NT-S].
xs:anyAtomicType
is an atomic type that includesall atomic values (and no values that are not atomic). Its basetype isxs:anySimpleType
from which all simple types,including atomic, list, and union types, are derived. All primitiveatomic types, such asxs:decimal
andxs:string
, havexs:anyAtomicType
as theirbase type.
xs:dayTimeDuration
is derived by restriction fromxs:duration
. The lexical representation ofxs:dayTimeDuration
is restricted to contain only day,hour, minute, and second components.
xs:untyped
is used as thetype annotation ofan element node that has not been validated, or has been validatedinskip
mode.
xs:untypedAtomic
is an atomic type that is used todenote untyped atomic data, such as text that has not been assigneda more specific type.
xs:yearMonthDuration
is derived by restriction fromxs:duration
. The lexical representation ofxs:yearMonthDuration
is restricted to contain onlyyear and month components.
This appendix provides a summary of the areas of incompatibilitybetween XPath 2.0 and[XPath 1.0].
Three separate cases are considered:
Incompatibilities that exist when source documents have noschema, and when running with XPath 1.0 compatibility mode set totrue. This specification has been designed to reduce the number ofincompatibilities in this situation to an absoluteminimum, but some differences remain and are listedindividually.
Incompatibilities that arise when XPath 1.0 compatibility modeis set to false. In this case, the number of expressions wherecompatibility is lost is rather greater.
Incompatibilities that arise when the source document isprocessed using a schema (whether or not XPath 1.0 compatibilitymode is set to true). Processing the document with a schema changesthe way that the values of nodes are interpreted, and this cancause an XPath expression to return different results.
The list below contains all known areas, within the scope ofthis specification, where an XPath 2.0 processor running withcompatibility mode set to true will produce different results froman XPath 1.0 processor evaluating the same expression, assumingthat the expression was valid in XPath 1.0, and that the nodes inthe source document have no type annotations other thanxs:untyped
andxs:untypedAtomic
.
Incompatibilities in the behavior of individual functions arenot listed here, but are included in an appendix of[XQuery 1.0 and XPath 2.0 Functions andOperators (Second Edition)].
Since both XPath 1.0 and XPath 2.0 leave some aspects of thespecification implementation-defined, there may be incompatiblitiesin the behavior of a particular implementation that are outside thescope of this specification. Equally, some aspects of the behaviorof XPath are defined by the host language.
Consecutive comparison operators such asA < B <C
were supported in XPath 1.0, but are not permitted by theXPath 2.0 grammar. In most cases such comparisons in XPath 1.0 didnot have the intuitive meaning, so it is unlikely that they havebeen widely used in practice. If such a construct is found, anXPath 2.0 processor will report a syntax error, and the constructcan be rewritten as(A < B) < C
When converting strings to numbers (either explicitly when usingthenumber
function, or implicitly say on a functioncall), certain strings that converted to the special valueNaN
under XPath 1.0 will convert to values other thanNaN
under XPath 2.0. These include any number writtenwith a leading+
sign, any number in exponentialfloating point notation (for example1.0e+9
), and thestringsINF
and-INF
.
Furthermore, the stringsInfinity
and-Infinity
, which were accepted by XPath 1.0 asrepresentations of the floating-point values positive and negativeinfinity, are no longer recognized. They are converted toNaN
when running under XPath 2.0 with compatibilitymode set to true, and cause a dynamic error when compatibility modeis set to false.
XPath 2.0 does not allow a token starting with a letter tofollow immediately after a numeric literal, without interveningwhitespace. For example,10div 3
was permitted inXPath 1.0, but in XPath 2.0 must be written as10 div3
.
The namespace axis is deprecated in XPath 2.0. Implementationsmay support the namespace axis for backward compatibility withXPath 1.0, but they are not required to do so. (XSLT 2.0 requiresthat if XPath backwards compatibility mode is supported, then thenamespace axis must also be supported; but other host languages maydefine the conformance rules differently.)
If one operand in a general comparison is a single atomic valueof typexs:boolean
, the other operand is converted toxs:boolean
when XPath 1.0 compatibility mode is set totrue. In XPath 1.0, if neither operand of a comparison operationusing the <, <=, > or >= operator was a node set, bothoperands were converted to numbers. The result of the expressiontrue() > number('0.5')
is therefore true in XPath1.0, but is false in XPath 2.0 even when compatibility mode is setto true.
In XPath 2.0, a type error is raised if, for a PITargetspecified in a SequenceType of formprocessing-instruction(N)
,fn:normalize-space(N) is not in the lexical space ofNCName. In XPath 1.0, this condition was not treated as anerror.
In XPath 1.0, the expression-x|y
parsed as-(x|y)
, and returned the negation of the numeric valueof the first node in the union ofx
andy
. In XPath 2.0, this expression parses as(-x)|y
. When XPath 1.0 Compatibility Mode is true,this will always cause a type error.
The rules for converting numbers to strings have changed. Thesemay affect the way numbers are displayed in the output of astylesheet. For numbers whose absolute value is in the range1E-6
to1E+6
, the result should be thesame, but outside this range, scientific format is used fornon-integralxs:float
andxs:double
values.
Even when the setting of the XPath 1.0 compatibility mode isfalse, many XPath expressions will still produce the same resultsunder XPath 2.0 as under XPath 1.0. The exceptions are described inthis section.
In all cases it is assumed that the expression in question wasvalid under XPath 1.0, that XPath 1.0 compatibility mode is false,and that all elements and attributes are annotated with the typesxs:untyped
andxs:untypedAtomic
respectively.
In the description below, the termsnode-set andnumber are used with their XPath 1.0 meanings, that is, todescribe expressions which according to the rules of XPath 1.0would have generated a node-set or a number respectively.
When a node-set containing more than one node is supplied as anargument to a function or operator that expects a single node orvalue, the XPath 1.0 rule was that all nodes after the first werediscarded. Under XPath 2.0, a type error occurs if there is morethan one node. The XPath 1.0 behavior can always be restored byusing the predicate[1]
to explicitly select the firstnode in the node-set.
In XPath 1.0, the<
and>
operators, when applied to two strings, attempted to convert boththe strings to numbers and then made a numeric comparison betweenthe results. In XPath 2.0, these operators perform a stringcomparison using the default collating sequence. (If either valueis numeric, however, the results are compatible with XPath 1.0)
When an empty node-set is supplied as an argument to a functionor operator that expects a number, the value is no longer convertedimplicitly to NaN. The XPath 1.0 behavior can always be restored byusing thenumber
function to perform an explicitconversion.
More generally, the supplied arguments to a function or operatorare no longer implicitly converted to the required type, except inthe case where the supplied argument is of typexs:untypedAtomic
(which will commonly be the case whena node in a schemaless document is supplied as the argument). Forexample, the function callsubstring-before(10 div 3,".")
raises a type error under XPath 2.0, because thearguments to thesubstring-before
function must bestrings rather than numbers. The XPath 1.0 behavior can be restoredby performing an explicit conversion to the required type using aconstructor function or cast.
The rules for comparing a node-set to a boolean have changed. InXPath 1.0, an expression such as$node-set = true()
was evaluated by converting the node-set to a boolean and thenperforming a boolean comparison: so this expression would returntrue
if$node-set
was non-empty. In XPath2.0, this expression is handled in the same way as othercomparisons between a sequence and a singleton: it istrue
if$node-set
contains at least onenode whose value, after atomization and conversion to a booleanusing the casting rules, istrue
.
This means that if$node-set
is empty, the resultunder XPath 2.0 will befalse
regardless of the valueof the boolean operand, and regardless of which operator is used.If$node-set
is non-empty, then in most cases thecomparison with a boolean is likely to fail, giving a dynamicerror. But if a node has the value "0", "1", "true", or "false",evaluation of the expression may succeed.
Comparisons of a number to a boolean, a number to a string, or astring to a boolean are not allowed in XPath 2.0: they result in atype error. In XPath 1.0 such comparisons were allowed, and werehandled by converting one of the operands to the type of the other.So for example in XPath 1.04 = true()
was true;4 = "+4"
was false (because the string+4
converts toNaN
), andfalse = "false"
wasfalse (because the string"false"
converts to thebooleantrue
). In XPath 2.0 all these comparisons aretype errors.
Additional numeric types have been introduced, with the effectthat arithmetic may now be done as an integer, decimal, or single-or double-precision floating point calculation where previously itwas always performed as double-precision floating point. The resultof thediv
operator when dividing two integers is nowa value of type decimal rather than double. The expression10div 0
raises an error rather than returning positiveinfinity.
The rules for converting strings to numbers have changed. Theimplicit conversion that occurs when passing anxs:untypedAtomic
value as an argument to a functionthat expects a number no longer converts unrecognized strings tothe valueNaN
; instead, it reports a dynamic error.This is in addition to the differences that apply when backwardscompatibility mode is set to true.
Many operations in XPath 2.0 produce an empty sequence as theirresult when one of the arguments or operands is an empty sequence.Where the operation expects a string, an empty sequence is usuallyconsidered equivalent to a zero-length string, which is compatiblewith the XPath 1.0 behavior. Where the operation expects a number,however, the result is not the same. For example, if@width
returns an empty sequence, then in XPath 1.0the result of@width+1
wasNaN
, whilewith XPath 2.0 it is()
. This has the effect that afilter expression such asitem[@width+1 != 2]
willselect items having nowidth
attribute under XPath1.0, and will not select them under XPath 2.0.
The typed value of a comment node, processing instruction node,or namespace node under XPath 2.0 is of typexs:string
, notxs:untypedAtomic
. Thismeans that no implicit conversions are applied if the value is usedin a context where a number is expected. If aprocessing-instruction node is used as an operand of an arithmeticoperator, for example, XPath 1.0 would attempt to convert thestring value of the node to a number (and deliverNaN
if unsuccessful), while XPath 2.0 will report a type error.
In XPath 1.0, it was defined that with an expression of the formA and B
, B would not be evaluated if A was false.Similarly in the case ofA or B
, B would not beevaluated if A was true. This is no longer guaranteed with XPath2.0: the implementation is free to evaluate the two operands ineither order or in parallel. This change has been made to give morescope for optimization in situations where XPath expressions areevaluated against large data collections supported by indexes.Implementations may choose to retain backwards compatibility inthis area, but they are not obliged to do so.
In XPath 1.0, the expression-x|y
parsed as-(x|y)
, and returned the negation of the numeric valueof the first node in the union ofx
andy
. In XPath 2.0, this expression parses as(-x)|y
. When XPath 1.0 Compatibility Mode is false,this will cause a type error, except in the situation wherex
evaluates to an empty sequence. In that situation,XPath 2.0 will return the value ofy
, whereas XPath1.0 returned the negation of the numeric value ofy
.
An XPath expression applied to a document that has beenprocessed against a schema will not always give the same results asthe same expression applied to the same document in the absence ofa schema. Since schema processing had no effect on the result of anXPath 1.0 expression, this may give rise to furtherincompatibilities. This section gives a few examples of thedifferences that can arise.
Suppose that the context node is an element node derived fromthe following markup:<background color="red greenblue"/>
. In XPath 1.0, the predicate[@color="blue"]
would returnfalse
. InXPath 2.0, if thecolor
attribute is defined in aschema to be of typexs:NMTOKENS
, the same predicatewill returntrue
.
Similarly, consider the expression@birth <@death
applied to the element<personbirth="1901-06-06" death="1991-05-09"/>
. With XPath 1.0,this expression would return false, because both attributes areconverted to numbers, which returnsNaN
in each case.With XPath 2.0, in the presence of a schema that annotates theseattributes as dates, the expression returnstrue
.
Once schema validation is applied, elements and attributescannot be used as operands and arguments of expressions that expecta different data type. For example, it is no longer possible toapply thesubstring
function to a date to extract theyear component, or to a number to extract the integer part.Similarly, if an attribute is annotated as a boolean then it is notpossible to compare it with the strings"true"
or"false"
. All such operations lead to type errors. Theremedy when such errors occur is to introduce an explicitconversion, or to do the computation in a different way. Forexample,substring-after(@temperature, "-")
might berewritten asabs(@temperature)
.
In the case of an XPath 2.0 implementation that provides thestatic typing feature, many further type errors will be reported inrespect of expressions that worked under XPath 1.0. For example, anexpression such asround(../@price)
might lead to astatic type error because the processor cannot infer staticallythat../@price
is guaranteed to be numeric.
Schema validation will in many cases perform whitespacenormalization on the contents of elements (depending on theirtype). This will change the result of operations such as thestring-length
function.
Schema validation augments the data model by adding defaultvalues for omitted attributes and empty elements.
This version of the XPath specification wascreated by applying the errata fromErratafor XML Path Language (XPath) 2.0 to theXPath 2.0Recommendation. No other substantive changes have beenmade.
Erratum | Bugzilla | Category | Description |
XP.E1 | 4298 | editorial | Spelling mistake: minimum |
XP.E2 | 4855 | editorial | Some incompatibilities from XPath 1.0 are undocumented; othersare wrongly classified as applying only when compatibility mode isfalse. |
XP.E3 | 4868 | editorial | For valid syntax, parentheses need to be added to the expansionfor leading "/" and leading "//" in a path expression. |
XP.E4 | 4446 | substantive | This erratum adds more details to the rules definingpermissible expression rewrites for optimization and otherpurposes. |
XP.E5 | 4873 | substantive | This erratum clarifies the conditions under which a castableexpression may raise an error. |
XP.E6 | 5445 | editorial | Undocumented incompatibility when the operators <, >,<=, or >= are used to compare a number to a boolean. |
XP.E7 | 5351 | substantive | Specifies that an error results if the PITarget specified in aSequenceType of form processing-instruction(PITarget) is not asyntactically valid NCName. |
XP.E8 | 5261 | editorial | Removes references to error code FORG0001 from description ofcast expression. Replaces them with a reference to Functions andOperators for normative description of error behavior. |
XP.E9 | 5471 | editorial | Deletes unnecessary reference to RFC2396 from NormativeReferences. This item is never referenced in the normativetext. |
XP.E10 | 5223 | substantive | Specifies that general comparisons cast an untyped operand tothe primitive base type of the other operand rather than to themost specific type of the other operand. |
XP.E11 | 5984 | editorial | Corrects a list of examples of primitive atomic types. |
XP.E13 | 5347 | substantive | Allows (and encourages) the use of XML 1.0 editions newer thanthe Third Edition. |
XP.E14 | 6027 | substantive | Specifies conformance criteria for syntax extensions. |
XP.E15 | 6287 | editorial | Defines the meaning of "undefined" for Data Modelproperties. |
XP.E16 | 5727 | substantive | Clarifications on parsing leading / in XPath expressions. |
XP.E18 | 5876 | substantive | Corrects the description of precedence with respect toparentheses and square brackets. |
XP.E19 | 5351 | substantive | Specifies that leading and trailing whitespace are strippedfrom a PITarget specified in a SequenceType of formprocessing-instruction(PITarget) before it is tested to see if itis a syntactically valid NCName. Also makes the description of theerror introduced in E12 more precise. If accepted, this supersedesE12. |