Changes

Serialization parameters define how XQuery items and XML nodes are textually output, i.e., ''serialized''.They have been formalized in This page is part of the [http://www.w3.org/TR/xquery-30/#id-serialization W3C Serialization[XQuery|XQuery Portal]] document.In BaseX, they can be specified in several ways:

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 using included in the [[XQuery_3.0#Serialization|prolog of the <code>XQuery expression]];* specified in XQuery functions ({{Function|File|file:write}}, {{Function|Database|db:export}}, [https://www.w3.org/TR/xpath-functions-s<31/code> flag of the #func-serialize fn:serialize()]);* specified in [[Startup_OptionsREST#BaseX_StandaloneParameters|BaseX StandaloneREST query parameters]] client,;* by setting the specified in [[OptionsRESTXQ#Query optionsOutput|SERIALIZERRESTXQ output annotations]] ;* set via the {{Option|SERIALIZER}} option before running a query,;* by setting set via the [[Options#Query options{{Option|EXPORTER]] }} option before exporting a database,; or* by setting them via supplied with the {{Code|-s}} flag of the BaseX [[JAXCommand-RX_APILine Options#Query_ParametersBaseX Standalone|Output Parametercommand-line]] clients. 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 JAXspecification, which requires non-official features to be defined in a non-RX APInull namespace URI. In the following,we will indicate which features are specific to our implementation. =Standard Parameters=* The following serialization parameters are supported by including them BaseX (further details can be looked up in the official specification): {| class="wikitable sortable" width="100%"|- valign="top"! width="140" | Parameter! Description! Allowed! Default|- valign="top"| {{Code|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_3XQuery Extensions#Serialization|XQuery Extensions]].| {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, {{Code|text}}, {{Code|json}}, {{Code|adaptive}}, {{Code|csv}}, {{Code|basex}}| {{Code|basex}}|- valign="top"| {{Code|version}}| Specifies the version of the serialization method.| xml/xhtml: {{Code|1.0}}, {{Code|1.1}}<br/>html: {{Code|4.0}}, {{Code|4.01}}, {{Code|5.0}}<br/>| {{Code|1.0}}|- valign="top"| {{Code|html-version}}| Specifies the version of the HTML serialization method.| {{Code|4.0}}, {{Code|4.01}}, {{Code|5.0}}| {{Code|4.0#Serialization}}|- valign="top"| {{Code|item-separator}}|prolog 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''||- valign="top"| {{Code|encoding}}| Encoding to be used for outputting the XQuery expressiondata.| ''[https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html all encodings supported by Java]''| {{Code|UTF-8}}|- valign="top"| {{Code|indent}}| Adds leading whitespaces to make the output more readable.| {{Code|yes}}, {{Code|no}}| {{Code|no}}|- valign="top"| {{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;}}| ''string''| |- valign="top"| {{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>| {{Code|yes}}, {{Code|no}}| {{Code|yes}}|- valign="top"| {{Code|standalone}}| Prints or omits the {{Code|standalone}} attribute in the XML declaration.| {{Code|yes}}, {{Code|no}}, {{Code|omit}}| {{Code|omit}}|- valign="top"| {{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;}}| ''string''||- valign="top"| {{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;}}| ''string''||- valign="top"| {{Code|undeclare-prefixes}}| Undeclares prefixes in XML 1.1.| {{Code|yes}}, {{Code|no}}| {{Code|no}}|- valign="top"| {{Code|normalization-form}}| Specifies a normalization form. BaseX supports Form C ({{Code|NFC}}).| {{Code|NFC}}, {{Code|none}}| {{Code|NFC}}|- valign="top"| {{Code|media-type}}| Specifies the media type.| ''string''| {{Code|application/xml}}|- valign="top"| {{Code|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.<br/>Example: <code>A=alpha,B=beta</code>| ''string''| |- valign="top"| {{Code|byte-order-mark}}| Prints a byte-order-mark before starting serialization.| {{Code|yes}}, {{Code|no}}| {{Code|no}}|- valign="top"| {{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>| {{Code|yes}}, {{Code|no}}| {{Code|no}}|- valign="top"| {{Code|include-content-type}}| 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}}|} =Query Prolog Parameters= The following parameters can only be specified in the query prolog (since see [https://www.w3.org/TR/xquery-31/#id-serialization XQuery 3: 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''| |} =Custom Parameters= BaseX provides some additional serialization parameters: {| class="wikitable sortable" width="100%"|- valign="top"! width="140" | Parameter! Description! Allowed! Default|- valign="top"| {{Code|csv}}| Defines the way how data is serialized as CSV.| see [[CSV Module]]||- valign="top"| {{Code|json}}| Defines the way how data is serialized as JSON.0| see [[JSON Module]]| |- valign="top"| {{Code|tabulator}}| Uses tab characters ({{Code|\t}})instead of spaces for indenting elements.| {{Code|yes}}, {{Code|no}}| {{Code|no}}|- valign="top"| {{Code|indents}}| Specifies the number of characters to be indented.| ''positive number''| {{Code|2}}|- valign="top"| {{Code|indent-attributes}}| {{Announce|Version 11:}} Indent attributes after the element name, orone below the other.| {{Code|yes}}, {{Code|no}}| {{Code|false}}|- valign="top"| {{Code|newline}}| Specifies the type of newline to be used as end-of-line marker. | {{Code|\n}}, {{Code|\r\n}}, {{Code|\r}}| ''system dependent''|- valign="top"| {{Code|limit}}| Stops serialization after the specified number of bytes has been serialized. If a negative number is specified, everything will be output.| ''positive number''| {{Code|-1}}|- 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 specifying them <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;CityJohn;NewtonJack;Oldtown</pre> =Character mappings= Character maps allow a specific character in the XQuery function 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 [File_Functionshttps://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;#file160;"/> </use-character-maps></serialization-parameters></pre> =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:write{{Code|csv}} and {{Code|filejson}} serialization parameters.* Removed:write{{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* 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>. ;Version 7.2* Added: {{Code|separator}} parameter. ;Version 7.1* Added: {{Code|newline}} parameter. ;Version 7.0* Added: Serialization parameters added to [[REST API]]; JSON/JsonML/raw methods.