Changes in 4.0 ⬇ ⬆
Record types are added as a new kind of ItemType, constraining the value space of maps.
The syntax record(*) is allowed; it matches any map. [Issue 52 PR 728 10 October 2023]
The syntax record() is allowed; the only thing it matches is an empty map. [Issue 1491 PR 1577 17 October 2024]
A RecordType matches maps that meet specific criteria.
For example, the RecordTyperecord(r as xs:double, i as xs:double) matches a map if the map has exactly two entries: an entry with key "r" whose value is a singletonxs:double value, and an entry with key "i" whose value is also a singletonxs:double value.
Record types describe a subset of the value space of maps. They do not define any new kinds of values, or any additional operations. They are useful in many cases to describe more accurately the type of a variable, function parameter, or function result, giving benefits both in the readability of the code, and in the ability of the processor to detect and diagnose type errors and to optimize execution.
If the list of fields ends with ",*" then the record type is said to be extensible. For example, the RecordTyperecord(e as element(Employee), *) matches a map if it has an entry with key "e" whose value matches element(Employee), regardless what other entries the map might contain.
For generality:
The syntax record() defines a record type that has no explicit fields and that is not extensible. The only thing it matches is an empty mapDM.
The syntax record(*) defines an extensible record type that has no explicit field declarations. It is equivalent to the item type map(*): that is, it matches any map.
A record type can constrain only those entries whose keys are strings, but when the record type is marked as extensible, then other entries may be present in the map with either string or non-string keys. Entries whose key is a string can be expressed using an (unquoted) NCName if the key conforms to NCName syntax, or using a (quoted) string literal otherwise.
Although constructors for named record types produce a map in which the entry orderDM reflects the order of field definitions in the record type definition, the entry orderDM of a map has no effect on whether the map matches a particular record type: the entries in a map do not have to be in any particular order.
Note:
Lookup expressions have been extended in 4.0 so that non-NCName keys can be used without parentheses: employee?"middle name"
If the type declaration for a field is omitted, then item()* is assumed: that is, the map entry may have any type.
If the field name is followed by a question mark, then the value must have the specified type if it is present, but it may also be absent. For example, the RecordTyperecord(first as xs:string, middle? as xs:string, last as xs:string, *) requires the map to have string-valued entries with keys "first" and "last"; it also declares that if the map has an entry with key "middle", the value of that entry must be a single xs:string. Declaring the type as record(first as xs:string, middle? as xs:string?, last as xs:string, *) also allows the entry with key "middle" to be present but empty.
Note:
Within an extensible record type, a FieldDeclaration that is marked optional and has no declared type does not constrain the map in any way, so it serves no practical purpose, but it is permitted because it may have documentary value.
The names of the fields in a record type must be distinct [err:XPST0021].
If a variable $rec is known to conform to a particular record type, then when a lookup expression $rec?field is used, (a) the processor can report a type error if $rec cannot contain an entry with name field (see 4.14.3.4 Implausible Lookup Expressions), and (b) the processor can make static type inferences about the type of value returned by $rec?field.
Note:
(TODO: change function signatures as suggested here!) A number of functions in the standard function library use maps as function arguments; this is a useful technique where the information to be supplied across the interface is highly variable. However, the type signature for such functions typically declares the argument type as map(*), which gives very little information (and places very few constraints) on the values that are actually passed across. Using record types offers the possibility of improving this: for example, the options argument of fn:parse-json, previously given as map(*), can now be expressed as record(liberal? as xs:boolean, duplicates? as xs:string, escape? as xs:boolean, fallback as fn(xs:string) as xs:string, *). In principle the xs:string type used to describe the duplicates option could also be replaced by a schema-defined subtype of xs:string that enumerates the permitted values ("reject", "use-first", "use-last").
The use of a record type in the signature of such a function causes the coercion rules to be invoked. So, for example, if the function expects an entry in the map to be an xs:double value, it becomes possible to supply a map in which the corresponding entry has type xs:integer.
Greater precision in defining the types of such arguments also enables better type checking, better diagnostics, better optimization, better documentation, and better syntax-directed editing tools.
Note:
One of the motivations for introducing record types is to enable better pattern matching in XSLT when processing JSON input. With XML input, patterns are often based around XML element names. JSON has no direct equivalent of XML’s element names; matching a JSON object such as {longitude: 130.2, latitude: 53.4} relies instead on recognizing the property names appearing in the object. XSLT 4.0, by integrating record types into pattern matching syntax, allows such an object to be matched with a pattern of the form match="record(longitude, latitude)"
Rules defining whether one record type is a subtype of another are given in 3.3.2.8 Subtyping Records.
A named record type N is said to be recursive if its definition includes a direct or indirect reference to N.
For example, the following XQuery declaration defines a linked list:
declare record my:list (value as item()*, next? as my:list);
The equivalent in XSLT is:
<xsl:record-type name="my:list">
<xsl:field name="value" as="item()*"/>
<xsl:field name="next" as="my:list" required="no"/>
</xsl:record-type>
Instances of recursive record types can be constructed and interrogated in the normal way. For example a list of length 3 can be constructed as:
{ "value": 1, "next": { "value": 2, "next": { "value": 3 } } }and the third value in the map can be retrieved as $list?next?next?value. In practice, recursive data structures are usually manipulated using recursive functions.
It is possible to define a recursive record type that cannot be instantiated, because it has no finite instances: for example (in XQuery) declare record X (next as X);. Such a record declaration is implausible, so the processor may treat it as an error [err:XPST0023], but it is not obliged to do so.
Note:
For an example of a practical use of recursive record types, see the specification of the function fn:random-number-generator.
Recursive type definitions need to be handled specially by the subtyping rules; a naïve approach of simply replacing each reference to a named item type with its definition would make the assessment of the subtype relationship non-terminating. For details see 3.3.2 Subtypes of Item Types.
A record used to represent a node in a binary tree might be represented (using XQuery syntax) as:
declare record t:binary-tree
( left? as t:binary-tree,
value as item()*,
right? as t:binary-tree
)A recursive function to walk this tree and enumerate all the values in depth-first order might be written (again using XQuery syntax) as:
declare function t:values($tree as t:binary-tree?) as item()* {
$tree ! (t:values(?left), ?value, t:values(?right))
}
A record used to represent a node in a tree where each node has an arbitrary number of children might be represented (using XQuery syntax) as:
declare record t:tree as (value, children as t:tree*);
A function to walk this tree and enumerate all the values in order might be written as:
declare function t:flatten($tree as t:tree) as item()* {
$tree?value, $tree?children ! t:flatten(.))
}
The usual textbook example of mutually-recursive types is that of a forest consisting of a list of trees, where each tree is a record comprising a value and a forest. As the previous example shows, this structure can be defined straightforwardly in XQuery 4.0 without recourse to mutual recursion.
A more realistic example where mutual recursion is needed is for the schema component model used in [XML Schema 1.0] or [XML Schema 1.1]. Simplifying greatly, the data representing an element declaration in XSD may contain references to a complex type, which in turn will typically contain references to further element declarations. The structure therefore involves mutual recursion. A simplified version of the schema component model might be written (in part) as:
declare record ElementDeclaration (
name as xs:NCName,
targetNamespace? as xs:anyURI,
typeDefinition as (SimpleTypeDefinition | ComplexTypeDefinition),
nillable as xs:boolean,
abstract as xs:boolean
);
declare record SimpleTypeDefinition (
name? as xs:NCName,
targetNamespace? as xs:anyURI,
baseType? as SimpleTypeDefinition,
variety as enum("atomic", "list", "union"),
facets as Facet*,
);
declare record ComplexTypeDefinition (
name? as xs:NCName,
targetNamespace? as xs:anyURI,
baseType? as ComplexTypeDefinition,
derivationMethod as enum("extension", "restriction"),
contentType as record (
variety as enum("empty", "simple", "element-only", "mixed"),
particle? as Particle,
simpleTypeDefinition? as SimpleTypeDefinition
)
);
declare record Particle (
minOccurs as xs:nonNegativeInteger,
maxOccurs as (xs:positiveInteger | enum("unbounded")),
term as (ElementDeclaration | Wildcard | Group)
);