Copyright © 2025World Wide Web Consortium.W3C®liability,trademark andpermissive document license rules apply.
This section describes the status of this document at the time of its publication. A list of currentW3C publications and the latest revision of this technical report can be found in theW3C technical reports index at https://www.w3.org/TR/.
This document was published by theWeb Applications Working Group as an Editor's Draft.
Publication as an Editor's Draft does not imply endorsement byW3C and its Members.
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 was produced by a group operating under theW3C Patent Policy.W3C maintains apublic list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.
This document is governed by the03 November 2023W3C Process Document.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript. [ECMA-262]
Unless otherwise stated, string comparisons are done in acase-sensitive manner.
If an algorithm calls into another algorithm, any exception that is thrown by the latter (unless it is explicitly caught), must cause the former to terminate, and the exception to be propagated up to its caller.
Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.
If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.
When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. Such an extension specification becomes anapplicable specification for the purposes of conformance requirements in this specification.
A document object model (DOM) is an in-memory representation of various types ofNodes where eachNode is connected in a tree. The [HTML5] and [DOM4] specifications describe DOM and itsNodes is greater detail.
Parsing is the term used for converting a string representation of a DOM into an actual DOM, andSerializing is the term used to transform a DOM back into a string. This specification concerns itself with defining various APIs for both parsing and serializing a DOM.
HTMLDivElement (nodeName:"div")┃┣━ HTMLSpanElement (nodeName:"span")┃ ┃┃ ┗━ Text (data:"some ")┃┗━ HTMLElement (nodeName:"em") ┃ ┗━ Text (data:"text!") And theHTMLDivElement node is stored in a variablemyDiv, then to serializemyDiv's children simplyget (read) theElement'sinnerHTML property (this triggers the serialization):var serializedChildren = myDiv.innerHTML;// serializedChildren has the value:// "<span>some </span><em>text!</em>"To parse new children formyDiv from a string (replacing its existing children), simplyset theinnerHTML property (this triggers parsing of the assigned string):
myDiv.innerHTML ="<span>new</span><em>children!</em>";This specification describes two flavors ofparsing andserializing: HTML and XML (with XHTML being a type of XML). Each follows the rules of its respective markup language. The above example shows HTML parsing and serialization. The specific algorithms for HTML parsing and serializing are defined in the [HTML5] specification. This specification contains the algorithm for XML serializing. The grammar for XML parsing is described in the [XML10] specification.
Round-tripping a DOM means to serialize and then immediately parse the serialized string back into a DOM. Ideally, this process does not result in any data loss with respect to the identity and attributes of theNode in the DOM.Round-tripping is especially tricky for an XML serialization, which must be concerned with preserving theNode's namespace identity in the serialization (wereas namespaces are ignored in HTML).
Element (nodeName:"root")┃┗━ HTMLScriptElement (nodeName:"script") ┃ ┗━ Text (data:"alert('hello world')") An XML serialization must include theHTMLScriptElementNode'snamespace in order to preserve the identity of thescript element, and to allow the serialized string toround-trip through an XML parser. Assuming thatroot is in a variable namedroot:var xmlSerialization =newXMLSerializer().serializeToString(root);// xmlSerialization has the value:// "<root><script xmlns="http://www.w3.org/1999/xhtml">alert('hello world')</script></root>"The termcontext object means the object on which the API being discussed was called.
The following terms are understood to represent their respective namespaces in this specification (and makes it easier to read):
http://www.w3.org/1999/xhtmlhttp://www.w3.org/XML/1998/namespacehttp://www.w3.org/2000/xmlns/The definition ofDOMParser has moved tothe HTML Standard.
The definition ofXMLSerializer has moved tothe HTML Standard.
The definition ofInnerHTML has moved tothe HTML Standard.
Element interfaceThe definition ofouterHTML has moved tothe HTML Standard.
The definition ofinsertAdjacentHTML has moved tothe HTML Standard.
Range interfaceThe definition ofcreateContextualFragment has moved tothe HTML Standard.
The definition offragment parsing algorithm has moved tothe HTML Standard.
The definition offragment serializing algorithm has moved tothe HTML Standard.
AnXML serialization differs from an HTML serialization in the following ways:
namespaceURI is preserved. In some cases this means that an existingprefix, prefix declaration attribute or default namespace declaration attribute might be dropped, substituted or changed. An HTML serialization does not attempt to preserve thenamespaceURI.Otherwise, the algorithm for producing anXML serialization is designed to produce a serialization that is compatible with theHTML parser. For example, elements in theHTML namespace that contain nochild nodes are serialized with an explicit begin and end tag rather than using theempty-element tag syntax.
Per [DOM4],Attr objects do not inherit fromNode, and thus cannot be serialized by theXML serialization algorithm. An attempt to serialize anAttr object will result in an empty string.
To produce anXML serialization of aNodenode given a flagrequire well-formed, run the following steps:
null. Thecontext namespace tracks theXML serialization algorithm's current default namespace. Thecontext namespace is changed when either anElementNode has a default namespace declaration, or the algorithm generates a default namespace declaration for theElementNode to match its own namespace. The algorithm assumes no namespace (null) to start.xml" toprefix map.1. Thegenerated namespace prefix index is used to generate a new unique prefix value when no suitable existing namespace prefix is available to serialize anode'snamespaceURI (or thenamespaceURI of one ofnode's attributes).See thegenerate a prefix algorithm.InvalidStateError"DOMException.Each of the following algorithms forproducing an XML serialization of a DOM node take as input anode to serialize and the following arguments:
TheXML serialization algorithmproduces an XML serialization of an arbitrary DOM nodenode based on thenode's interface type. Each referenced algorithm is to be passed the arguments as they were recieved by the caller and return their result to the caller. Re-throw any exceptions. Ifnode's interface is:
ElementDocumentCommentTextDocumentFragmentDocumentTypeProcessingInstructionAttr objecttrue), and thisnode'slocalName attribute contains the character ":" (U+003A COLON) or does not match the XMLName production, thenthrow an exception; the serialization of thisnode would not be a well-formed element.<" (U+003C LESS-THAN SIGN).false.false.prefix strings as its keys, with correspondingnamespaceURINode values as the map's key values (in this map, thenull namespace is represented by the empty string).This map is local to each element. It is used to ensure there are no conflicting prefixes should a new namespaceprefix attribute need to begenerated. It is also used to enable skipping of duplicate prefix definitions whenwriting an element's attributes: the map allows the algorithm to distinguish between aprefix in thenamespace prefix map that might be locally-defined (to the currentElement) and one that is not.
The above step will updatemap with any found namespace prefix definitions, add the found prefix definitions to thelocal prefixes map and return alocal default namespace value defined by a default namespace attribute if one exists. Otherwise it returnsnull.
namespaceURI attribute.null, then setignore namespace definition attribute totrue.xml:" and the value ofnode'slocalName.localName.Thenode'sprefix if it exists, is dropped.prefix attribute.The above may returnnull if no namespace keyns exists inmap.
xmlns", then run the following steps:prefix "xmlns" will not legally round-trip in a conformingXML parser.null (a namespace prefix is defined which maps tons), then:The following may serialize a differentprefix than theElement's existingprefix if it already had one. However, theretrieving a preferred prefix string algorithm already tried to match the existing prefix if possible.
:" (U+003A COLON), andnode'slocalName.There exists on thisnode or thenode's ancestry a namespace prefix definition that defines thenode's namespace.null (there exists a locally-defined default namespace declaration attribute) and its value is not theXML namespace, then letinherited ns get the value oflocal default namespace unless thelocal default namespace is the empty string in which case let it getnull (thecontext namespace is changed to the declared default, rather than thisnode's own namespace).Any default namespace definitions or namespace prefixes that define theXML namespace are omitted when serializing this node's attributes.
null, then:By this step, there is no namespace or prefix mapping declaration in thisnode (or any parentnode visited by this algorithm) that definesprefix otherwise the step labelledFound a suitable namespace prefix would have been followed. The sub-steps that follow will create a new namespace prefix declaration forprefix and ensure thatprefix does not conflict with an existing namespace prefix declaration of the samelocalName innode'sattribute list.
:" (U+003A COLON), andnode'slocalName.The following serializes a namespace prefix declaration forprefix which was just added to themap.
" (U+0020 SPACE);xmlns:";="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);"" (U+0022 QUOTATION MARK).null (there exists a locally-defined default namespace declaration attribute), then letinherited ns get the value oflocal default namespace unless thelocal default namespace is the empty string in which case let it getnull.null, orlocal default namespace is notnull and its value is not equal tons, then:At this point, the namespace for this node still needs to be serialized, but there's noprefix (orcandidate prefix) availble; the following uses the default namespace declaration to define the namespace--optionally replacing an existing default declaration if present.
true.localName.The new default namespace will be used in the serialization to define thisnode's namespace and act as thecontext namespace for itschildren.
The following serializes the new (or replacement) default namespace definition.
" (U+0020 SPACE);xmlns";="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);"" (U+0022 QUOTATION MARK).localName, let the value ofinherited ns bens, and append the value ofqualified name tomarkup.All of the combinations wherens is not equal toinherited ns are handled above such thatnode will be serialized preserving its originalnamespaceURI.
localName matches any one of the followingvoid elements: "area", "base", "basefont", "bgsound", "br", "col", "embed", "frame", "hr", "img", "input", "keygen", "link", "menuitem", "meta", "param", "source", "track", "wbr"; then append the following tomarkup, in the order listed:" (U+0020 SPACE);/" (U+002F SOLIDUS).true./" (U+002F SOLIDUS) tomarkup and set theskip end tag flag totrue.>" (U+003E GREATER-THAN SIGN) tomarkup.true, then return the value ofmarkup and skip the remaining steps. Thenode is a leaf-node.localName matches the string "template", then this is atemplate element. Append tomarkup the result ofXML serializing a DocumentFragment node given thetemplate element'stemplate contents (aDocumentFragment), providinginherited ns,map,prefix index, and therequire well-formed flag.This allowstemplate content to round-trip , given the rules forparsing XHTML documents.
</" (U+003C LESS-THAN SIGN, U+002F SOLIDUS);>" (U+003E GREATER-THAN SIGN).This following algorithm will update thenamespace prefix map with any found namespace prefix definitions, add the found prefix definitions to thelocal prefixes map, and return alocal default namespace value defined by a default namespace attribute if one exists. Otherwise it returnsnull.
Whenrecording the namespace information for anElementelement, given anamespace prefix mapmap and alocal prefixes map (initially empty), the user agent must run the following steps:
null.attributes, in the order they are specified in theelement'sattribute list:The following conditional steps find namespace prefixes. Only attributes in theXMLNS namespace are considered (e.g., attributes made to look like namespace declarations viasetAttribute("xmlns:pretend-prefix","pretend-namespace") are not included).
namespaceURI value.prefix.null, thenattr is a default namespace declaration. Set thedefault namespace attr value toattr'svalue and stop running these steps, returning toMain to visit the next attribute.null andattr is a namespace prefix definition. Run the following steps:localName.value.XML namespace definitions in prefixes are completely ignored (in order to avoid unnecessary work when there might be prefix conflicts).XML namespaced elements are always handled uniformly by prefixing (and overriding if necessary) the element's localname with the reserved "xml" prefix.
null instead.This step avoids adding duplicate prefix definitions for the same namespace in themap. This has the side-effect of avoiding later serialization of duplicate namespace prefix declarations in any descendant nodes.
null with the empty string if applicable.The empty string is a legitimate return value and is not converted tonull.
Anamespace prefix map is a map that associatesnamespaceURI andnamespace prefix lists, wherenamespaceURI values are the map's unique keys (which can include thenull value representing no namespace), and ordered lists of associatedprefix values are the map's key values. Thenamespace prefix map will be populated by previously seen namespaceURIs and all their previously encountered prefix associations for a given node and its ancestors.
Note: the last seenprefix for a givennamespaceURI is at the end of its respectivelist. The list is searched to find potentially matching prefixes, and if no matches are found for the givennamespaceURI, then the lastprefix in the list is used. Seecopy a namespace prefix map andretrieve a preferred prefix string for additional details.
Tocopy a namespace prefix mapmap means to copy themap's keys into a new emptynamespace prefix map, and to copy each of the values in thenamespace prefix list associated with each keys' value into a newlist which should be associated with the respective key in the new map.
Toretrieve a preferred prefix stringpreferred prefix from thenamespace prefix mapmap given a namespacens, the user agent should:
null value.There will always be at least one prefix value in the list.
To check if a prefix stringprefix isfound in anamespace prefix mapmap given a namespacens, the user agent should:
false.true, otherwise returnfalse.Toadd a prefix stringprefix to thenamespace prefix mapmap given a namespacens, the user agent should:
null.null, then create a newlist withprefix as the only item in thelist, and associate thatlist with a new keyns inmap.The steps inretrieve a preferred prefix string use thelist to track the most recently used (MRU)prefix associated with a given namespace, which will be theprefix at the end of the list. This list may contain duplicates of the sameprefix value seen earlier (and that's OK).
TheXML serialization of the attributes of anElementelement together with anamespace prefix mapmap, agenerated namespace prefix indexprefix index reference, alocal prefixes map, aignore namespace definition attribute flag, and arequire well-formed flag, is the result of the following algorithm:
namespaceURI andlocalName pairs, and is populated as eachattr is processed.This set is used to [optionally] enforce the well-formed constraint that an element cannot have two attributes with the samenamespaceURI andlocalName. This can occur when two otherwise identical attributes on the same element differ only by their prefix values.attributes, in the order they are specified in theelement'sattribute list:true), and thelocalname set contains a tuple whose values match those of a new tuple consisting ofattr'snamespaceURI attribute andlocalName attribute, thenthrow an exception; the serialization of thisattr would fail to produce a well-formed element serialization.namespaceURI attribute andlocalName attribute, and add it to thelocalname set.namespaceURI value.null.null, then run these sub-steps:prefix value.value is theXML namespace;TheXML namespace cannot be redeclared and surviveround-tripping (unless it defines the prefix "xml"). To avoid this problem, this algorithm always prefixes elements in theXML namespace with "xml" and drops any related definitions as seen in the above condition.
prefix isnull and theignore namespace definition attribute flag istrue (theElement's default namespace attribute should be skipped);prefix is notnull and eitherlocalName is not a key contained in thelocal prefixes map, orlocalName is present in thelocal prefixes map but the value of the key does not matchattr'svaluelocalName (as theprefix to find) isfound in thenamespace prefix map given the namespace consisting of theattr'svalue (the current namespace prefix definition was exactly defined previously--on an ancestor element not the current element whose attributes are being processed).true), and the value ofattr'svalue attribute matches theXMLNS namespace, then throw an exception; the serialization of this attribute would produce invalid XML because theXMLNS namespace is reserved and cannot be applied as an element's namespace via XML parsing.DOM APIs do allow creation of elements in theXMLNS namespace but with strict qualifications.
true), and the value ofattr'svalue attribute is the empty string, then throw an exception; namespace prefix declarations cannot be used to undeclare a namespace (use a default namespace declaration instead).prefix matches the string "xmlns", then letcandidate prefix be the string "xmlns"." (U+0020 SPACE);xmlns:";="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);"" (U+0022 QUOTATION MARK)." (U+0020 SPACE) toresult.null, then append toresult the concatenation ofcandidate prefix with ":" (U+003A COLON).true), and thisattr'slocalName attribute contains the character ":" (U+003A COLON) or does not match the XMLName production or equals "xmlns" andattribute namespace isnull, thenthrow an exception; the serialization of thisattr would not be a well-formed attribute.localName;="" (U+003D EQUALS SIGN, U+0022 QUOTATION MARK);value attribute and therequire well-formed flag as input;"" (U+0022 QUOTATION MARK).Whenserializing an attribute value given anattribute value andrequire well-formed flag, the user agent must run the following steps:
true), andattribute value contains characters that are not matched by the XMLChar production, thenthrow an exception; the serialization of thisattribute value would fail to produce a well-formed element serialization.null, then return the empty string.&" with "&""" with """<" with "<">" with ">"This matches behavior present in browsers, and goes above and beyond the grammar requirement in the XML specification'sAttValue production by also replacing ">" characters.
Togenerate a prefix given anamespace prefix mapmap, a stringnew namespace, and a reference to agenerated namespace prefix indexprefix index, the user agent must run the following steps:
ns" and the current numerical value ofprefix index.If therequire well-formed flag is set (its value istrue), and thisnode has nodocumentElement (thedocumentElement attribute's value isnull), thenthrow an exception; the serialization of thisnode would not be a well-formed document.
Otherwise, run the following steps:
This will serialize any number ofProcessingInstruction andComment nodes both before and after theDocument'sdocumentElement node, including at most oneDocumentType node. (Text nodes are not allowed as children of theDocument.)
If therequire well-formed flag is set (its value istrue), andnode'sdata contains characters that are not matched by the XMLChar production or contains "--" (two adjacent U+002D HYPHEN-MINUS characters) or that ends with a "-" (U+002D HYPHEN-MINUS) character, thenthrow an exception; the serialization of thisnode'sdata would not be well-formed.
Otherwise, return the concatenation of "<!--",node'sdata, and "-->".
true), andnode'sdata contains characters that are not matched by the XMLChar production, thenthrow an exception; the serialization of thisnode'sdata would not be well-formed.data.&" inmarkup by "&".<" inmarkup by "<".>" inmarkup by ">".true and thenode'spublicId attribute contains characters that are not matched by the XMLPubidChar production, thenthrow an exception; the serialization of thisnode would not be a well-formed document type declaration.true and thenode'ssystemId attribute contains characters that are not matched by the XMLChar production or that contains both a """ (U+0022 QUOTATION MARK) and a "'" (U+0027 APOSTROPHE), thenthrow an exception; the serialization of thisnode would not be a well-formed document type declaration.<!DOCTYPE" tomarkup." (U+0020 SPACE) tomarkup.name attribute tomarkup. For anode belonging to anHTML document, the value will be all lowercase.publicId is not the empty string then append the following, in the order listed, tomarkup:" (U+0020 SPACE);PUBLIC";" (U+0020 SPACE);"" (U+0022 QUOTATION MARK);publicId attribute;"" (U+0022 QUOTATION MARK).systemId is not the empty string and thenode'spublicId is set to the empty string, then append the following, in the order listed, tomarkup:" (U+0020 SPACE);SYSTEM".systemId is not the empty string then append the following, in the order listed, tomarkup:" (U+0020 SPACE);"" (U+0022 QUOTATION MARK);systemId attribute;"" (U+0022 QUOTATION MARK).>" (U+003E GREATER-THAN SIGN) tomarkup.true), andnode'starget contains a ":" (U+003A COLON) character or is anASCII case-insensitive match for the string "xml", thenthrow an exception; the serialization of thisnode'starget would not be well-formed.true), andnode'sdata contains characters that are not matched by the XMLChar production or contains the string "?>" (U+003F QUESTION MARK, U+003E GREATER-THAN SIGN), thenthrow an exception; the serialization of thisnode'sdata would not be well-formed.AttValue,Char,EmptyElemTag,Name andPubidChar productionsWe acknowledge with gratitude the original work of Ms2ger and others at the WHATWG, who created and maintained the original DOM Parsing and Serialization Living Standard upon which this specification is based.
Thanks to C. Scott Ananian, Victor Costan, Aryeh Gregor, Anne van Kesteren, Arkadiusz Michalski, Simon Pieters, Henri Sivonen, Josh Soref and Boris Zbarsky, for their useful comments.
Special thanks to Ian Hickson for first defining theinnerHTML andouterHTML attributes, and theinsertAdjacentHTML method in [HTML5] and his useful comments.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: