XSLT and XQuery Serialization 4.0

1 Introduction

This document defines serialization of the W3C XQuery and XPath Data Model 4.0 (XDM), which is the data model of at least [XML Path Language (XPath) 4.0], [XSL Transformations (XSLT) Version 4.0], and [XQuery 4.0: An XML Query Language], and any other specifications that reference it.

In this document, examples and material labeled as “Note” are provided for explanatory purposes and are not normative.

Serialization is the process of converting an instance of the [XQuery and XPath Data Model (XDM) 4.0] into a sequence of octets.

[Definition: The XDM value supplied as input to the serializer is referred to as the input value.] Some serialization methods apply only to certain types of input value.

[Definition: In general the output of the serializer will represent the items actually present in the input value, together with other items that are reachable from these, for example (in the case of nodes) their descendants. The complete set of items that are represented in the output of the serializer is referred to (without loss of generality) as the input tree.]

2 Sequence Normalization

The input value is a sequence. Prior to serializing a sequence using any of the output methods whose behavior is specified by this document (3 Serialization Parameters), with the exception of the JSON and Adaptive output methods, the serializermust first compute a normalized sequence for serialization; it is the normalized sequence that is actually serialized. [Definition: The purpose of sequence normalization is to create a sequence that can be serialized as a well-formed XML document or external general parsed entity, that also reflects the content of the input sequence to the extent possible.] [Definition: The result of the sequence normalization process is a result tree.]

The normalized sequence for serialization is constructed by applying all of the following rules in order, with the input value being input to the first step, and the sequence that results from any step being used as input to the subsequent step. For any implementation-defined output method, it is implementation-defined whether this sequence normalization process takes place. For the JSON and Adaptive output methods, sequence normalization must not take place.

Where the process of converting the input sequence to a normalized sequence indicates that a value must be cast to xs:string, that operation is defined in Section 21.1.2 Casting to xs:string^FO of [XQuery and XPath Functions and Operators 4.0]. Where a step in the sequence normalization process indicates that a node should be copied, the copy is performed in the same way as an XSLT xsl:copy-of instruction that has a validation attribute whose value is preserve and has a select attribute whose effective value is the node, as described in Section 11.9.2 Deep Copy^XT of [XSL Transformations (XSLT) Version 4.0], or equivalently in the same way as an XQuery content expression as described in Step 1e of Section 4.12.1.3 Content^XQ of [XQuery 4.0: An XML Query Language], where the construction mode is preserve. Let S₀ be the sequence that is input to serialization. The steps in computing the normalized sequence are:

1. Create a new sequence S₁ from S₀ as follows. For each item in S₀, if the item is an array, copy the results of passing the item into the function array:flatten(); otherwise, copy the item itself. If S₀ is empty, let S₁ consist of a zero-length string.

2. Create a new sequence S₂ from S₁ as follows. For each item in S₁, if the item is atomic, copy to S₂ only the lexical representation resulting from casting the item to an xs:string, otherwise, copy the item to S₂.

3. Create a new sequence S₃ from S₂ as follows. If the item-separator serialization parameter is present, then copy each item in S₂ to S₃, inserting between each pair of items a string whose value is equal to the value of the item-separator parameter. If the item-separator serialization parameter is not present, then first maximally group the items in S₂ into subsequences of xs:string items and non-xs:string items. For each group of items, if the group is a subsequence of non-xs:string items, copy the subsequence to S₃; if the group is a subsequence of xs:string items, copy to S₃ the results of passing to fn:string-join() the subsequence and the value of item-separator as the function’s two parameters.

4. Create a new sequence S₄ from S₃ as follows. For each item in S₃, if the item is a string, copy to S₄ a text node whose string value is equal to the string; otherwise, copy the item to S₄.

5. Create a new sequence S₅ from S₄ as follows. For each item in S₄, if the item is a document node, copy its children to S₅; otherwise, copy the item to S₅.

6. Create a new sequence S₆ from S₅ as follows. First, remove any text nodes with values of zero length from S₅, then maximally group the results into groups of text nodes and non-text nodes. For each group of items, if the group is a subsequence of text nodes, copy to S₆ a single text node whose value is equal to the concatenated values of the subsequence; if the group is a subsequence of non-text nodes, copy the subsequence of items to S₆. It is a serialization error [err:SENR0001] if any item in S₆ is an attribute node, a namespace node, or a function.

7. Create a new sequence S₇ from S₆ as follows. Let S₇ be a single document node. Copy sequence S₆ to the document node as its children.

S₇ is the normalized sequence.

The result tree rooted at the document node that is created by the final step of this sequence normalization process is the value to which the rules of the appropriate output method are applied. If the sequence normalization process results in a serialization error, the serializermust raise the error.

<xsl:document>
  <xsl:copy-of select="$seq" validation="preserve"/>
</xsl:document>

declare construction preserve;

document { $seq }

<xsl:document>
  <xsl:for-each select="$seq">
    <xsl:sequence select="if (position() gt 1) 
                          then $sep 
                          else ()"/>

    <xsl:choose>
      <xsl:when test=". instance of node()">
        <xsl:sequence select="."/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="."/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:for-each>
</xsl:document>

declare construction preserve; 

document {
  for $item at $pos in $seq
  let $node := 
    if ($item instance of node()) then 
      $item 
    else 
      text { $item }
  return
    if ($pos eq 1) then
      $node
    else
      ($sep, $node)  
}

3 Serialization Parameters

There are a number of parameters that influence how serialization is performed. Host languagesmay allow users to specify any or all of these parameters, but they are not required to be able to do so. However, the host language specification must specify how the values of all applicable parameters are to be determined.

Host languages may also define alternative representations of the values of serialization parameters. For example, both XSLT and XQuery allow the boolean values true and false to be written as 1/0 or yes/no. The $options map passed to the fn:serialize function, by contrast, requires an xs:boolean value.

It is a serialization error [err:SEPM0016] if a parameter value is invalid for the given parameter. It is the responsibility of the host language to specify how invalid values should be handled at the level of that language.

The following serialization parameters are defined:

In those cases where they have no important effect on the content of the serialized result, details of the output methods defined by this specification are left unspecified and are regarded as implementation-dependent. Whether a serializer uses apostrophes or quotation marks to delimit attribute values in the XML output method is an example of such a detail.

The detailed semantics of each parameter will be described separately for each output method for which it is applicable. If the semantics of a parameter are not described for an output method, then it is not applicable to that output method.

Implementations may define additional serialization parameters, and may allow users to do so. For this purpose, the name of a serialization parameter is considered to be a QName; the parameters listed above are QNames whose expanded-QName has a null namespace URI, while any additional serialization parameters that are either implementation-defined or defined by the host languagemust have names that are namespace-qualified. Any such additional serialization parameters must not be in the namespace https://www.w3.org/2010/xslt-xquery-serialization. A host languagemay specify the means by which an implementation can define such an additional serialization parameter, and implementations may provide mechanisms by which users can define such an additional serialization parameter. If the serialization method is one of the six methods xml, html, xhtml, text, json, or adaptive then the additional serialization parameters may affect the output of the serializer to the extent (but only to the extent) that this specification leaves the output implementation-defined or implementation-dependent. For example, such parameters might control whether namespace declarations on an element are written before or after the attributes of the element, or they might define the number of space or tab characters to be inserted when the indent parameter is set to true; but they could not instruct the serializer to suppress the error that occurs when the HTML output method encounters characters that are not permitted (see error [err:SERE0014]).

document { . } 
   /output:serialization-parameters
   /(validate lax { 
      output:*[local-name() eq $param-name] 
   })
   /data(@value)

<xsl:sequence>
  <xsl:variable name="validated-instance">
    <xsl:document validation="lax">
      <xsl:sequence select="
        self::output:serialization-parameters
        /output:*
       [local-name() eq $param-name]"/>
    </xsl:document>
  </xsl:variable>
  <xsl:sequence select="$validated-instance
                        /data(@value)"/>
</xsl:sequence>

document { . }
/output:serialization-parameters
/ ( validate lax { output:use-character-maps } )
/output:character-map[@character eq $char]
/string(@map-string)

<xsl:sequence>
  <xsl:variable name="validated-instance">
    <xsl:document validation="lax">
      <xsl:sequence select="
        self::output:serialization-parameters
         /output:use-character-maps"/>
    </xsl:document>
  </xsl:variable>
  <xsl:sequence select="$validated-instance                          
                        /output:character-map
                        [@character eq $char]
                        /string(@map-string)"/>
</xsl:sequence>

(document { . })/output:serialization-parameters
   /(count(distinct-values(*/node-name(.))) eq (count(*)))

<xsl:sequence>
  <xsl:variable name="doc">
    <xsl:document>
      <xsl:sequence select="."/>
    </xsl:document>
  </xsl:variable>
  <xsl:sequence
    select="$doc/output:serialization-parameters
                /(count(distinct-values(
                    */node-name(.))) 
                eq (count(*)))"/>
</xsl:sequence>

<output:serialization-parameters 
    xmlns:output 
    = "http://www.w3.org/2010/xslt-xquery-serialization">
  <output:method value="xml"/>
  <output:version value="1.0"/>
  <output:indent value="yes"/>
</output:serialization-parameters>

<output:serialization-parameters
    xmlns:output
    = "http://www.w3.org/2010/xslt-xquery-serialization"
    xmlns:book="http://example.org/book"
    xmlns="http://example.org/book/chapter">
  <output:cdata-section-elements value="heading book:footnote"/>
</output:serialization-parameters>

<output:serialization-parameters
    xmlns:output
    = "http://www.w3.org/2010/xslt-xquery-serialization"
    xmlns="http://example.org/ext">
  <output:method value="html"/>
</output:serialization-parameters>

<output:serialization-parameters
    xmlns:output
    = "http://www.w3.org/2010/xslt-xquery-serialization"
    xmlns:ext="http://example.org/ext">
  <output:method value="ext:jsp"/>
  <output:use-character-maps>
    <output:character-map character="&#xAB;" map-string="&lt;%"/>
    <output:character-map character="&#xBB;" map-string="%&gt;"/>
  </output:use-character-maps>
</output:serialization-parameters>

4 Phases of Serialization

For the XML, HTML, XHTML and Text output methods, serialization comprises five phases of processing (preceded by the sequence normalization process described in 2 Sequence Normalization). For the JSON and Adaptive output methods, serialization is described in 9 JSON Output Method and 10 Adaptive Output Method respectively.

For an implementation-defined output method, any of these phases may be skipped or may be performed in a different order than is specified here. For the output methods defined in this specification, these phases are carried out sequentially as follows:

1. A meta element is added to the sequence, possibly replacing existing meta elements, as controlled by the include-content-type parameter for the XHTML and HTML output methods. This step is skipped for the other output methods defined by this specification.

2. Markup generation produces the character representation of those parts of the serialized result that describe the structure of the sequence. In the cases of the XML, HTML and XHTML output methods, this phase produces the character representations of the following:

   • the document type declaration;

   • start tags and end tags (except for attribute values, whose representation is produced by the character expansion phase);

   • processing instructions; and

   • comments.

   In the cases of the XML and XHTML output methods, this phase also produces the following:

   • the XML or text declaration; and

   • empty element tags (except for the attribute values);

   In the case of the text output method, this phase replaces the single document node produced by sequence normalization with a new document node that has exactly one child, which is a text node. The string value of the new text node is the string value of the document node that was produced by sequence normalization.

3. Character expansion is concerned with the representation of characters appearing in text and attribute nodes in the sequence. For each text and attribute node, the following rules are applied in sequence.

   1. If the node is an attribute that is a URI attribute value and the escape-uri-attributes parameter is set to require escaping of URI attributes, apply URI escaping as defined below, and skip rules b-e. Otherwise, continue with rule b.

      [Definition: URI escaping consists of the following three steps applied in sequence to the content of URI attribute values:]

      1. normalize to NFC using the method defined in Section 5.4.9 fn:normalize-unicode^FO

      2. percent-encode any special characters in the URI using the method defined in Section 6.5 fn:escape-html-uri^FO

      3. escape according to the rules of the XML or HTML output method, whichever is applicable, any characters that require escaping, and any characters that cannot be represented in the selected encoding. For example, replace < with < (See also section 7.3 Writing Character Data).

      [Definition: The values of attributes listed in D List of URI Attributes are URI attribute values. Attributes are not considered to be URI attributes simply because they are namespace declaration attributes or have the type annotation xs:anyURI.]

   2. If the node is a text node whose parent element is selected by the rules of the cdata-section-elements parameter for the applicable output method, create CDATA sections as described below, and skip rules c-e. Otherwise, continue with rule c.

      Apply the following two processes in sequence to create CDATA sections

      1. Unicode Normalization if requested by the normalization-form parameter.

      2. The application of changes as detailed in the description of the cdata-section-elements parameter for the applicable output method.

   3. Apply character mapping as determined by the use-character-maps parameter for the applicable output method. For characters that were substituted by this process, skip rules d and e. For the remaining characters that were not modified by character mapping, continue with rule d.

   4. Apply Unicode Normalization if requested by the normalization-form parameter.

      [Definition: Unicode Normalization is the process of removing alternative representations of equivalent sequences from textual data, to convert the data into a form that can be binary-compared for equivalence, as specified in [UAX #15: Unicode Normalization Forms]. For specific recommendations for character normalization on the World Wide Web, see [Character Model for the World Wide Web 1.0: Normalization].]

      The meanings associated with the possible values of the normalization-form parameter are defined in section 5.1.8 XML Output Method: the normalization-form Parameter.

      Continue with step e.

   5. Escape according to the rules of the XML or HTML output method, whichever is applicable, any characters (such as < and &) where XML or HTML requires escaping, and any characters that cannot be represented in the selected encoding. For example, replace < with <. (See also section 7.3 Writing Character Data). For characters such as > where XML defines a built-in entity but does not require its use in all circumstances, it is implementation-dependent whether the character is escaped.

4. Indentation, as controlled by the indent parameter and the suppress-indentation parameter, may add or remove whitespace according to the rules defined by the applicable output method.

5. Encoding, as controlled by the encoding parameter, converts the character sequence produced by the previous phases into an octet stream.

   Note:

   Serialization is defined only in terms of encoding the result as a stream of octets. However, a serializermay provide an option that allows the encoding phase to be skipped, so that the result of serialization can be encoded in a way required by a particular destination (e.g., a Java StringBuffer). The effect of any such option is implementation-defined, and a serializer is not required to support such an option.

5 XML Output Method

The XML output method serializes the normalized sequence as an XML entity that must satisfy the rules for either a well-formed XML document entity, a well-formed XML external general parsed entity, or both. A serialization error [err:SERE0003] results if the serializer is unable to satisfy those rules, except for content modified by the character expansion phase of serialization, as described in 4 Phases of Serialization. The effects of the character expansion phase could result in the serialized output being not well-formed, but will not result in a serialization error. If a serialization error results, the serializermust raise the error.

If the document node of the normalized sequence has a single element node child and no text node children, then the serialized output is a well-formed XML document entity, and the serialized output must conform to the appropriate version of the XML Namespaces Recommendation [XML Names] or [XML Names 1.1]. If the normalized sequence does not take this form, then the serialized output is a well-formed XML external general parsed entity, which, when referenced within a trivial XML document wrapper like this:

<?xml version="version"?>
<!DOCTYPE doc [
<!ENTITY e SYSTEM "entity-URI">
]>
<doc>&e;</doc>

where entity-URI is a URI for the entity, and the value of the version pseudo-attribute is the value of the version parameter, produces a document which must itself be a well-formed XML document conforming to the corresponding version of the XML Namespaces Recommendation [XML Names] or [XML Names 1.1].

[Definition: A reconstructed tree may be constructed by parsing the XML document and converting it into an document node as specified in [XQuery and XPath Data Model (XDM) 4.0].] The result of serialization must be such that the reconstructed tree is the same as the result tree except for the following permitted differences:

• If the document was produced by adding a document wrapper, as described above, then it will contain an extra doc element as the document element.

• The order of attribute and namespace nodes in the two trees may be different.

• The following properties of corresponding nodes in the two trees may be different:

  • the base-uri property of document nodes and element nodes;

  • the document-uri and unparsed-entities properties of document nodes;

  • the type-name and typed-value properties of element and attribute nodes;

  • the nilled property of element nodes;

  • the content property of text nodes, due to the effect of the indent and use-character-maps parameters.

• The reconstructed treemay contain additional attributes and text nodes resulting from the expansion of default and fixed values in its DTD or schema; also, in the presence of a DTD, non-CDATA attributes may lose whitespace characters as a result of attribute value normalization.

• The type annotations of the nodes in the two trees may be different. Type annotations in a result tree are discarded when the tree is serialized. Any new type annotations obtained by parsing the document will depend on whether the serialized XML document is assessed against a schema, and this may result in type annotations that are different from those in the original result tree.

  Note:

  In order to influence the type annotations in the tree that would result from processing a serialized XML document, the author of the XSLT stylesheet, XQuery expression or other process might wish to create the input tree so that it makes use of mechanisms provided by [XML Schema], such as xsi:type and xsi:schemaLocation attributes. The serialization process will not automatically create such attributes in the serialized document if those attributes were not part of the result tree that is to be serialized.

  Similarly, it is possible that an element node in the input tree has the nilled property with the value true, but no xsi:nil attribute. The serialization process will not create such an attribute in the serialized document simply to reflect the value of the property. The value of the nilled property has no direct effect on the serialized result.

• Additional namespace nodes may be present in the reconstructed tree if the serialization process did not undeclare one or more namespaces, as described in 5.1.7 XML Output Method: the undeclare-prefixes Parameter, and the input tree contained an element node with a namespace node that declared some prefix, but a child element of that node did not have any namespace node that declared the same prefix.

  The result treemay contain namespace nodes that are not present in the reconstructed tree, as the process of creating an instance of the data model may ignore namespace declarations in some circumstances. See Section 5.2.3 Construction from an Infoset^DM and Section 5.2.4 Construction from a PSVI^DM of [XQuery and XPath Data Model (XDM) 4.0] for additional information.

• If the indent parameter has the value true,

  • additional text nodes consisting of whitespace characters may be present in the reconstructed tree; and

  • text nodes in the result tree that contained only whitespace characters may correspond to text nodes in the reconstructed tree that contain additional whitespace characters that were not present in the result tree

  See 5.1.3 XML Output Method: the indent and suppress-indentation Parameters for more information on the indent parameter.

• Additional nodes may be present in the reconstructed tree due to the effect of character mapping in the character expansion phase, and the values of attribute nodes and text nodes in the reconstructed treemay be different from those in the result tree, due to the effects of URI expansion, character mapping and Unicode Normalization in the character expansion phase of serialization.

  Note:

  The use-character-maps parameter can cause arbitrary characters to be inserted into the serialized XML document in an unescaped form, including characters that would be considered to be part of XML markup. Such characters could result in arbitrary new element nodes, attribute nodes, and so on, in the reconstructed tree that results from processing the serialized XML document.

A consequence of this rule is that certain characters must be output as character references, to ensure that they survive the round trip through serialization and parsing. Specifically:

• In text nodes, the characters U+000D (CARRIAGE RETURN) , U+0085 (NEXT LINE, NEL) , and U+2028 (LINE SEPARATOR) must be output respectively as "
", "…", and "
", or their equivalents

• In attribute nodes, the characters U+000D (CARRIAGE RETURN) , U+000A (NEWLINE) , U+0009 (TAB) , U+0085 (NEXT LINE, NEL) , and U+2028 (LINE SEPARATOR) must be output respectively as "
", "
", "	", "…", and "
", or their equivalents.

• In both text nodes and attribute nodes, control characters U+0001 (SOH) through U+001F (IS1) and U+007F (DELETE) through U+009F (APC) (except U+0009 (TAB) , U+000A (NEWLINE) , and U+000D (CARRIAGE RETURN) , and U+0085 (NEXT LINE, NEL) ) must be output as character references.

For example, an attribute with the value "x" followed by "y" separated by a newline will result in the output "x
y" (or with any equivalent character reference). The XML output cannot be "x" followed by a literal newline followed by a "y" because after parsing, the attribute value would be "x y" as a consequence of the XML attribute normalization rules.

It is a serialization error [err:SEPM0004] to specify the doctype-system parameter, or to specify the standalone parameter with a value other than omit, if the input tree contains text nodes or multiple element nodes as children of the root node. The serializermust either raise the error, or recover by ignoring the request to output a document type declaration or standalone parameter.

<x:foo xmlns:x="http://example.org/x"
       xmlns:y="http://example.org/y"
       xmlns:z="http://example.org/z">
       
       <x:bar xmlns:z="">...</x:bar>
       
</x:foo>

6 XHTML Output Method

The XHTML output method serializes the input tree as XML, using the HTML compatibility guidelines defined in the XHTML specification ([XHTML 1.0] or the XHTML syntax of HTML5 (see [HTML5]).

[Definition: An element node is recognized as an HTML element by the XHTML output method if

• the element node is in the XHTML namespace, regardless of the value of the html-version serialization parameter or if the html-version serialization parameter is absent; or

• the value of the html-version serialization parameter is 5.0, the element has a null namespace URI, and the local part of the name is equal to the name of an element defined by HTML5 [HTML5], making the comparison without regard to case.

]

It is entirely the responsibility of the person or process that creates the input tree to ensure that it conforms to the [XHTML 1.0] or [XHTML 1.1] specification if the html-version serialization parameter is absent or has a value less than 5.0 or the XHTML syntax of HTML5 if the value of the html-version serialization parameter is 5.0. It is not an error if the instance of the data model is invalid XHTML. Equally, it is entirely under the control of the person or process that creates the input tree whether the output conforms to XHTML 1.0 Strict, XHTML 1.0 Transitional, the XHTML syntax of HTML5 (see [HTML5]), [POLYGLOT] or any other specific definition of XHTML.

The serialization of the input tree follows the same rules as for the XML output method, with the general exceptions noted below and parameter-specific exceptions in 6.1 The Influence of Serialization Parameters upon the XHTML Output Method. These differences are based on the HTML compatibility guidelines published in Appendix C of [XHTML 1.0] and on [POLYGLOT], both of which are designed to ensure that as far as possible, XHTML is rendered correctly on user agents designed originally to handle HTML.

If the value of the html-version serialization parameter is 5.0, the input tree is first subjected to prefix normalization.

[Definition: During prefix normalization, any element node in the input tree that is in one of the XHTML namespace, the SVG namespace or the MathML namespace has its name replaced by the local part of its name. Such an element node is given a default namespace node whose value is the element’s namespace URI. Any namespace node for any of those three namespaces that was previously present on any element node in the input tree is also removed, unless the prefix that that namespace node declared is used as the prefix on the name of an attribute on that element or an ancestor of that element.]

The process of prefix normalization is equivalent to replacing the input tree with the result of the transformation described by this XSLT stylesheet, with the root of the input tree as the initial context value.

<xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    version="4.0"
    xmlns:xhtml="http://www.w3.org/1999/xhtml"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns:mathml="http://www.w3.org/1998/Math/MathML">
  <xsl:template match="xhtml:*|svg:*|mathml:*">
    <xsl:element name="{local-name()}" 
                 namespace="{namespace-uri()}">
      <xsl:apply-templates select="@*|namespace::*|node()"/>
    </xsl:element>
  </xsl:template>

  <xsl:template match="node()|@*|namespace::*">
    <xsl:copy copy-namespaces="no">
      <xsl:apply-templates select="@*|namespace::*|node()"/>
    </xsl:copy>
  </xsl:template>

  <xsl:template
    match="namespace::*[. eq 'http://www.w3.org/1999/xhtml']|
           namespace::*[. eq 'http://www.w3.org/2000/svg']|
           namespace::*[. eq 'http://www.w3.org/1998/Math/MathML']"/>
</xsl:stylesheet>

• [Definition: The following XHTML elements have an EMPTY content model: area, base, br, col, embed, hr, img, input, link, meta, basefont, frame, isindex, and param.] [Definition: The void elements of HTML5 are area, base, br, col, embed, hr, img, input, keygen, link, meta, param, source, track and wbr.] [Definition: An element node is expected to be empty if it is recognized as an HTML element and if either

  • the html-version serialization parameter is absent or has a value less than 5.0 and the content model is EMPTY, or

  • the html-version serialization parameter has the value 5.0 and the element is a void element.

  ]

  If an element node that has no child nodes is not expected to be empty, and:

  • the html-version serialization parameter is absent or has a value less than 5.0, and the content model of the HTML element is not EMPTY (for example, an empty title or paragraph); or

  • the value of the html-version serialization parameter is 5.0, and the HTML element is not a void element,

  the serializermust not use the minimized form. That is, it must output <p></p> and not <p />.

• If an element that has no children is expected to be empty, the serializermust use the minimized tag syntax, for example <br />, as the alternative syntax <br></br> allowed by XML gives uncertain results in many legacy user agents. If the html-version serialization parameter is absent or has a value less than 5.0, the serializermust include a space before the trailing />, e.g. <br />, <hr /> and <img src="karen.jpg" alt="Karen" />.

• If the html-version serialization parameter is absent or has a value less than 5.0, the serializermust not use the entity reference ' which, although defined in XML and therefore in XHTML, is not defined in versions of HTML prior to HTML5, and is not recognized by all HTML user agents.

• If the html-version serialization parameter is absent or has a value less than 5.0, the serializershould output namespace declarations in a way that is consistent with the requirements of the XHTML DTD if this is possible. If the value of the html-version serialization parameter is 5.0, the serializershould output namespace declarations in a way that is consistent with the requirements of [POLYGLOT]. The XHTML 1.0 DTDs require the declaration xmlns="http://www.w3.org/1999/xhtml" to appear on the html element, and only on the html element. The [POLYGLOT] specification permits namespace declarations to appear in a conforming document, but restricts the elements on which they can appear. The serializermust output namespace declarations that are consistent with the namespace nodes present in the result tree, but it must avoid outputting redundant namespace declarations on elements where the DTD would make them invalid, for versions prior to HTML5, or where they are not permitted by [POLYGLOT], for serialization according to the syntax of HTML5.

  Note:

  If the html element is generated by an XSLT literal result element of the form <html xmlns="http://www.w3.org/1999/xhtml"> ... </html>, or by an XQuery direct element constructor of the same form, then the html element in the result document will have a node name whose prefix is "", which will satisfy the requirements of the DTD. In other cases the prefix assigned to the element is implementation-dependent.

<head>
<meta http-equiv="Content-Type" 
      content="text/html; charset=EUC-JP" />
...

<meta http-equiv="Content-Type" 
      content="text/html;version='4.0'" />

<meta http-equiv="Content-Type" 
      content="text/html;charset=utf-8" />

<meta charset="utf-8"/>

7 HTML Output Method

The HTML output method serializes the input tree as HTML.

<xsl:stylesheet version="2.0" 
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" version="4.0"/>
<xsl:template match="/">
  <html>
    <xsl:apply-templates/>
  </html>
</xsl:template>
...
</xsl:stylesheet>

In the example, the version attribute of the xsl:output element indicates the version of the HTML Recommendation [HTML] to which the serialized result is to conform.

It is entirely the responsibility of the person or process that creates the input tree to ensure that it conforms to the HTML Recommendation [HTML]. It is not an error if the input tree is invalid HTML. Equally, it is entirely under the control of the person or process that creates the input tree whether the output conforms to HTML. If the result tree is valid HTML, the serializermust serialize the result in a way that conforms with the version of HTML specified by the requested HTML version.

<script>if (a &lt; b) foo()</script>

<script><![CDATA[if (a < b) foo()]]></script>

<script>if (a < b) foo()</script>

<script type="application/ecmascript">
      document.write ("<em>This won't work</em>")
</script>

<script type="application/ecmascript">
      document.write ("<em>This won't work</em>")
</script>

<script type="application/ecmascript">
      document.write ("&lt;em&gt;This won't work&lt;/em&gt;")
</script>

<script type="application/ecmascript">
      document.write ("&lt;em&gt;This will work&lt;\/em&gt;")
</script>

<OPTION selected="selected">

<OPTION selected>

<BODY bgcolor='&amp;{{randomrbg}};'>

<BODY bgcolor='&{randomrbg};'>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=EUC-JP">
...

<head>
<meta charset="EUC-JP">
...

<meta http-equiv="Content-Type" 
      content="text/html;version='4.0'">

<meta http-equiv="Content-Type" 
      content="text/html;charset=utf-8">

<meta charset="utf-8">

8 Text Output Method

The Text output method serializes the input tree by outputting the string value of the document node created by the markup generation step of the phases of serialization without any escaping.

A newline character in the input treemay be output using any character sequence that is conventionally used to represent a line ending in the chosen system environment.

9 JSON Output Method

The JSON output method serializes the input tree using the JSON syntax defined in [RFC 7159]. Sequence normalization is not performed for this output method. A list with values to be serialized is created from the input value, depending on the value of the json-lines parameter:

• If the value is true, each item of the input value becomes a separate list entry. If the input value is an empty sequence, the serialized result is empty.

• If the value is false, the input value becomes a single list entry. If the input value is an empty sequence, the serialized result is the string null.

The serialized entries of the list are separated by the character U+000A (NEWLINE) . The entries are serialized as follows:

• An array item in the input tree is serialized to a JSON array by outputting the serialized JSON value of each member within the array separated by delimiters according to the JSON array syntax, i.e. [member, member, ...]. Each member in the array is to be serialized by recursively applying the rules in this section.

• A map item in the input tree is serialized to a JSON object by outputting, for each key/value pair, the string value of the key to a JSON string, followed by the serialized JSON value of the entry, separated by delimiters according to the JSON object syntax, i.e. {key:value, key:value, ...}. The order in which each key/value pair appears in the serialized output is implementation-dependent.A map item in the input tree is serialized to a JSON object by outputting, for each key/value pair, the string value of the key to a JSON string, followed by the serialized JSON value of the entry, separated by delimiters according to the JSON object syntax, i.e. {key:value, key:value, ...}. The key/value pairs in the serialized output retain the entry order^DM of entries in the map.A map item in the input tree is serialized to a JSON object by outputting, for each key/value pair, the string value of the key to a JSON string, followed by the serialized JSON value of the entry, separated by delimiters according to the JSON object syntax, i.e. {key:value, key:value, ...}. The order in which each key/value pair appearspairs in the serialized output isretain the implementation-dependententry order^DM of entries in the map.

  Note:

  The order is implementation-dependent in the default case where the ordered^DM property of the map is false.

  If any two keys of the map item have the same string value, serialization error [err:SERE0022] is raised, unless the allow-duplicate-names parameter has the value true.

• A node in the input tree is serialized to a JSON string by outputting the result of serializing the node using the method specified by the json-node-output-method parameter. The node is serialized with the serialization parameter omit-xml-declaration set to true and with no other serialization parameters set.

• An atomic value^XP in the input tree with a numeric type, or derived from a numeric type xs:float, xs:double or xs:decimal is serialized to a JSON number. Implementations may serialize the numeric value using any lexical representation of a JSON number defined in [RFC 7159]. If the numeric value cannot be represented in the JSON grammar (such as Infinity or NaN), then the serializermust raise a serialization error [err:SERE0020].

• An atomic item^XP in the input tree of type xs:boolean and value true is serialized to the JSON token true.

• An atomic item^XP in the input tree of type xs:boolean and value false is serialized to the JSON token false.

• An atomic item^XP of type xs:QName in the input tree whose namespace part is "http://www.w3.org/2005/xpath-functions" and whose local part is "null" is serialized to the JSON token null.

  Note:

  This rule is introduced in 4.0, along with an option in the fn:parse-json function to allow a user-defined representation of the JSON value null. While the default representation of null as an empty sequence is usable in many circumstances, an explicit representation of null as a recognizable item can make some operations on JSON-derived values easier.

• Any other atomic value^XP in the input tree is serialized to a JSON string by outputting the result of applying the fn:string function to the item.

• An empty sequence in the input tree is serialized to the JSON token null.

• A sequence of length greater than one in the input tree will result in a serialization error [err:SERE0023].

• Any item in the input tree of a type not specified in the above list will result in a serialization error [err:SERE0021].

[Definition: Whenever a value is serialized to a JSON string, the following procedure is applied to the supplied string:

1. Any character in the string for which character mapping is defined (see 11 Character Maps) is substituted by the replacement string defined in the character map.

2. Any other character in the input string (but not a character produced by character mapping) is a candidate for Unicode Normalization if requested by the normalization-form parameter, and JSON escaping. JSON escaping replaces the characters quotation mark, backspace, form-feed, newline, carriage return, tab, or reverse solidus by the corresponding JSON escape sequences \", \b, \f, \n, \r, \t, or \\ respectively, and any other codepoint in the range 1-31 or 127-159 by an escape in the form \uHHHH where HHHH is the hexadecimal representation of the codepoint value. Escaping further replaces the solidus character (/) by the escape sequence \/ if the escape-solidus parameter is set to true, but not if it is set to false. Escaping is also applied to any characters that cannot be represented in the selected encoding.

3. The resulting string is enclosed in double quotation marks.

]

Finally, encoding, as controlled by the encoding parameter, converts the character stream produced by the preceding rules into an octet stream.

10 Adaptive Output Method

The Adaptive output method serializes the input tree into a human readable form for the purposes of debugging query results. The intention of this is to allow any input value to be serialized without raising a serialization error. Sequence normalization is not performed for this output method.

Each item in the supplied sequence is serialized individually as follows, with an occurrence of the chosen item-separator between successive items.

• A document, element, text, comment, or processing instruction node is serialized using the XML output method described in 5 XML Output Method.

• An attribute or namespace node is serialized as if it had a containing element node. For example an attribute node might be serialized as the string xsi:type="xs:integer"; a namespace node might be serialized as xmlns:sns="http://example.com/sample-namespace".

  Note:

  This may result in output of QNames containing prefixes whose binding is not displayed.

• An atomic value^XP is serialized as follows:

  • An instance of xs:boolean is serialized as true() or false().

  • An instance of xs:string, xs:untypedAtomic or xs:anyURI is serialized by enclosing the value in double quotation marks and doubling any quotes within the value; or optionally by enclosing the value in apostrophes and doubling any apostrophes within the value. The resulting value is then serialized using the Text output method described in 8 Text Output Method.

    Note:

    The Text output method will apply character expansion and encoding rules to this string as specified by the serialization parameters.

  • An instance of xs:integer or xs:decimal is serialized by converting the value to a string using the fn:string function.

  • An instance of xs:double is serialized by applying the function format-number(?, '0.0##########################e0') using the following default decimal format properties:

    Decimal format

    Property name	Property value
    decimal-separator	U+002E (FULL STOP, PERIOD, .)
    exponent-separator	U+0065 (LATIN SMALL LETTER E, e)
    grouping-separator	U+002C (COMMA, ,)
    zero-digit	U+0030 (DIGIT ZERO, 0)
    digit	U+0023 (NUMBER SIGN, #)
    infinity	The string "INF"
    NaN	The string "NaN"
    minus-sign	U+002D (HYPHEN-MINUS, -)

  • An instance of xs:QName or xs:NOTATION is serialized as a URI-qualified name (that is, in the form Q{uri}local).

  • An atomic item of any other type is serialized using the syntax of a constructor function: xs:TYPE("VAL") where TYPE is the name of the primitive type, and VAL is the result of applying the fn:string() function. For example, xs:date("2015-07-17"). The resulting string is then serialized using the Text output method described in 8 Text Output Method.

• An array item is serialized using the syntax of a SquareArrayConstructor^XP, that is as [member,member, ... ]. The members, which in general are sequences, are serialized in the form (item,item, ...) where the items are serialized by applying these rules recursively. The items are separated by commas (not by the item-separator character). The enclosing parentheses are optional if the sequence has length one.

  Note:

  The serializer should avoid outputting the parentheses if it is able to determine the length of the sequence before serializing the first item; but it is allowed to output parentheses around a singleton if this avoids buffering data in memory.

• A map item is serialized using the syntax of a MapConstructor^XP without the optional map keyword, that is in the format {key:value, key:value, ...}. The order of entries is implementation-dependent. The key is serialized by applying the rules for serializing an atomic item. The values are serialized in the same way as the members of an array (see above). A map item is serialized using the syntax of a MapConstructor^XP without the optional map keyword, that is in the format {key:value, key:value, ...}. The key/value pairs in the serialized output retain the entry order^DM of entries in the map. The key is serialized by applying the rules for serializing an atomic item. The values are serialized in the same way as the members of an array (see above). A map item is serialized using the syntax of a MapConstructor^XP without the optional map keyword, that is in the format {key:value, key:value, ...}. The orderkey/value pairs in the serialized output retain the entry order^DM of entries is implementation-dependentin the map. The key is serialized by applying the rules for serializing an atomic item. The values are serialized in the same way as the members of an array (see above).

  Note:

  The order of entries is implementation-dependent in the default case where the ordered^DM property of the map is false.

• A function item is serialized to the representation name#A where fn:name is a representation of the function name and A is the arity. If the function name is in one of the namespaces http://www.w3.org/2005/xpath-functions, http://www.w3.org/2005/xpath-functions/math, http://www.w3.org/2005/xpath-functions/map, http://www.w3.org/2005/xpath-functions/array or http://www.w3.org/2001/XMLSchema, then the name is output as a lexical QName using the conventional prefix fn, math, map, array, or xs as appropriate; if it is in any other namespace or in no namespace, then the name is output as a URI-qualified name (that is, Q{uri}local). If the function is anonymous, name is replaced by the string (anonymous-function).

  Note:

  The following examples illustrate this rule:

  • fn:exists#1 is serialized as function fn:exists#1

  • Q{http://www.w3.org/2005/xpath-functions}exists#1 is serialized as fn:exists#1

  • function($a) { $a } is serialized as (anonymous-function)#1

  • math:pi#0 is serialized as math:pi#0

Character maps are applied (a) when nodes are serialized using the XML output method, and (b) to any value represented as a string enclosed in quotation marks.

Optionally, in all the above constructs, characters whose visual representation is ambiguous (for example tab or non-breaking-space) may be represented in the form of an XML numeric character reference (for example 	 or  )

If any value cannot be output because doing so would cause a serialization error, the behavior is implementation-defined.

If the output is sent to a destination that allows hyperlinks to be included in the generated text, then the serializer may include implementation-dependent hyperlinks to provide additional information for example:

• to allow the type of atomic items^XP to be ascertained.

• to allow the namespace binding of prefixes to be ascertained.

• to provide further information about the cause of error indicators.

11 Character Maps

The use-character-maps parameter is a list of characters and corresponding string substitutions.

Character maps allow a specific character appearing in a text or attribute node or a string in the input tree 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 mechanism can therefore be used to introduce arbitrary markup in the serialized output. See Section 27.3 Character Maps^XT of [XSL Transformations (XSLT) Version 4.0] for examples of using character mapping in XSLT.

Character mapping is applied to the characters that actually appear in a text or attribute node or a string in the input tree, before any other serialization operations such as escaping or Unicode Normalization are applied. If a character is mapped, then it is not subjected to XML or HTML escaping, nor to Unicode Normalization. The string that is substituted for a character is not validated or processed in any way by the serializer, except for translation into the target encoding. In particular, it is not subjected to XML or HTML escaping, it is not subjected to Unicode Normalization, and it is not subjected to further character mapping.

Character mapping is not applied to characters in text nodes whose parent elements are listed in the cdata-section-elements parameter, nor to characters for which output escaping has been disabled (disabling output escaping is an [XSL Transformations (XSLT) Version 4.0] feature), nor to characters in attribute values that are subject to URI escaping defined for the HTML and XHTML output methods, unless URI escaping has been disabled using the escape-uri-attributes parameter in the output definition.

On serialization, occurrences of a character specified in the use-character-maps in text nodes, attribute values and strings are replaced by the corresponding string from the use-character-maps parameter.

If a character is mapped, then it is not subjected to XML or HTML escaping.

A serialization error [err:SERE0008] occurs if character mapping causes the output of a string containing a character that cannot be represented in the encoding that the serializer is using for output. The serializermust raise the error.

12 Conformance

Serialization is intended primarily as a component of a host language. [Definition: A host language is another specification that includes, by reference, this specification and all of its requirements. A host language might be a programming language such as [XSL Transformations (XSLT) Version 4.0] or [XQuery 4.0: An XML Query Language], or it might be an application programming interface (API) intended to be used by programs written in some other high-level programming language. The use of the term language is not intended to preclude the possibility that this specification might be referenced outside the context of a programming language specification.] This document relies on specifications that use it to specify conformance criteria for Serialization in their respective environments. Specifications that set conformance criteria for their use of Serialization must not change the semantic definitions of Serialization as given in this specification, except by subsetting and/or compatible extensions. It is the responsibility of the host language to specify how serialization errors are to be handled.

Certain facilities in this specification are described as producing implementation-defined results. A claim that asserts conformance with this specification must be accompanied by documentation stating the effect of each implementation-defined feature. For convenience, a non-normative checklist of implementation-defined features is provided at F.1 Checklist of Implementation-Defined Features.