Serialization Parameters

This page describes the full set of serialization parameters supported by XmlPrime.

This topic contains the following sections.

Overview

The XSLT 2.0 and XQuery 1.0 Serialization (Second Edition) specification describes a large set of serialization parameters which determine the behaviour of serialization. XmlPrime adds some extra implementation-specific parameters which add some new features to the serializer. This document lists all the serialization parameters supported by XmlPrime, and all the values that are supported by these parameters.

As of version 2.2, XmlPrime has support for serialization parameters specified in XSLT and XQuery Serialization 3.0.

Declaring serialization parameters

Serialization parameters can be declared in several ways depending on how serialization is invoked.

Declaring serialization parameters in code

If serialization is being invoked from the API then the serialization parameters are set using the XdmWriterSettingsXdmWriterSettingsXdmWriterSettings class. Each parameter is equivalent to a property on this class, as described below; but the values can also be set by name using the SetParameter (XmlQualifiedName, string)SetParameter (XmlQualifiedName, String)SetParameter (XmlQualifiedName^, String^) and SetParameter (XmlQualifiedName, string, IXmlNamespaceResolver)SetParameter (XmlQualifiedName, String, IXmlNamespaceResolver)SetParameter (XmlQualifiedName^, String^, IXmlNamespaceResolver^) methods. The code snippet below shows two different ways of setting the indent property to yes.

 
XdmWriterSettings serializationSettings = new XdmWriterSettings();

// setting the value directly with a property
settings.Indent = true;

// setting the value by name and value
settings.SetParameter(new XmlQualifiedName("indent"), "yes");
 

The serialization settings may also be read from a serialization parameters document, using the ParameterDocumentParameterDocumentParameterDocument method.

Declaring serialization parameters in XQuery

XQuery serialization parameters can also be set within a query using declare option declarations. These override any serialization settings specified by the XQuerySettings.SerializationSettingsXQuerySettings.SerializationSettingsXQuerySettings::SerializationSettings property. The post-compilation serialization settings are exposed by the XQuery.SerializationSettingsXQuery.SerializationSettingsXQuery::SerializationSettings property.

As of version 2.2, XmlPrime supports the setting of serialization parameters as defined in section 2.2.4 Serialization of XQuery 3.0.

To set XmlPrime-specific serialization parameters, an option declaration with the namespace http://www.xmlprime.com/serialization is treated as a serialization parameter declaration. If the local name of the option corresponds to a standard serialization parameter then the serialization parameter is assumed to be in no namespace; otherwise the parameter is assumed to be in the http://www.xmlprime.com/serialization namespace. QName values are specified as lexical QNames, and are resolved against the in-scope namespaces.

The following example illustrates how to set the indent property to yes using declare option within an XQuery program.

 
              
declare namespace output="http://www.w3.org/2010/xslt-xquery-serialization";
declare option output:indent "yes";
 

Declaring serialization parameters in XSLT

XSLT serialization parameters can also be set within a transformation using xsl:output or xsl:result-document declarations. These override any serialization settings specified by the XsltSettings.SerializationSettingsXsltSettings.SerializationSettingsXsltSettings::SerializationSettings property. The post-compilation serialization settings are exposed by the XsltSettings.SerializationSettingsXsltSettings.SerializationSettingsXsltSettings::SerializationSettings property.

To set XmlPrime-specific serialization parameters, use extension attributes in the namespace http://www.xmlprime.com/serialization on xsl:output or xsl:result-document elements.

The following example illustrates how to set the new-line-chars property to a single linefeed (LF) character. using xsl:output within an XSLT program.

 
            
<xsl:output xmlns:xps="http://www.xmlprime.com/serialization"
            xps:new-line-chars="&#0A;" />
 

Declaring serialization parameters on the command line

If a query is run on the command line with the XQuery.exe tool, then serializationde parameters can be set by adding !parameter=value to the command line. QName values can be specified in Clark notation. The following example shows how to set the indent property to yes, and also shows how to set the (implementation specific) serialization:conformance-level property to document.

 
xquery query.xq !indent=yes !{http://www.xmlprime.com/serialization}conformance-level=document
 

Serialization parameters can also be set from a serialization parameter document as in the following example. For more information about serialization parameter documents, see the Schema for Serialization Parameters in XSLT and XQuery Serialization 3.0.

 
xquery query.xq !parameter-document="serialization.xml"
 

Serialization parameters

The following section lists the full set of serialization settings supported by XmlPrime.

In this section the prefix ser is assumed to be bound to http://www.xmlprime.com/serialization.

Standard serialization parameters

The following parameters are defined in the XSLT 2.0 and XQuery 1.0 Serialization (Second Edition) and XSLT and XQuery Serialization 3.0 specifications. The table below specifies the name of each parameter, the equivalent property on the XdmWriterSettingsXdmWriterSettingsXdmWriterSettings class, the default value of the property, and the supported values that the property can take.

Built in serialization parameters

NameCorresponding propertyDefault valueDescription
byte-order-mark ByteOrderMarkByteOrderMarkByteOrderMark no This can be set to either yes or no. This indicates whether the serialized document should start with a Unicode Byte Order Mark. If this does not apply to the specified encoding, then it is ignored.
cdata-section-elements CDataSectionElementsCDataSectionElementsCDataSectionElements (empty) This is set to a list of qualified element names, separated by a single space. The text content of any element with a name in this list is serialized as a CDATA section. This parameter is ignored in the text and ser:canonical output modes, and used only for elements with non-null namespace in the html output mode.
doctype-public DoctypePublicDoctypePublicDoctypePublic (not set) This specifies the public document type to be serialized in the document type declaration. This parameter is ignored unless doctype-system has been set. This parameter is ignored when method is not set to xml or xhtml. If method is set to xml or xhtml and doctype-public is not a valid public identifier, then a SERE0003 error is raised when serialization is attempted.
doctype-system DoctypeSystemDoctypeSystemDoctypeSystem (not set)

Specifies the system document type to be used in the document type declaration. Setting this property causes a document type declaration to be serialized immediately before the first element. If this property is not set then no document type declaration is serialized. This parameter is ignored when method is set to text or ser:canonical.

If doctype-system is set, the omit-xml-declataration parameter is set to yes, the method parameter is set to xml or xhtml and the version parameter has been set to a value other than 1.0 then a SEPM0009 error is raised if serialization is attempted.

encoding EncodingEncodingEncoding UTF-8

Specifies the encoding to be used when serializing. The following encodings are supported: IBM037, IBM500, IBM1047, IBM273, IBM277, IBM280, IBM284, IBM285, IBM297, IBM871, iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9, iso-8859-13, iso-8859-15, us-ascii, utf-8, utf-16, utf-16BE, utf-16LE, utf-32, utf-32BE, utf-32LE, GB18030, unicodeFFFE and Windows-1252. These values are case-insensitive.

If encoding is set to an unsupported value and the method parameter is not set to ser:canonical then a SESU0007 error is raised if serialization is not attempted.

When serializing to a TextWriterTextWriterTextWriter this parameter is ignored, and the encoding specified by EncodingEncodingEncoding is used instead. This parameter is ignored when method is set to ser:canonical.

escape-uri-attributes EscapeUriAttributesEscapeUriAttributesEscapeUriAttributes yes This can be set to either yes or no. In html and XHTML output methods this setting indicates that all attributes that must take URIs (for example the href attribute on the a tag) will have their values escaped as is performed by the fn:escape-html-uri function. If the method parameter is not set to html or xhtml, this parameter is ignored.
include-content-type IncludeContentTypeIncludeContentTypeIncludeContentType no This can be set to either yes or no. If include-content-type is set to yes, then in html and XHTML output methods, the serializer should add a meta element as the first child of the head element specifying the content type from the media-type parameter, and with the encoding actually used. If the method parameter is not set to html or xhtml, this parameter is ignored.
indent IndentIndentIndent no This can be set to either yes or no. If indent is set to yes, then extra whitespace may be added to the document in order to make it easier to read, in accordance with the rules specific to the current output method. If the method parameter is set to text or ser:canonical, this parameter is ignored.
media-type MediaTypeMediaTypeMediaType (not set)

When the media-type parameter is set, it specifies the media type of the serialized document. When the method parameter is set to html or xhtml, and the include-content-type property is set to yes, then the value of the media-type property is used to specify the media type of the generated content type declaration. The media type may also be used to annotate the serialized data, for example in an HTTP request. The value of the media-type parameter must not contain a charset declaration - instead this should be set by using the encoding property. If the parameter is not specified, then the default media type is used (this is application/xhtml+xml when the method parameter is set to xhtml, text/html when the method parameter is set to html, and text/xml otherwise.

method MethodMethodMethod xml

Specifies the output mode. The supported output modes are the standard output modes (xml, xhtml, html and text) as defined in the specification, along with the implementation specific value ser:canonical. If the value is not a supported method then a SEPM0016 error is thrown if any serialization is attempted.

Setting this parameter to ser:canonical indicates that the serialization process should produce canonical XML.

normalization-form NormalizationFormNormalizationFormNormalizationForm none

Specifies the unicode normalization form. All text content in the serialized document will be normalized with this normalization form. The supported normalization forms are none, NFC, NFD, NFKC, NFKD and fully-normalized as specified in the specification. These values are case-insensitive. If the value is not a supported method and the method parameter is not set to ser:canonical then a SESU0011 error is raised when serialization is attempted. If the method parameter is set to ser:canonical, this parameter is ignored.

omit-xml-declaration OmitXmlDeclarationOmitXmlDeclarationOmitXmlDeclaration no This parameter takes one of the enumerated values yes or no. This parameter indicates whether the xml declaration should be omitted. If the method parameter is not set to html or xhtml, this parameter is ignored.
standalone StandaloneStandaloneStandalone omit

This parameter takes one of the enumerated values yes or no. If standalone is set to yes or no then the XML declaration includes a standalone document declaration with the value specified by this property. If standalone is set to omit then the XML declaration will not include a standalone document declaration. If the method parameter is not set to xml or xhtml then this parameter is ignored. If omit-xml-declaration is set to false, standalone is not set to omit, and the method parameter is set to xml or xhtml then a SEPM0009 error is raised if serialization is attempted.

suppress-indentation SuppressIndentationSuppressIndentationSuppressIndentation (empty) This is set to a list of qualified element names, separated by a single space. Whitespace characters will not be added, elided or replaced in any element with a name in this list. If the method parameter is set to text or ser:canonical, this parameter is ignored.
undeclare-prefixes UndeclarePrefixesUndeclarePrefixesUndeclarePrefixes no

This parameter takes one of the enumerated values yes or no. If undeclare-prefixes is set to yes then if an element is serialized whose parent has namespaces that are not in scope in the element itself, then these namespaces are undeclared. If the method parameter is set to xml or xhtml and the version parameter is set to 1.0 then an SEPM0010 error is raised when serialization is attempted. If the method parameter is not set to xml or xhtml then this parameter is ignored.

version VersionVersionVersion (not set)

Specifies either the XML version (if the method parameter is set to either xml or xhtml), the HTML version (if the method parameter is set to html) or the version of the Canonical XML specification (if method is set to ser:canonical). This parameter is ignored if the method parameter is not set to any of the above values.

If the version is not supported (XML version is not 1.0, HTML version is not 4.0 or 4.01 or the Canonical XML version is not 1.0 then an SESU0013 error is raised if serialization is attempted.

If this parameter is not set then the version is assumed to be 4.01 if the method parameter is set to html, and 1.0 otherwise.

use-character-maps CharacterMappingCharacterMappingCharacterMapping (empty) Specifies a mapping from characters to strings. Character maps allow specific characters that are serialized to be replaced with a specific string of characters. No escaping is applied to the string that is substituted and so this mechanism can be used to introduce arbitrary markup in the serialized output. This parameter can only be set with the CharacterMappingCharacterMappingCharacterMapping property. This parameter is ignored when method is set to ser:canonical.

Implementation-defined parameters

The following parameters are specific to XmlPrime, and allow for further customization of the serialization specification. All the parameters below are in the namespace http://www.xmlprime.com/serialization. The table below specifies the name of each parameter, the equivalent property on the XdmWriterSettingsXdmWriterSettingsXdmWriterSettings class, the default value of the property, and the supported values that the property can take.

Implementation-specific serialization parameters

NameCorresponding propertyDefault valueDescription
ser:character-reference-style CharacterReferenceStyleCharacterReferenceStyleCharacterReferenceStyle hexadecimal This parameter takes one of the enumerated values decimal or hexadecimal. This parameter specifies the style in which character references are encoded. If the method parameter is set to text or ser:canonical, this parameter is ignored.
ser:check-namespaces CheckNamespacesCheckNamespacesCheckNamespaces auto

This parameter takes one of the enumerated values check-absolute, none or auto. If this is set to check-absolute then a SERE0003 error is raised if a namespace declaration is encountered whose namespace URI is not a valid absolute URI. If this is set to none then the check is not performed (even when method is set to ser:canonical).

If check-namespaces is set to auto, then this behaves like check-absolute if method is set to ser:canonical; and like none otherwise.

ser:conformance-level ConformanceLevelConformanceLevelConformanceLevel auto

This parameter takes one of the enumerated values document, fragment or auto. If this is set to document then a SERE0003 error is raised if the serialized document contains top level text nodes, or if the serialized content does not contain a single top level element, even if the other serialization settings allow for this.

If this is set to fragment and method is set to ser:canonical then all nodes are treated as if they are children of a single top level element.

If check-namespaces is set to auto, then this behaves like document if method is set to ser:canonical; and like fragment otherwise.

ser:indentation-characters IndentationCharactersIndentationCharactersIndentationCharacters (two spaces) This property specifies the characters that are used for indentation. If the method parameter is set to text or ser:canonical, or if the indent parameter is not set to yes then this parameter is ignored.
ser:new-line-chars NewLineCharsNewLineCharsNewLineChars Environment.NewLineEnvironment.NewLineEnvironment::NewLine Any newline (&#10;) characters serialized, and any new lines introduced are replaced by the value of this property. If the method parameter is set to ser:canonical then this parameter is ignored.