Main Page » XQuery » Serialization

Serialization

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:

included in the prolog of the XQuery expression
specified in XQuery functions, for example fn:serialize, file:write, or db:export
specified in REST query parameters
specified in RESTXQ output annotations
set via the SERIALIZER option before running a query
set via the EXPORTER option before exporting a database
supplied with the -s flag of the BaseX command-line clients

The output prefix is statically bound to the namespace for serialization parameters. This means that it need not (but may) be declared in the query prolog:

declare namespace output = 'http://www.w3.org/2010/xslt-xquery-serialization';
declare option output:method 'text';
<xml>Hi there</xml>

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.

Standard Parameters

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

Parameter	Description	Allowed	Default
`byte-order-mark`	Prints a byte-order-mark before starting serialization.	`yes`, `no`; map: boolean	`no`
`cdata-section-elements`	List of elements to be output as CDATA, separated by whitespace. Example: `<text><![CDATA[ <> ]]></text>`	string; map: QNames
`doctype-public`	If `doctype-system` is specified, adds a public identifier. Example: `<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">`	string
`doctype-system`	Introduces the output with a document type declaration and the given system identifier. Example: `<!DOCTYPE x SYSTEM "entities.dtd">`	string
`encoding`	Encoding to be used for outputting the data.	all encodings supported by Java	`UTF-8`
`escape-solidus`	Added: Escapes backslashes. Only applicable to `json` serialization method.	`yes`, `no`; map: boolean	`yes`
`escape-uri-attributes`	Escapes URI information in certain HTML attributes. Example: `<a href="%C3%A4%C3%B6%C3%BC">äöü<a>`	`yes`, `no`; map: boolean	`no`
`html-version`	Specifies the version of the HTML serialization method.	`4.0`, `4.01`, `5.0`; map: decimal	`4.0`
`include-content-type`	Inserts a `meta` content-type element into the head element if the result is output as HTML Example: `<head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></head>`. The head element must already exist or nothing will be added. Any existing `meta` content-type elements will be removed.	`yes`, `no`; map: boolean	`yes`
`indent`	Adds leading whitespace to make the output more readable.	`yes`, `no`; map: boolean	`no`
`indent-attributes`	Updated: Outputs the attributes of an element on separate lines. Has no effect if `indent` is disabled.	`yes`, `no`	`no`
`indent-unit`	Added: Specifies the string that represents a single level of indentation. It is repeated once for each level of nesting. If the value is empty, line breaks are output without indentation. Has no effect if `indent` is disabled. Supersedes `indents` and `tabulator`.	spaces or tabs; `\t` is interpreted as a tab	two spaces
`item-separator`	Determines a string to be used as item separator. If a separator is specified, the default separation of atomic values with single whitespace will be skipped.	string
`json-lines`	Added: Output in JSON Lines format. Only applicable to `json` serialization method.	`yes`, `no`; map: boolean	`no`
`line-ending`	Added: Specifies the string that is used to separate lines of output. Every newline character that would otherwise be output, including newlines in the serialized content, is replaced with this string. If results are returned as strings (see `fn:serialize`), the default is `\n`. Supersedes `newline`.	`\n`, `\r\n`, `\r`	system dependent
`media-type`	Specifies the media type.	string	`application/xml`
`method`	Specifies the serialization method. `xml`, `xhtml`, `html`, `text` and `adaptive` are part of the official specification. For more details on `basex`, `csv` and `json`, see XQuery Extensions.	`xml`, `xhtml`, `html`, `text`, `json`, `adaptive`, `csv`, `basex`; map: string or QName	`basex`
`normalization-form`	Specifies a normalization form. BaseX supports Form C (`NFC`).	`NFC`, `none`	`NFC`
`omit-xml-declaration`	Omits the XML declaration, which is serialized before the actual query result Example: `<?xml version="1.0" encoding="UTF-8"?>`	`yes`, `no`; map: boolean	`yes`
`parameter-document`	Parses the value as an XML document with additional serialization parameters. Can only be specified in the query prolog (see XQuery: Specification for details and examples).	string
`standalone`	Prints or omits the `standalone` attribute in the XML declaration.	`yes`, `no`, `omit`; map: boolean, `()` for `omit`	`omit`
`undeclare-prefixes`	Undeclares prefixes in XML 1.1.	`yes`, `no`; map: boolean	`no`
`use-character-maps`	Defines character mappings. If mappings are supplied as a single string, keys and values are separated by the equal sign, and multiple pairs are separated by commas. Example: `A=alpha,B=beta`. In a key, the characters `%`, `,`, `=` and whitespace are percent-encoded (`%25`, `%2C`, `%3D`, `%20`); in a value, commas are duplicated. Example: `%3D=equals,;=,,`	string; map: map
`version`	Specifies the version of the serialization method.	xml/xhtml: `1.0`, `1.1` html: `4.0`, `4.01`, `5.0`	`1.0`

Custom Parameters

BaseX provides some additional serialization parameters:

Parameter	Description	Allowed	Default
`binary`	Indicates if items of binary type are output in their native byte representation. Only applicable to the `basex` serialization method.	`yes`, `no`	`yes`
`csv`	Defines the way how data is serialized as CSV.	see CSV Functions
`indents`	Specifies the number of characters to be indented. Updated: Superseded by `indent-unit`.	positive number	`2`
`json`	Defines the way how data is serialized as JSON.	see JSON Functions
`limit`	Stops serialization after the specified number of bytes has been serialized. If a negative number is specified, everything will be output.	positive number	`-1`
`newline`	Specifies the type of newline to be used as end-of-line marker. Updated: Superseded by `line-ending`.	`\n`, `\r\n`, `\r`	system dependent
`tabulator`	Uses tab characters (`\t`) instead of spaces for indenting elements. Updated: Superseded by `indent-unit`.	`yes`, `no`	`no`

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

declare option output:method "csv";
declare option output:csv "header=yes, separator=semicolon";
<csv>
  <record>
    <Name>John</Name>
    <City>Newton</City>
  </record>
  <record>
    <Name>Jack</Name>
    <City>Oldtown</City>
  </record>
</csv>

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

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

Result:

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   (without the serialization parameter, the Unicode character would be output):

Example query:

declare option output:parameter-document "map.xml";
<x>&#xA0;</x>

Example parameter-document:

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

Changelog

Version 13.0

Added: Serialization parameters escape-solidus, json-lines, indent-unit, line-ending.
Updated: indent-attributes is now a standard serialization parameter.
Updated: indents, newline and tabulator are superseded by indent-unit and line-ending.

Version 11.0

Added: Serialization parameter indent-attributes.

Version 10.0

Updated: indent: Default changed from yes to no.

Version 9.2

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

Version 8.4

Added: Serialization parameter binary.
Updated: New serialization method basex. By default, items of binary type are now output in their native byte representation. The method raw 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: method=html5 removed; serializers updated with the latest version of the specification, using method=html and version=5.0.

Version 7.2

Added: separator parameter.

Version 7.1

Added: newline parameter.

Version 7.0

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

⚡Generated with XQuery