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 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]).
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
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;
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.
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.
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="«" map-string="<%"/> <output:character-map character="»" map-string="%>"/> </output:use-character-maps> </output:serialization-parameters>