Serialization

This page is part of the XQuery Portal.

Serialization parameters define how XQuery items and XML nodes will be serialized (i.e., returned to the client or an API, usually in textual form). The official parameters are defined in the W3C XQuery Serialization 3.1 document. In BaseX, they can be specified by:


 * including them in the prolog of the XQuery expression;
 * specifying them in the XQuery functions file:write or fn:serialize. The serialization parameters are specified as
 * children of an &lt;output:serialization-parameters/&gt; element, as defined for the fn:serialize function, or as
 * map, which contains all key/value pairs: ;
 * using the -s flag of the BaseX command-line clients;
 * setting the option before running a query;
 * setting the option before exporting a database; or
 * setting them as REST query parameters.

Due to the wide range of ways how parameters can be supplied, we deliberately ignored one rule of the specification, which requires non-official features to be defined in a non-null namespace URI. In the following, we will indicate which features are specific to our implementation.

=Parameters=

The following serialization parameters are supported by BaseX (further details can be looked up in the official specification):

BaseX provides some additional serialization parameters:

The csv and json parameters are supplied with a list of options. Option names and values are combined with, several options are separated by  :

 (: The output namespace declaration is optional, because it is statically declared in BaseX) :) declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization"; declare option output:method "csv"; declare option output:csv "header=yes, separator=semicolon";   John    Newton    Jack    Oldtown

If fn:serialize is called, output-specific parameters can be supplied via nested options:

 serialize(     John      Newton      Jack      Oldtown</City> ,  map {    'method': 'csv',    'csv': map { 'header': 'yes', 'separator': ';' }  } )

Result: <pre class="brush:xml"> Name;City John;Newton Jack;Oldtown

=Character mappings=

Character maps allow a specific character in the instance of the data model to be replaced with a specified string of characters during serialization. The string that is substituted is output "as is," and the serializer performs no checks that the resulting document is well-formed. This may only occur in documents parsed with parameter-document. If a character is mapped, then it is not subjected to XML or HTML escaping. For details refer to section 11 Character maps in the W3C XQuery Serialization 3.1 document

This example maps the Unicode U+00A0 NO-BREAK SPACE as &amp;#160; (without the serialization parameter, the Unicode character would be output):

Example query: <pre class="brush:xquery"> declare option output:parameter-document "map.xml"; <x>&amp;#xA0;</x>

Example parameter-document: <pre class="brush:xml"> <serialization-parameters xmlns="http://www.w3.org/2010/xslt-xquery-serialization"> <use-character-maps> <character-map character="&amp;#160;" map-string="&amp;amp;#160;"/> </use-character-maps> </serialization-parameters>

=Changelog=


 * Version 9.2


 * Updated: New default value for include-content-type is yes.


 * Version 8.4


 * Added: Serialization parameter binary.
 * Updated: New serialization method . By default, items of binary type are now output in their native byte representation. The method   was removed.


 * Version 8.0


 * Added: Support for use-character-maps and parameter-document.
 * Added: Serialization method adaptive.
 * Updated: adaptive is new default method (before: xml).
 * Removed: format, wrap-prefix, wrap-uri.


 * Version 7.8.2


 * Added: limit: Stops serialization after the specified number of bytes has been serialized.


 * Version 7.8


 * Added: csv and json serialization parameters.
 * Removed: separator option (use item-separator instead).


 * Version 7.7.2


 * Added: csv serialization method.
 * Added: temporary serialization methods csv-header, csv-separator, json-unescape, json-spec, json-format.


 * Version 7.5


 * Added: official item-separator and html-version parameter.
 * Updated:  removed; serializers updated with the latest version of the specification, using   and.


 * Version 7.2


 * Added: separator parameter.


 * Version 7.1


 * Added: newline parameter.


 * Version 7.0


 * Added: Serialization parameters added to REST API; JSON/JsonML/raw methods.