Changes in 4.0 ⬇ ⬆
In map constructors, the keyword map is now optional, so map { 0: false(), 1: true() } can now be written { 0: false(), 1: true() }, provided it is used in a context where this creates no ambiguity. [Issue 1070 PR 1071 26 March 2024]
The order of key-value pairs in the map constructor is now retained in the constructed map. [Issue 1651 PR 1703 14 January 2025]
A general expression is allowed within a map constructor; this facilitates the creation of maps in which the presence or absence of particular keys is decided dynamically. [Issue 2003 PR 2094 13 July 2025]
A map can be created using a MapConstructor.
Examples are:
which constructs a map with two entries, and
{ "a": 1, if ($condition) { map{ "b": 2 } } }which constructs a map having either one or two entries depending on the value of $condition.
Both the keys and the values in a map constructor can be supplied as expressions rather than as constants.
Note:
The keyword map was required in earlier versions of the language; in XPath 4.0 it becomes optional. There may be cases where using the keyword improves readability.
In order to allow the map keyword to be omitted, an incompatible change has been made to XQuery computed element and attribute constructors: if the name of the constructed element or attribute is a language keyword, it must now be written using the QNameLiteral syntax, for example element #div {}.
Although the grammar allows a MapConstructor to appear within an EnclosedExpr (that is, between curly brackets), this may be confusing to readers, and using the map keyword in such cases may improve clarity. The keyword map is used in the second example above to avoid any confusion between the braces required for the then part of the conditional expression, and the braces required for the inner map constructor.
If the EnclosedExpr appears in a context such as a StringTemplate, the two adjacent left opening braces must at least be separated by whitespace.
When a MapConstructorEntry is written as two instances of ExprSingle separated by a colon, the first expression is evaluated and atomized to form a key, and the second expression is evaluated to form the corresponding value. The result is a single-entry mapDM which will be merged into the constructed map, as described below. A type error [err:XPTY0004] occurs if the result of the first expression (after atomization) is not a single atomic item. The result of the second expression is used as is.
When the MapConstructorEntry is written as a single instance of ExprSingle with no colon, it must evaluate to a sequence of zero or more map items ([err:XPTY0004]). These map items will be merged into the constructed map, as described below.
Each contained MapConstructorEntry thus delivers zero or more maps, and the result of the map constructor is a new map obtained by merging these component maps, in order, as if by the map:merge function.
[Definition: Two atomic items K1 and K2 have the same key value if fn:atomic-equal(K1, K2) returns true, as specified in Section 14.2.1 fn:atomic-equalFO ] If two or more entries have the same key value then a dynamic error is raised [err:XQDY0137]. The error may be raised statically if two or more entries can be determined statically to have the same key value.
The entry orderDM of the entries in the constructed map retains the order of the MapConstructorEntry entries in the input.
The following expression constructs a map with seven entries:
{
"Su" : "Sunday",
"Mo" : "Monday",
"Tu" : "Tuesday",
"We" : "Wednesday",
"Th" : "Thursday",
"Fr" : "Friday",
"Sa" : "Saturday"
}
The following expression constructs a map with either five or seven entries, depending on a supplied condition:
{
"Mo" : "Monday",
"Tu" : "Tuesday",
"We" : "Wednesday",
"Th" : "Thursday",
"Fr" : "Friday",
if ($include-weekends) {
{ "Sa" : "Saturday",
"Su" : "Sunday"
}
}
}This could also be written:
{
"Mo" : "Monday",
"Tu" : "Tuesday",
"We" : "Wednesday",
"Th" : "Thursday",
"Fr" : "Friday",
{ "Sa" : "Saturday",
"Su" : "Sunday"
} [$include-weekends]
}
The following expression (which uses two nested map constructors) constructs a map that indexes employees by the value of their @id attribute:
{ //employee ! {@id, .} }{ //employee ! {@id : .} }
Maps can nest, and can contain any XDM value. Here is an example of a nested map with values that can be string values, numeric values, or arrays:
{
"book": {
"title": "Data on the Web",
"year": 2000,
"author": [
{
"last": "Abiteboul",
"first": "Serge"
},
{
"last": "Buneman",
"first": "Peter"
},
{
"last": "Suciu",
"first": "Dan"
}
],
"publisher": "Morgan Kaufmann Publishers",
"price": 39.95
}
}Note:
The syntax deliberately mimics JSON, but there are a few differences. JSON constructs that are not accepted in XPath 4.0 map constructors include the keywords true, false, and null, and backslash-escaped characters such as "\n" in string literals. In an XPath 4.0 map constructor, of course, any literal value can be replaced with an expression.
Note:
In some circumstances, it is necessary to include whitespace before or after the colon of a MapConstructorEntry to ensure that it is parsed as intended.
For instance, consider the expression {a:b}. Although it matches the EBNF for MapConstructor (with a matching MapKeyExpr and b matching MapValueExpr), the "longest possible match" rule requires that a:b be parsed as a QName, which results in a syntax error. Changing the expression to {a :b} or {a: b} will prevent this, resulting in the intended parse. For instance, consider the expression {a:b}. Although it matches the EBNF for MapConstructor, the “longest terminal” rule (see A.3 Lexical structure) requires that a:b be parsed as a QName, which is likely to result in an error indicating that the prefix a has not been declared. Changing the expression to {a :b} or {a: b} will prevent this, resulting in the intended parse. For instance, consider the expression {a:b}. Although it matches the EBNF for MapConstructor (with a matching MapKeyExpr and b matching MapValueExpr)MapConstructor, the "longest possible match" rule“longest terminal” rule (see A.3 Lexical structure) requires that a:b be parsed as a QName, which results inis likely to result in an error indicating that the prefix a syntax errorhas not been declared. Changing the expression to {a :b} or {a: b} will prevent this, resulting in the intended parse.
Similarly, consider these three expressions:
In each case, the expression matches the EBNF in two different ways, but the “longest possible match” rule forces the parse in which the MapKeyExpr is a:b, a:*, or *:b (respectively) and the MapValueExpr is c. To achieve the alternative parse (in which the MapKeyExpr is merely a or *), insert whitespace before and/or after the first colon. In each case, the expression matches the EBNF in two different ways, but the “longest possible match” rule forces the parse in which the first subexpression is a:b, a:*, or *:b (respectively) and the second subexpression is c. To achieve the alternative parse (in which the first expression is merely a or *), insert whitespace before and/or after the first colon. In each case, the expression matches the EBNF in two different ways, but the “longest possible match” rule forces the parse in which the MapKeyExprfirst subexpression is a:b, a:*, or *:b (respectively) and the MapValueExprsecond subexpression is c. To achieve the alternative parse (in which the MapKeyExprfirst expression is merely a or *), insert whitespace before and/or after the first colon.
See A.3 Lexical structure.
Note:
There are also several functions that can be used to construct maps with a variable number of entries:
map:build takes any sequence as input, and for each item in the sequence, it computes a key and a value, by calling user-supplied functions.
map:merge takes a sequence of maps (often but not necessarily single-entry mapDM) and merges them into a single map.
map:of-pairs takes a sequence of key-value pair mapsFO and merges them into a single map.
Any of these functions can be used to build an index of employee elements using the value of the @id attribute as a key:
map:build(//employee, fn { @id })
map:merge(//employee ! { @id, . })
map:of-pairs(//employee ! { 'key': @id, 'value': . })
All three functions also provide control over: