├── .github
└── workflows
│ └── build-validate-publish.yml
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── CR-DOM-Parsing-20140624.html
├── LC1_comments.htm
├── LC2_comments.html
├── LCWD-DOM-Parsing-20131205.html
├── LCWD-DOM-Parsing-20140501.html
├── LICENSE.md
├── README.md
├── W3CTRMANIFEST
├── WD-DOM-Parsing-20120920.html
├── implementationReport.html
├── index.html
├── respecConfig-CR.js
├── respecConfig-FPWD.js
├── respecConfig-LCWD.js
├── respecConfig.js
└── w3c.json
/.github/workflows/build-validate-publish.yml:
--------------------------------------------------------------------------------
1 | name: CI
2 | on:
3 | pull_request: {}
4 | push:
5 | branches: [main]
6 |
7 | jobs:
8 | main:
9 | name: Build, Validate, and Publish
10 | runs-on: ubuntu-latest
11 | steps:
12 | - uses: actions/checkout@v2
13 | - uses: w3c/spec-prod@v2
14 | with:
15 | GH_PAGES_BRANCH: gh-pages
16 | VALIDATE_MARKUP: false
17 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Code of Conduct
2 |
3 | All documentation, code and communication under this repository are covered by the [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/).
4 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Web Platform Working Group
2 |
3 | Contributions to this repository are intended to become part of Recommendation-track documents governed by the
4 | [W3C Patent Policy](http://www.w3.org/Consortium/Patent-Policy-20040205/) and
5 | [Software and Document License](http://www.w3.org/Consortium/Legal/copyright-software). To make substantive contributions to specifications, you must either participate
6 | in the relevant W3C Working Group or make a non-member patent licensing commitment.
7 |
8 | If you are not the sole contributor to a contribution (pull request), please identify all
9 | contributors in the pull request comment.
10 |
11 | To add a contributor (other than yourself, that's automatic), mark them one per line as follows:
12 |
13 | ```
14 | +@github_username
15 | ```
16 |
17 | If you added a contributor by mistake, you can remove them in a comment with:
18 |
19 | ```
20 | -@github_username
21 | ```
22 |
23 | If you are making a pull request on behalf of someone else but you had no part in designing the
24 | feature, you can remove yourself with the above syntax.
25 |
26 | # Tests
27 |
28 | For normative changes, a corresponding
29 | [web-platform-tests](https://github.com/web-platform-tests/wpt) PR is highly appreciated. Typically,
30 | both PRs will be merged at the same time. Note that a test change that contradicts the spec should
31 | not be merged before the corresponding spec change. If testing is not practical, please explain why
32 | and if appropriate [file an issue](https://github.com/web-platform-tests/wpt/issues/new) to follow
33 | up later. Add the `type:untestable` or `type:missing-coverage` label as appropriate.
34 |
--------------------------------------------------------------------------------
/LC1_comments.htm:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | Disposition of Comments - DOM Parsing and Serialization
5 |
12 |
13 |
14 |
Disposition of Comments
15 |
DOM Parsing and Serialization
16 |
17 |
This document tracks the comments received from the
18 | DOM Parsing and Serialization
19 | specification's Last Call period ending 07 January 2014.
20 |
21 |
The following comments were recieved during the Last Call period:
22 |
23 |
The setAttributeNS allows the creation of attributes that have a non-null namespace URI, but
79 | no prefix. This case does not seem to be handled by the current algorithm in the spec, but should
80 | be.
81 |
82 | Accepted. Fixing this required a substantial update to the algorithm, but the update now includes proper
83 | handling of attributes in non-null namespaces including automatic prefix generation if necessary (which
84 | also applies to elements in certain situations).
85 | [First draft diff,
86 | Followup draft diff,
87 | Polish pass diff]
88 |
This document tracks the comments received from the
18 | DOM Parsing and Serialization
19 | specification's 2nd Last Call period ending 22 May 2014.
20 |
21 |
The following comments were received during the Last Call period:
22 |
23 |
24 |
25 |
Comment Number
26 |
Comment
27 |
Editor's Response
28 |
Commentor's Response
29 |
30 |
31 |
1
32 |
33 |
Reported by Arkadiusz Michalski (crimsteam@gmail.com):
34 |
This specification defines various APIs for programmatic access to
493 | HTML and generic XML parsers by web applications for use in parsing
494 | and serializing DOM nodes
495 |
Status of This Document
496 |
497 |
498 |
499 |
500 | This section describes the status of this document at the time of its publication. Other
501 | documents may supersede this document. A list of current W3C publications and the latest revision
502 | of this technical report can be found in the W3C technical reports
503 | index at http://www.w3.org/TR/.
504 |
505 |
506 |
507 | Comments submitted in regard to this document should have their subject line prefixed with the string [DOM-Parsing] to help facilitate tracking on the
508 | www-dom mailing list.
509 |
510 |
511 |
512 | This document was published by the Web Applications Working Group as a First Public Working Draft.
513 |
514 | This document is intended to become a W3C Recommendation.
515 |
516 | If you wish to make comments regarding this document, please send them to
517 | www-dom@w3.org
518 | (subscribe,
519 | archives).
520 |
521 |
522 | All feedback is welcome.
523 |
524 |
525 |
526 | Publication as a Working Draft does not imply endorsement by the W3C Membership.
527 | This is a draft document and may be updated, replaced or obsoleted by other documents at
528 | any time. It is inappropriate to cite this document as other than work in progress.
529 |
530 |
531 |
532 |
533 |
534 | This document was produced by a group operating under the
535 | 5 February 2004 W3C Patent Policy.
536 |
537 |
538 |
539 |
540 | W3C maintains a public list of any patent disclosures
541 |
542 | made in connection with the deliverables of the group; that page also includes instructions for
543 | disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains
544 | Essential Claim(s) must disclose the
545 | information in accordance with section
546 | 6 of the W3C Patent Policy.
547 |
548 |
549 |
Various issues are listed in the rest of the document.
563 |
564 |
Issue 1
This specification currently requires using the XML
565 | Parser for some APIs, when in an XML document. It is unclear whether
566 | consensus can be found for this approach.
567 |
568 |
569 |
1. Conformance
570 |
571 | As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
572 | and notes in this specification are non-normative. Everything else in this specification is
573 | normative.
574 |
575 |
576 | The key words must, must not, required, should, should not, recommended, may,
577 | and optional in this specification are to be interpreted as described in [RFC2119].
578 |
579 |
580 |
Requirements phrased in the imperative as part of algorithms
581 | (such as "strip any leading space characters" or "return false and
582 | terminate these steps") are to be interpreted with the meaning of the
583 | key word ("must", "should", "may", etc) used in introducing the
584 | algorithm.
585 |
586 |
Conformance requirements phrased as algorithms or specific steps
587 | may be implemented in any manner, so long as the end result is
588 | equivalent. (In particular, the algorithms defined in this
589 | specification are intended to be easy to follow, and not intended to
590 | be performant.)
591 |
592 |
User agents may impose
593 | implementation-specific limits on otherwise unconstrained inputs,
594 | e.g. to prevent denial of service attacks, to guard against running
595 | out of memory, or to work around platform-specific limitations.
596 |
597 |
When a method or an attribute is said to call another method or
598 | attribute, the user agent must invoke its internal API for that
599 | attribute or method so that e.g. the author can't change the behavior
600 | by overriding attributes or methods with custom properties or functions
601 | in ECMAScript.
602 |
603 |
Unless otherwise stated, string comparisons are done in a
604 | case-sensitive manner.
605 |
606 |
If an algorithm calls into another algorithm, any exception that is
607 | thrown by the latter (unless it is explicitly caught), must cause the
608 | former to terminate, and the exception to be propagated up to
609 | its caller.
610 |
611 |
612 |
1.1 Dependencies
613 |
614 |
The IDL fragments in this specification must be interpreted as
615 | required for conforming IDL fragments, as described in the Web IDL
616 | specification. [WEBIDL]
617 |
618 |
Some of the terms used in this specification are defined in
619 | [DOM4], [HTML5], and [XML10].
620 |
621 |
622 |
623 |
1.2 Extensibility
624 |
625 |
Vendor-specific proprietary extensions to this specification are
626 | strongly discouraged. Authors must not use such extensions, as
627 | doing so reduces interoperability and fragments the user base,
628 | allowing only users of specific user agents to access the content in
629 | question.
630 |
631 |
If vendor-specific extensions are needed, the members should be
632 | prefixed by vendor-specific strings to prevent clashes with future
633 | versions of this specification. Extensions must be defined so that
634 | the use of extensions neither contradicts nor causes the
635 | non-conformance of functionality defined in the specification.
636 |
637 |
When vendor-neutral extensions to this specification are needed,
638 | either this specification can be updated accordingly, or an
639 | extension specification can be written that overrides the
640 | requirements in this specification. When someone applying this
641 | specification to their activities decides that they will recognise
642 | the requirements of such an extension specification, it becomes an
643 | applicable
644 | specification for the purposes of conformance requirements in
645 | this specification.
646 |
647 |
648 |
649 |
650 |
651 |
2. Terminology
652 |
653 |
The term context object means the object on which the method or
654 | attribute being discussed was called.
655 |
If data doesn't match the
807 | CData production, throw a
808 | DOMException
809 | with name InvalidStateError and terminate the entire algorithm.
810 |
811 |
Let markup be the concatenation of
812 | "<![CDATA[", data, and
813 | "]]>".
814 |
815 |
The
884 | parseFromString(str, type)
885 | method must run these steps, depending on type:
886 |
887 |
888 |
"text/html"
889 |
890 |
Parse str with an
891 | HTML parser, and return the newly
892 | created document.
893 |
894 |
The scripting flag must be set to
895 | "disabled".
896 |
897 |
Note
meta elements are not
898 | taken into account for the encoding used, as a Unicode stream is passed into
899 | the parser.
900 |
901 |
Note
script elements get marked
902 | unexecutable and the contents of noscript
903 | get parsed as markup.
904 |
905 |
"text/xml"
906 |
"application/xml"
907 |
"application/xhtml+xml"
908 |
"image/svg+xml"
909 |
910 |
911 |
Parse str with a namespace-enabled
912 | XML parser.
913 |
914 |
If the previous step didn't return an error, return the newly
915 | created document
916 | and terminate these steps.
917 |
918 |
Let document be a newly-created
919 | XMLDocument.
920 |
921 |
922 |
Let root be a new
923 | Element, with its
924 | local name
925 | set to "parsererror" and its
926 | namespace
927 | set to
928 | "http://www.mozilla.org/newlayout/xml/parsererror.xml".
929 |
930 |
At this point user agents may
931 | append nodes
932 | to root, for example to describe the nature of the
933 | error.
934 |
935 |
The innerHTML IDL
1006 | attribute represents the markup of the
1007 | Element's contents.
1008 |
1009 |
1010 |
1028 |
1029 |
element . innerHTML [ = value ]
1030 |
1031 |
Returns a fragment of HTML or XML that represents the element's
1032 | contents.
1033 |
1034 |
Can be set, to replace the contents of the element with nodes
1035 | parsed from the given string.
1036 |
1037 |
In the case of an XML document,
1038 | will throw a
1039 | DOMException with name InvalidStateError
1040 | if the Element cannot be serialized
1041 | to XML, and a
1042 | DOMException with name SyntaxError
1043 | if the given string is not well-formed.
1044 |
On setting, these steps must be run:
1060 |
1061 |
1062 |
Let fragment be the result of invoking the
1063 | fragment parsing algorithm with
1064 | the new value as markup, and the
1065 | context object as the context element.
1066 |
1067 |
The outerHTML IDL
1072 | attribute represents the markup of the
1073 | Element and its contents.
1074 |
1075 |
1076 |
element . outerHTML [ = value ]
1077 |
1078 |
Returns a fragment of HTML or XML that represents the element and its
1079 | contents.
1080 |
1081 |
Can be set, to replace the element with nodes parsed from the given
1082 | string.
1083 |
1084 |
In the case of an XML document,
1085 | will throw a
1086 | DOMException with name InvalidStateError
1087 | if the element cannot be serialized to XML, and a
1088 | DOMException with name SyntaxError
1089 | if the given string is not well-formed.
1090 |
1091 |
Throws a
1092 | DOMException with name NoModificationAllowedError
1093 | if the parent of the element is the
1094 | Document node.
1095 |
If parent is null, terminate these steps. There would be no
1118 | way to obtain a reference to the nodes created even if the remaining steps
1119 | were run.
1120 |
1121 |
If parent is a
1122 | Document, throw a
1123 | DOMException with name NoModificationAllowedError
1124 | exception and terminate these steps.
1125 |
1126 |
If parent is a
1127 | DocumentFragment, let
1128 | parent be a new
1129 | Element with
1130 |
1131 |
Let fragment be the result of invoking the
1144 | fragment parsing algorithm with
1145 | the new value as markup, and parent as
1146 | the context element.
1147 |
1148 |
element . insertAdjacentHTML(position, text)
1156 |
1157 |
1158 |
Parses the given string text as HTML or XML and inserts
1159 | the resulting nodes into the tree in the position given by the
1160 | position argument, as follows:
1161 |
1162 |
1163 |
"beforebegin"
1164 |
Before the element itself.
1165 |
1166 |
"afterbegin"
1167 |
Just inside the element, before its first child.
1168 |
1169 |
"beforeend"
1170 |
Just inside the element, after its last child.
1171 |
1172 |
"afterend"
1173 |
After the element itself.
1174 |
1175 |
1176 |
Throws a TypeError exception if the position argument
1177 | has an invalid value.
1178 |
1179 |
In XML documents,
1180 | throws a
1181 | DOMException with name SyntaxError
1182 | if the given string is not well-formed.
1183 |
1184 |
Throws a
1185 | DOMException with name NoModificationAllowedError
1186 | if the given position isn't possible (e.g. inserting elements
1187 | after the root element of a Document).
1188 |
1189 |
1190 |
The
1191 | insertAdjacentHTML(position, text)
1192 | method must run these steps:
1193 |
1194 |
1195 |
Use the first matching item from this list:
1196 |
1197 |
1198 |
If position is an
1199 | ASCII case-insensitive match for
1200 | the string "beforebegin"
1201 |
1202 |
If position is an
1203 | ASCII case-insensitive match for
1204 | the string "afterend"
1205 |
1206 |
If context is null or a
1211 | document, throw
1212 | a
1213 | DOMException with name NoModificationAllowedError
1214 | and terminate these steps.
1215 |
1216 |
If position is an
1217 | ASCII case-insensitive match for
1218 | the string "afterbegin"
1219 |
1220 |
If position is an
1221 | ASCII case-insensitive match for
1222 | the string "beforeend"
1223 |
1224 |
Let fragment be the result of invoking the
1261 | fragment parsing algorithm with text as
1262 | markup, and parent as the context element.
1263 |
1264 |
Use the first matching item from this list:
1265 |
1266 |
1267 |
If position is an
1268 | ASCII case-insensitive match for
1269 | the string "beforebegin"
1270 |
1271 |
Controls whether, in XML, this node is serialized as a CDATA section.
1316 |
1317 |
1318 |
Text nodes have an additional
1319 | associated flag, the serialize as CDATA flag.
1320 |
1321 |
The
1322 | serializeAsCDATA
1323 | attribute must return true if the context object has its
1324 | serialize as CDATA flag set, or false otherwise.
1325 |
1326 |
Setting the serializeAsCDATA
1327 | attribute must, if the new value is true, set the
1328 | context object's serialize as CDATA flag, or unset
1329 | it otherwise.
1330 |
fragment = range . createContextualFragment(fragment)
1341 |
Returns a DocumentFragment, created
1342 | from the markup string given.
1343 |
1344 |
1345 |
The
1346 | createContextualFragment(fragment)
1347 | method must run these steps:
1348 |
1349 |
1350 |
If the context object's
1351 | detached flag
1352 | is set, throw a
1353 | DOMException with name InvalidStateError
1354 | and terminate these steps.
1355 |
1356 |
Let fragment node be the result of invoking the
1412 | fragment parsing algorithm with fragment as
1413 | markup, and element as the context element.
1414 |
1415 |
Unmark all scripts in fragment node as "already started".
1416 |
1417 |
Thanks to Ms2ger for maintaining the initial drafts of this specification.
1425 |
1426 |
Thanks to Anne van Kesteren, Aryeh Gregor, Henri Sivonen, Simon Pieters and timeless
1427 | for their useful comments.
1428 |
1429 |
Special thanks to Ian Hickson for defining the
1430 | innerHTML and
1431 | outerHTML attributes, and the
1432 | insertAdjacentHTML() method in
1433 | [HTML5] and his useful comments.
1434 |
DOM Parsing and Serialization Implementation Report
7 |
Last updated: 2014-05-29
8 |
It will be several months before the TestSuite is complete and there are at least two implementations that pass each test case. Stay tuned.
--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | DOM Parsing and Serialization
5 |
39 |
40 |
41 |
42 |
43 |
44 |
45 | This specification defines APIs for the parsing and serializing of HTML and XML-based DOM nodes
46 | for web applications.
47 |
48 |
49 |
50 |
51 |
52 |
Candidate Recommendation Exit Criteria
53 |
54 | This specification will not advance to Proposed Recommendation before the spec's
55 | test suite is completed and two or more independent
56 | implementations pass each test, although no single implementation must pass each test. We expect
57 | to meet this criteria no sooner than 24 October 2014. The group will also create an
58 | Implementation
59 | Report.
60 |
61 |
62 |
63 |
The IDL fragments in this specification must be interpreted as required for conforming IDL
64 | fragments, as described in the Web IDL specification. [[!WEBIDL]]
65 |
66 |
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space
67 | characters" or "return false and terminate these steps") are to be interpreted with the meaning of
68 | the key word ("must", "should", "may", etc) used in introducing the algorithm.
69 |
70 |
Conformance requirements phrased as algorithms or specific steps may be implemented in any
71 | manner, so long as the end result is equivalent. (In particular, the algorithms defined in this
72 | specification are intended to be easy to follow, and not intended to be performant.)
73 |
74 |
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g.
75 | to prevent denial of service attacks, to guard against running out of memory, or to work around
76 | platform-specific limitations.
77 |
78 |
When a method or an attribute is said to call another method or attribute, the user agent must
79 | invoke its internal API for that attribute or method so that e.g. the author can't change the
80 | behavior by overriding attributes or methods with custom properties or functions in ECMAScript.
81 | [[ECMA-262]]
82 |
83 |
Unless otherwise stated, string comparisons are done in a case-sensitive manner.
84 |
85 |
If an algorithm calls into another algorithm, any exception that is thrown by the latter
86 | (unless it is explicitly caught), must cause the former to terminate, and the exception to be
87 | propagated up to its caller.
88 |
89 |
90 |
91 |
Extensibility
92 |
93 |
Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors
94 | must not use such extensions, as doing so reduces interoperability and fragments the user base,
95 | allowing only users of specific user agents to access the content in question.
96 |
97 |
If vendor-specific extensions are needed, the members should be prefixed by vendor-specific
98 | strings to prevent clashes with future versions of this specification. Extensions must be defined
99 | so that the use of extensions neither contradicts nor causes the non-conformance of functionality
100 | defined in the specification.
101 |
102 |
When vendor-neutral extensions to this specification are needed, either this specification can
103 | be updated accordingly, or an extension specification can be written that overrides the
104 | requirements in this specification. Such an extension specification becomes an
105 | applicable specification for the purposes of conformance requirements in this
106 | specification.
107 |
108 |
109 |
110 |
Introduction
111 |
112 |
A document object model (DOM) is an in-memory representation of various types of Nodes
113 | where each Node is connected in a tree. The [[HTML5]] and [[DOM4]] specifications describe
114 | DOM and its Nodes is greater detail.
115 |
116 |
Parsing is the term used for converting a string representation of a DOM into an
117 | actual DOM, and Serializing is the term used to transform a DOM back into a string.
118 | This specification concerns itself with defining various APIs for both parsing and serializing a
119 | DOM.
120 |
121 |
For example: the innerHTML API is a common way to both
122 | parse and serialize a DOM (it does both). If a particular Node, has the following in-memory
123 | DOM:
124 |
135 | And the HTMLDivElement node is stored in a variable myDiv,
136 | then to serialize myDiv's children simply get (read) the
137 | Element's innerHTML property (this triggers the serialization):
138 |
139 |
140 | var serializedChildren = myDiv.innerHTML;
141 | // serializedChildren has the value:
142 | // "<span>some </span><em>text!</em>"
143 |
144 |
145 |
To parse new children for myDiv from a string (replacing its existing
146 | children), simply set the innerHTML property (this triggers
147 | parsing of the assigned string):
148 |
149 |
This specification describes two flavors of parsing and serializing: HTML and
155 | XML (with XHTML being a type of XML). Each follows the rules of its respective markup language.
156 | The above example shows HTML parsing and serialization. The specific algorithms for HTML parsing
157 | and serializing are defined in the [[HTML5]] specification. This specification contains the
158 | algorithm for XML serializing. The grammar for XML parsing is described in the [[XML10]]
159 | specification.
160 |
161 |
Round-tripping a DOM means to serialize and then immediately parse the serialized
162 | string back into a DOM. Ideally, this process does not result in any data loss with respect to the
163 | identity and attributes of the Node in the DOM.
164 |
165 | Round-tripping is especially tricky for an XML serialization, which must be concerned with
166 | preserving the Node's namespace identity in the serialization (wereas namespaces are
167 | ignored in HTML).
168 |
169 |
Consider the XML serialization of the following in-memory DOM:
170 |
177 | An XML serialization must include the HTMLScriptElementNode's
178 | namespace in order to preserve the identity of the
179 | script element, and to allow the serialized string to
180 | round-trip through an XML parser. Assuming that root
181 | is in a variable named root:
182 |
183 |
184 | var xmlSerialization = new XMLSerializer().serializeToString(root);
185 | // xmlSerialization has the value:
186 | // "<root><script xmlns="http://www.w3.org/1999/xhtml">alert('hello world')</script></root>"
187 |
188 |
189 |
190 |
The term context object means the object on which the API being discussed was
191 | called.
192 |
193 |
The following terms are understood to represent their respective namespaces in this
194 | specification (and makes it easier to read):
195 |
196 |
197 |
The HTML namespace is http://www.w3.org/1999/xhtml
198 |
The XML namespace is http://www.w3.org/XML/1998/namespace
199 |
The XMLNS namespace is http://www.w3.org/2000/xmlns/
200 |
The definition of fragment parsing algorithm has moved to the HTML Standard.
299 |
300 |
301 |
302 |
Serializing
303 |
304 |
305 |
306 |
The definition of fragment serializing algorithm has moved to the HTML Standard.
307 |
308 |
XML Serialization
309 |
310 |
An XML serialization differs from an HTML serialization in the following ways:
311 |
312 |
313 |
Elements and attributes will always be serialized such
314 | that their namespaceURI is preserved. In some cases this means that an existing
315 | prefix, prefix declaration attribute or default namespace declaration attribute
316 | might be dropped, substituted or changed. An HTML serialization does not attempt to
317 | preserve the namespaceURI.
318 |
319 |
Otherwise, the algorithm for producing an XML serialization is designed to produce a
325 | serialization that is compatible with the HTML parser. For example, elements in the
326 | HTML namespace that contain no child nodes are serialized with an explicit begin and end
327 | tag rather than using the empty-element tag syntax.
328 |
329 |
Per [[DOM4]], Attr objects do not inherit from Node, and
330 | thus cannot be serialized by the XML serialization algorithm. An attempt to serialize an
331 | Attr object will result in an empty string.
332 |
333 |
To produce an XML serialization of a Nodenode given
334 | a flag require well-formed, run the following steps:
335 |
336 |
337 |
Let namespace be a context namespace with value null.
338 | The context namespace tracks the XML serialization algorithm's current default
339 | namespace. The context namespace is changed when either an ElementNode has
340 | a default namespace declaration, or the algorithm generates a default namespace declaration for
341 | the ElementNode to match its own namespace. The algorithm assumes no namespace
342 | (null) to start.
343 |
344 |
Let prefix index be a generated namespace prefix index with value
350 | 1. The generated namespace prefix index is used to generate a new unique
351 | prefix value when no suitable existing namespace prefix is available to serialize a
352 | node's namespaceURI (or the namespaceURI of one of
353 | node's attributes). See the generate a prefix algorithm.
354 |
355 |
356 |
Each of the following algorithms for producing an XML serialization of a DOM node
366 | take as input a node to serialize and the following arguments:
367 |
The XML serialization algorithm
375 | produces an XML serialization of an arbitrary DOM node
376 | node based on the node's interface type. Each referenced algorithm is
377 | to be passed the arguments as they were recieved by the caller and return their result to the
378 | caller. Re-throw any exceptions. If node's interface is:
If the require well-formed flag is set (its value is true),
422 | and this node's localName attribute contains the character
423 | ":" (U+003A COLON) or does not match the XML Name production, then
424 | throw an exception; the serialization of this node would not be a well-formed
425 | element.
426 |
427 |
Let markup be the string "<" (U+003C LESS-THAN SIGN).
428 |
429 |
Let qualified name be an empty string.
430 |
431 |
Let skip end tag be a boolean flag with value false.
432 |
433 |
Let ignore namespace definition attribute be a boolean flag with value
434 | false.
435 |
436 |
Let local prefixes map be an empty map. The map has unique Node
440 | prefix strings as its keys, with corresponding namespaceURI
441 | Node values as the map's key values (in this map, the null namespace is
442 | represented by the empty string).
443 |
444 |
This map is local to each element. It is used to ensure there are no conflicting
445 | prefixes should a new namespace prefix attribute need to be
446 | generated. It is also used to enable skipping of duplicate
447 | prefix definitions when
448 | writing an element's attributes: the map
449 | allows the algorithm to distinguish between a prefix in the
450 | namespace prefix map that might be locally-defined (to the current Element) and
451 | one that is not.
The above step will update map with any found namespace prefix
458 | definitions, add the found prefix definitions to the local prefixes map and
459 | return a local default namespace value defined by a default namespace attribute if one
460 | exists. Otherwise it returns null.
461 |
462 |
Let inherited ns be a copy of namespace.
463 |
464 |
Let ns be the value of node's
465 | namespaceURI attribute.
466 |
467 |
If ns is the XML namespace, then append to
473 | qualified name the concatenation of the string "xml:" and the
474 | value of node's localName.
475 |
476 |
Otherwise, append to qualified name the value of node's
477 | localName. The node's
478 | prefix if it exists, is dropped.
479 |
480 |
Otherwise, inherited ns is not equal to ns (the node's
484 | own namespace is different from the context namespace of its parent). Run these sub-steps:
485 |
490 |
491 |
Let prefix be the value of node's
492 | prefix attribute.
493 |
494 |
The above may return null if no namespace key ns exists
499 | in map.
500 |
501 |
If the value of prefix matches "xmlns", then run the following
502 | steps:
503 |
504 |
If the require well-formed flag is set, then throw an error. An
505 | Element with prefix "xmlns"
506 | will not legally round-trip in a conforming XML parser.
507 |
508 |
Let candidate prefix be the value of prefix.
509 |
510 |
513 |
Found a suitable namespace prefix: if candidate prefix is not
514 | null (a namespace prefix is defined which maps to ns), then:
515 |
516 |
The following may serialize a different
517 | prefix than the Element's existing
518 | prefix if it already had one. However, the
519 | retrieving a preferred prefix string algorithm already tried to match the existing
520 | prefix if possible.
521 |
522 |
523 |
Append to qualified name the concatenation of
524 | candidate prefix, ":" (U+003A COLON), and node's
525 | localName. There exists on this node or the
526 | node's ancestry a namespace prefix definition that defines the node's
527 | namespace.
528 |
529 |
If the local default namespace is not null (there exists
530 | a locally-defined default namespace declaration attribute) and its value is not the
531 | XML namespace, then let inherited ns get the value of
532 | local default namespace unless the
533 | local default namespace is the empty string in which case let it get
534 | null (the context namespace is changed to the declared default, rather
535 | than this node's own namespace).
536 |
537 |
Any default namespace definitions or namespace prefixes that define the
538 | XML namespace are omitted when serializing this node's attributes.
Otherwise, if prefix is not null, then:
544 |
545 |
By this step, there is no namespace or prefix mapping declaration in this
546 | node (or any parent node visited by this algorithm) that defines
547 | prefix otherwise the step labelled Found a suitable namespace prefix would
548 | have been followed. The sub-steps that follow will create a new namespace prefix declaration
549 | for prefix and ensure that prefix does not conflict with an existing
550 | namespace prefix declaration of the same localName in node's
551 | attribute list.
At this point, the namespace for this node still needs to be serialized, but
597 | there's no prefix (or candidate prefix) availble; the following uses
598 | the default namespace declaration to define the namespace--optionally replacing an existing
599 | default declaration if present.
The new default namespace will be used in the serialization to define this
611 | node's namespace and act as the context namespace for its
612 | children.
613 |
614 |
Append the value of qualified name to markup.
615 |
616 |
Append the following to markup, in the order listed:
617 |
618 |
The following serializes the new (or replacement) default namespace
619 | definition.
All of the combinations where ns is not equal to
642 | inherited ns are handled above such that node will be serialized
643 | preserving its original namespaceURI.
If ns is the HTML namespace, and the node's list of
653 | children is empty, and the node's localName matches any
654 | one of the following void elements:
655 | "area",
656 | "base",
657 | "basefont",
658 | "bgsound",
659 | "br",
660 | "col",
661 | "embed",
662 | "frame",
663 | "hr",
664 | "img",
665 | "input",
666 | "keygen",
667 | "link",
668 | "menuitem",
669 | "meta",
670 | "param",
671 | "source",
672 | "track",
673 | "wbr";
674 | then append the following to markup, in the order listed:
675 |
676 |
"" (U+0020 SPACE);
677 |
678 |
"/" (U+002F SOLIDUS).
679 |
680 | and set the skip end tag flag to true.
681 |
682 |
If ns is not the HTML namespace, and the node's list of
683 | children is empty, then append "/" (U+002F SOLIDUS) to markup
684 | and set the skip end tag flag to true.
685 |
686 |
This following algorithm will update the namespace prefix map with any found namespace
722 | prefix definitions, add the found prefix definitions to the local prefixes map,
723 | and return a local default namespace value defined by a default namespace attribute if one
724 | exists. Otherwise it returns null.
725 |
726 |
When recording the namespace information for an Element
727 | element, given a namespace prefix mapmap and a
728 | local prefixes map (initially empty), the user agent must run the following
729 | steps:
730 |
731 |
732 |
Let default namespace attr value be null.
733 |
734 |
Main: For each attributeattr in element's
735 | attributes, in the order they are specified in the element's
736 | attribute list:
737 |
738 |
The following conditional steps find namespace prefixes. Only attributes
739 | in the XMLNS namespace are considered (e.g., attributes made to look like namespace
740 | declarations via setAttribute("xmlns:pretend-prefix",
741 | "pretend-namespace") are not included).
742 |
743 |
744 |
Let attribute namespace be the value of attr's
745 | namespaceURI value.
746 |
747 |
Let attribute prefix be the value of attr's
748 | prefix.
749 |
750 |
If the attribute namespace is the XMLNS namespace, then:
751 |
752 |
If attribute prefix is null, then attr is a default
753 | namespace declaration. Set the default namespace attr value to attr's
754 | value and stop running these steps, returning to Main to visit
755 | the next attribute.
756 |
757 |
Otherwise, the attribute prefix is not null and attr
758 | is a namespace prefix definition. Run the following steps:
759 |
760 |
Let prefix definition be the value of attr's
761 | localName.
762 |
763 |
Let namespace definition be the value of attr's
764 | value.
765 |
766 |
If namespace definition is the XML namespace, then stop running
767 | these steps, and return to Main to visit the next attribute.
768 |
769 |
XML namespace definitions in prefixes are completely ignored (in
770 | order to avoid unnecessary work when there might be prefix conflicts).
771 | XML namespaced elements are always handled uniformly by prefixing (and overriding
772 | if necessary) the element's localname with the reserved "xml" prefix.
773 |
774 |
If namespace definition is the empty string (the declarative form of
775 | having no namespace), then let namespace definition be null
776 | instead.
777 |
778 |
If prefix definition is found in map given the namespace
779 | namespace definition, then stop running these steps, and return to Main
780 | to visit the next attribute.
781 |
782 |
This step avoids adding duplicate prefix definitions for the same namespace
783 | in the map. This has the side-effect of avoiding later serialization of
784 | duplicate namespace prefix declarations in any descendant nodes.
785 |
786 |
Add the prefix prefix definition to map given namespace
787 | namespace definition.
788 |
789 |
Add the value of prefix definition as a new key to the
790 | local prefixes map, with the namespace definition as the
791 | key's value replacing the value of null with the empty string if applicable.
792 |
793 |
794 |
795 |
Return the value of default namespace attr value.
796 |
797 |
The empty string is a legitimate return value and is not converted to
798 | null.
799 |
800 |
801 |
802 |
803 |
The Namespace Prefix Map
804 |
805 |
A namespace prefix map is a map that associates namespaceURI and
806 | namespace prefix lists, where namespaceURI values are the
807 | map's unique keys (which can include the null value representing no namespace), and
808 | ordered lists of associated prefix values are the map's key values. The
809 | namespace prefix map will be populated by previously seen namespaceURIs and all their
810 | previously encountered prefix associations for a given node and its ancestors.
811 |
812 |
Note: the last seen prefix for a given
813 | namespaceURI is at the end of its respective list. The list is searched to
814 | find potentially matching prefixes, and if no matches are found for the given
815 | namespaceURI, then the last prefix in the list is used. See
816 | copy a namespace prefix map and retrieve a preferred prefix string for additional
817 | details.
818 |
819 |
To copy a namespace prefix map map means to copy the map's
820 | keys into a new empty namespace prefix map, and to copy each of the values in the
821 | namespace prefix list associated with each keys' value into a new
822 | list which should be associated with the respective key in the new map.
823 |
824 |
To retrieve a preferred prefix string
825 | preferred prefix from the namespace prefix mapmap given a namespace
826 | ns, the user agent should:
827 |
828 |
829 |
Let candidates list be the result of retrieving a list from map
830 | where there exists a key in map that matches the value of ns or if there
831 | is no such key, then stop running these steps, and return the null value.
832 |
833 |
Otherwise, for each prefix value prefix in candidates list, iterating
834 | from beginning to end:
835 |
836 |
There will always be at least one prefix value in the list.
837 |
838 |
839 |
If prefix matches preferred prefix, then stop running these steps
840 | and return prefix.
841 |
842 |
If prefix is the last item in the candidates list, then stop running
843 | these steps and return prefix.
844 |
845 |
846 |
847 |
To check if a prefix string prefix is found in a
848 | namespace prefix mapmap given a namespace ns, the user agent should:
849 |
850 |
851 |
Let candidates list be the result of retrieving a list from map
852 | where there exists a key in map that matches the value of ns or if there
853 | is no such key, then stop running these steps, and return false.
854 |
855 |
If the value of prefix occurs at least once in candidates list, return
856 | true, otherwise return false.
857 |
858 |
859 |
To add a prefix string prefix to the namespace prefix map
860 | map given a namespace ns, the user agent should:
861 |
862 |
863 |
Let candidates list be the result of retrieving a list from map
864 | where there exists a key in map that matches the value of ns or if there
865 | is no such key, then let candidates list be null.
866 |
867 |
If candidates list is null, then create a new list with
868 | prefix as the only item in the list, and associate that list with a new
869 | key ns in map.
870 |
871 |
Otherwise, append prefix to the end of candidates list.
872 |
873 |
The steps in retrieve a preferred prefix string use the list to
874 | track the most recently used (MRU) prefix associated with a given namespace, which
875 | will be the prefix at the end of the list. This list may contain duplicates of the
876 | same prefix value seen earlier (and that's OK).
Let localname set be a new empty namespace localname set. This
893 | localname set will contain tuples of unique attribute
894 | namespaceURI and localName pairs, and is populated as
895 | each attr is processed. This set is used to [optionally] enforce
896 | the well-formed constraint that an element cannot have two attributes with the same
897 | namespaceURI and localName. This can occur when two
898 | otherwise identical attributes on the same element differ only by their prefix values.
899 |
900 |
Loop: For each attributeattr in element's
901 | attributes, in the order they are specified in the element's
902 | attribute list:
903 |
904 |
If the require well-formed flag is set (its value is true), and the
905 | localname set contains a tuple whose values match those of a new tuple consisting
906 | of attr's namespaceURI attribute and
907 | localName attribute, then throw an exception; the serialization of
908 | this attr would fail to produce a well-formed element serialization.
909 |
910 |
Create a new tuple consisting of attr's namespaceURI
911 | attribute and localName attribute, and add it to the
912 | localname set.
913 |
914 |
Let attribute namespace be the value of attr's
915 | namespaceURI value.
916 |
917 |
918 |
Let candidate prefix be null.
919 |
920 |
If attribute namespace is not null, then run these sub-steps:
921 |
922 |
Let candidate prefix be the result of
923 | retrieving a preferred prefix string from map given namespace
924 | attribute namespace with preferred prefix being attr's
925 | prefix value.
926 |
927 |
If the value of attribute namespace is the XMLNS namespace, then run
928 | these steps:
929 |
930 |
If any of the following are true, then stop running these steps and goto Loop
931 | to visit the next attribute:
932 |
The XML namespace cannot be redeclared and survive
936 | round-tripping (unless it defines the prefix "xml"). To avoid this
937 | problem, this algorithm always prefixes elements in the XML namespace with
938 | "xml" and drops any related definitions as seen in the above condition.
the attr's localName is
950 | present in the local prefixes map but the value of the key does not match
951 | attr's value
952 |
953 | and furthermore that the attr's
954 | localName (as the prefix to
955 | find) is found in the namespace prefix map given the namespace consisting
956 | of the attr's value (the current namespace prefix
957 | definition was exactly defined previously--on an ancestor element not the current
958 | element whose attributes are being processed).
959 |
960 |
961 |
If the require well-formed flag is set (its value is true), and
962 | the value of attr's value attribute matches the
963 | XMLNS namespace, then throw an exception; the serialization of this attribute would
964 | produce invalid XML because the XMLNS namespace is reserved and cannot be applied
965 | as an element's namespace via XML parsing.
966 |
967 |
DOM APIs do allow creation of elements in the XMLNS namespace but
968 | with strict qualifications.
969 |
970 |
If the require well-formed flag is set (its value is true), and
971 | the value of attr's value attribute is the empty string,
972 | then throw an exception; namespace prefix declarations cannot be used to undeclare a
973 | namespace (use a default namespace declaration instead).
974 |
975 |
the attr's prefix matches the string
976 | "xmlns", then let candidate prefix be the string
977 | "xmlns".
978 |
979 |
980 |
Otherwise, the attribute namespace in not the XMLNS namespace. Run
981 | these steps:
982 |
983 |
Let candidate prefix be the result of generating a prefix providing
984 | map, attribute namespace, and prefix index as input.
985 |
986 |
Append the following to result, in the order listed:
987 |
988 |
Append a "" (U+0020 SPACE) to result.
1005 |
1006 |
If candidate prefix is not null, then append to result
1007 | the concatenation of candidate prefix with ":" (U+003A COLON).
1008 |
1009 |
If the require well-formed flag is set (its value is true), and this
1010 | attr's localName attribute contains the character
1011 | ":" (U+003A COLON) or does not match the XML Name production or equals
1012 | "xmlns" and attribute namespace is null, then
1013 | throw an exception; the serialization of this attr would not be a
1014 | well-formed attribute.
1015 |
1016 |
Append the following strings to result, in the order listed:
1017 |
1018 |
When serializing an attribute value given an attribute value and
1032 | require well-formed flag, the user agent must run the following steps:
1033 |
1034 |
1035 |
If the require well-formed flag is set (its value is true), and
1036 | attribute value contains characters that are not matched by the XML Char
1037 | production, then throw an exception; the serialization of this attribute value
1038 | would fail to produce a well-formed element serialization.
1039 |
1040 |
If attribute value is null, then return the empty string.
1041 |
1042 |
Otherwise, attribute value is a string. Return the value of
1043 | attribute value, first replacing any occurrences of the following:
1044 |
1045 |
"&" with "&"
1046 |
1047 |
""" with """
1048 |
1049 |
"<" with "<"
1050 |
1051 |
">" with ">"
1052 |
1053 |
This matches behavior present in browsers, and goes above and beyond the grammar
1054 | requirement in the XML specification's AttValue production by also replacing
1055 | ">" characters.
1056 |
1057 |
1058 |
1059 |
1060 |
Generating namespace prefixes
1061 |
1062 |
To generate a prefix given a
1063 | namespace prefix mapmap, a string new namespace, and a reference to
1064 | a generated namespace prefix indexprefix index, the user agent must run the
1065 | following steps:
1066 |
1067 |
Let generated prefix be the concatenation of the string "ns" and the
1068 | current numerical value of prefix index.
1069 |
1070 |
Let the value of prefix index be incremented by one.
1071 |
1072 |
Add to map the generated prefix given the
1073 | new namespace namespace.
1074 |
1075 |
If the require well-formed flag is set (its value is true), and this
1088 | node has no documentElement (the
1089 | documentElement attribute's value is null), then
1090 | throw an exception; the serialization of this node would not be a well-formed
1091 | document.
1092 |
1093 |
Otherwise, run the following steps:
1094 |
1095 |
Let serialized document be an empty string.
1096 |
1097 |
For each childchild of node, in tree order, run the
1098 | XML serialization algorithm on the child passing along the provided arguments,
1099 | and append the result to serialized document.
1100 |
1101 |
If the require well-formed flag is set (its value is true), and
1117 | node's data contains characters that are not matched by the XML
1118 | Char production or contains "--" (two adjacent U+002D HYPHEN-MINUS
1119 | characters) or that ends with a "-" (U+002D HYPHEN-MINUS) character, then
1120 | throw an exception; the serialization of this node's data
1121 | would not be well-formed.
1122 |
1123 |
Otherwise, return the concatenation of "<!--", node's
1124 | data, and "-->".
1125 |
1126 |
If the require well-formed flag is set (its value is true), and
1152 | node's data contains characters that are not matched by the XML
1153 | Char production, then throw an exception; the serialization of this
1154 | node's data would not be well-formed.
1155 |
1156 |
Let markup be the value of node's data.
1157 |
1158 |
Replace any occurrences of "&" in markup by
1159 | "&".
1160 |
1161 |
Replace any occurrences of "<" in markup by
1162 | "<".
1163 |
1164 |
Replace any occurrences of ">" in markup by
1165 | ">".
1166 |
1167 |
If the require well-formed flag is true and the node's
1197 | publicId attribute contains characters that are not matched by the XML
1198 | PubidChar production, then throw an exception; the serialization of this
1199 | node would not be a well-formed document type declaration.
1200 |
1201 |
If the require well-formed flag is true and the node's
1202 | systemId attribute contains characters that are not matched by the XML
1203 | Char production or that contains both a """ (U+0022 QUOTATION MARK) and a
1204 | "'" (U+0027 APOSTROPHE), then throw an exception; the serialization of this
1205 | node would not be a well-formed document type declaration.
1206 |
1207 |
Let markup be an empty string.
1208 |
1209 |
Append the string "<!DOCTYPE" to markup.
1210 |
1211 |
Append "" (U+0020 SPACE) to markup.
1212 |
1213 |
Append the value of the node's name
1214 | attribute to markup. For a node belonging to an HTML document, the
1215 | value will be all lowercase.
1216 |
1217 |
If the node's publicId is not the empty string then append
1218 | the following, in the order listed, to markup:
1219 |
1220 |
"" (U+0020 SPACE);
1221 |
1222 |
The string "PUBLIC";
1223 |
1224 |
"" (U+0020 SPACE);
1225 |
1226 |
""" (U+0022 QUOTATION MARK);
1227 |
1228 |
The value of the node's publicId attribute;
1229 |
1230 |
""" (U+0022 QUOTATION MARK).
1231 |
1232 |
1233 |
If the node's systemId is not the empty string and the
1234 | node's publicId is set to the empty string, then append the
1235 | following, in the order listed, to markup:
1236 |
1237 |
"" (U+0020 SPACE);
1238 |
1239 |
The string "SYSTEM".
1240 |
1241 |
1242 |
If the node's systemId is not the empty string then append
1243 | the following, in the order listed, to markup:
1244 |
1245 |
"" (U+0020 SPACE);
1246 |
1247 |
""" (U+0022 QUOTATION MARK);
1248 |
1249 |
The value of the node's systemId attribute;
1250 |
1251 |
If the require well-formed flag is set (its value is true), and
1286 | node's target contains a ":" (U+003A COLON)
1287 | character or is an ASCII case-insensitive match for the string "xml", then
1288 | throw an exception; the serialization of this node's
1289 | target would not be well-formed.
1290 |
1291 |
If the require well-formed flag is set (its value is true), and
1292 | node's data contains characters that are not matched by the XML
1293 | Char production or contains the string "?>" (U+003F QUESTION MARK,
1294 | U+003E GREATER-THAN SIGN), then throw an exception; the serialization of this
1295 | node's data would not be well-formed.
1296 |
1297 |
Let markup be the concatenation of the following, in the order listed:
1298 |
1299 |
1442 |
1443 | The following is an informative summary of the changes since the last publication of this
1444 | specification. A complete revision history of the Editor's Drafts of this specification can be
1445 | found at the
1446 | W3C Github Repository and older
1447 | revisions at the
1448 | W3C Mercurial server.
1449 |
1450 |
1451 |
2016-06 WD - Editorial restructuring of the document; monolithic XML serialization algorithm
1452 | factored into sections. Dependencies clarified. XML Serialization algorithm updated to get
1453 | closer to interoperable browser behavior.
1454 |
1455 |
We acknowledge with gratitude the original work of Ms2ger and others at the WHATWG, who created
1464 | and maintained the original DOM Parsing and Serialization Living Standard upon which this
1465 | specification is based.
1466 |
1467 |
Thanks to
1468 | C. Scott Ananian,
1469 | Victor Costan,
1470 | Aryeh Gregor,
1471 | Anne van Kesteren,
1472 | Arkadiusz Michalski,
1473 | Simon Pieters,
1474 | Henri Sivonen,
1475 | Josh Soref
1476 | and Boris Zbarsky,
1477 | for their useful comments.
1478 |
1479 |
Special thanks to Ian Hickson for first defining the innerHTML and outerHTML
1480 | attributes, and the insertAdjacentHTML method in [[HTML5]] and his useful comments.
1481 |