Changes

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: * including them included in the [[XQuery_3.0#Serialization|prolog of the XQuery expression]],;* specifying them specified in the XQuery functions [[File_Module#file:write({{Function|File|file:write()]] or [[XQuery_3.0#Functions|fn:serialize()]]. The serialization parameters are specified as** children of an }}, {{CodeFunction|Database|&lt;outputdb:serialization-parameters/&gt;export}} element, as defined for the [httphttps://www.w3.org/TR/xpath-functions-3031/#func-serialize fn:serialize()] function, or as);* specified in [[REST#Parameters|REST query parameters]];* specified in [[RESTXQ#Output|RESTXQ output annotations]];*set via the {{Option|SERIALIZER}} option before running a query;* map, which contains all key/value pairs: <code>map set via the {{ "method": "xml", "cdata-section-elements": "div", ... Option|EXPORTER}}</code>,option before exporting a database; or* using supplied with the {{Code|-s}} flag of the BaseX [[Command-Line Options#BaseX Standalone|command-line]] clients,. * setting The namespace for serialization parameters is statically bound to the [[Options#SERIALIZER{{Code|SERIALIZER]] output}} prefix. This means that it need not (but may) be declared in the query prolog: <syntaxhighlight lang="xquery">declare namespace output = 'http://www.w3.org/2010/xslt-xquery-serialization';declare option before running a queryoutput:method 'text';<xml>Hi there</xml></syntaxhighlight> Due to the wide range of ways how parameters can be supplied,* setting we deliberately ignored one rule of the [[Options#EXPORTER|EXPORTER]] option before exporting specification, which requires non-official features to be defined in a databasenon-null namespace URI. In the following, or* setting them as [[REST#Parameters|REST]] query parameterswe will indicate which features are specific to our implementation.

The following table gives a brief summary of all serialization parameters recognized are supported by BaseX. For (further details, please refer to can be looked up in the official specification.):

! width="60%" | Description

| Specifies the serialization method:* . {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, {{Code|text}} and {{Code|adaptive}} are adopted from part of the official specification.* For more details on {{Code|jsonbasex}} is specific to BaseX and can be used to output XML nodes as JSON objects (see the [[JSON Module]] for more details).* , {{Code|csv}} is BaseX-specific and can be used to output XML nodes as CSV data (see the [[CSV Module]] for more details).* {{Code|rawjson}} is BaseX-specific, too: 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 entitiessee [[XQuery Extensions#Serialization|XQuery Extensions]].| {{Code|adaptivexml}}, {{Code|xmlxhtml}}, {{Code|xhtmlhtml}}, {{Code|htmltext}}, {{Code|textjson}}, {{Code|jsonadaptive}}, {{Code|csv}}, {{Code|rawbasex}}| {{Code|adaptivebasex}}

| {{Code|xml/xhtml}}: {{Code|1.0}}, {{Code|1.1}}<br/>{{Code|html}}: {{Code|4.0}}, {{Code|4.01}}, {{Code|5.0}}<br/>

| ''arbitrary stringsstring'', {{Code|\n}}, {{Code|\r\n}}, {{Code|\r}}| ''empty''

| ''[httphttps://docs.oracle.com/javase/78/docs/technotes/guides/intl/encoding.doc.html all encodings supported by Java]''

| Adjusts Adds leading whitespaces to make the output better more readable.

| {{Code|yesno}} {{Announce|Default changed with Version 10}}

| ''string''

| Prints or omits the "{{Code|standalone" }} attribute in the XML declaration.

|''string''

| ''string''

| ''string''

| Parses the value as XML document with additional serialization parameters (see the [httphttps://www.w3.org/TR/xslt-xquery-serialization-31/#serparams-in-xdm-instance Serialization Specification] for more detailsand examples).| ''string''

| Defines character mappings. May only occur in documents parsed with {{Code|parameter-document}}If mappings are supplied as 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''

| Includes 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|noyes}}

! width="60%" | Description

'''Query''':<pre classsyntaxhighlight lang="brush:xquery">(: The output namespace declaration is optional, because it is statically declared in BaseX) :)declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";

</presyntaxhighlight> If {{Code|fn:serialize}} is called, output-specific parameters can be supplied via nested options: <syntaxhighlight 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': ';' } })</syntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight> =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''':<syntaxhighlight lang="xquery">declare option output:parameter-document "map.xml";<x>&amp;#xA0;</x></syntaxhighlight> '''Example parameter-document''':<syntaxhighlight 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></syntaxhighlight>

 * 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}}.

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

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

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

 * Added: official {{Code|item-separator}} and {{Code|html-version}} parameter.* Updated: <code>method=html5</code> removed; serializers updated with the [httphttps://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>.

 * Added: {{Code|separator}} parameter.

 * Added: {{Code|newline}} parameter.

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