]>
XSLT 2.0 and XQuery 1.0 Serialization &doc.prefix;-&doc.date; W3C Working Draft &date.day; &date.month; &date.year; &url.this; XML http://www.w3.org/TR/xslt-xquery-serialization/ http://www.w3.org/TR/2003/WD-xslt-xquery-serialization-20031112/ http://www.w3.org/TR/2003/WD-xslt-xquery-serialization-20030502/ Michael Kay Saxonica (formerly of Software AG) http://www.saxonica.comMichael.Kay@softwareag.com Norman Walsh Sun Microsystems Norman.Walsh@Sun.COM Henry Zongaro IBM zongaro@ca.ibm.com

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a Public Working Draft for review by W3C Members and other interested parties. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document describes how and convert an instance of the into a sequence of octets. This material has been moved out of the XSLT draft and into a separate document so that it can be shared by both the named specifications and possibly other specifications as well.

This draft includes many corrections and changes based on member-only and public comments on the Last Call Working Draft (http://www.w3.org/TR/2003/WD-xslt-xquery-serialization-20031112/). The XML Query and XSL WGs wish to thank the people who have sent in comments for their close reading of the document.

This draft reflects decisions taken up to and including the face-to-face meeting in Cambridge, MA during the week of 21 June 2004. These decisions are recorded in the Last Call issues list (http://www.w3.org/2004/07/xquery-serialization-issues.html). However, some of these decisions may not yet be reflected in this document.

XSLT 2.0 and XQuery 1.0 Serialization has been defined jointly by the XSL Working Group and the XML Query Working Group (both part of the XML Activity).

Public comments on this document and its open issues are invited. Comments should be sent to the W3C XSLT/XPath/XQuery mailing list, public-qt-comments@w3.org (archived at http://lists.w3.org/Archives/Public/public-qt-comments/), with “[Serial]” at the beginning of the subject field.

The patent policy for this document is expected to become the 5 February 2004 W3C Patent Policy, pending the Advisory Committee review of the renewal of the XML Query Working Group. Patent disclosures relevant to this specification may be found on the XML Query Working Group's patent disclosure page and the XSL Working Group's patent disclosure page. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

This document defines serialization for the and specifications and any other specifications that reference it.

 English

See the CVS changelog.
Introduction

This document defines serialization of the W3C XQuery 1.0 and XPath 2.0 Data Model, which is the data model of at least , , and , and any other specifications that reference it.

This material has been moved out of the XSLT draft and into a separate document. The Working Groups also considered moving this material directly into the Data Model document, but elected to keep it separate for the moment, principally in order to advance the Data Model to Last Call. In the future, this material may be moved into the Data Model. The Working Groups solicit public opinion about which alternative is superior.

Serialization is the process of converting an instance of the into a sequence of octets. Serialization is well-defined for most data model instances.

The document assumes the reader already knows generally what serialization is. A brief explanation will be added, especially to disabuse any reader who thinks it might mean Java (or .NET) serialization. The editor has yet to align the description of serialization errors with the description of errors in related specifications. That will be done in a future public working draft.

In this specification the words must, must not, should, should not, may, required, and recommended are to be interpreted as described in .

 Serializing Arbitrary Instances of the Data Model

The XQuery 1.0 and XPath 2.0 Data Model is richer and less constrained than XML. There are valid instances of the data model that have no direct analog in XML. In particular, instances of the data model can contain typed values, sequences, and sequences of typed values. And whereas XML deals only with documents, instances of the data model can have as their root any node type, simple value, or sequence and may even be empty.

This section describes how to convert an arbitrary instance of the data model into one of several simplified forms. We then describe how these forms are serialized. This greatly simplifies the sections which follow. Implementations are not required to implement serialization of arbitrary instances of the data model in this way, provided that they produce the same results as this conceptual model.

If the instance of the data model contains any typed or untyped atomic values, or sequences that contain typed or untyped atomic values, convert them to strings: obtain the lexical representation of each value by casting it to an xs:string and replace the value with its string representation. If the value cannot be cast to xs:string, serialization of the instance of the data model is undefined.

If adjacent strings occur in a sequence, replace both values with their concatenation separated by a single space.

If empty sequences occur, replace them with the empty string.

To complete the simplification, perform the following steps interactively iteratively until a simplest form is reached:

If the instance of the data model has as its root an attribute or namespace node, or a QName value, or if it has as its root a sequence which contains one of these items, serialization is undefined.

If the instance of the data model has as its root a single document node, or an element, processing instruction, comment, or text node, or a sequence of only element, processing instruction, comment, and text nodes, it is already in its simplest form.

If the instance of the data model has as its root a sequence of document nodes, or a sequence which contains document nodes, replace each document node with its children in document order.

If the instance of the data model has as its root a string value, or a sequence which contains one or more string values, replace each string value with a text node that contains the same string.

If there are any remaining string values among the children of elements in the instance of the data model, replace them with text nodes that contain the same string values and merge adjacent text nodes.

An instance of the data model that is input to the serialization process is a sequence. Prior to serializing a sequence using any of the output methods whose behavior is specified by this document () the serialization process must first place that input sequence into a normalized form for serialization; it is the normalized sequence that is actually serialized. The normalized form for serialization is constructed by applying all of the following rules in order, with the initial sequence 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 normalization process takes place.

Where the process of converting the input sequence to a normalized form indicates that a value must be cast to xs:string, that operation is as defined in of .

Replace an empty sequence with a zero-length string.

If the instance of the data model contains any atomic values, or sequences that contain atomic values, convert the atomic values to strings: obtain the lexical representation of each value by casting it to an xs:string and replace the value with its string representation. It is a serialization error if the value cannot be cast to xs:string.

Replace all adjacent strings in the sequence, with a single string equal to the values of the strings concatenated, each separated by a single space.

Replace any string in the sequence with a text node whose string value is equal to the string.

Replace any document node in the sequence with its children.

It is a serialization error if an item in the sequence is an attribute node or a namespace node. Otherwise, create a new document node and make all the items in the sequence, which are all nodes, children of that document node.

The tree rooted in the document node that is created by the final step of this normalization process is the instance of the data model to which the rules of the appropriate output method are applied. If the normalization process results in a serialization error, the processor must signal the error.

The normalization process for a sequence $seq is equivalent to constructing a document node using the XSLT instruction:

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

or the XQuery expression:

document { for $s in $seq return if ($s instance of document-node()) then $s/child::node() else $s }

and then serializing the document node as described in , , , , or in an implementation-defined manner.

This process will fail results in a serialization error with certain sequences, for example sequences containing parentless attribute and namespace nodes, or atomic values of types that cannot be cast to a string, such as xs:QName. and xs:NOTATION Such a failure results in a serialization error; the processor must signal the error.

 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.

The following serialization parameters are defined:

Here and throughout the document, the distinction between "should" and "must" will be revisited. When serialization was described in the XSLT specification, use of "should" helped to clarify that the serialization process was optional. Now that it's described here in a standalone specification, many of those clauses should use "must".
Serialization parameter name Permitted values for parameter
cdata-section-elements A list of expanded-QNames, possibly empty.
doctype-public A string of Unicode characters. This parameter is optional.
doctype-system A string of Unicode characters. This parameter is optional.
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 , or begin with the characters x- or X-.
escape-uri-attributes One of the enumerated values yes or no.
include-content-type One of the enumerated values yes or no.
indent One of the enumerated values yes or no.
media-type A string of Unicode characters specifying the media type (MIME content type) ; the charset parameter of the media type must not be specified explicitly in the value of the media-type parameter.
method An expanded-QName with a null namespace URI, and the local part of the name equal to one of xml, xhtml, html or text, or having a non-null namespace URI. 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, none or an implementation-defined value.
omit-xml-declaration One of the enumerated values yes or no.
standalone One of the enumerated values yes, no or none.
undeclare-namespaces One of the enumerated values yes or no.
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.

encoding specifies the preferred character encoding that the processor should use for encoding sequences of characters as sequences of bytes; the value of the parameter should be treated case-insensitively; the value must contain only characters in the range #x21 to #x7E (i.e. printable ASCII characters); the value should either be a charset registered with the Internet Assigned Numbers Authority , or start with X-

If this parameter is not specified, and the output method does not specify any additional requirements, the encoding used is implementation-defined.

cdata-section-elements specifies a list of the names of elements whose text node children are to be output using CDATA sections

If this parameter is not specified, no elements will be treated specially.

doctype-system specifies the system identifier to be used in the document type declaration

If this parameter is not specified, no system identifier will a system identifer must not be generated. For XML and XHTML output methods, no public identifier will a public identifer must not be generated either, regardless of the setting of doctype-public.

doctype-public specifies the public identifier to be used in the document type declaration

If this parameter is not specified, a public identifier must not no public identifier will be generated.

escape-uri-attributes specifies whether the processor should is to escape URI-valued attributes in HTML and XHTML output using the method recommended in (section 2.4.1). The value must be yes or no.

If this parameter is not specified, the value is implementation-defined.

include-content-type specifies whether the serialization process is to add a meta element in HTML and XHTML output. The value must be yes or no.

If this parameter is not specified, the value is implementation-defined.

indent specifies whether the processor may add additional whitespace when outputting the instance of the data model; the value must be yes or no

If this parameter is not specified, the value is implementation-defined.

media-type specifies the media type (MIME content type) of the data that results from outputting the instance of the data model; the charset parameter of the media type must not be specified explicitly ; instead, when the top-level media type is text, a charset parameter should be added according to the character encoding actually used by the output method

If this parameter is not specified, the media type is implementation-defined.

normalize-unicode indicates whether or not the serialization process should must convert requests conversion of the serialized output to Unicode Normalization Form C as specified in . The value must be yes or no.

If this parameter is not specified, the value is implementation-defined.

omit-xml-declaration specifies whether the serialization process should must is to output an XML declaration., unless the declaration is required by the setting of either the encoding parameter or the standalone parameter The value must be yes or no

If this parameter is not specified, the value is implementation-defined.

standalone specifies whether the processor should must output a standalone document declaration and what its value should must be; is to emit a standalone document declaration and the value of the declaration; the value of the parameter must be yes or no

If this parameter is not specified, a standalone document declaration must not be output.

undeclare-namespaces specifies whether namespaces, shouldmust are to be undeclared during serialization; the value must be yes or no.

If this parameter is not specified, the value is implementation-defined.

This parameter only applies when the XML serialization method is used and the version is greater than 1.0.

use-character-maps provides specifies a list of character/string pairs that are used in serialization (see ).

If this parameter is not specified, no character maps are used.

version specifies the version of the output method

If this parameter is not specified, the value is implementation-defined.

The method parameter identifies the overall output method that should be used for serializing. The value of the method parameter must be a valid QName. If the QName is in no namespace, then it identifies a method specified in this document and must be one of xml, html, xhtml, or text; in this case, the output method specified must be used for serializing. If the QName is in a namespace, then it identifies an implementation-defined output method; the behavior in this case is not specified by this document.

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.

 Phases of Serialization

Following the normalization process described in , serialization can be regarded as involving four phases of processing, carried out sequentially as follows:

Markup generation produces the representation of start and end tags for elements, and other constructs such as XML declarations, processing instructions, and so on. This is influenced by the parameters method, doctype-system, doctype-public, include-content-type, indent, omit-xml-declaration, standalone, undeclare-namespaces and version.

Character expansion is concerned with the representation of characters appearing in text and attribute nodes in the instance of the data model. The substitution processes that may apply are listed below, in priority order: a character that is handled by one process in this list will be unaffected by processes appearing later in the list:

URI escaping (in the case of URI-valued attributes in the HTML and XHTML output methods), as determined by the escape-uri-attributes parameter

Creation of CDATA sections, as determined by the cdata-section-elements parameter. Note that this is also affected by the encoding parameter, in that characters not present in the selected encoding cannot be represented in a CDATA section.

Character mapping, as determined by the use-character-maps parameter.

Escaping of special characters according to XML or HTML rules, for example replacing < by &lt;

Unicode Normalization, if requested by the normalize-unicode normalization-form parameter. Unicode normalization is applied to the character stream that results after all markup generation and character expansion has taken place.

For the definitions of the various normalization forms, see

The meanings associated with the possible values of the normalization-form parameter are as follows:

NFC specifies the serialized result should be in Unicode Normalization Form C.

NFD specifies the serialized result should be in Unicode Normalization Form D.

NFKC specifies the serialized result should be in Unicode Normalization Form KC.

NFKD specifies the serialized result should be in Unicode Normalization Form KD.

fully-normalized specifies the serialized result should be in fully normalized form.

none specifies that no Unicode normalization should be applied.

An implementation-defined value has an implementation-defined effect.

Any characters produced under the effect of the use-character-maps parameter are not subject to Unicode normalization. If the normalization-form parameter has a value other than none and the use-character-maps parameter is not empty, the whole of the serialized document may not be in the normalization form specified by the normalization-form parameter.

Encoding, as controlled by the encoding parameter. This converts the character stream produced by the previous phases into a byte stream.

Serialization is only defined in terms of encoding the result as a stream of bytes. However, a processor may provide an option that allows the encoding phase to be skipped, so that the result of serialization is a stream of Unicode characters. The effect of any such option is implementation-defined, and a processor is not required to support such an option.

 XML Output Method

The xml output method outputs the instance of the data model as an XML entity that must satisfy the rules for either a well-formed XML document entity or a well-formed XML external general parsed entity, or both, unless the processor is unable to satisfy those rules due to either serialization errors or the requirements of the character expansion phase of serialization, as described in . If the processor is unable to satisfy those requirements for any other reason, a serialization error results. The processor must signal the error. Many of the requirements for the serialized form of the instance of the data model with the xml output method are described using the verb "should"; the processor might not be able to meet the requirements of the xml output method due to:

serialization errors;

specification of character mapping, as determined by the use-character-maps parameter, whose expansion results in XML that is not well-formed; or

disabled output escaping, that results in XML that is not well-formed.

In all other circumstances, the serialized form must comply with the requirements described for the xml output method.

If the document node of the instance of the data model has a single element node child and no text node children, and then the serialized output is a well-formed XML document entity, and the serialized output must conform to the XML Namespaces Recommendation . If the instance of the data model does not take this form, and then the serialized output is a well-formed XML external general parsed entity, then the serialized output must be an entity which, when referenced within a trivial XML document wrapper like this

entity-URI ]> &e;]]>

where entity-URI is a URI for the entity, produces a document which must itself be a well-formed XML document conforming to the XML Namespaces Recommendation .

In addition, the output must be such that if a new tree was constructed by parsing the XML document and converting it into an instance of the data model as specified in this document , then the new instance of the data model would be the same as the starting instance of the data model that resulted from the normalization process described in , with the following possible exceptions:

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 base URIs of 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 new tree may contain additional attributes and text nodes resulting from the expansion of default and fixed values in its DTD or schema.

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 be derived by processing depend on whether the serialized XML document is assessed against a schema, and this may result in type annotations that are either more or less precise than those in the original result tree.

In order to influence the type annotations in the instance of the data model that would result from processing a serialized XML document, the author of the XSLT stylesheet, XQuery expression or other process may wish to create the instance of the data model that is input to the serialization process so that it makes use of mechanisms provided by , 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 instance of the data model that is to be serialized 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.

In order to permit such type annotations to be available in a data model that results from processing a serialized XML document, the process that creates the input instance of the data model could create it so that the serialized form uses mechanisms provided by , such as the xsi:type and xsi:schemaLocation attributes.

Additional namespace nodes may be present in the new tree if the serialization process did not undeclare undeclared one or more namespaces, as described in , and the starting instance of the data model 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.

Additional namespace nodes may also be present in the new tree if the serialization process had to add namespace declarations for attribute or element content of type xs:QName. The original tree may contain namespace nodes that are not present in the new tree, as the process of creating an instance of the data model may ignore namespace declarations in some circumstances. See and of for additional information. We've talked about this a couple of times now, but I'm still concerned about the preceding paragraph. This text was added in response to issue qt-Feb0059-01. Today, XSLT describes a namespace fixup procedure that ensures namespaces exist for values of type xs:QName. Is the resolution for this issue requiring the same thing for serialization? Or something else?

If the indent parameter has the value yes,

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

text nodes in the original tree that contained only whitespace characters may correspond to text nodes in the new tree that contain additional whitespace characters that were not present in the original tree

See for more information on the indent parameter.

Additional nodes may be present in the new tree, and the values of attribute nodes and text nodes in the new tree may be different from those in the original tree, due to the character expansion phase of serialization.

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 new tree that results from processing the serialized XML document.

A consequence of this rule is that certain whitespace characters should must be output as character references, to ensure that they survive the round trip through serialization and parsing. Specifically, CR, NEL and LINE SEPARATOR characters in text nodes must be output respectively as &#xD;, &#x85;, and &#x2028;, or their equivalents; while CR, NL, TAB, NEL and LINE SEPARATOR characters in attribute nodes must be output respectively as &#xD;, &#xA;, &#x9;, &#x85;, and &#x2028;, or their equivalents. Specifically, CR characters in text nodes should must be written as &#xD; or an equivalent; while CR, NL, and TAB characters in attribute nodes should must be output respectively as &#xD;, &#xA;, and &#x9;, or their equivalents.

For example, an attribute with the value "x" followed by "y" separated by a newline will result in the output "x&#xA;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.

XML 1.0 did not permit processors to normalize NEL or LINE SEPARATOR characters to a LINE FEED character. However, if a document entity that specifies version 1.1 invokes an external general parsed entity with no text declaration or a text declaration that specifies version 1.0, the external parsed entity is processed according to the rules of XML 1.1. For this reason, NEL and LINE SEPARATOR characters in text and attribute nodes must always be escaped using character references or CDATA sections, regardless of the value of the version parameter.

To anticipate the proposed changes to end-of-line handling in XML 1.1, implementations may also output the characters x85 and x2028 as character references. This will not affect the way they are interpreted by an XML 1.0 parser.

It is a serialization error to request the output of a document type declaration, or of a standalone parameter, if the instance of the data model contains text nodes or multiple element nodes as children of the root node. The processor may signal the error, or may recover must either signal the error, or recover by ignoring the request to output a document type declaration or standalone parameter.

The result of serialization using the XML output method is not guaranteed to be well-formed XML if character maps have been specified (see ) or if nodes in the instance of the data model contain characters that are invalid in XML (introduced, perhaps, by calling a user-written extension function: this is an error but the processor is not required to signal it).

XML Output Method: the version Parameter

The version parameter specifies the version of XML to be used for outputting the instance of the data model. If the processor does not support this version of XML, it should must use a version of XML that it does support. it must signal a serialization error. The version output in the XML declaration (if an XML declaration is output) should must correspond to the version of XML that the processor used for outputting the instance of the data model. The value of the version parameter should must match the production of the XML Recommendation .

 XML Output Method: the encoding Parameter

The encoding parameter specifies the preferred encoding to use for outputting the instance of the data model. Processors are required to support values of UTF-8 and UTF-16. A serialization error occurs if an output encoding other than UTF-8 or UTF-16 is requested and the implementation does not support that encoding. The processor must may signal the error, or may recover by using UTF-8 or UTF-16 instead. The processor must not use an encoding whose name does not match the production of the XML Recommendation . If no encoding parameter is specified, then the processor should must use either UTF-8 or UTF-16.

When outputting a newline character in the instance of the data model, the implementation is free to represent it using any character sequence that will be normalized to a newline character by an XML parser, unless a specific mapping for the newline character is provided in a character map: see .

When outputting any other character that is defined in the selected encoding, the character should must be output using the correct representation of that character in the selected encoding.

It is possible that the instance of the data model will contain a character that cannot be represented in the encoding that the processor is using for output. In this case, if the character occurs in a context where XML recognizes character references (that is, in the value of an attribute node or text node), then the character should must be output as a character reference. A serialization error occurs if such a character appears in a context where character references are not allowed (for example if the character occurs in the name of an element). The processor should must signal the error.

XML Output Method: the indent Parameter

If the indent parameter has the value yes, then the xml output method may output whitespace in addition to the whitespace in the instance of the data model (possibly based on whitespace stripped from either the source document or the stylesheet, in the case of XSLT, or guided by other means that might depend on the host language, in the case of an instance of the data model created using some other process) in order to indent the result nicely; if the indent parameter has the value no, it should must not output any additional whitespace. If the xml output method does output additional whitespace, it should must use an algorithm to output additional whitespace that satisfies the following constraints:

Whitespace characters must not be added adjacent to a text node that contains non-whitespace characters.

Whitespace may only be added adjacent to an element node, that is, immediately before a start tag or immediately after an end tag.

The new whitespace characters may replace existing whitespace characters in the same position, for example a tab may be inserted as a replacement for existing spaces. However, existing whitespace must not be removed without such a replacement.

Whitespace characters must not be inserted in a part of the result document that is controlled by an xml:space="preserve" attribute. xml:space attribute with value preserve.

The effect of these rules is to ensure that whitespace may only be is only added in places where (a) XSLT's <xsl:strip-space> declaration could cause it to be removed, and (b) it does not affect the string value of any element node with simple content. It is usually not safe to indent document types that include elements with mixed content.

 XML Output Method: the cdata-section-elements Parameter

The cdata-section-elements parameter contains a list of expanded-QNames. If the expanded-QName of the parent of a text node is a member of the list, then the text node should must be output as a CDATA section, except in those circumstances described below.

If the text node contains the sequence of characters ]]>, then the currently open CDATA section should must be closed following the ]] and a new CDATA section opened before the >.

If the text node contains characters that are not representable in the character encoding being used to output the instance of the data model, then the currently open CDATA section should must be closed before such characters, the characters should must be output using character references or entity references, and a new CDATA section should must be opened for any further characters in the text node.

CDATA sections should must not be used except where they have been explicitly requested by the user, either by using the cdata-section-elements parameter, or by using some other implementation-defined mechanism.

This is phrased to permit an implementor to provide an option that attempts to preserve CDATA sections present in the source document.

 XML Output Method: the omit-xml-declaration and standalone Parameters

The xml output method should must output an XML declaration unless if the omit-xml-declaration parameter has the value yes no. The XML declaration should must include both version information and an encoding declaration. If the standalone parameter has the value yes or the value no, the XML declaration should must include a standalone document declaration with the same value as the value of the standalone parameter. Otherwise, it should must not include a standalone document declaration; this ensures that it is both an XML declaration (allowed at the beginning of a document entity) and a text declaration (allowed at the beginning of an external general parsed entity).

The omit-xml-declaration parameter should must be ignored if the standalone parameter has the value yes or the value no, or if the encoding parameter specifies a value other than UTF-8 or UTF-16.

A serialization error results if the omit-xml-declaration parameter has the value yes, and

the standalone attribute has a value other than none; or

the version parameter has a value other than 1.0 and the doctype-system parameter is present.

 The processor must signal the error.

XML Output Method: the doctype-system and doctype-public Parameters

If the doctype-system parameter is specified, the xml output method should must output a document type declaration immediately before the first element. The name following <!DOCTYPE should must be the name of the first element, if any. If the doctype-public parameter is also specified, then the xml output method should must output PUBLIC followed by the public identifier and then the system identifier; otherwise, it should must output SYSTEM followed by the system identifier. The internal subset should must be empty. The doctype-public parameter should must be ignored unless the doctype-system parameter is specified.

 XML Output Method: the undeclare-namespaces Parameter

The Data Model allows an element to have fewer in-scope namespaces than its parent. In XML 1.1, this can be represented most accurately by undeclaring namespaces. If the undeclare-namespaces parameter has the value yes and the output method is XML and the version is greater than 1.1 1.0, serialization should must undeclare namespaces.

Consider an element x:foo with three in-scope namespaces:

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

Suppose that it has a child element with two in-scope namespaces:

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

If namespace undeclaration is in effect, it will be serialized this way:

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

In XML 1.0, namespace undeclaration is not possible. If the output method is xml, the value of the undeclare-namespaces parameter is yes, and the value of the version parameter is 1.0, a serialization error results; the processor must signal the error. namespace undeclaration is not performed, and the undeclare-namespace parameter is ignored.

XML Output Method: the normalization-form Parameter

The normalize-unicode normalization-form parameter is applicable for the xml output method. The values NFC and none must be supported by the processor. A serialization error results if the value of the normalization-form parameter specifies a normalization form that is not supported by the processor; the processor must signal the error.

It is a serialization error if the value of the parameter is fully-normalized and any relevant construct of the result begins with a combining character. The processor must signal the error. See Section 2.13 of for the definition of the relevant constructs of XML.

 XML Output Method: Other Parameters

The media-type parameter is applicable for the xml output method.

The use-character-maps parameter is applicable for the xml output method.

 XHTML Output Method

The xhtml output method serializes the instance of the data model as XML, using the HTML compatibility guidelines defined in the XHTML specification.

It is entirely the responsibility of the person or process that creates the instance of the data model to ensure that the instance of the data model conforms to the or specification. 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 instance of the data model whether the output conforms to XHTML Strict, XHTML Transitional, XHTML Frameset, or XHTML Basic.

The serialization of the instance of the data model follows the same rules as for the xml output method, with the exceptions noted below. These differences are based on the HTML compatibility guidelines published in Appendix C of , which are designed to ensure that as far as possible, XHTML is rendered correctly on user agents designed originally to handle HTML.

Given an empty instance of an XHTML element whose content model is not EMPTY (for example, an empty title or paragraph) the serializer should must not use the minimized form. That is, it should must output <p></p> and not <p />.

Given an XHTML element whose content model is EMPTY, the serializer should must use the minimized tag syntax, for example <br />, as the alternative syntax <br></br> allowed by XML gives uncertain results in many existing user agents. The serializer should must include a space before the trailing />, e.g. <br />, <hr /> and <img src="karen.jpg"  alt="Karen" />.

The serializer should avoid outputting line breaks and multiple whitespace characters within attribute values. These are handled inconsistently by user agents.

The serializer should avoid use of must not use the entity reference &apos; which, although legal in XML and therefore in XHTML, is not defined in HTML and is not recognized by all HTML user agents.

The serializer should output namespace declarations in a way that is consistent with the requirements of the XHTML DTD if this is possible. The DTD requires the declaration xmlns="http://www.w3.org/1999/xhtml" to appear on the html element, and only on the html element. The serializer must output namespace declarations that are consistent with the namespace nodes present in the result tree, but it should avoid outputting redundant namespace declarations on elements where the DTD would make them invalid.

Where the process used to construct the input instance of the data model does not provide complete control over the prefix used for an element name in the instance of the data model or control of whether the element is in the default namespace (for instance, the XSLT namespace fixup process), implementors are encouraged to provide means or endeavor to preserve the obvious intent of a user to place the html element in in the default namespace, wherever possible. For example, implementors of XSLT processors are encouraged to place the html element that results from a literal result element like the following in the default namespace.

<html xmlns="http://www.w3.org/1999/xhtml"> ... </html>

Although the specification of the namespace fixup process provides no guarantees about the namespace prefixes that are allocated, implementors are encouraged to ensure that where possible, writing the literal result element <html xmlns="http://www.w3.org/1999/xhtml"> ... </html> places the resulting html element in the default namespace.

If the instance of the data model includes a head element in the XHTML namespace, then unless and the include-content-type parameter has the value "no" yes, the xhtml output method must add a meta element immediately after the start-tag of the head element specifying the character encoding actually used.

For example,

...]]>

The content type should be set to the value given for the media-type parameter; the default value for XHTML is text/html. The value application/xhtml+xml, registered in , may also be used.

If the instance of the data model includes a head element that has a meta element child, the processor should replace any content attribute of the meta element, or add such an attribute, with the value as described above, rather than output a new meta element.

Unless If the escape-uri-attributes parameter has the value no yes, the xhtml output method should must escape non-ASCII characters in URI attribute values using the method recommended in Seciton 2.4.1 of .

This escaping is deliberately confined to non-ASCII characters, because escaping of ASCII characters is not always appropriate, for example when URIs or URI fragments are interpreted locally by the HTML user agent. Even in the case of non-ASCII characters, escaping can sometimes cause problems. More precise control of URI escaping is therefore available by setting escape-uri-attributes to no, and controlling the escaping of URIs by means of the fn:escape-uri function defined in .

As with the XML output method, the XHTML output method outputs an XML declaration unless it is suppressed using the omit-xml-declaration parameter. Appendix C.1 of provides advice on the consequences of including, or omitting, the XML declaration.

Appendix C of describes a number of compatibility guidelines for users of XHTML who wish to render their XHTML documents with HTML user agents. In some cases, such as the guideline on the form empty elements should take, only the serialization process itself has the ability to follow the guideline. In such cases, those guidelines are reflected in the requirements on the processor described above.

In all other cases, the guidelines can be adhered to by the instance of the data model that is input to the serialization process. The guideline on the use of whitespace characters in attribute values is one such example. It is the responsibility of the person or process that creates the instance of the data model that is input to the serialization process to ensure it is created in a way that is consistent with the guidelines. No serialization error results if the input instance of the data model does not adhere to the guidelines.

 HTML Output Method

The html output method outputs the instance of the data model as HTML.

For example,

... ]]>

The version parameter indicates the version of the HTML Recommendation to which the serialized result should conform. The default value is 4.0, which specifies that the result should must should be output as HTML conforming to the HTML 4.0 Recommendation . If the processor does not support the version of HTML specified by the version parameter, it must signal a serialization error.

HTML Output Method: Markup for Elements

The html output method should must not output an element differently from the xml output method unless the expanded-QName of the element has a null namespace URI; an element whose expanded-QName has a non-null namespace URI should must be output as XML. If the expanded-QName of the element has a null namespace URI, but the local part of the expanded-QName is not recognized as the name of an HTML element, the element should must be output in the same way as a non-empty, inline element such as span. In particular:

If the result tree contains namespace nodes for namespaces other than the XML namespace, the HTML output method will must represent these namespaces using attributes named xmlns or xmlns:prefix in the same way as the XML output method would represent them when the version parameter is set to 1.0.

If the result tree contains elements or attributes whose names have a non-null namespace URI, the HTML output method will must generate namespace-prefixed QNames for these nodes in the same way as the XML output method would do when the version parameter is set to 1.0.

Where special rules are defined later in this section for serializing specific HTML elements and attributes, these rules are never must not be applied to an element or attribute whose name has a non-null namespace URI. However, the generic rules for the HTML output method that apply to all elements and attributes, for example the rules for escaping special characters in the text and the rules for indentation, must be used also for namespaced elements and attributes.

When serializing an element whose name is not defined in the HTML specification, but that is in the null namespace, the HTML output method should must apply the same rules (for example, indentation rules) as when serializing a span element. The descendants of such an element should must be serialized as if they were descendants of a span element.

When serializing an element whose name is in a non-null namespace, the HTML output method should must apply the same rules (for example, indentation rules) as when serializing a div element. The descendants of such an element should must be serialized as if they were descendants of a div element.

The html output method should must not output an end-tag for empty elements. For HTML 4.0, the empty elements are area, base, basefont, br, col, frame, hr, img, input, isindex, link, meta and param. For example, an element written as <br/> or <br></br> in an XSLT stylesheet should must be output as <br>.

The html output method should must recognize the names of HTML elements regardless of case. For example, elements named br, BR or Br should must all be recognized as the HTML br element and output without an end-tag.

The html output method should must not perform escaping for the content of the script and style elements.

For example, a script element created by an XQuery direct element constructor or an XSLT literal result element, such as:

if (a < b) foo()]]>

or

]]>

should must be output as

if (a < b) foo()]]>

A common requirement is to output a script element as shown in the example below:

document.write ("This won't work") ]]>

This is illegal HTML, for the reasons explained in section B.3.2 of the HTML 4.01 specification. Nevertheless, it is possible to output this fragment, using either of the following constructs:

Firstly, by use of a script element created by an XQuery direct element constructor or an XSLT literal result element:

document.write ("This won't work") ]]>

Secondly, by constructing the markup from ordinary text characters:

document.write ("<em>This won't work</em>") ]]>

As the HTML specification points out, the correct way to write this is to use the escape conventions for the specific scripting language. For JavaScript, it can be written as:

document.write ("<em>This will work<\/em>") ]]>

The HTML 4.01 specification also shows examples of how to write this in various other scripting languages. The escaping must be done manually, it will not be done by the serializer.

 HTML Output Method: Writing Attributes

The html output method must not escape "<" characters occurring in attribute values.

If the indent parameter has the value yes, then the html output method may add or remove whitespace as it outputs the instance of the data model, so long as it does not change how an HTML user agent would render the output.

Unless If the escape-uri-attributes parameter is present and has the value no yes, the html output method should must escape non-ASCII characters in URI attribute values using the method recommended in (section 2.4.1).

This escaping is deliberately confined to non-ASCII characters, because escaping of ASCII characters is not always appropriate, for example when URIs or URI fragments are interpreted locally by the HTML user agent. Even in the case of non-ASCII characters, escaping can sometimes cause problems. More precise control of URI escaping is therefore available by setting escape-uri-attributes to no, and controlling the escaping of URIs by means of the fn:escape-uri function defined in .

The html output method must output boolean attributes (that is attributes with only a single allowed value that is equal to the name of the attribute) in minimized form.

For example, a start-tag created using the following XQuery direct element constructor or XSLT literal result element

<OPTION selected="selected">

must be output as

<OPTION selected>

The html output method should must not escape a & character occurring in an attribute value immediately followed by a { character (see Section B.7.1 of the HTML 4.0 Recommendation).

For example, a start-tag created using the following XQuery direct element constructor or XSLT literal result element

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

should must be output as

<BODY bgcolor='&{randomrbg};'> HTML Output Method: Indentation

If the indent attribute has the value yes, then the html output method may add or remove whitespace as it outputs the result tree, so long as it does not change the way that a conforming HTML user agent would render the output. The default value is yes.

This rule can be satisfied by observing the following constraints:

Whitespace must only be added before or after an element, or adjacent to an existing whitespace character.

Whitespace must not be added or removed adjacent to an inline element. The inline elements are those included in the %inline category of any of the HTML 4.01 DTD's, as well as the INS and DEL elements if they are used as inline elements (i.e., if they do not contain element children).

Whitespace must not be added or removed inside a formatted element, the formatted elements being pre, script, style, and textarea.

Note that the HTML definition of whitespace is different from the XML definition: see section 9.1 of the HTML 4.01 specification.

 HTML Output Method: Writing Character Data

The html output method may output a character using a character entity reference in preference to using a numeric character reference, if an entity is defined for the character in the version of HTML that the output method is using. Entity references and character references should be used only where the character is not present in the selected encoding, or where the visual representation of the character is unclear (as with &nbsp;, for example).

When outputting a sequence of whitespace characters in the instance of the data model, within an element where whitespace is treated normally, (but not in elements such as pre and textarea) the html output method is free to may represent it using any sequence of whitespace that will be treated as whitespace in the same way by an HTML user agent. See section 3.5 of for some additional information on handling of whitespace by an HTML user agent.

Certain characters, specifically the control characters #x7F-#x9F, are legal in XML but not in HTML. It is an error to use the HTML output method when such characters appear in the instance of the data model. The processor may signal the error, but is not required to do so. If it does not signal the error, it may copy the offending characters into the serialized output, creating invalid HTML.

The html output method should must terminate processing instructions with > rather than ?>.

 HTML Output Method: Encoding

The encoding parameter specifies the preferred encoding to be used. Processors are required to support values of UTF-8 and UTF-16. A serialization error occurs if an output encoding other than UTF-8 or UTF-16 is requested and the implementation does not support that encoding. The processor must signal the error.

If there is a HEAD element, then unless and the include-content-type parameter is present and has the value no yes, the html output method must add a META element immediately after the start-tag of the HEAD element specifying the character encoding actually used.

For example,

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

The content type must be set to the value given for the media-type parameter; the default value is text/html.

If the instance of the data model includes a head element that has a meta element child, the processor should replace any content attribute of the meta element, or add such an attribute, with the value as described above, rather than output a new meta element.

It is possible that the instance of the data model will contain a character that cannot be represented in the encoding that the processor is using for output. In this case, if the character occurs in a context where HTML recognizes character references, then the character should must be output as a character entity reference or decimal numeric character reference; otherwise (for example, in a script or style element or in a comment), the processor should must signal a serialization error.

HTML Output Method: Document Type Declaration

If the doctype-public or doctype-system parameters are specified, then the html output method should must output a document type declaration immediately before the first element. The name following <!DOCTYPE should must be HTML or html. If the doctype-public parameter is specified, then the output method should must output PUBLIC followed by the specified public identifier; if the doctype-system parameter is also specified, it should must also output the specified system identifier following the public identifier. If the doctype-system parameter is specified but the doctype-public parameter is not specified, then the output method should must output SYSTEM followed by the specified system identifier.

 HTML Output Method: Unicode Normalization

The normalize-unicode normalization-form parameter is applicable for the html output method. The values NFC and none must be supported by the processor. A serialization error results if the value of the normalization-form parameter specifies a normalization form that is not supported by the processor; the processor must signal the error.

 HTML Output Method: Other Parameters

The media-type parameter is applicable for the html output method.

The use-character-maps parameter is applicable for the xml output method.

The use-character-maps parameter is applicable for the html output method.

 Text Output Method

The text output method outputs the instance of the data model by outputting the string-value of every text node in the instance of the data model in document order without any escaping.

A newline character in the instance of the data model may be output using any character sequence that is conventionally used to represent a line ending in the chosen system environment.

The media-type parameter is applicable for the text output method.

The encoding parameter identifies the encoding that the text output method must use to convert sequences of characters to sequences of bytes. Processors are required to support values of UTF-8 and UTF-16. The default is implementation-defined. A serialization error occurs if the implementation does not support the encoding specified by the encoding parameter. The processor must signal the error. If the instance of the data model contains a character that cannot be represented in the encoding that the processor is using for output, the implementation should must signal a serialization error.

The default encoding for the text output method is implementation-defined.

The normalize-unicode normalization-form parameter is applicable for the text output method. The values NFC and none must be supported by the processor. A serialization error results if the value of the normalization-form parameter specifies a normalization form that is not supported by the processor; the processor must signal the error.

The use-character-maps parameter is applicable for the xml output method.

The use-character-maps parameter is applicable for the text output method.

 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 in the instance of the data model to be substituted by 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.

Character mapping is applied to the characters that actually appear in a text or attribute node in the instance of the data model, 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. If the string cannot be represented using the target encoding, the serializer takes the same action as it would if the offending characters appeared directly in the instance of the data model.

Character mapping is not applied to characters in text nodes whose parent elements are listed in the cdata-section-elements parameter, nor to characters in attribute values that are subject to the 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 and attribute values are replaced by the corresponding string from the use-character-maps parameter.

Using a character map can result in non-well-formed documents if the string contains XML-significant characters. For example, it is possible to create documents containing unmatched start and end tags, references to entities that are not declared, or attributes that contain tags or unescaped quotation marks.

Character mapping is applied to the characters that actually appear in a text or attribute node in the instance of the data model, before any other serialization operations such as escaping or Unicode normalization are applied.

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

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

A serialization error occurs if character mapping causes the output of a string containing a character that cannot be represented in the encoding that the processor is using for output. The processor mustshould signal the error.

 References Normative References World Wide Web Consortium, Character Model for the World Wide Web 1.0, Last Call Working Draft. See http://www.w3.org/TR/2002/WD-charmod-20020430/ World Wide Web Consortium, XQuery 1.0 and XPath 2.0 Data Model. See http://www.w3.org/TR/xpath-datamodel/. World Wide Web Consortium, XQuery 1.0 and XPath 2.0 Functions and Operators. W3C Working Draft. See . World Wide Web Consortium. HTML 4.01 specification. W3C Recommendation. See . Internet Assigned Numbers Authority. Character Sets. See . S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119. See . N. Freed, J. Postel. IANA Charset Registration Procedures. IETF RFC 2278. See . E. Whitehead, M. Murata. XML Media Types. IETF RFC 2376. See . T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource Identifiers (URI): Generic Syntax. IETF RFC 2396. See . M. Baker, P. Stark. The 'application/xhtml+xml' Media Type. IETF RFC 3236. See . Unicode Consortium. Unicode Normalization Forms. Unicode Standard Annex #15. See . World Wide Web Consortium. XHTML 1.0: The Extensible HyperText Markup Language (Second Edition). W3C Recommendation. See . World Wide Web Consortium. XHTML 1.1: Module-Based XHTML. W3C Recommendation. See . World Wide Web Consortium. Extensible Markup Language (XML) 1.0 (Second Edition) W3C Recommendation. See . World Wide Web Consortium. Extensible Markup Language (XML) 1.1 W3C Recommendation. See . World Wide Web Consortium. Namespaces in XML. W3C Recommendation. See . World Wide Web Consortium. XML Schema Part 1: Structures and XML Schema Part 2: Data Types. W3C Recommendation. See and World-Wide Web Consortium, XML Path Language (XPath) 2.0. See http://www.w3.org/TR/xpath20/. World Wide Web Consortium, XQuery 1.0: An XML Query Language. See http://www.w3.org/TR/xquery/. World Wide Web Consortium, XSL Transformations Language (XSLT) Version 2.0. See http://www.w3.org/TR/xslt20/. Non-normative References World Wide Web Consortium, Modularization of XHTML&tm; See http://www.w3.org/TR/xhtml-modularization/.