XQuery and XPath Data Model 4.0

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document is governed by the 1 March 2017 W3C Process Document.

This is a Recommendation of the W3C. It was jointly developed by the W3C XML Query Working Group and the W3C XSLT Working Group, each of which is part of the XML Activity.

This Editor's Draft specifies the XQuery and XPath Data Model (XDM) version 4.0, a fully compatible extension of XDM version 3.1.

This specification is designed to be referenced normatively from other specifications defining a host language for it; it is not intended to be implemented outside a host language. The implementability of this specification has been tested in the context of its normative inclusion in host languages defined by the XQuery 3.1 and XSLT 3.0 specifications; see the XQuery 3.1 implementation report (and, in the future, the WGs expect that there will also be an XSLT 3.0 implementation report) for details.

No substantive changes have been made to this specification since its publication as a Proposed Recommendation.

Please report errors in this document using W3C's public Bugzilla system (instructions can be found at https://www.w3.org/XML/2005/04/qt-bugzilla). If access to that system is not feasible, you may send your comments to the W3C XSLT/XPath/XQuery public comments mailing list, public-qt-comments@w3.org. It will be very helpful if you include the string “[XDM31]” in the subject line of your report, whether made in Bugzilla or in email. Please use multiple Bugzilla entries (or, if necessary, multiple email messages) if you have more than one comment to make. Archives of the comments and responses are available at https://lists.w3.org/Archives/Public/public-qt-comments/.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document was produced by groups operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures (W3C XML Query Working Group) and a public list of any patent disclosures (W3C XSLT Working Group) made in connection with the deliverables of each group; these pages also include instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Dedication

The publications of this community group are dedicated to our co-chair, Michael Sperberg-McQueen (1954–2024).

7 Function Items, Maps, and Arrays

7.2 Map Items

Changes in 4.0 ⬇ ⬆

Constructors are added, and the single accessor function is now an iterator over the key/value pairs in the map. [Issue 1335 20 July 2024]
Ordered maps are introduced. [Issue 1651 PR 1703 14 January 2025]

[Definition: A map item (also called simply a map) is an itema function item that represents an ordered sequence of key/value pairs, in which the keys are unique.] In other languages this is sometimes called a hash, dictionary, or associative array. The keys are atomic items, and each key in the map is unique (there is no other key to which it is equal). Each key is associated with a value that may be any sequence of zero or more items. There is no uniqueness constraint on values, only on keys. The semantics of equality when comparing keys are described in Section 14.2.1 fn:atomic-equal^FO.

[Definition: The key/value pairs in a map are referred to as entries.]

Considered as a function item, a map is a function from atomic items to values: if M is a map and K is an atomic item, then the function call M(K) returns the value associated with the key K, if present, or an empty sequence otherwise. More specifically, the properties of a map when considered as a function item are:

name: absent.
identity: implementation dependent.
parameter names: A single parameter named key, in no namespace.
signature: function(xs:anyAtomicType) as item()*.
annotations: none.
body: equivalent to a call on map:get.
captured context: empty.

[Definition: A map containing exactly one entry is referred to as a single-entry map.]

[Definition: A map containing no entries is referred to as an empty map.]

Note:

Maps have no intrinsic identity separate from their content. A map can be given a transient identity, represented by an id property in its label, by applying the fn:pin function. This property is expected to be used in defining operations for deep update of maps.

[Definition: The order of entries in a map is referred to as entry order.] The entry order affects the result of functions such as map:keys and map:for-each, and also determines the order of entries when a map is serialized using the JSON output method.

Constructor and accessor functions for maps are defined in the following sections.

7.3 Array Items

Changes in 4.0 ⬆

Constructors are added, and the single accessor function is now an iterator over the members of the array. [Issue 1335 20 July 2024]

[Definition: An array item (also called simply an array) is a valuefunction item that represents an array.] [Definition: An array is an ordered list of values; these values are called the members of the array.] Unlike sequences, a member of an array can be any value (including a sequence or an array). The number of members in an array is called its size, and they are referenced by their position, in the range 1 to the size of the array.

Considered as a function item, an array is a function from integers to values: if A is an array and N is an integer, then the function call A(N) returns the Nth member of the array (counting from one). More specifically, the properties of an array, considered as a function item, are:

name: absent.
identity: implementation dependent.
parameter names: A single parameter named index, in no namespace.
signature: function(xs:integer) as item()*.
annotations: none.
body: equivalent to a call on array:get.
captured context: empty.

[Definition: An array containing exactly one member is referred to as a single-member array.]

[Definition: An array containing no members is referred to as an empty array.]

Note:

Arrays have no intrinsic identity separate from their content. An array can be given a transient identity, represented by an id property in its label, by applying the fn:pin function. This property is expected to be used in defining operations for deep update of arrays.

Constructor and accessor functions for arrays are defined in the following sections.

C Glossary (Non-Normative)

absent: When a property has no value, we say that it is absent.
array item: An array item (also called simply an array) is a valuefunction item that represents an array.
atomic item: An atomic item is a pair (T, D) where T (the type annotation) is an atomic type, and D (the datum) is a point in the value space of T.
atomic type: An atomic type is either a primitive simple typewith variety atomic, or a type derived by restriction from another atomic type.
character: A character is any Unicode character.
codepoint: A codepoint is a non-negative integer assigned to a character by the Unicode consortium, or reserved for future assignment to a character.
compatible (of schemas): Two schemasX and Y are compatible if the union of X and Y is a valid schema.
datum: The datum of an atomic item is a point in the value space of its type, which is also a point in the value space of the primitive type from which that type is derived.
document: A tree whose root node is a document node is referred to as a document.
document order: A document order is defined among all the nodes accessible during a given query or transformation. Document order is a total ordering, although the relative order of some nodes is implementation-dependent. Informally, document order is the order in which nodes appear in the XML serialization of a document.
empty array: An array containing no members is referred to as an empty array.
empty map: A map containing no entries is referred to as an empty map.
entry: The key/value pairs in a map are referred to as entries.
entry order: The order of entries in a map is referred to as entry order.
expanded QName: An expanded QName is a triple consisting of a possibly absent prefix, a possibly absent namespace URI, and a local name.
fragment: A tree whose root node is not a document node is referred to as a fragment.
function annotation: A function annotation consists of an annotation name (an instance of xs:QName) and an annotation value (an arbitrary sequence of atomic items).
function arity: The arity of a function item is the number of its parameters.
function item: A function item is an item that can be called.
function signature: A function signature represents the type of a function.
implementation defined: Implementation-defined indicates an aspect that may differ between implementations, but must be specified by the implementer for each particular implementation.
implementation dependent: Implementation-dependent indicates an aspect that may differ between implementations, is not specified by this or any W3C specification, and is not required to be specified by the implementer for any particular implementation.
incompletely validated: An incompletely validated document is an XML document that has a corresponding schema but whose schema-validity assessment has resulted in one or more element or attribute information items being assigned values other than ‘valid’ for the [validity] property in the PSVI.
instance of the data model: Every instance of the data model is a sequence.
item: An item is either a node, a function, or an atomic item.
item type: An item type represents a class of items.
labeled item: A labeled item is a pair (S, L) where S (called the subject) is any item, and L (called the label) is a map containing supplementary information about the item.
map item: A map item (also called simply a map) is an itema function item that represents an ordered sequence of key/value pairs, in which the keys are unique.
member: An array is an ordered list of values; these values are called the members of the array.
Namespace URI: This specification uses the term Namespace URI to refer to a namespace name, whether or not it is a valid URI or IRI
node: There are seven kinds of nodes in the data model: document, element, attribute, text, namespace, processing instruction, and comment.
primitive simple type: The primitive simple types are the types defined in 4.1.1 Types adopted from XML Schema.
root node: The root node is the topmost node of a tree, the node with no parent.
schema: Following the terminology of [Schema Part 1], a schema is defined as set of schema components. Schema components include, for example, element declarations and type definitions.
schema type: A schema type corresponds to a type definition component as defined in XSD.
sequence: A sequence is an ordered collection of zero or more items.
sequence type: A sequence type constrains the set of permitted sequences, by defining the permitted item types and the permitted number of items in the sequence (exactly zero, exactly one, zero-or-more, one-or-more, zero-or-one).
single-entry map: A map containing exactly one entry is referred to as a single-entry map.
single-member array: An array containing exactly one member is referred to as a single-member array.
stable: Document order is stable, which means that the relative order of two nodes will not change during the processing of a given query or transformation, even if this order is implementation-dependent.
string: A string is a sequence of zero or more characters.
type annotation: The term type annotation has two slightly different meanings. For an atomic item, the type annotation of the value is the most specific atomic type that it is an instance of (it is also an instance of every type from which that type is derived). For an element or attribute node, the type annotation is the schema type (a simple or complex type) against which the node has been validated, defaulting to xs:untypedAtomic for unvalidated attribute nodes, and xs:untyped for unvalidated element nodes.
value: Because every value is a sequence, the term value is used synonymously with sequence.