Root and Document

Various

There is confusion between the top level (document) element (which is an element node) with the root node of the document (which is not)

The root node is basically the node representing the document itself, whereas the document element is the element node representing the element that has all other elements within the document as children.

In a match="/" template, the context node (from which relative paths are resolved) is the root node, *not* the document element.

See Section 5.1(Root Node) of the XPath Recommendation

remember that match="/" doesn't match the root ELEMENT, but the root NODE.

The XML 1.0 Recommendation says "There is exactly one element, called the root, or document element...".

Luckily, the difference between this and the 'root node' in the XPath data model is one of the first things we have to learn if we want our stylesheets to work as expected :)

> the root NODE [...] is the abstract thing which contains everything in
> the document (including the prolog e.g.)

It doesn't contain the prolog, at least not in the current data model. It should just be thought of as "the node that's one level above the document element".

Various.(Sept 2000)

Kay Michael

> The "root node" in XPath is not an element, and it does not 
> have attributes.
> It is not the same as what the XML spec calls the "root, or document
> element"; rather it is the parent of this element, the 
> equivalent of what
> DOM calls the Document node.
> 
> You are not the only one confused by this inconsistency of terminology
> between different W3C standards.

The separation of concepts is essential, because the root node can have other children besides the document element, e.g. comments and processing instructions; in fact in a result tree fragment it can also have text nodes and multiple element children. The unnecessary confusion is the inconsistent terminology between the DOM, XML, and XPath specs.

David Carlisle

Also the xpath tree model works with trees that need not have a single top level document node at all (xsl variables, rtf-node set coercions, etc)

Andrew

Given that the confusion about the "root" of an XML document has featured recently in discussion on the list I thought it might be useful to list members if I were to try and identify the profusion ... and confusion ... of terminology used in W3C documents.

The following represents my understanding. If I have misunderstood any part of this then I would welcome correction.

The following terms are used for the ROOT of the document (of which the "element root" or "root element" is a child) i.e. these are all different terms used for the same thing in W3C documents, as I understand it.

XML 1.0 - "document entity" (Section 4.8). The terms "root node" and "document root" do not occur in the XML 1.0 Recommendation.

Joe English notes

I think [4.8 "Document Entity"] is using the term "entity" in the SGML sense: that is, it's an abstract storage location.

In this sense, the "document entity" is not part of the Infoset; rather, it is the thing which is fed to a parser in order to *produce* an infoset.

In addition XML 1.0 confuses the issue by using the term "document entity" to, apparently, refer to both the root of the tree (Section 4.8) and also the whole serialised document.

Joe again adds I think it only refers to the serialized document. Not the _whole_ serialized document though, since parts of it may be included via entity references. (and wryly)You know, this was all much easier to understand when everybody just called everything "tags" :-)

Andrew Again.

XML 1.0 further confuses the issue by using the term "root" (with no qualifier) to refer to the "document element", a child of the "document entity".

DOM 1.0 - "root node" - makes a reference to XML 1.0 where the term "root node" is not used (Appendix B)

DOM 1.0 - "Document interface" roughly corresponds to the root node The term "document root" does not occur in either DOM 1 Recommendation or DOM 2 Candidate Recommendation.

XSLT - "root node" (Section 3.1) XSLT - "document root" (Section 5.2)

XPath - "root node" (Section 5.1) XPath - "document root" (Section 2)

XPointer (CR) - introduces the term of "root location" (Section 5.3.3)

SVG (CR) - "root object" (Section 5.10) The term "root" is used in an unqualified way to refer to what I take to be the "element root" <svg> (e.g. Section 19.2.2).

Thus, for this foundational concept of the "root" of an XML document we find multiple terms being, apparently, used for the same thing and certain terms being used for more than one thing.

I cannot guarantee that I have identified every distinct term used for this foundational concept. There is certainly cause for concern about this inconsistent use of terminology within and between W3C documents.

It is unsurprising that there is significant confusion about what constitutes the "root" of an XML document.

Further confusion is introduced in the 27th March 2000 Working Draft of the Extensible Stylesheet Language (XSL) specification where the term "root node" is introduced in a way which is NOT the "root node" as used above (in XPath and XSLT) but is actually the "root element" or "element root". See, for example, the reference to the <fo:root> element in Section 6.4.1.

I would firmly suggest that the W3C needs to give some attention to this problem and introduce some consistency in terminology between W3C documents.

Robert DuCharme

An XML document can be represented as various kinds of trees, which serve different purposes, and any tree has a root that serves an important role in the use of that tree. There is no single concept of an XML document "root" that serves all purposes; the meaning of "root" depends on the type of tree representation of the XML document being discussed.

When switching back and forth between XML-related specs, the difference in the types of trees being discussed can be confusing. I don't understand them all, but I do know the XML 1.0 spec pretty well, and it's much more internally consistent than you make it out to be.

The XML 1.0 Rec says that documents have a physical structure and a logical structure. The document entity is the root of the physical structure. It's the entity (on most operating systems, a file) that the parser reads in first, looking for references to additional external entities to read in. The root element is the root of the logical structure; it's the element that contains all the other elements--the document element. The logical structure doesn't care about the physical structure, and the physical structure only cares about logical structure if each component of the physical structure (each entity) wants to qualify as a well-formed entity.

>XML 1.0 - "document entity" (Section 4.8). The terms "root node" and 
>"document root" do not occur in the XML 1.0 Recommendation.

The DOM came after the XML spec, so the term "node" doesn't appear in the Rec except for a reference in Appendix E to a classic computer science work's description of finite state algorithms. The XML Rec never set out to define things in terms of nodes. Representations of XML documents that serve certain purposes, like XPath and the DOM, later used the concept of a tree of nodes to describe their representations.

>In addition XML 1.0 confuses the issue by using the term "document entity" 
>to, apparently, refer to both the root of the tree (Section 4.8) and also
the 
>whole serialised document.

The XML 1.0 Rec never mentions serialization either. Section 4.8 clearly states that the document entity is the root of the *entity* tree (i.e. the physical structure). Nowhere does the Rec imply that the document entity is the whole document; a document entity can easily have references to other entities that act as components of the document without being part of the document entity.

>XML 1.0 further confuses the issue by using the term "root" (with no 
>qualifier) to refer to the "document element", a child of the "document 
>entity".

The XML 1.0 spec *never* refers to the document element as a child of the document entity. This confuses the physical and logical structure of an XML document. (In XSLT, a document element node is a child of the source tree node, but this is unrelated. Entities in general are meaningless to XSLT because the XML parser that passes an input document to an XSLT processor resolves all entities as it builds the source tree that XSLT actually works on.)

Outside of the XML Rec, the XPath Rec says that "XPath models an XML document as a tree of nodes." This is the model that XSLT uses, and while the DOM also talks in terms of trees of nodes, a DOM tree is different.

I'm not claiming that it's all very well-organized. Otherwise, there wouldn't have been a need for the Infoset document, and Paul Prescod's talk of groves wouldn't sound so useful. There is plenty of potential for confusion, but if you remember that different tree representations of a document (each with their own root) serve different purposes, it's a big help in keeping better track of what's what.

From 2 in XML rec "Each XML document has both a logical and a physical structure. Physically, the document is composed of units called entities. An entity may refer to other entities to cause their inclusion in the document. A document begins in a 'root' or 'document entity'."

That first sentence is the explanation about the two structures. Yes, it's terse, I can only respond to complaints that it's too terse with a crass commercial plug (see http://www.snee.com/bob/xmlann/). The second and third sentence go on about the physical structure. I mentioned in my last post that the physical structure doesn't care about the logical structure except to specify how an entity qualifies as being well-formed; that's what 2.1 is about. Item 2 in the second list ("There is exactly one element...") is talking about logical structure, because it's talking about elements.

An XML parser must read in a document entity and resolves external entity references by locating and reading in referenced external entities. If document entity A refers to external entities B and C, and B refers to D and E, and C refers to F and G, the parser must open each of those files and read them off the disk into its memory. That's what they mean by physical. If you sketch out the relationship between these entities, that's the physical tree they're talking about.

If I declare an entity like this,

  <!ENTITY foo SYSTEM "bar.xml">

the entity's name is foo. The filename bar.xml is not the entity's name, but its system identifier. A document entity may have a filename (the more generic term "system identifier" is used because it all still works on operating systems that don't use the concept of a "file") but as an entity, it has no entity name. (And remember, a document entity doesn't have to even have a filename or other system identifier--it might be handed to the XML parser in memory from a database manager or from a perl script via a pipe.)

"Root element" already has a specific meaning: the root of a tree representing a document's logical structure. "Document root" already has a vague meaning, and will continue to do so. Documents don't really have roots, anyway--tree representations of them do, and the presence of different tree representations is what makes the concept of "document root" so vague. We can't retroactively make this vague term mean something more specific.

>With respect to the XPath date model, these two are
>the "document root node" and the "root element node".

Calling the XPath tree's root the "document root" doesn't distinguish it from the roots of the DOM, element, or entity trees, all of which represent a document and have a root.

Section 5 of the XPath Rec says "XPath operates on an XML document as a tree. This section describes how XPath models an XML document as a tree...The relationship of this model to the XML Information Set [XML Infoset] is described in [Appendix B XML Information Set Mapping]." This Appendix B is the kind of effort toward clearing up the confusion that I described in an earlier post.

Section 3 of the XSLT spec says "The data model used by XSLT is the same as that used by XPath with the additions described in this section."

So, while I can't find any W3C use of the term "XPath tree root" or even "XPath tree" (there are other uses of the latter on the Web) it does seem to make the most sense when discussing XPath and XSLT data model issues.

Wendell Piez

You've been caught by one of the few terminological gotchas of XSLT/XPath.

XPath posits a "root node" to be the parent of the root element of the document, which we try to call the "document element" in order to alleviate exactly this confusion. So the "root node" is not what you think it is (that element you've named "root").

The XPath model finds it convenient to have this root node for several reasons:

* Since as children it can have not only the document element, but also comments and PIs that are siblings of that element, the latter have a place in the model. (If the root were that element, we'd need a way to have siblings without a parent.)

* Since the document element is now the child of something, it can be matched by the expressions "*" (short for child::*, that is any child element) or "root" (for child::root -- this likewise has to be someone's child for it to match).

... and perhaps others that elude me at the moment.

In any case, this is the kind of thing you can learn in a formal exposition of XPath.

So while match="/" matches the root node, match="/*" is short for match="/child::*", which matches the document element (the only element child of the root), no matter what it's named. The actual root is referred to by the XPath "/", but has no name as such (which accounts for the behavior of your stylesheet).

Michael Kay

Yes, it's an odd omission. As a path expression, you can write (/)[X], but not /[X] - this is true both in 1.0 and 2.0. XSLT doesn't allow parentheses within a pattern, so you can't use this construct in a pattern.

However, there's a workaround in 2.0: you can write document-node()[X], either as an XPath expression or as a pattern.

Michael Kay

The top of the tree is a root node (1.0 terminology) or document node (2.0). This is what "/" refers to. It's not an element: it's the parent of the outermost element (and any comments and processing instructions that precede or follow the outermost element). The root node has no name.

The outermost element can be obtained using /*, and its name is name(/*).

Andrew Welch

top-level elements are those things that are child nodes of xsl:stylesheet|xsl:transform W3C

In an XML document there is a root element and a root node. The root node is the level above the root element. Its not too bad to think about when you can distinguish between an element (something between angle brackets) and a node (say a text node or attribute node). XML is a tree, so it should really have a root.

Googling around though, shows "top-level element" refers to both the single root element of an xml document (in error messages), and the top-level child elements in xslt.... One must be wrong.