Difference between revisions of "Serialization"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "syntaxhighlight" to "pre")
 
(108 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
This page is part of the [[XQuery|XQuery Portal]].
 
This page is part of the [[XQuery|XQuery Portal]].
−
Serialization parameters define how XQuery items and XML nodes are textually output, i.e., ''serialized''. (For input see [[Parsers]].)
 
−
They have been formalized in the [http://www.w3.org/TR/xslt-xquery-serialization-30 W3C XQuery Serialization 3.0] document.
 
−
In BaseX, they can be specified in several ways:
 
  
−
* by including them in the [[XQuery_3.0#Serialization|prolog of the XQuery expression]],
+
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 [https://www.w3.org/TR/xslt-xquery-serialization-31 W3C XQuery Serialization 3.1] document. In BaseX, they can be:
−
* by specifying them in the XQuery functions [[File_Module#file:write|file:write()]] or [[XQuery_3.0#Functions|fn:serialize()]],
 
−
* by using the {{Code|-s}} flag of the BaseX [[Startup_Options#BaseX|command-line]] clients,
 
−
* by setting the [[Options#SERIALIZER|SERIALIZER]] option before running a query,
 
−
* by setting the [[Options#EXPORTER|EXPORTER]] option before exporting a database, or
 
−
* by setting them as [[REST#Query_Parameters|REST]] query parameters<br/><br/>
 
  
−
=Parameters=
+
* included in the [[XQuery_3.0#Serialization|prolog of the XQuery expression]];
 +
* specified in XQuery functions ({{Function|File|file:write}}, {{Function|Database|db:export}}, [https://www.w3.org/TR/xpath-functions-31/#func-serialize fn:serialize()]);
 +
* specified in [[REST#Parameters|REST query parameters]];
 +
* specified in [[RESTXQ#Output|RESTXQ output annotations]];
 +
* set via the {{Option|SERIALIZER}} option before running a query;
 +
* set via the {{Option|EXPORTER}} option before exporting a database; or
 +
* supplied with the {{Code|-s}} flag of the BaseX [[Command-Line Options#BaseX Standalone|command-line]] clients.
  
−
The following table gives a brief summary of all serialization parameters recognized by BaseX. For details, please refer to official specification.
+
The namespace for serialization parameters is statically bound to the {{Code|output}} prefix. This means that it need not (but may) be declared in the query prolog:
 +
 
 +
<pre lang='xquery'>
 +
declare namespace output = 'http://www.w3.org/2010/xslt-xquery-serialization';
 +
declare option output:method 'text';
 +
<xml>Hi there</xml>
 +
</pre>
 +
 
 +
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):
  
 
{| class="wikitable sortable" width="100%"
 
{| class="wikitable sortable" width="100%"
 
|- valign="top"
 
|- valign="top"
−
! Parameter
+
! width="140" | Parameter
 
! Description
 
! Description
 
! Allowed
 
! Allowed
 
! Default
 
! Default
−
! Examples
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|method}}
 
| {{Code|method}}
−
| Specifies the serialization method:
+
| Specifies the serialization method. {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, {{Code|text}} and {{Code|adaptive}} are part of the official specification. For more details on {{Code|basex}}, {{Code|csv}} and {{Code|json}}, see [[XQuery Extensions#Serialization|XQuery Extensions]].
−
* {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, and {{Code|text}} are adopted from the official specification.
+
| {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, {{Code|text}}, {{Code|json}}, {{Code|adaptive}}, {{Code|csv}}, {{Code|basex}}
−
* {{Code|json}} and {{Code|jsonml}} are specific to BaseX and can be used to output XML nodes in the JSON format (see the [[JSON Module]] for more details).
+
| {{Code|basex}}
−
* {{Code|raw}} is BaseX-specific as well: Binary data types are output in their ''raw'' form, i.e., without modifications. For all other types, the items’ string values are returned. No indentation takes place, and and no characters are encoded via entities.
 
−
| {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, {{Code|text}}, {{Code|json}}, {{Code|jsonml}}, {{Code|raw}}
 
−
| {{Code|xml}}
 
−
| <code>method=xml</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|version}}
 
| {{Code|version}}
−
| Specifies the version of the serialization method. Added with {{Version|7.5}}.
+
| Specifies the version of the serialization method.
−
| {{Code|xml/xhtml}}: {{Code|1.0}}, {{Code|1.1}}<br/>{{Code|html}}: {{Code|4.0}}, {{Code|4.01}}, {{Code|5.0}}<br/>
+
| xml/xhtml: {{Code|1.0}}, {{Code|1.1}}<br/>html: {{Code|4.0}}, {{Code|4.01}}, {{Code|5.0}}<br/>
 
| {{Code|1.0}}
 
| {{Code|1.0}}
−
| <code>version=1.0</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|html-version}}
 
| {{Code|html-version}}
−
| Specifies the version of the HTML serialization method. Added with {{Version|7.5}}.
+
| Specifies the version of the HTML serialization method.
 
| {{Code|4.0}}, {{Code|4.01}}, {{Code|5.0}}
 
| {{Code|4.0}}, {{Code|4.01}}, {{Code|5.0}}
 
| {{Code|4.0}}
 
| {{Code|4.0}}
−
| <code>html-version=5.0</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|item-separator}}
 
| {{Code|item-separator}}
 
| Determines a string to be used as item separator. If a separator is specified, the default separation of atomic values with single whitespaces will be skipped.
 
| Determines a string to be used as item separator. If a separator is specified, the default separation of atomic values with single whitespaces will be skipped.
−
| ''arbitrary strings'', {{Code|\n}}, {{Code|\r\n}}, {{Code|\r}}
+
| ''string''
−
| ''empty''
+
|
−
| <code>item-separator=&#a;</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|encoding}}
 
| {{Code|encoding}}
 
| Encoding to be used for outputting the data.
 
| Encoding to be used for outputting the data.
−
| ''[http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html all encodings supported by Java]''
+
| ''[https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html all encodings supported by Java]''
 
| {{Code|UTF-8}}
 
| {{Code|UTF-8}}
−
| <code>encoding=US-ASCII</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|indent}}
 
| {{Code|indent}}
−
| Adjusts whitespaces to make the output better readable.
+
| Adds leading whitespaces to make the output more readable.
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}, {{Code|no}}
−
| {{Code|yes}}
+
| {{Code|no}}
−
| <code>indent=no</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|cdata-section-elements}}
 
| {{Code|cdata-section-elements}}
−
| List of elements to be output as CDATA, separated by whitespaces.<br />Example: {{Code|&lt;text&gt;&lt;![CDATA[ &lt;&gt; ]]&gt;&lt;/text&gt;}}
+
| List of elements to be output as CDATA, separated by whitespaces.<br/>Example: {{Code|&lt;text&gt;&lt;![CDATA[ &lt;&gt; ]]&gt;&lt;/text&gt;}}
−
|  
+
| ''string''
 
|  
 
|  
−
| <code>cdata-section-elements=text</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|omit-xml-declaration}}
 
| {{Code|omit-xml-declaration}}
−
| Omits the XML declaration, which is serialized before the actual query result<br />Example: <code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</code>
+
| Omits the XML declaration, which is serialized before the actual query result<br/>Example: <code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</code>
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}
 
| {{Code|yes}}
−
| <code>omit-xml-declaration=no</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|standalone}}
 
| {{Code|standalone}}
−
| Prints or omits the "standalone" attribute in the XML declaration.
+
| Prints or omits the {{Code|standalone}} attribute in the XML declaration.
 
| {{Code|yes}}, {{Code|no}}, {{Code|omit}}
 
| {{Code|yes}}, {{Code|no}}, {{Code|omit}}
 
| {{Code|omit}}
 
| {{Code|omit}}
−
| <code>standalone=yes</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|doctype-system}}
 
| {{Code|doctype-system}}
−
| Introduces the output with a document type declaration and the given system identifier.<br />Example: {{Code|&lt;!DOCTYPE x SYSTEM "entities.dtd"&gt;}}
+
| Introduces the output with a document type declaration and the given system identifier.<br/>Example: {{Code|&lt;!DOCTYPE x SYSTEM "entities.dtd"&gt;}}
−
|
+
| ''string''
 
|
 
|
−
| <code>doctype-system=entities.dtd</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|doctype-public}}
 
| {{Code|doctype-public}}
−
| If {{Code|doctype-system}} is specified, adds a public identifier.<br />Example: {{Code|&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"&gt;}}
+
| If {{Code|doctype-system}} is specified, adds a public identifier.<br/>Example: {{Code|&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"&gt;}}
−
|  
+
| ''string''
 
|
 
|
−
| <code>doctype-public=-//W3C//DTD HTML 4.01//EN,<br />doctype-system=http://www.w3.org/TR/html4/strict.dtd</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|undeclare-prefixes}}
 
| {{Code|undeclare-prefixes}}
Line 96: Line 91:
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|no}}
 
| {{Code|no}}
−
| <code>undeclare-prefixes=yes</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|normalization-form}}
 
| {{Code|normalization-form}}
Line 102: Line 96:
 
| {{Code|NFC}}, {{Code|none}}
 
| {{Code|NFC}}, {{Code|none}}
 
| {{Code|NFC}}
 
| {{Code|NFC}}
−
| <code>normalization-form=none</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|media-type}}
 
| {{Code|media-type}}
 
| Specifies the media type.
 
| Specifies the media type.
−
|  
+
| ''string''
 
| {{Code|application/xml}}
 
| {{Code|application/xml}}
−
| <code>media-type=text/plain</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|use-character-maps}}
 
| {{Code|use-character-maps}}
−
| Defines character mappings (not supported).
+
| 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. Separators that are to be defined as keys or values can be encoded as entities.<br/>Example: <code>A=alpha,B=beta</code>
−
|  
+
| ''string''
 
|  
 
|  
−
|
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|byte-order-mark}}
 
| {{Code|byte-order-mark}}
Line 120: Line 111:
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|no}}
 
| {{Code|no}}
−
| <code>byte-order-mark=yes</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|escape-uri-attributes}}
 
| {{Code|escape-uri-attributes}}
−
| Escapes URI information in certain HTML attributes<br />Example: <code>&lt;a&nbsp;href="%C3%A4%C3%B6%C3%BC"&gt;äöü&lt;a&gt;</code>
+
| Escapes URI information in certain HTML attributes<br/>Example: <code>&lt;a&nbsp;href="%C3%A4%C3%B6%C3%BC"&gt;äöü&lt;a&gt;</code>
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|no}}
 
| {{Code|no}}
−
| <code>escape-uri-attributes=yes, method=html</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|include-content-type}}
 
| {{Code|include-content-type}}
−
| Includes a {{Code|meta}} content-type element if the result is output as HTML<br />Example: <code>&lt;head&gt;&lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8"&gt;&lt;/head&gt;</code>
+
| Inserts a {{Code|meta}} content-type element into the head element if the result is output as HTML<br/>Example: <code>&lt;head&gt;&lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8"&gt;&lt;/head&gt;</code>. The head element must already exist or nothing will be added. Any existing {{Code|meta}} content-type elements will be removed.
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}, {{Code|no}}
−
| {{Code|no}}
+
| {{Code|yes}}
−
| <code>include-content-type=yes, method=html</code>
+
|}
 +
 
 +
=Query Prolog Parameters=
 +
 
 +
The following parameters can only be specified in the query prolog (see [https://www.w3.org/TR/xquery-31/#id-serialization XQuery: Specification] for more details and examples):
 +
 
 +
{| class="wikitable sortable" width="100%"
 +
|- valign="top"
 +
! width="140" | Parameter
 +
! Description
 +
! Allowed
 +
! Default
 +
|- valign="top"
 +
| {{Code|parameter-document}}
 +
| Parses the value as an XML document with additional serialization parameters.
 +
| ''string''
 +
|
 
|}
 
|}
  
−
BaseX provides some additional, implementation-specific serialization parameters:
+
=Custom Parameters=
 +
 
 +
BaseX provides some additional serialization parameters:
  
 
{| class="wikitable sortable" width="100%"
 
{| class="wikitable sortable" width="100%"
 
|- valign="top"
 
|- valign="top"
−
! Parameter
+
! width="140" | Parameter
 
! Description
 
! Description
 
! Allowed
 
! Allowed
 
! Default
 
! Default
−
! Examples
 
 
|- valign="top"
 
|- valign="top"
−
| {{Code|format}}
+
| {{Code|csv}}
−
| Turns output formatting on/off, including the conversion of special characters to entities and insertion of item separators.
+
| Defines the way how data is serialized as CSV.
−
| {{Code|yes}}, {{Code|no}}
+
| see [[CSV Module]]
−
| {{Code|yes}}
+
|
−
| <code>format=no</code>
+
|- valign="top"
 +
| {{Code|json}}
 +
| Defines the way how data is serialized as JSON.
 +
| see [[JSON Module]]
 +
|  
 
|- valign="top"
 
|- valign="top"
 
| {{Code|tabulator}}
 
| {{Code|tabulator}}
−
| Uses tab characters ({{Code|\t}}) for indenting elements.
+
| Uses tab characters ({{Code|\t}}) instead of spaces for indenting elements.
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|yes}}, {{Code|no}}
 
| {{Code|no}}
 
| {{Code|no}}
−
| <code>tabulator=yes</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|indents}}
 
| {{Code|indents}}
Line 161: Line 170:
 
| ''positive number''
 
| ''positive number''
 
| {{Code|2}}
 
| {{Code|2}}
−
| <code>indents=1, tabulator=yes</code>
 
 
|- valign="top"
 
|- valign="top"
−
| {{Code|wrap-prefix}},<br />{{Code|wrap-uri}}
+
| {{Code|indent-attributes}}
−
| Specifies a prefix and/or URI for wrapping the query results.
+
| {{Announce|Version 11:}} Indent attributes after the element name, one below the other.
−
|  
+
| {{Code|yes}}, {{Code|no}}
−
|  
+
| {{Code|false}}
−
| <code>wrap-prefix=rest, wrap-uri=http://basex.org/rest</code>
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|newline}}
 
| {{Code|newline}}
Line 173: Line 180:
 
| {{Code|\n}}, {{Code|\r\n}}, {{Code|\r}}
 
| {{Code|\n}}, {{Code|\r\n}}, {{Code|\r}}
 
| ''system dependent''
 
| ''system dependent''
−
| <code>newline=\r\n</code>
 
 
|- valign="top"
 
|- valign="top"
−
| {{Code|separator}}
+
| {{Code|limit}}
−
| Determines the string to be used as item separator (deprecated, replaced with {{Code|item-separator}}).
+
| Stops serialization after the specified number of bytes has been serialized. If a negative number is specified, everything will be output.
−
| {{Code|\n}}, {{Code|\r\n}}, {{Code|\r}}, ''arbitrary strings''
+
| ''positive number''
−
| ''single space''
+
| {{Code|-1}}
−
| <code>separator=\n</code>
+
|- valign="top"
 +
| {{Code|binary}}
 +
| Indicates if items of binary type are output in their native byte representation. Only applicable to the <code>base</code> serialization method.
 +
| {{Code|yes}}, {{Code|no}}
 +
| {{Code|yes}}
 
|}
 
|}
 +
 +
The {{Code|csv}} and {{Code|json}} parameters are supplied with a list of options. Option names and values are combined with <code>=</code>, several options are separated by <code>,</code>:
 +
 +
<pre lang='xquery'>
 +
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>
 +
</pre>
 +
 +
If {{Code|fn:serialize}} is called, output-specific parameters can be supplied via nested options:
 +
 +
<pre lang='xquery'>
 +
serialize(
 +
  <csv>
 +
    <record>
 +
      <Name>John</Name>
 +
      <City>Newton</City>
 +
    </record>
 +
    <record>
 +
      <Name>Jack</Name>
 +
      <City>Oldtown</City>
 +
    </record>
 +
  </csv>,
 +
  map {
 +
    'method': 'csv',
 +
    'csv': map { 'header': 'yes', 'separator': ';' }
 +
  }
 +
)
 +
</pre>
 +
 +
'''Result''':
 +
<pre lang="xml">
 +
Name;City
 +
John;Newton
 +
Jack;Oldtown
 +
</pre>
 +
 +
=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 {{Code|parameter-document}}. If a character is mapped, then it is not subjected to XML or HTML escaping. For details, refer to section [https://www.w3.org/TR/2015/CR-xslt-xquery-serialization-31-20151217/#character-maps 11 Character maps] in the [https://www.w3.org/TR/xslt-xquery-serialization-31 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 lang='xquery'>
 +
declare option output:parameter-document "map.xml";
 +
<x>&amp;#xA0;</x>
 +
</pre>
 +
 +
'''Example parameter-document''':
 +
<pre lang="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>
 +
</pre>
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 11.0
 +
* Added: Serialization parameter {{Code|indent-attributes}}.
 +
 +
;Version 10.0
 +
* Updated: {{Code|indent}}: Default changed from {{Code|yes}} to {{Code|no}}.
 +
 +
;Version 9.2
 +
* Updated: New default value for {{Code|include-content-type}} is {{Code|yes}}.
 +
 +
;Version 8.4
 +
* Added: Serialization parameter {{Code|binary}}.
 +
* Updated: New serialization method <code>basex</code>. By default, items of binary type are now output in their native byte representation. The method <code>raw</code> was removed.
 +
 +
;Version 8.0
 +
* Added: Support for {{Code|use-character-maps}} and {{Code|parameter-document}}.
 +
* Added: Serialization method {{Code|adaptive}}.
 +
* Updated: {{Code|adaptive}} is new default method (before: {{Code|xml}}).
 +
* Removed: {{Code|format}}, {{Code|wrap-prefix}}, {{Code|wrap-uri}}.
 +
 +
;Version 7.8.2
 +
* Added: {{Code|limit}}: Stops serialization after the specified number of bytes has been serialized.
 +
 +
;Version 7.8
 +
* Added: {{Code|csv}} and {{Code|json}} serialization parameters.
 +
* Removed: {{Code|separator}} option (use {{Code|item-separator}} instead).
 +
 +
;Version 7.7.2
 +
* Added: {{Code|csv}} serialization method.
 +
* Added: temporary serialization methods {{Code|csv-header}}, {{Code|csv-separator}}, {{Code|json-unescape}}, {{Code|json-spec}}, {{Code|json-format}}.
  
 
;Version 7.5
 
;Version 7.5
−
 
+
* Added: official {{Code|item-separator}} and {{Code|html-version}} parameter.
−
* Added: official {{Code|item-separator}} and {{Code|html-version}} parameter
+
* Updated: <code>method=html5</code> removed; serializers updated with the [https://www.w3.org/TR/2013/WD-xslt-xquery-serialization-30-20130108/ latest version of the specification], using <code>method=html</code> and <code>version=5.0</code>.
−
* Updated: <code>method=html5</code> removed; serializers updated with the [http://www.w3.org/TR/2013/WD-xslt-xquery-serialization-30-20130108/ latest version of the specification], using <code>method=html</code> and <code>version=5.0</code>.
 
  
 
;Version 7.2
 
;Version 7.2
−
 
+
* Added: {{Code|separator}} parameter.
−
* Added: {{Code|separator}} parameter
 
  
 
;Version 7.1
 
;Version 7.1
−
 
+
* Added: {{Code|newline}} parameter.
−
* Added: {{Code|newline}} parameter
 
  
 
;Version 7.0
 
;Version 7.0
−
 
+
* Added: Serialization parameters added to [[REST API]]; JSON/JsonML/raw methods.
−
* Added: Serialization parameters added to [[REST API]]; JSON/JsonML/raw methods
 

Latest revision as of 18:39, 1 December 2023

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:

The namespace for serialization parameters is statically bound to the output prefix. 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[edit]

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

Parameter Description Allowed Default
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 basex
version Specifies the version of the serialization method. xml/xhtml: 1.0, 1.1
html: 4.0, 4.01, 5.0
 1.0
html-version Specifies the version of the HTML serialization method. 4.0, 4.01, 5.0 4.0
item-separator Determines a string to be used as item separator. If a separator is specified, the default separation of atomic values with single whitespaces will be skipped. string
encoding Encoding to be used for outputting the data. all encodings supported by Java UTF-8
indent Adds leading whitespaces to make the output more readable. yes, no no
cdata-section-elements List of elements to be output as CDATA, separated by whitespaces.
Example: <text><![CDATA[ <> ]]></text> 		string
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 yes
standalone Prints or omits the standalone attribute in the XML declaration. yes, no, omit omit
doctype-system Introduces the output with a document type declaration and the given system identifier.
Example: <!DOCTYPE x SYSTEM "entities.dtd"> 		string
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
undeclare-prefixes Undeclares prefixes in XML 1.1. yes, no no
normalization-form Specifies a normalization form. BaseX supports Form C (NFC). NFC, none NFC
media-type Specifies the media type. string application/xml
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. Separators that are to be defined as keys or values can be encoded as entities.
Example: A=alpha,B=beta 		string
byte-order-mark Prints a byte-order-mark before starting serialization. yes, no no
escape-uri-attributes Escapes URI information in certain HTML attributes
Example: <a href="%C3%A4%C3%B6%C3%BC">äöü<a> 		yes, no no
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 yes

Query Prolog Parameters[edit]

The following parameters can only be specified in the query prolog (see XQuery: Specification for more details and examples):

Parameter Description Allowed Default
parameter-document Parses the value as an XML document with additional serialization parameters. string

Custom Parameters[edit]

BaseX provides some additional serialization parameters:

Parameter Description Allowed Default
csv Defines the way how data is serialized as CSV. see CSV Module
json Defines the way how data is serialized as JSON. see JSON Module
tabulator Uses tab characters (\t) instead of spaces for indenting elements. yes, no no
indents Specifies the number of characters to be indented. positive number 2
indent-attributes Version 11: Indent attributes after the element name, one below the other. yes, no false
newline Specifies the type of newline to be used as end-of-line marker. \n, \r\n, \r system dependent
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
binary Indicates if items of binary type are output in their native byte representation. Only applicable to the base serialization method. yes, no yes

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>,
  map {
    'method': 'csv',
    'csv': map { 'header': 'yes', 'separator': ';' }
  }
)

Result: 

Name;City
John;Newton
Jack;Oldtown

Character mappings[edit]

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 &#160; (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[edit]

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 REST API; JSON/JsonML/raw methods.
Retrieved from "http://docs.basex.org/index.php?title=Serialization&oldid=16900"