fn:serialize

fn:serialize($arg as item()*) as xs:string

fn:serialize(
    $arg as item()*, 
    $params as item()?
) as xs:string

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

The value of the first argument $arg acts as the input sequence to the serialization process, which starts with sequence normalization.

The second argument $params, if present, provides serialization parameters. These may be supplied in either of two forms:

1. As an output:serialization-parameters element, having the format described in Setting Serialization Parameters by Means of a Data Model Instance. In this case the type of the supplied argument must match the required type element(output:serialization-parameters).

2. As a map. In this case the type of the supplied argument must match the required type map(*)

The single-argument version of this function has the same effect as the two-argument version called with $params set to an empty sequence. This in turn is the same as the effect of passing an output:serialization-parameters element with no child elements.

The final stage of serialization, that is, encoding, is skipped. If the serializer does not allow this phase to be skipped, then the sequence of octets returned by the serializer is decoded into a string by reversing the character encoding performed in the final stage.

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.

If the second argument is supplied as a map, then the option parameter conventions apply. In this case:

1. Each entry in the map defines one serialization parameter.

2. The key of the entry is an xs:string value in the cases of parameter names defined in these specifications, or an xs:QName (with non-absent namespace) in the case of implementation-defined serialization parameters.

3. The required type of each parameter, and its default value, are defined by the following table. The default value is used when the map contains no entry for the parameter in question, and also when an entry is present, with the empty sequence as its value. The table also indicates how the value of the map entry is to be interpreted in cases where further explanation is needed.

Notes to the table:

1. The notation union(A, B) is used to represent a union type whose member types are A and B.

2. If an xs:QName is supplied for the method or json-node-output-method options, then it must have a non-absent namespace URI. This means that system-defined serialization methods such as xml and json are defined as strings, not as xs:QName values.

3. For the use-character-maps option, the value is a map, whose keys are the characters to be mapped (as xs:string instances), and whose corresponding values are the strings to be substituted for these characters.

A type error [ERRXPTY0004] occurs if the second argument is present and does not match either of the types element(output:serialization-parameters)? or map(*).

This is defined as a type error so that it can be enforced via the function signature by implementations that generalize the type system in a suitable way.

If the host language makes serialization an optional feature and the implementation does not support serialization, then a dynamic error [ERRFODC0010] is raised.

The serialization process will raise an error if $arg is an attribute or namespace node.

When the second argument is supplied as a map, and the supplied value is of the wrong type for the particular parameter, for example if the value of indent is a string rather than a boolean, then as defined by the option parameter conventions, a type error [ERRXPTY0004] is raised. If the value is of the correct type, but does not satisfy the rules for that parameter defined in [Serialization 3.1], then a dynamic error [ERRSER31PM0016] is raised. (For example, this occurs if the map supplied to use-character-maps includes a key that is a string whose length is not one (1)).

If any serialization error occurs, including the detection of an invalid value for a serialization parameter as described above, this results in the fn:serialize call failing with a dynamic error.

One use case for this function arises when there is a need to construct an XML document containing nested XML documents within a CDATA section (or on occasions within a comment). See fn:parse-xml for further details.

Another use case arises when there is a need to call an extension function that expects a lexical XML document as input.

There are also use cases where the application wants to post-process the output of a query or transformation, for example by adding an internal DTD subset, or by inserting proprietary markup delimiters such as the <% ... %> used by some templating languages.

The ability to specify the serialization parameters in an output:serialization-parameters element provides backwards compatibility with the 3.0 version of this specification; the ability to use a map takes advantage of new features in the 3.1 version. The default parameter values are implementation-defined when an output:serialization-parameters element is used (or when the argument is omitted), but are fixed by this specification in the case where a map (including an empty map) is supplied for the argument.

Given the variables:

let $params := 
<output:serialization-parameters 
        xmlns:output="http://www.w3.org/2010/xslt-xquery-serialization">
  <output:omit-xml-declaration value="yes"/>
</output:serialization-parameters>
         

let $data := 
<a b="3"/>
         

The following call might produce the output shown:

The expression fn:serialize($data, $params) returns '<a b="3"/>'.

The following call would also produce the output shown (though the second argument could equally well be supplied as an empty map (map{}), since both parameters are given their default values):

The expression fn:serialize($data, map{"method":"xml", "omit-xml-declaration":true()}) returns '<a b="3"/>'.