XPath and XQuery Functions and Operators 4.0

5 Processing strings

This section specifies functions and operators on the [XML Schema Part 2: Datatypes Second Edition]xs:string datatype and the datatypes derived from it.

5.2 Functions to assemble and disassemble strings

Function	Meaning
`fn:codepoints-to-string`	Returns an `xs:string` whose characters have supplied codepoints.
`fn:string-to-codepoints`	Returns the sequence of codepoints that constitute an `xs:string` value.

5.2.1 fn:codepoints-to-string

Changes in 4.0 ⬇ ⬆

It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. [Issue 414 PR 546 25 July 2023]

Summary

Returns an xs:string whose characters have supplied codepoints.

Signature

`fn:codepoints-to-string`(
`$values`	`as` `xs:integer*`
) `as` `xs:string`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function returns the string made up from the characters whose Unicode codepoints are supplied in $values. This will be the zero-length string if $values is the empty sequence.

Error Conditions

A dynamic error is raised [err:FOCH0001] if any of the codepoints in $values is not a permitted character.

Examples

Expression	Result
`codepoints-to-string((66, 65, 67, 72))`	"BACH"
`codepoints-to-string((2309, 2358, 2378, 2325))`	"अशॊक"
`codepoints-to-string(())`	""
`codepoints-to-string(0)`	Raises error FOCH0001.

A sequence is an ordered collection of zero or more items. An item is a node, an atomic item, or a function, such as a map or an array. The terms sequence and item are defined formally in [XQuery 4.0: An XML Query Language] and [XML Path Language (XPath) 4.0].

14.6 Functions giving access to external information

The functions in this section provide access to resources (such as files) in the external environment.

Function	Meaning
`fn:doc`	Retrieves a document using a URI supplied as an `xs:string`, and returns the corresponding document node.
`fn:doc-available`	The function returns `true` if and only if the function call `fn:doc($source, $options)` would return a document node.
`fn:collection`	Returns a sequence of items identified by a collection URI; or a default collection if no URI is supplied.
`fn:uri-collection`	Returns a sequence of `xs:anyURI` values representing the URIs in a URI collection.
`fn:unparsed-text`	The `fn:unparsed-text` function reads an external resource (for example, a file) and returns a string representation of the resource.
`fn:unparsed-text-lines`	The `fn:unparsed-text-lines` function reads an external resource (for example, a file) and returns its contents as a sequence of strings, one for each line of text in the string representation of the resource.
`fn:unparsed-text-available`	Allows an application to determine whether a call on `fn:unparsed-text` with particular arguments would succeed.
`fn:environment-variable`	Returns the value of a system environment variable, if it exists.
`fn:available-environment-variables`	Returns a list of environment variable names that are suitable for passing to `fn:environment-variable`, as a (possibly empty) sequence of strings.

14.6.5 fn:unparsed-text

Changes in 4.0 ⬇ ⬆

The $options parameter has been added. [Issue 1116 PR 1117 21 May 2024]
It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. [Issue 414 PR 546 25 July 2023]
It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. [Issue 414 PR 546 25 July 2023]
The specification now describes how an initial BOM should be handled. [Issue 1704 ]
The specification now describes how an initial BOM should be handled. [Issue 1704 ]

Summary

The fn:unparsed-text function reads an external resource (for example, a file) and returns a string representation of the resource.

Signature

`fn:unparsed-text`(
`$source`	`as` `xs:string?`,
`$options`	`as` `(xs:string \| map(*))?`	`:=` `()`
) `as` `xs:string?`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on static base URI.

Rules

The $source argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource for which a string representation is available. If the URI is a relative URI reference, then it is resolved relative to the static base URI property from the static context.

The $options argument, for backwards compatibility reasons, may be supplied either as a map, or as a string. Supplying a value $S that is not a map is equivalent to supplying the map { "encoding": $S }. After that substitution, the option parameter conventions apply.

The entries that may appear in the $options map are as follows:

`record(`
`encoding?`	`as` `xs:string?`,
`normalize-newlines?`	`as` `xs:boolean`
`)`

Key	Value	Meaning
`encoding?`	Defines the encoding of the resource, as described below. Type: `xs:string?` Default: `()`
`normalize-newlines?`	Determines whether CR and CRLF character sequences are treated as equivalent to NL characters. Type: `xs:boolean` Default: `false()`
	`false`	No normalization of line endings takes place.
	`true`	The character U+000D (CARRIAGE RETURN) and the character pair (U+000D (CARRIAGE RETURN) , U+000A (NEWLINE) ) are converted to the single character U+000A (NEWLINE) .

The mapping of URIs to the string representation of a resource is the mapping defined in the available text resources^XP31 component of the dynamic context.

If the $source argument is an empty sequence, the function returns an empty sequence.

The encoding option, if present and non-empty, is the name of an encoding. The values for this option follow the same rules as for the encoding attribute in an XML declaration. The only values which every implementation is required to recognize are utf-8 and utf-16.

The encoding of the external resource is determined as followsby applying the following rules, in order:

externalExternal encoding information is used if available, otherwise.
ifIf the media type of the resource is text/xml or application/xml (see [RFC 2376]), or if it matches the conventions text/*+xml or application/*+xml (see [RFC 7303] and/or its successors), then the encoding is recognized as specified in [Extensible Markup Language (XML) 1.0 (Fifth Edition)], otherwise.
The encoding option is used if present.theThe encoding option is used if present, otherwise.
If the initial octets represent a byte order mark in a known encoding, then the corresponding encoding is used: specifically:
- Initial octets FE FF imply UTF-16LE.
- Initial octets FF FE imply UTF-16BE.
- Initial octets EF BB BF imply UTF-8.
If the initial octets represent a byte order mark in a known encoding, then the corresponding encoding is used: specifically:
- Initial octets FE FF imply UTF-16LE.
- Initial octets FF FE imply UTF-16BE.
- Initial octets EF BB BF imply UTF-8.
theThe processor may use implementation-defined heuristics to determine the likely encoding, otherwise.
UTF-8 is assumed.

The result of the function is a string containing the string representation of the resource retrieved using the URI, decoded according to the specified encoding. If the first codepoint, after decoding, is U+FEFF, then it is assumed to represent a byte order mark and is discarded from the result.

Error Conditions

A dynamic error is raised [err:FOUT1170] if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the string representation of a resource.

A dynamic error is raised [err:FOUT1190] if the value of the encoding option is not a valid encoding name, if the processor does not support the specified encoding, if the string representation of the retrieved resource contains octets that cannot be decoded into Unicode characters using the specified encoding, or if any resulting character is not a permitted character.

A dynamic error is raised [err:FOUT1200] if the encoding option is absent and the processor cannot infer the encoding using external information and the actual encoding is not UTF-8.

Notes

If it is appropriate to use a base URI other than the dynamic base URI (for example, when resolving a relative URI reference read from a source document) then it is advisable to resolve the relative URI reference using the fn:resolve-uri function before passing it to the fn:unparsed-text function.

There is no essential relationship between the sets of URIs accepted by the two functions fn:unparsed-text and fn:doc (a URI accepted by one may or may not be accepted by the other), and if a URI is accepted by both there is no essential relationship between the results (different resource representations are permitted by the architecture of the web).

There are no constraints on the MIME type of the resource.

The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:

The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.
The handling of media types is implementation-defined.
Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in reading its content. When errors have been handled in this way, the function may return a fallback document provided by the error handler.
For backwards compatibility reasons, implementations may provide configuration options that alter the default for the deterministic option.

The rules for determining the encoding are chosen for consistency with [XML Inclusions (XInclude) Version 1.0 (Second Edition)]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.

If the text file contains characters such as < and &, these will typically be output as < and & if the string is serialized as XML or HTML. If these characters actually represent markup (for example, if the text file contains HTML), then an XSLT stylesheet can attempt to write them as markup to the output file using the disable-output-escaping attribute of the xsl:value-of instruction. Note, however, that XSLT implementations are not required to support this feature.

Examples

This XSLT example attempts to read a file containing “boilerplate” HTML and copy it directly to the serialized output file:

<xsl:output method="html"/>

<xsl:template match="/">
  <xsl:value-of select="unparsed-text('header.html', 'iso-8859-1')"
                disable-output-escaping="yes"/>
  <xsl:apply-templates/>
  <xsl:value-of select="unparsed-text('footer.html', 'iso-8859-1')"
                disable-output-escaping="yes"/>
</xsl:template>

15 Parsing and serializing

These functions convert between the lexical representation and XPath and XQuery data model representation of various file formats.

15.1 Functions on XML Data

These functions convert between the lexical representation of XML and the tree representation.

(The fn:serialize function also handles HTML and JSON output, but is included in this section for editorial convenience.)

Function	Meaning
`fn:parse-xml`	This function takes as input an XML document represented as a string, and returns the document node at the root of an XDM tree representing the parsed document.
`fn:parse-xml-fragment`	This function takes as input an XML external entity represented as a string, and returns the document node at the root of an XDM tree representing the parsed document fragment.
`fn:serialize`	This function serializes the supplied input sequence `$input` as described in [XSLT and XQuery Serialization 3.1], returning the serialized representation of the sequence as a string.

15.1.2 fn:parse-xml-fragment

Changes in 4.0 ⬇ ⬆

The $options parameter has been added. [Issue 305 PR 1257 11 June 2024]

Summary

This function takes as input an XML external entity represented as a string, and returns the document node at the root of an XDM tree representing the parsed document fragment.

Signature

`fn:parse-xml-fragment`(
`$value`	`as` `xs:string?`,
`$options`	`as` `map(*)?`	`:=` `{}`
) `as` `document-node()?`

Properties

This function is nondeterministic, context-dependent, and focus-independent. It depends on static base URI.

Rules

If $value is the empty sequence, the function returns the empty sequence.

The input must be a namespace-well-formed external general parsed entity. More specifically, it must be a string conforming to the production rule extParsedEnt^XML in [Extensible Markup Language (XML) 1.0 (Fifth Edition)], it must contain no entity references other than references to predefined entities, and it must satisfy all the rules of [Namespaces in XML] for namespace-well-formed documents with the exception that the rule requiring it to be a well-formed document is replaced by the rule requiring it to be a well-formed external general parsed entity.

Because the input is supplied as a string, not as an octet stream, the encoding specified in the text declaration (if present) should be ignored. For similar reasons, any initial byte order mark (codepoint U+FEFF) should be ignored.

The string is parsed to form a sequence of nodes which become children of the new document node, in the same way as the content of any element is converted into a sequence of children for the resulting element node.

The $options argument, if present and non-empty, defines the detailed behavior of the function. The option parameter conventions apply. The options available are as follows:

`record(`
`base-uri?`	`as` `xs:anyURI`,
`strip-space?`	`as` `xs:boolean`
`)`

Key	Value	Meaning
`base-uri?`	Determines the base URI. This is used as the base URI of the document node that is returned. It defaults to the static base URI of the function call. Type: `xs:anyURI` Default: `static-base-uri()`
`strip-space?`	Determines whether whitespace-only text nodes are removed from the resulting document. Type: `xs:boolean` Default: `false()`
	`true`	All whitespace-only text nodes are stripped, unless they are within the scope of the attribute `xml:space="preserve"`.
	`false`	All whitespace-only text nodes are preserved.

DTD validation is not invoked (an external general parsed entity cannot contain a DOCTYPE declaration.

Schema validation is not invoked, which means that the nodes in the returned document will all be untyped.

XInclude processing is not invoked.

Except as explicitly defined, the precise process used to construct the XDM instance is implementation-defined. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used.

The document URI of the returned node is absent^DM.

The function is notdeterministic: that is, if the function is called twice with the same arguments, it is implementation-dependent whether the same node is returned on both occasions.

Error Conditions

A dynamic error is raised [err:FODC0006] if the content of $value is not a well-formed external general parsed entity, if it contains entity references other than references to predefined entities, or if a document that incorporates this well-formed parsed entity would not be namespace-well-formed.

Notes

See also the notes for the fn:parse-xml function.

The main differences between fn:parse-xml and fn:parse-xml-fragment are that for fn:parse-xml, the children of the resulting document node must contain exactly one element node and no text nodes, wheras for fn:parse-xml-fragment, the resulting document node can have any number (including zero) of element and text nodes among its children. An additional difference is that the text declaration at the start of an external entity has slightly different syntax from the XML declaration at the start of a well-formed document.

Note that all whitespace outside the text declaration is significant, including whitespace that precedes the first element node, unless the strip-space option is set.

One use case for this function is to handle XML fragments stored in databases, which frequently allow zero-or-more top level element nodes. Another use case is to parse the contents of a CDATA section embedded within another XML document.

Examples

The expression `parse-xml-fragment("<alpha>abcd</alpha><beta>abcd</beta>")` returns a newly created document node, having two elements named `alpha` and `beta` as its children; each of these elements in turn is the parent of a text node.
The expression `parse-xml-fragment("He was <i>so</i> kind")` returns a newly created document node having three children: a text node whose string value is `"He was "`, an element node named `i` having a child text node with string value `"so"`, and a text node whose string value is `" kind"`.
The expression `parse-xml-fragment("")` returns a document node having no children.
The expression `parse-xml-fragment(" ")` returns a document node whose children comprise a single text node whose string value is a single space.
The expression `parse-xml-fragment(" ", { "strip-space": true() })` returns a document node having no children.
The expression `parse-xml-fragment('<?xml version="1.0" encoding="utf8" standalone="yes"?><a/>')` results in a dynamic error [err:FODC0006] because the `standalone` keyword is not permitted in the text declaration that appears at the start of an external general parsed entity. (Thus, it is not the case that any input accepted by the `fn:parse-xml` function will also be accepted by `fn:parse-xml-fragment`.)

15.2 Functions on HTML Data

Changes in 4.0 ⬇ ⬆

A new function is available for processing input data in HTML format. [Issues 74 850 1799 1889 1891 PRs 259 956 10 January 2023]

This function converts between the lexical representation of HTML and the XDM tree representation.

Function	Meaning
`fn:parse-html`	This function takes as input an HTML document, and returns the document node at the root of an XDM tree representing the parsed document.

15.2.2 fn:parse-html

Changes in 4.0 ⬇ ⬆

New in 4.0 [Issues 74 850 1799 1889 1891 PRs 259 956 10 January 2023]

Summary

This function takes as input an HTML document, and returns the document node at the root of an XDM tree representing the parsed document.

Signature

`fn:parse-html`(
`$html`	`as` `(xs:string \| xs:hexBinary \| xs:base64Binary)?`,
`$options`	`as` `map(*)?`	`:=` `{}`
) `as` `document-node(*:html)?`

Properties

This function is nondeterministic, context-independent, and focus-independent.

Rules

If $html is the empty sequence the function returns the empty sequence.

In other cases, $html is expected to contain an HTML document supplied either as a string, or as a binary value.

The entries that may appear in the $options map are as follows:

`record(`
`encoding?`	`as` `xs:string?`,
`fail-on-error?`	`as` `xs:boolean?`,
`include-template-content?`	`as` `xs:boolean?`
`)`

Key	Value	Meaning
`encoding?`	The character encoding to use to decode a sequence of octets that represents an HTML document. Type: `xs:string?`
`fail-on-error?`	Indicates whether the function should fail with a dynamic error if the input is not syntactically valid. Type: `xs:boolean?` Default: `false()`
	`false`	Parsing errors should be handled as described in [HTML: Living Standard] section 13.2.2, Parse Errors.
	`true`	A parsing error should result in the function failing with a dynamic error.
`include-template-content?`	Defines how to handle elements in the `HTMLTemplateElement.content` property. If this option is `true`, the `template` element’s children are the children of the `content` property’s document fragment node. If this option is `false`, the `template` element’s children are the empty sequence. The default behaviour is implementation-defined. Note: This allows an implementation to support the behaviour defined in [HTML: Living Standard] section 4.12.3.1, Interaction of `template` elements with XSLT and XPath: This option would default to `true` for an XSLT processor operating on an HTML DOM constructed from an XHTML document. This option would default to `false` for an XPath processor using the [DOM: Living Standard] section 8, XPath APIs. Type: `xs:boolean?`

The option parameter conventions apply.

If $html is not the empty sequence, an input byte stream is constructed as follows:

If $html is an xs:string, the encoding of the input byte stream is determined in a way consistent with [HTML: Living Standard] section 13.2.3.1, Parsing with a known character encoding to generate the bytes for that string. The specific character encoding is the implementation-dependent encoding corresponding to the implementation’s string representation.
If $html is an xs:string, then in principle no decoding is needed. Conceptually, however, the HTML parsing algorithm always starts by decoding an octet stream. The string is therefore first encoded using UTF-8, and the resulting octet stream is then passed to the HTML parser with a known definite encoding of UTF-8, as described in [HTML: Living Standard] section 13.2.3.1, Parsing with a known character encoding.
If the first codepoint of the string is U+FEFF, this should be stripped, since it might otherwise lead to an incorrect encoding inference.
If the type of $html is a sequence of octets (xs:hexBinary or xs:base64Binary) the encoding of the input byte stream is determined in a way consistent with [HTML: Living Standard] section 13.2.3.2, Determining the character encoding:
1. The encoding key of $options is interpreted in step 2 of Determining the character encoding as the user instructing the user agent to override the document’s character encoding with the specified encoding.
2. If the encoding key of $options is not specified, step 2 of Determining the character encoding is skipped.

The resulting byte stream is then used to construct an XDM representation of the HTML document in a way that is equivalent to:

Tokenizing the byte stream according to the HTML parsing algorithm as described in [HTML: Living Standard] section 13.2.5, Tokenization.
Constructing a HTMLDocument object for HTML documents, or an XMLDocument for XML/XHTML documents as described in [HTML: Living Standard] section 13.2.6, Tree construction.
Building an XDM representation of the HTMLDocument or XMLDocument according to the rules in 15.2.1 XDM Mapping from HTML DOM Nodes.

The implementation should process any input HTML that adheres to the current practice of mainstream web browsers, as this evolves over time. Since this is defined by a “living standard” (see [HTML: Living Standard]), no specific version is prescribed. An implementation may define additional options to control aspects of the HTML parsing algorithm, including the selection of a specific HTML parsing library; it may also provide options to process alternative HTML versions or dialects.

The implementation should recognize and process XHTML (referred to in [HTML: Living Standard] as the XML concrete syntax of HTML).

The function is nondeterministic with respect to node identity: that is, if the function is called twice with the same arguments, it is implementation-dependent whether the same node is returned on both occasions.

Error Conditions

A dynamic error is raised [err:FODC0011] if the content of $html is not a well-formed HTML document.

A dynamic error is raised [err:FODC0012] if the method key of $options is not supported by the implementation.

A dynamic error is raised [err:FODC0012] if a key passed to $options, or the value of that key, is not supported by the implementation.

Notes

If the HTML parser accepts a string as the input then that may be used directly when $html is an xs:string instead of converting the string to a sequence of octets in an implementation-dependent encoding. The HTML parser must not perform character encoding processing on that input, treating the HTML string as being in a known character encoding that matches the encoding of the string.

The WHATWG Encoding specification defines the ISO 8859-1 (latin1) and ASCII encodings as aliases of the windows-1252 encoding.

Examples

The expression `parse-html(())` returns `()`.
The expression `parse-html("<p>Hello</p>")` returns an XDM document node equivalent to the result of parsing the XML `<html xmlns='http://www.w3.org/1999/xhtml'><head/><body><p>Hello</p></body></html>`
The expression `parse-html("<p>Hi</p>", method:="html")` is equivalent to `parse-html("<p>Hi</p>")`.

15.3 Functions on JSON Data

The functions listed in this section parse or serialize JSON data.

JSON is a popular format for exchange of structured data on the web: it is specified in [RFC 7159]. This section describes facilities allowing JSON data to be converted to and from XDM values.

This specification describes two ways of representing JSON data losslessly using XDM constructs. The first method uses XDM maps to represent JSON objects, and XDM arrays to represent JSON arrays. The second method represents all JSON constructs using XDM element and attribute nodes.

Function	Meaning
`fn:parse-json`	Parses a string supplied in the form of a JSON text, returning the results typically in the form of a map or array.
`fn:json-doc`	Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.
`fn:json-to-xml`	Parses a string supplied in the form of a JSON text, returning the results in the form of an XML document node.
`fn:xml-to-json`	Converts an XML tree, whose format corresponds to the XML representation of JSON defined in this specification, into a string conforming to the JSON grammar.
`fn:pin`	Adapts a map or array so that retrieval operations retain additional information.
`fn:label`	Returns the label associated with a labeled item, as a map.

Note also:

The function fn:serialize has an option to generate JSON output from a structure of maps and arrays.
The function fn:elements-to-maps enables arbitrary XML node trees to be converted to trees of maps and arrays suitable for serializing as JSON.

15.3.5 fn:json-doc

Changes in 4.0 ⬇ ⬆

Additional options are available, as defined by fn:parse-json.
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. [Issue 414 PR 546 25 July 2023]
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. [Issue 414 PR 546 25 July 2023]

Summary

Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.

Signature

`fn:json-doc`(
`$source`	`as` `xs:string?`,
`$options`	`as` `map(*)?`	`:=` `{}`
) `as` `item()?`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on static base URI.

Rules

If the second argument is omitted or an empty sequence, the result is the same as calling the two-argument form with an empty map as the value of the $options argument.

The effect of the two-argument function call fn:json-doc($H, $M)is equivalent to the function composition fn:unparsed-text($H) => fn:parse-json($M); except that if the resource contains characters that are not permitted characters:, then rather than raising an error as fn:unparsed-text#1 does, the function replaces such characters by the equivalent JSON escape sequence prior to parsing.

The function may accept a resource in any encoding. [RFC 7159] requires UTF-8, UTF-16, or UTF-32 to be accepted, but it is not an error if a different encoding is used. Unless external encoding information is available, the function must assume that the encoding is one of UTF-8, UTF-16, or UTF-32, and must distinguish these cases by examination of the initial octets of the resource.
If the resource contains characters that are not permitted characters, then rather than raising an error as fn:unparsed-text#1 does, the function replaces such characters by the equivalent JSON escape sequence prior to parsing.
Note:
Equivalently, the implementation can use some other internal representation of strings that allows non-XML characters to be manipulated.

If $source is the empty sequence, the function returns the empty sequence.

Error Conditions

The function may raise any error defined for the fn:unparsed-text or fn:parse-json functions.

Notes

An initial byte order mark is dropped, as with the fn:unparsed-text function.

If the input cannot be decoded (that is, converted into a sequence of Unicode codepoints, which may or may not represent characters), then a dynamic error occurs as with the fn:unparsed-text function.

If the input can be decoded, then the possibility still arises that the resulting sequence of codepoints includes codepoints that doare not represent characters that are valid in the version of XML that the processor supportspermitted characters. Such codepoints are translated into JSON escape sequences (for example, \uFFFF), and the JSON escape sequence is then passed to the fallback function specified in the $options argument, which in turn defaults to a function that returns the Unicode REPLACEMENT CHARACTER (xFFFD).

The function may accept a resource in any encoding. [RFC 7159] requires UTF-8, UTF-16, or UTF-32 to be accepted, but it is not an error if a different encoding is used. The function detects the encoding using the same rules as the unparsed-text function, except that the special handling of media types such as text/xml and application/xml may be skipped.

F Implementation-defined features (Non-Normative)

It is implementation-defined which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used. (See Conformance.)
It is implementation-defined whether the type system is based on XML Schema 1.0 or XML Schema 1.1. (See Conformance.)
It is implementation-defined whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1. (See Conformance.)
Implementations may attach an implementation-defined meaning to options in the map that are not described in this specification. These options should use values of type xs:QName as the option names, using an appropriate namespace. (See Options.)
It is implementation-defined which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used. (See Strings, characters, and codepoints.)
[Definition] Some functions (such as fn:distinct-values, fn:unordered, map:keys, and map:for-each) produce results in an implementation-defined or implementation-dependent order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering. (See Properties of functions.)
Where the results of a function are described as being (to a greater or lesser extent) implementation-defined or implementation-dependent, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results. (See Properties of functions.)
In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an implementation-defined destination. (See fn:trace.)
Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will return $v. The processor may output "124.84" and "the value of $v is:" to an implementation-defined destination. (See fn:trace.)
Similar to fn:trace, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an implementation-defined destination. (See fn:message.)
They may provide an implementation-defined mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967]. (See Arithmetic operators on numeric values.)
For xs:decimal values, let N be the number of digits of precision supported by the implementation, and let M (M <= N) be the minimum limit on the number of digits required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication operations, the returned result should be accurate to N digits of precision, and for division and modulus operations, the returned result should be accurate to at least M digits of precision. The actual precision is implementation-defined. If the number of digits in the mathematical result exceeds the number of digits that the implementation retains for that operation, the result is truncated or rounded in an implementation-defined manner. (See Arithmetic operators on numeric values.)
The [IEEE 754-2019] specification also describes handling of two exception conditions called divideByZero and invalidOperation. The IEEE divideByZero exception is raised not only by a direct attempt to divide by zero, but also by operations such as log(0). The IEEE invalidOperation exception is raised by attempts to call a function with an argument that is outside the function’s domain (for example, sqrt(-1) or log(-1)). Although IEEE defines these as exceptions, it also defines “default non-stop exception handling” in which the operation returns a defined result, typically positive or negative infinity, or NaN. With this function library, these IEEE exceptions do not cause a dynamic error at the application level; rather they result in the relevant function or operator returning the defined non-error result. The underlying IEEE exception may be notified to the application or to the user by some implementation-defined warning condition, but the observable effect on an application using the functions and operators defined in this specification is simply to return the defined result (typically -INF, +INF, or NaN) with no error. (See Arithmetic operators on numeric values.)
The [IEEE 754-2019] specification distinguishes two NaN values: a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM model: the value spaces of xs:float and xs:double each include only a single NaN value. This does not prevent the implementation distinguishing them internally, and triggering different implementation-defined warning conditions, but such distinctions do not affect the observable behavior of an application using the functions and operators defined in this specification. (See Arithmetic operators on numeric values.)
The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where implementation-dependent or implementation-defined behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division. (See op:numeric-integer-divide.)
There may be implementation-defined limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:round.)
There may be implementation-defined limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:round-half-to-even.)
There may be implementation-defined limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:divide-decimals.)
XSD 1.1 allows the string +INF as a representation of positive infinity; XSD 1.0 does not. It is implementation-defined whether XSD 1.1 is supported. (See fn:number.)
Any other format token, which indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is implementation-defined which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1. (See fn:format-integer.)
For all format tokens other than a digit-pattern, there may be implementation-defined lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the format token U+2460 (CIRCLED DIGIT ONE, ①) has a range imposed by the Unicode character repertoire — zero to 20 in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1. (See fn:format-integer.)
The set of languages for which numbering is supported is implementation-defined. If the $language argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context. (See fn:format-integer.)
...either a or t, to indicate alphabetic or traditional numbering respectively, the default being implementation-defined. (See fn:format-integer.)
The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is implementation-defined. No error occurs if the implementation does not define any interpretation for the defined string. (See fn:format-integer.)
It is implementation-defined what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead. (See fn:format-integer.)
The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is implementation-defined. (See fn:format-integer.)
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are implementation-defined. (See Defining a decimal format.)
IEEE states that the preferred quantum is language-defined. In this specification, it is implementation-defined. (See Trigonometric and exponential functions.)
IEEE defines various rounding algorithms for inexact results, and states that the choice of rounding direction, and the mechanisms for influencing this choice, are language-defined. In this specification, the rounding direction and any mechanisms for influencing it are implementation-defined. (See Trigonometric and exponential functions.)
The map returned by the fn:random-number-generator function may contain additional entries beyond those specified here, but it must match the record type defined above. The meaning of any additional entries is implementation-defined. To avoid conflict with any future version of this specification, the keys of any such entries should start with an underscore character. (See fn:random-number-generator.)
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:codepoints-to-string.)
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:codepoints-to-string.)
If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not defined in this specification then the meaning is implementation-defined. If the implementation recognizes the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize the keyword or value then if the fallback parameter is present with the value no it should reject the collation as unsupported, otherwise it should ignore the unrecognized parameter. (See The Unicode Collation Algorithm.)
The following query parameters are defined. If any parameter is absent, the default is implementation-defined except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in [UTS #35]. (See The Unicode Collation Algorithm.)
Because the set of collations that are supported is implementation-defined, an implementation has the option to support all collation URIs, in which case it will never raise this error. (See Choosing a collation.)
The properties available are as defined for the Unicode Collation Algorithm (see 5.3.4 The Unicode Collation Algorithm). Additional implementation-defined properties may be specified as described in the rules for UCA collation URIs. (See fn:collation.)
It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an implementation-defined property of the collation. (See fn:collation-key.)
Conforming implementations must support normalization form NFC and may support normalization forms NFD, NFKC, NFKD, and FULLY-NORMALIZED. They may also support other normalization forms with implementation-defined semantics. (See fn:normalize-unicode.)
It is implementation-defined which version of Unicode (and therefore, of the normalization algorithms and their underlying data) is supported by the implementation. See [UAX #15] for details of the stability policy regarding changes to the normalization rules in future versions of Unicode. If the input string contains codepoints that are unassigned in the relevant version of Unicode, or for which no normalization rules are defined, the fn:normalize-unicode function leaves such codepoints unchanged. If the implementation supports the requested normalization form then it must be able to handle every input string without raising an error. (See fn:normalize-unicode.)
It is possible to define collations that do not have the ability to decompose a string into units suitable for substring matching. An argument to a function defined in this section may be a URI that identifies a collation that is able to compare two strings, but that does not have the capability to split the string into collation units. Such a collation may cause the function to fail, or to give unexpected results, or it may be rejected as an unsuitable argument. The ability to decompose strings into collation units is an implementation-defined property of the collation. The fn:collation-available function can be used to ask whether a particular collation has this property. (See Functions based on substring matching.)
The result of the function will always be such that validation against this schema would succeed. However, it is implementation-defined whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:analyze-string.)
Some URI schemes are hierarchical and some are non-hierarchical. Implementations must treat the following schemes as non-hierarchical: jar, mailto, news, tag, tel, and urn. Whether additional schemes are known to be non-hierarchical implementation-defined. If a scheme is not known to be non-hierarchical, it must be treated as hierarchical. (See Parsing and building URIs.)
If the omit-default-ports option is true, the port is discarded and set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is implementation-defined. (See fn:parse-uri.)
If the omit-default-ports option is true then the $port is set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is implementation-defined. (See fn:build-uri.)
Processors may support a greater range and/or precision. The limits are implementation-defined. (See Limits and precision.)
Similarly, a processor may be unable accurately to represent the result of dividing a duration by 2, or multiplying a duration by 0.5. A processor that limits the precision of the seconds component of duration values must deliver a result that is as close as possible to the mathematically precise result, given these limits; if two values are equally close, the one that is chosen is implementation-defined. (See Limits and precision.)
All conforming processors must support year values in the range 1 to 9999, and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, processors may set larger implementation-defined limits on the maximum number of digits they support in these two situations. Processors may also choose to support the year 0 and years with negative values. The results of operations on dates that cross the year 0 are implementation-defined. (See Limits and precision.)
Similarly, a processor that limits the precision of the seconds component of date and time or duration values may need to deliver a rounded result for arithmetic operations. Such a processor must deliver a result that is as close as possible to the mathematically precise result, given these limits: if two values are equally close, the one that is chosen is implementation-defined. (See Limits and precision.)
...the format token n, N, or Nn, indicating that the value of the component is to be output by name, in lower-case, upper-case, or title-case respectively. Components that can be output by name include (but are not limited to) months, days of the week, timezones, and eras. If the processor cannot output these components by name for the chosen calendar and language then it must use an implementation-defined fallback representation. (See The picture string.)
...indicates alphabetic or traditional numbering respectively, the default being implementation-defined. This has the same meaning as in the second argument of fn:format-integer. (See The picture string.)
The sequence of characters in the (adjusted) first presentation modifier is reversed (for example, 999'### becomes ###'999). If the result is not a valid decimal digit pattern, then the output is implementation-defined. (See Formatting Fractional Seconds.)
The output for these components is entirely implementation-defined. The default presentation modifier for these components is n, indicating that they are output as names (or conventional abbreviations), and the chosen names will in many cases depend on the chosen language: see 10.8.4.8 The language, calendar, and place arguments. (See Formatting Other Components.)
The set of languages, calendars, and places that are supported in the date formatting functions is implementation-defined. When any of these arguments is omitted or is an empty sequence, an implementation-defined default value is used. (See The language, calendar, and place arguments.)
The choice of the names and abbreviations used in any given language is implementation-defined. For example, one implementation might abbreviate July as Jul while another uses Jly. In German, one implementation might represent Saturday as Samstag while another uses Sonnabend. Implementations may provide mechanisms allowing users to control such choices. (See The language, calendar, and place arguments.)
The choice of the names and abbreviations used in any given language for calendar units such as days of the week and months of the year is implementation-defined. (See The language, calendar, and place arguments.)
The calendar value if present must be a valid EQName (dynamic error: [err:FOFD1340]). If it is a lexical QName then it is expanded into an expanded QName using the statically known namespaces; if it has no prefix then it represents an expanded-QName in no namespace. If the expanded QName is in no namespace, then it must identify a calendar with a designator specified below (dynamic error: [err:FOFD1340]). If the expanded QName is in a namespace then it identifies the calendar in an implementation-defined way. (See The language, calendar, and place arguments.)
At least one of the above calendars must be supported. It is implementation-defined which calendars are supported. (See The language, calendar, and place arguments.)
The requirement to deliver a deterministic result has performance implications, and for this reason implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:doc.)
Various aspects of this processing are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:doc.)
It is implementation-defined whether DTD validation and/or schema validation is applied to the source document. (See fn:doc.)
The effect of a fragment identifier in the supplied URI is implementation-defined. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child. (See fn:doc.)
By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:collection.)
By default, this function is deterministic. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:uri-collection.)
It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:unparsed-text.)
It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:unparsed-text.)
...theThe processor may use implementation-defined heuristics to determine the likely encoding, otherwise.... (See fn:unparsed-text.)
The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:unparsed-text.)
The collation used for matching names is implementation-defined, but must be the same as the collation used to ensure that the names of all environment variables are unique. (See fn:environment-variable.)
Except to the extent defined by these options, the precise process used to construct the XDM instance is implementation-defined. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml.)
Options set in $options may be supplemented or modified based on configuration options defined externally using implementation-defined mechanisms. (See fn:parse-xml.)
Except as explicitly defined, the precise process used to construct the XDM instance is implementation-defined. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml-fragment.)
If the second argument is omitted, or is supplied in the form of an output:serialization-parameters element, then the values of any serialization parameters that are not explicitly specified is implementation-defined, and may depend on the context. (See fn:serialize.)
Because the [DOM: Living Standard] and [HTML: Living Standard] are not fixed, it is implementation-defined which versions are used. (See XDM Mapping from HTML DOM Nodes.)
If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is implementation-defined. (See XDM Mapping from HTML DOM Nodes.)
If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an implementation-defined replacement string is used. The result must be a valid NCName. (See node-name Accessor.)
If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an implementation-defined replacement string is used. The result must be a valid NCName. (See node-name Accessor.)
The default behaviour is implementation-defined. (See fn:parse-html.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an implementation-defined way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised [err:FOJS0001] if the input does not conform to the grammar. (See fn:parse-json.)
The supplied function is called to process the string value of any JSON number in the input. By default, numbers are processed by converting to xs:double using the XPath casting rules. Supplying the value xs:decimal#1 will instead convert to xs:decimal (which potentially retains more precision, but disallows exponential notation), while supplying a function that casts to (xs:decimal | xs:double) will treat the value as xs:decimal if there is no exponent, or as xs:double otherwise. Supplying the value fn:identity#1 causes the value to be retained unchanged as an xs:untypedAtomic. If the liberal option is false (the default), then the supplied number-parser is called if and only if the value conforms to the JSON grammar for numbers (for example, a leading plus sign and redundant leading zeroes are not allowed). If the liberal option is true then it is also called if the value conforms to an implementation-defined extension of this grammar. (See fn:parse-json.)
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:json-doc.)
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted. (See fn:json-doc.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an implementation-defined way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar. (See fn:json-to-xml.)
Default: Implementation-defined. (See fn:json-to-xml.)
Indicates that the resulting XDM instance must be typed; that is, the element and attribute nodes must carry the type annotations that result from validation against the schema given at C.2 Schema for the result of fn:json-to-xml, or against an implementation-defined schema if the liberal option has the value true. (See fn:json-to-xml.)
The result of the function will always be such that validation against this schema would succeed. However, it is implementation-defined whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:csv-to-xml.)
Additional, implementation-defined options may be available, for example, to control aspects of the XML serialization, to specify the grammar start symbol, or to produce output formats other than XML. (See fn:invisible-xml.)
If the arguments to fn:function-lookup identify a function that is present in the static context of the function call, the function will always return the same function that a static reference to this function would bind to. If there is no such function in the static context, then the results depend on what is present in the dynamic context, which is implementation-defined. (See fn:function-lookup.)
Default: The version given in the prolog of the library module; or implementation-defined if this is absent. (See fn:load-xquery-module.)
A sequence of URIs (in the form of xs:string values) which may be used or ignored in an implementation-defined way.... (See fn:load-xquery-module.)
Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XQuery processor. The meaning of the associated value is implementation-defined. Implementations should ignore options whose names are in an unrecognized namespace. The option parameter conventions do not apply to this contained map.... (See fn:load-xquery-module.)
It is implementation-defined whether constructs in the library module are evaluated in the same execution scope as the calling module. (See fn:load-xquery-module.)
The library module that is loaded may import schema declarations using an import schema declaration. It is implementation-defined whether schema components in the in-scope schema definitions of the calling module are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions of the calling and called modules must be consistent, according to the rules defined in Section 2.2.5 Consistency Constraints ^XQ31. (See fn:load-xquery-module.)
Default: Implementation-defined. (See fn:transform.)
Default: Implementation-defined. (See fn:transform.)
If the implementation provides a way of writing or invoking functions with side-effects, this post-processing function might be used to save a copy of the result document to persistent storage. For example, if the implementation provides access to the EXPath File library [EXPath], then a serialized document might be written to filestore by calling the file:write function. Similar mechanisms might be used to issue an HTTP POST request that posts the result to an HTTP server, or to send the document to an email recipient. The semantics of calling functions with side-effects are entirely implementation-defined. (See fn:transform.)
Calls to fn:transform can potentially have side-effects even in the absence of the post-processing option, because the XSLT specification allows a stylesheet to invoke extension functions that have side-effects. The semantics in this case are implementation-defined. (See fn:transform.)
A string intended to be used as the static base URI of the principal stylesheet module. This value must be used if no other static base URI is available. If the supplied stylesheet already has a base URI (which will generally be the case if the stylesheet is supplied using stylesheet-node or stylesheet-location) then it is implementation-defined whether this parameter has any effect. If the value is a relative reference, it is resolved against the static base URI of the fn:transform function call.... (See fn:transform.)
Values for vendor-defined configuration options for the XSLT processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is implementation-defined. Implementations should ignore options whose names are in an unrecognized namespace. Default is an empty map.... (See fn:transform.)
It is implementation-defined whether the XSLT transformation is executed within the same execution scope as the calling code. (See fn:transform.)
XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an implementation-defined way. (See fn:transform.)
If ST is xs:float or xs:double, then TV is the xs:decimal value, within the set of xs:decimal values that the implementation is capable of representing, that is numerically closest to SV. If two values are equally close, then the one that is closest to zero is chosen. If SV is too large to be accommodated as an xs:decimal, (see [XML Schema Part 2: Datatypes Second Edition] for implementation-defined limits on numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:decimal.)
In casting to xs:decimal or to a type derived from xs:decimal, if the value is not too large or too small but nevertheless cannot be represented accurately with the number of decimal digits available to the implementation, the implementation may round to the nearest representable value or may raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm and the choice between rounding and error behavior is implementation-defined. (See Casting from xs:string and xs:untypedAtomic.)
If ST is xs:decimal, xs:float or xs:double, then TV is SV with the fractional part discarded and the value converted to xs:integer. Thus, casting 3.1456 returns 3 while -17.89 returns -17. Casting 3.124E1 returns 31. If SV is too large to be accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for implementation-defined limits on numeric values) a dynamic error is raised [err:FOCA0003]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:integer.)
The tz timezone database, available at http://www.iana.org/time-zones. It is implementation-defined which version of the database is used. (See IANA Timezone Database.)
Unicode Standard Annex #15: Unicode Normalization Forms. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-02-24. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr15/. (See UAX #15.)
Unicode Standard Annex #29: Unicode Text Segmentation. Ed. Josh Hadley, Unicode Consortium. The current version is 15.1.0, dated 2023-08-16. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr29/. (See UAX #29.)
The Unicode Consortium, Reading, MA, Addison-Wesley, 2016. The Unicode Standard as updated from time to time by the publication of new versions. See http://www.unicode.org/standard/versions/ for the latest version and additional information on versions of the standard and of the Unicode Character Database. The version of Unicode to be used is implementation-defined, but implementations are recommended to use the latest Unicode version; currently, Version 9.0.0. (See The Unicode Standard.)
Unicode Technical Standard #10: Unicode Collation Algorithm. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-05-18. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr10/. (See UTS #10.)
Unicode Technical Standard #35: Unicode Locale Data Markup Language. Ed Mark Davis et al, Unicode Consortium. The current version is 29, dated 2016-03-15. As with [The Unicode Standard], the version to be used is implementation-defined. Available at: http://www.unicode.org/reports/tr35/. (See UTS #35.)

G Changes since 3.1 (Non-Normative)

G.1 Summary of Changes

Use the arrows to browse significant changes since the 3.1 version of this specification.
See 1 Introduction
Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.
See 1 Introduction
PR 1620 1886
Options are added to customize the form of the output.
See 2.2.6 fn:path
PR 1547 1551
New in 4.0
See 2.2.8 fn:siblings
PR 629 803
New in 4.0
See 3.2.2 fn:message
PR 1260 1275
A third argument has been added, providing control over the rounding mode.
See 4.4.4 fn:round
New in 4.0
See 4.4.7 fn:is-NaN
PR 1049 1151
Decimal format parameters can now be supplied directly as a map in the third argument, rather than referencing a format defined in the static context.
See 4.7.2 fn:format-number
PR 1205 1230
New in 4.0
See 4.8.2 math:e
See 4.8.16 math:sinh
See 4.8.17 math:cosh
See 4.8.18 math:tanh
The 3.1 specification suggested that every value in the result range should have the same chance of being chosen. This has been corrected to say that the distribution should be arithmetically uniform (because there are as many xs:double values between 0.01 and 0.1 as there are between 0.1 and 1.0).
See 4.9.2 fn:random-number-generator
PR 261 306 993
New in 4.0
See 5.4.1 fn:char
New in 4.0
See 5.4.2 fn:characters
PR 937 995 1190
New in 4.0
See 5.4.13 fn:hash
New in 4.0
See 7.6.2 fn:parse-uri
PR 1423 1413
New in 4.0
See 7.6.3 fn:build-uri
New in 4.0
See 11.2.6 fn:in-scope-namespaces
Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.
See 11.2.7 fn:in-scope-prefixes
Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.
See 11.2.8 fn:namespace-uri-for-prefix
New in 4.0
See 14.1.9 fn:replicate
New in 4.0
See 14.1.12 fn:slice
New in 4.0. The function is identical to the internal op:same-key function in 3.1
See 14.2.1 fn:atomic-equal
PR 1120 1150
A callback function can be supplied for comparing individual items.
See 14.2.2 fn:deep-equal
Changed in 4.0 to use transitive equality comparisons for numeric values.
See 14.2.4 fn:distinct-values
PR 614 987
New in 4.0
See 14.2.5 fn:duplicate-values
New in 4.0. Originally proposed under the name fn:uniform
See 14.4.6 fn:all-equal
New in 4.0. Originally proposed under the name fn:unique
See 14.4.7 fn:all-different
PR 1117 1279
The $options parameter has been added.
See 14.6.6 fn:unparsed-text-lines
PR 259 956
A new function is available for processing input data in HTML format.
See 15.2 Functions on HTML Data
New in 4.0
See 15.2.2 fn:parse-html
PR 975 1058 1246
An option is provided to control how JSON numbers should be formatted.
See 15.3.4 fn:parse-json
Additional options are available, as defined by fn:parse-json.
See 15.3.5 fn:json-doc
PR 533 719 834 1066
New in 4.0
See 15.4.4 fn:csv-to-arrays
See 15.4.7 fn:parse-csv
PR 533 719 834 1066 1605
New in 4.0
See 15.4.9 fn:csv-to-xml
PR 791 1256 1282 1405
New in 4.0
See 15.5.1 fn:invisible-xml
New in 4.0
See 17.2.4 fn:every
New in 4.0
See 17.2.10 fn:highest
New in 4.0
See 17.2.11 fn:index-where
New in 4.0
See 17.2.12 fn:lowest
New in 4.0
See 17.2.16 fn:scan-right
New in 4.0
See 17.2.17 fn:some
PR 521 761
New in 4.0
See 17.2.22 fn:transitive-closure
New in 4.0
See 18.4.6 map:filter
New in 4.0
See 18.4.10 map:items
PR 478 515
New in 4.0
See 18.4.12 map:keys-where
New in 4.0
See 18.4.14 map:of-pairs
New in 4.0
See 18.4.15 map:pair
New in 4.0
See 18.4.16 map:pairs
New in 4.0.
See 18.5.7 fn:elements-to-maps
New in 4.0
See 19.2.3 array:empty
PR 968 1295
New in 4.0
See 19.2.13 array:index-of
PR 476 1087
New in 4.0
See 19.2.16 array:items
PR 360 476
New in 4.0
See 19.2.18 array:members
See 19.2.19 array:of-members
New in 4.0
See 19.2.24 array:slice
New in 4.0
See 19.2.25 array:sort
New in 4.0
See 19.2.26 array:split
Supplying an empty sequence as the value of an optional argument is equivalent to omitting the argument.
See 19.2.27 array:subarray
PR 533 719 834
New functions are available for processing input data in CSV (comma separated values) format.
See 15.4 Functions on CSV Data
PR 734 1233
New in 4.0
See 17.2.2 fn:chain
PR 289 1901
A third argument is added, allowing user control of how absent keys should be handled.
See 18.4.9 map:get
A third argument is added, allowing user control of how index-out-of-bounds conditions should be handled.
See 19.2.11 array:get
The specification now describes how an initial BOM should be handled.
See 14.6.5 fn:unparsed-text
The specification now describes how an initial BOM should be handled.
See 14.6.5 fn:unparsed-text
PR 1727 1740
It is no longer guaranteed that the new key replaces the existing key.
See 18.4.17 map:put
PR 173
New in 4.0
See 17.3.4 fn:op
PR 203
New in 4.0
See 18.4.1 map:build
PR 207
New in 4.0
See 11.1.2 fn:parse-QName
See 11.2.5 fn:expanded-QName
PR 222
New in 4.0
See 14.2.7 fn:starts-with-subsequence
See 14.2.8 fn:ends-with-subsequence
See 14.2.9 fn:contains-subsequence
PR 250
New in 4.0
See 14.1.3 fn:foot
See 14.1.15 fn:trunk
See 19.2.2 array:build
See 19.2.8 array:foot
See 19.2.29 array:trunk
PR 258
New in 4.0
See 19.2.14 array:index-where
PR 313
The second argument can now be a sequence of integers.
See 14.1.8 fn:remove
PR 314
New in 4.0
See 18.4.4 map:entries
PR 326
Higher-order functions are no longer an optional feature.
See 1.2 Conformance
PR 419
New in 4.0
See 14.1.7 fn:items-at
PR 434
New in 4.0
See 4.5.2 fn:parse-integer
The function has been extended to allow output in a radix other than 10, for example in hexadecimal.
See 4.6.1 fn:format-integer
PR 482
Deleted an inaccurate statement concerning the behavior of NaN.
See 4.3 Comparison operators on numeric values
PR 507
New in 4.0
See 17.2.14 fn:partition
PR 546
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted.
See 5.2.1 fn:codepoints-to-string
It is no longer automatically an error if the resource (after decoding) contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted.
See 14.6.5 fn:unparsed-text
The rules regarding use of non-XML characters in JSON texts have been relaxed.
See 15.3.3 JSON character repertoire
See 15.3.4 fn:parse-json
It is no longer automatically an error if the input contains a codepoint that is not valid in XML. Instead, the codepoint must be a permitted character. The set of permitted characters is implementation-defined, but it is recommended that all Unicode characters should be accepted.
See 15.3.5 fn:json-doc
PR 623
Substantially revised to allow multiple sort key definitions.
See 17.2.18 fn:sort
PR 631
New in 4.0
See 7.3 fn:decode-from-uri
PR 662
Constructor functions now have a zero-arity form; the first argument defaults to the context item.
See 21 Constructor functions
PR 680
The case-insensitive collation is now defined normatively within this specification, rather than by reference to the HTML "living specification", which is subject to change. The collation can now be used for ordering comparisons as well as equality comparisons.
See 5.3.5 The HTML ASCII Case-Insensitive Collation
PR 702
The function can now take any number of arguments (previously it had to be two or more), and the arguments can be sequences of strings rather than single strings.
See 5.4.4 fn:concat
PR 710
Changes the function to return a sequence of key-value pairs rather than a map.
See 17.1.5 fn:function-annotations
PR 727
It has been clarified that loading a module has no effect on the static or dynamic context of the caller.
See 17.3.2 fn:load-xquery-module
PR 795
New in 4.0
See 17.2.19 fn:sort-with
PR 828
The $predicate callback function accepts an optional position argument.
See 17.2.5 fn:filter
The $action callback function accepts an optional position argument.
See 17.2.7 fn:fold-right
See 17.2.8 fn:for-each
See 17.2.9 fn:for-each-pair
The $predicate callback function now accepts an optional position argument.
See 19.2.4 array:filter
The $action callback function now accepts an optional position argument.
See 19.2.7 array:fold-right
See 19.2.9 array:for-each
See 19.2.10 array:for-each-pair
PR 881
The way that fn:min and fn:max compare numeric values of different types has changed. The most noticeable effect is that when these functions are applied to a sequence of xs:integer or xs:decimal values, the result is an xs:integer or xs:decimal, rather than the result of converting this to an xs:double
See 14.4.3 fn:max
See 14.4.4 fn:min
PR 901
All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.
See 3.1.1 fn:error
The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.
See 3.2.1 fn:trace
The third argument can now be supplied as an empty sequence.
See 5.4.6 fn:substring
The second argument can now be an empty sequence.
See 6.3.3 fn:tokenize
The optional second argument can now be supplied as an empty sequence.
See 7.1 fn:resolve-uri
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
See 10.8.1 fn:format-dateTime
See 10.8.2 fn:format-date
See 10.8.3 fn:format-time
The optional third argument can now be supplied as an empty sequence.
See 14.1.13 fn:subsequence
PR 905
The rule that multiple calls on fn:doc supplying the same absolute URI must return the same document node has been clarified; in particular the rule does not apply if the dynamic context for the two calls requires different processing of the documents (such as schema validation or whitespace stripping).
See 14.6.1 fn:doc
PR 909
The function has been expanded in scope to handle comparison of values other than strings.
See 14.2.3 fn:compare
PR 924
Rules have been added clarifying that users should not be allowed to change the schema for the fn namespace.
See C Schemas
PR 925
The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.
See 4.7.2 fn:format-number
PR 932
The specification now prescribes a minimum precision and range for durations.
See 9.1.2 Limits and precision
PR 933
When comments and processing instructions are ignored, any text nodes either side of the comment or processing instruction are now merged prior to comparison.
See 14.2.2 fn:deep-equal
PR 940
New in 4.0
See 17.2.20 fn:subsequence-where
PR 953
Constructor functions for named record types have been introduced.
See 21.6 Constructor functions for named record types
PR 962
New in 4.0
See 17.2.3 fn:do-until
See 17.2.23 fn:while-do
PR 969
New in 4.0
See 18.4.3 map:empty
PR 984
New in 4.0
See 9.4.1 fn:seconds
PR 987
The order of results is now prescribed; it was previously implementation-dependent.
See 14.2.4 fn:distinct-values
PR 988
New in 4.0
See 15.3.8 fn:pin
See 15.3.9 fn:label
PR 1022
Regular expressions can include comments (starting and ending with #) if the c flag is set.
See 6.1 Regular expression syntax
See 6.2 Flags
PR 1028
An option is provided to control how the JSON null value should be handled.
See 15.3.4 fn:parse-json
PR 1032
New in 4.0
See 14.1.17 fn:void
PR 1046
New in 4.0
See 17.2.21 fn:take-while
PR 1059
Use of an option keyword that is not defined in the specification and is not known to the implementation now results in a dynamic error; previously it was ignored.
See 1.7 Options
PR 1068
New in 4.0
See 5.4.3 fn:graphemes
PR 1072
The return type is now specified more precisely.
See 17.3.2 fn:load-xquery-module
PR 1090
When casting from a string to a duration or time or dateTime, it is now specified that when there are more digits in the fractional seconds than the implementation is able to retain, excess digits are truncated. Rounding upwards (which could affect the number of minutes or hours in the value) is not permitted.
See 22.2 Casting from xs:string and xs:untypedAtomic
PR 1093
New in 4.0
See 5.3.8 fn:collation
PR 1117
The $options parameter has been added.
See 14.6.5 fn:unparsed-text
See 14.6.7 fn:unparsed-text-available
PR 1182
The $predicate callback function may return an empty sequence (meaning false).
See 17.2.3 fn:do-until
See 17.2.4 fn:every
See 17.2.5 fn:filter
See 17.2.11 fn:index-where
See 17.2.17 fn:some
See 17.2.21 fn:take-while
See 17.2.23 fn:while-do
See 18.4.6 map:filter
See 18.4.12 map:keys-where
See 19.2.4 array:filter
See 19.2.14 array:index-where
PR 1191
New in 4.0
See 2.3.1 fn:distinct-ordered-nodes
The $options parameter has been added, absorbing the $collation parameter.
See 14.2.2 fn:deep-equal
PR 1250
For selected properties including percent and exponent-separator, it is now possible to specify a single-character marker to be used in the picture string, together with a multi-character rendition to be used in the formatted output.
See 4.7.2 fn:format-number
PR 1257
The $options parameter has been added.
See 15.1.1 fn:parse-xml
See 15.1.2 fn:parse-xml-fragment
PR 1262
New in 4.0
See 5.3.9 fn:collation-available
PR 1265
The constraints on the result of the function have been relaxed.
See 2.1.6 fn:document-uri
PR 1280
As a result of changes to the coercion rules, the number of supplied arguments can be greater than the number required: extra arguments are ignored.
See 17.2.1 fn:apply
PR 1288
Additional error conditions have been defined.
See 15.1.1 fn:parse-xml
PR 1296
New in 4.0
See 17.2.15 fn:scan-left
PR 1333
A new option is provided to allow the content of the loaded module to be supplied as a string.
See 17.3.2 fn:load-xquery-module
PR 1353
An option has been added to suppress the escaping of the solidus (forwards slash) character.
See 15.3.7 fn:xml-to-json
PR 1358
New in 4.0
See 10.3.2 fn:unix-dateTime
PR 1361
The term atomic value has been replaced by atomic item.
See 1.9 Terminology
PR 1393
Changes the function to return a sequence of key-value pairs rather than a map.
See 17.1.5 fn:function-annotations
PR 1409
This section now uses the term primitive type strictly to refer to the 20 atomic types that are not derived by restriction from another atomic type: that is, the 19 primitive atomic types defined in XSD, plus xs:untypedAtomic. The three types xs:integer, xs:dayTimeDuration, and xs:yearMonthDuration, which have custom casting rules but are not strictly-speaking primitive, are now handled in other subsections.
See 22.1 Casting from primitive types to primitive types
The rules for conversion of dates and times to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since these deliver exactly the same result as the XPath 3.1 rules.
See 22.1.2.2 Casting date/time values to xs:string
The rules for conversion of durations to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since the XSD 1.1 rules deliver exactly the same result as the XPath 3.1 rules.
See 22.1.2.3 Casting xs:duration values to xs:string
PR 1455
Numbers now retain their original lexical form, except for any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).
See 15.3.7 fn:xml-to-json
PR 1473
New in 4.0
See 14.1.5 fn:identity
PR 1481
The function has been extended to handle other Gregorian types such as xs:gYearMonth.
See 10.5.1 fn:year-from-dateTime
See 10.5.2 fn:month-from-dateTime
The function has been extended to handle other Gregorian types such as xs:gMonthDay.
See 10.5.3 fn:day-from-dateTime
The function has been extended to handle other types including xs:time.
See 10.5.4 fn:hours-from-dateTime
See 10.5.5 fn:minutes-from-dateTime
The function has been extended to handle other types such as xs:gYearMonth.
See 10.5.7 fn:timezone-from-dateTime
PR 1504
New in 4.0
See 14.1.11 fn:sequence-join
Optional $separator added.
See 19.2.17 array:join
PR 1523
New functions are provided to obtain information about built-in types and types defined in an imported schema.
See 20 Processing types
New in 4.0
See 20.1.2 fn:schema-type
See 20.1.4 fn:atomic-type-annotation
See 20.1.5 fn:node-type-annotation
PR 1545
New in 4.0
See 10.6.4 fn:civil-timezone
PR 1565
The default for the escape option has been changed to false. The 3.1 specification gave the default value as true, but this appears to have been an error, since it was inconsistent with examples given in the specification and with tests in the test suite.
See 15.3.4 fn:parse-json
PR 1570
New in 4.0
See 20.1.3 fn:type-of
PR 1575
A new function fn:elements-to-maps is provided for converting XDM trees to maps suitable for serialization as JSON. Unlike the fn:xml-to-json function retained from 3.1, this can handle arbitrary XML as input.
See 18.5 Converting Elements to Maps
PR 1611
The spec has been corrected to note that the function depends on the implicit timezone.
See 14.2.3 fn:compare
PR 1671
New in 4.0.
See 4.4.6 fn:divide-decimals
PR 1703
The order of entries in maps is retained.
See 15.3.4 fn:parse-json
Ordered maps are introduced.
See 18.1 Ordering of Maps
Enhanced to allow for ordered maps.
See 18.4.6 map:filter
See 18.4.7 map:find
See 18.4.8 map:for-each
See 18.4.17 map:put
See 18.4.18 map:remove
PR 1711
It is explicitly stated that the limits for $precision are implementation-defined.
See 4.4.4 fn:round
See 4.4.5 fn:round-half-to-even
PR 1727
For consistency with the new functions map:build and map:of-pairs, the handling of duplicates may now be controlled by supplying a user-defined callback function as an alternative to the fixed values for the earlier duplicates option.
See 18.4.13 map:merge
PR 1734
In 3.1, given a mixed input sequence such as (1, 3, 4.2e0), the specification was unclear whether it was permitted to add the first two integer items using integer arithmetic, rather than converting all items to doubles before performing any arithmetic. The 4.0 specification is clear that this is permitted; but since the items can be reordered before being added, this is not required.
See 14.4.2 fn:avg
See 14.4.5 fn:sum
PR 1825
New in 4.0
See 17.2.13 fn:partial-apply
PR 1856
Word boundaries can be matched. Lookahead and lookbehind assertions are supported. Assertions (including ^ and $) can no longer be followed by a quantifier.
See 6.1 Regular expression syntax
It is now permitted for the regular expression to match a zero-length string.
See 6.3.2 fn:replace
See 6.3.3 fn:tokenize
The output of the function is extended to allow the represention of captured groups found within lookahead assertions.
See 6.3.4 fn:analyze-string
It is now permitted for the regular expression to match a zero-length string.
See 6.3.4 fn:analyze-string
PR 1879
Additional options to control DTD and XInclude processing have been added.
See 15.1.1 fn:parse-xml
PR 1897
The $replacement argument can now be a function that computes the replacement strings.
See 6.3.2 fn:replace
PR 1910
An $options parameter is added. Note that the rules for the $options parameter control aspects of processing that were implementation-defined in earlier versions of this specification. An implementation may provide configuration options designed to retain backwards-compatible behavior when no explicit options are supplied.
See 14.6.1 fn:doc
See 14.6.2 fn:doc-available

XPath and XQuery Functions and Operators 4.0

W3C Editor's Draft 23 February 2026

Abstract

Status of this Document

Dedication

5 Processing strings

5.2 Functions to assemble and disassemble strings

5.2.1 fn:codepoints-to-string

14 Processing sequences

14.6 Functions giving access to external information

14.6.5 fn:unparsed-text

15 Parsing and serializing

15.1 Functions on XML Data

15.1.2 fn:parse-xml-fragment

15.2 Functions on HTML Data

15.2.2 fn:parse-html

15.3 Functions on JSON Data

15.3.5 fn:json-doc

F Implementation-defined features (Non-Normative)

G Changes since 3.1 (Non-Normative)

G.1 Summary of Changes