3 Serialization Parameters

There are a number of parameters that influence how serialization is performed. Host languages MAY 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.

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:

Serialization parameters
Serialization parameter name Permitted values for parameter
allow-duplicate-names One of the enumerated values yes, no, true, false, 1 or 0. This parameter indicates whether a map item serialized as a JSON object using the JSON output method is allowed to contain duplicate member names. If the value no, false or 0 is specified, serialization error [err:SERE0022] will be raised.
byte-order-mark One of the enumerated values yes, no, true, false, 1 or 0. This parameter indicates whether the serialized sequence of octets is to be preceded by a Byte Order Mark (See Section 5.1 of [Unicode Encoding]). The actual octet order used is implementation-dependent. If the encoding defines no Byte Order Mark, or if the Byte Order Mark is prohibited for the specific Unicode encoding or implementation environment, then this parameter is ignored.
cdata-section-elements A list of expanded QNames, possibly empty.
doctype-public A string of PubidCharXML characters. This parameter MAY be absent.
doctype-system A string of Unicode characters that does not include both an apostrophe (#x27) and a quotation mark (#x22) character. This parameter MAY be absent.
encoding A string of Unicode characters in the range #x21 to #x7E (that is, printable ASCII characters); the value SHOULD be a charset registered with the Internet Assigned Numbers Authority [IANA], [RFC2978] or begin with the characters x- or X-.
escape-uri-attributes One of the enumerated values yes, no, true, false, 1 or 0.
html-version A decimal value. This parameter MAY be absent.
include-content-type One of the enumerated values yes, no, true, false, 1 or 0.
indent One of the enumerated values yes, no, true, false, 1 or 0.
item-separator A string of Unicode characters. This parameter MAY be absent.
json-node-output-method An expanded QName with a non-null namespace URI, or with a null namespace URI and a local name equal to one of xml, xhtml, html or text. If the namespace URI is non-null, the parameter specifies an implementation-defined output method.
media-type A string of Unicode characters specifying the media type (MIME content type) [RFC2046]; the charset parameter of the media type MUST NOT be specified explicitly in the value of the media-type parameter. If the destination of the serialized output is annotated with a media type, this parameter MAY be used to provide such an annotation. For example, it MAY be used to set the media type in an HTTP header.
method An expanded QName with a non-null namespace URI, or with a null namespace URI and a local name equal to one of xml, xhtml, html, text, json, or adaptive. If the namespace URI is non-null, the parameter specifies an implementation-defined output method.
normalization-form One of the enumerated values NFC, NFD, NFKC, NFKD, fully-normalized or none, or an implementation-defined value of type NMTOKEN.
omit-xml-declaration One of the enumerated values yes, no, true, false, 1 or 0.
standalone One of the enumerated values yes, no, true, false, 1 or 0 or omit.
suppress-indentation A list of expanded QNames, possibly empty.
undeclare-prefixes One of the enumerated values yes, no, true, false, 1 or 0.
use-character-maps A list of pairs, possibly empty, with each pair consisting of a single Unicode character and a string of Unicode characters.
version A string of Unicode characters.

The value of the method parameter is an expanded QName. If the value has a null namespace URI, then the local name identifies a method specified in this document and MUST be one of xml, html, xhtml, text, json , or adaptive; in this case, the output method specified MUST be used for serializing. If the namespace URI is non-null, then it identifies an implementation-defined output method; the behavior in this case is not specified by this document.

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 language MUST 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 language MAY 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 yes, true or 1; 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]).

3.1 Setting Serialization Parameters by Means of a Data Model Instance

A host language MAY provide, by reference to this section, a mechanism by which the settings of serialization parameters are supplied in the form of an instance of the data model as specified in [XQuery and XPath Data Model (XDM) 3.1]. The instance of the data model used to determine the settings of serialization parameters MUST be processed as if by the procedure described below.

With the exception of the use-character-maps parameter, the setting of each serialization parameter defined in this specification is equal to the result of evaluating the XQuery expression

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

or equivalently the XSLT instructions

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

with the supplied instance of the data model as the context item, the param-name variable bound to a value of type xs:string equal to the local part of the name of the particular serialization parameter, and the other components of the dynamic context and static context as specified in the subsequent tables. If in any case evaluating this expression would yield an error, serialization error [err:SEPM0017] results.

If the result of evaluating this expression for a particular serialization parameter is the empty sequence, then

  1. If the parameter is either cdata-section-elements or suppress-indentation and the result of evaluating the XQuery expression

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

    or equivalently the XSLT instructions

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

    with the same settings of the static context and dynamic context is not an empty sequence, the setting of the parameter is the empty list;

  2. otherwise, the setting of the parameter is absent.

The components of the static context used in evaluating the XQuery expressions or XSLT instructions are as defined in the following table.

Settings of static context components used in extracting serialization parameter settings from an XDM instance
Static Context Component XQuery or XSLT Setting
XPath 1.0 compatibility mode Both false
Statically known namespaces XQuery The pair (output,http://www.w3.org/2010/xslt-xquery-serialization)
XSLT The pairs (output,http://www.w3.org/2010/xslt-xquery-serialization), (xsl,http://www.w3.org/1999/XSL/Transform)
Default element/type namespace Both "none"
Default function namespace Both http://www.w3.org/2005/xpath-functions
In-scope schema types, In-scope element declarations, Substitution groups, In-scope attribute declarations Both As defined by the schema for serialization parameters (B Schema for Serialization Parameters) and any additional implementation-defined in-scope schema components
In-scope variables Both {param-name}
Context item static type Both node()
Statically-known function signatures Both {fn:data($arg as item()*) as xs:anyAtomicType*}, {fn:local-name($arg as node()?) as xs:string}
Statically known collations Both { (http://www.w3.org/2005/xpath-functions/collation/codepoint, The Unicode codepoint collation ) }
Default collation Both The Unicode codepoint collation
Construction mode XQuery strip
Ordering mode XQuery ordered
Default order for empty sequences XQuery least
Boundary space policy XQuery strip
Copy-namespaces mode XQuery (preserve,inherit)
Base URI Both Absent
Statically known documents Both None
Statically known collections Both None
Statically known default collection type Both node()*
Statically known decimal formats Both None
Set of named keys XSLT {}
Values of system properties XSLT None
Set of available instructions XSLT The set of all instructions defined by [XSL Transformations (XSLT) Version 3.0]

The remaining components of the dynamic context used in evaluating the XQuery expressions or XSLT instructions in the preceding table are as defined in the following table.

Settings of dynamic context components used in extracting serialization parameter settings from an XDM instance
Dynamic Context Component XQuery or XSLT Setting
Context position Both 1
Context size Both 1
Variable values Both The param-name variable has a value of type xs:string equal the local part of the name of the serialization parameter under consideration
Function implementations Both The implementation of fn:data
Current dateTime Both Absent
Implicit timezone Both Absent
Available documents Both None
Available collections Both None
Default collection Both None
Current template rule XSLT Absent
Current mode XSLT The default mode
Current group XSLT Absent
Current grouping key XSLT Absent
Current captured substrings XSLT The empty sequence
Output state XSLT Temporary output state

In the case of the use-character-maps parameter, the XQuery expression

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

or equivalently the XSLT instructions

<xsl:sequence>
  <xsl:variable name="validated-instance">
    <xsl:document validation="lax">
      <xsl:sequence select="
        ./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>

is evaluated for each Unicode character that is permitted in an XML document. The dynamic context and static context used to evaluate the expression are as defined above, except that in-scope variables is the set {char} and the value of the variable "char" is a value of type xs:string of length one whose value is the Unicode character under consideration. If the result of evaluating the expression is not an empty sequence, the pair consisting of the Unicode character and the result of evaluating the expression is part of the list of pairs in the value of the use-character-maps parameter. It is a serialization error [err:SEPM0018] if the result of evaluating this expression for any character is a sequence of length greater than one.

Using the same settings of the components of the dynamic context and static context, serialization error [err:SEPM0019] results if the result of evaluating the following XQuery expression is not true

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

or equivalently if the result of evaluating the following XSLT instructions is not true.

<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>

The result of evaluating either will be false if the data model instance supplies a value for any particular serialization parameter more than once, or will be the empty sequence if the data model instance does not have as its root node an element node or a document node with an element node child, where the local part of the name of the element node is serialization-parameters and the namespace URI is http://www.w3.org/2010/xslt-xquery-serialization.

Note:

A serializer or implementation of a host language does not need to be accompanied by an XQuery processor nor by a general-purpose schema validator in order to meet the requirements of this section. It merely needs to be capable of extracting values from an XDM instance that conforms to the schema for serialization parameters, while checking that the constraints implied by the schema and additional constraints implied by the XQuery validate expression or explicitly stated in this section are satisfied.

The host language MAY provide additional mechanisms for overriding the values of any serialization parameters specified through the mechanism defined in this section, as well as additional mechanisms for specifying the values of any serialization parameters whose values are absent after applying the mechanism defined in this section.

If the instance of the data model contains elements or attributes that are in a namespace other than http://www.w3.org/2010/xslt-xquery-serialization, the implementation MAY interpret them to specify the values of implementation-defined serialization parameters in an implementation-defined manner.

The following XML document, if converted to a data model instance and processed using the mechanism described in this section, would specify the settings of the method, version and indent serialization parameters with the values xml, 1.0 and yes, respectively.

<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>

The following document would specify the setting of the cdata-section-elements serialization parameter with value the pair of expanded QNames (http://example.org/book/chapter,heading) and (http://example.org/book,footnote)

<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>

The following document would specify the value of the method serialization parameter with the value html.

Notice that in this example, the default namespace declaration in scope has no effect on the interpretation of the setting of the method parameter.

<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>

The following document would specify the value of the method serialization parameter with value equal to the expanded QName (http://example.org/ext, jsp), and the use-character-maps parameter with value equal to the list of pairs, («, <%), (», %>).

<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>