1.1 Relationship to XLink

XInclude differs from the linking features described in the XML Linking Language [XLink], specifically links with the attribute value show="embed" . Such links provide a media-type independent syntax for indicating that a resource is to be embedded graphically within the display of the document. XLink does not specify a specific processing model, but simply facilitates the detection of links and recognition of associated metadata by a higher level application.

XInclude, on the other hand, specifies a media-type specific (XML into XML) transformation. It defines a specific processing model for merging information sets. XInclude processing occurs at a low level, often by a generic XInclude processor which makes the resulting information set available to higher level applications.

Simple node inclusion as described in this specification differs from transclusion, which preserves contextual information such as style.

1.2 Relationship to XML External Entities

There are a number of differences between XInclude and XML external entities [XML] which make them complimentary technologies.

Processing of external entities (as with the rest of DTDs) occurs at parse time. XInclude operates on information sets and thus is orthogonal to parsing.

Declaration of external entities requires a DTD or internal subset. This places a set of dependencies on inclusion, for instance, the syntax for the DOCTYPE declaration requires that the document element be named - clearly orthogonal to inclusion in many cases. Validating parsers must have a complete content model defined. XInclude is orthogonal to validation and the name of the document element.

External entities provide a level of indirection - the external entity must be declared and named, and separately invoked. XInclude uses direct referencecs. Applications which generate XML output incrementally can benefit from not having to pre-declare inclusions.

The syntax for an internal subset is cumbersome to many authors of simple well-formed XML documents. XInclude syntax is based on familiar XML constructs.

Note also that XInclude together with XPointer [XPointer] can replace certain forms of internal entities, although XInclude syntax is not optimized for this purpose.

1.3 Relationship to Grammar-specific Inclusions

Special purpose inclusion mechanisms have been introduced into specific XML grammars. XInclude provides a generic mechanism for recognizing and processing inclusions, and as such can offer a simpler overall authoring experience, greater performance, and less code redundancy.

3.1 Locating an Inclusion

The existence of an include is asserted by an include element.

When performing inclusions, an XInclude processor identifies an xinclude:include element in the source infoset and acquires the resource specified. The information set for the resource is created and merged with the source infoset. This process is repeated until all xinclude:include elements have been processed. The order in which include elements are processed is not defined by this specification. Intra-document references within include elements must be resolved against the original infoset, instead of resolving them against some intermediate state.

In the following example, the infoset representing something.xml will appear twice.

<x xmlns:xinclude="...">
  <xinclude:include href="something.xml"/>
  <xinclude:include href="#xpointer(x/xinclude:include[1])"/>
</x>

3.2 Acquiring the Resource to be Included

The value of the href attribute on an xinclude:include is combined with the base URI of the xinclude:include element as specified in XML Base [XMLBase]. The resource identified by the full URI reference is acquired and an infoset created, either by parsing the resource as xml, or by converting it into an infoset consisting of a single text information item. This latter behavior allows the inclusion of "working examples" into explanatory text. Which of the two methods for creating an infoset is to be used is determined by the parse attribute, which may take the values "xml", "text", or "cdata".

Note that the character encodings of the including and included resources can be different. This does not affect the resulting infoset, but may need to be taken into account during any subsequent serialization.

Resources that are unavailable for any reason result in an error. Resources that resolve to non-well-formed XML given the parse="xml" option result in an error. Resources that resolve to something other than text when parse="text" or parse="cdata" is specified result in an error.

Any xinclude:include elements in this infoset are recursively processed.

<foo xmlns:x="uri1">
 <xinclude:include href="common.xml#xptr(a/b)"/>
</foo>

<a xmlns:x="uri2">
  <b>
    <x:a/>
  </b>
</a>

<foo xmlns:x="uri1">
  <b xmlns:x="uri2">
    <x:a/>
  </b>
</foo>

3.3 Merging infosets

The acquired infoset is merged with the source infoset to create a new infoset by replacing the information items representing the xinclude:include elements with information items in the acquired infoset. The xinclude:include element, its attributes and any children, are not represented in the result infoset.

The base URI property of the acquired infoset is not changed as result of merging the infoset, so the base URI property remains unchanged after merging.

4.1 Exposing the Base URI

An XInclude processor may expose the base URI of a document, element, or processing instruction information item. This enables applications which resolve URI References to process them correctly. Two examples where this is necessary are XLink, and the xml-stylesheet processing instruction.

4.2 Validation

XML 1.0 validation is not performed on the results of the inclusion, nor on the included elements. The include mechanism introduces the notion of infoset validation. After all inclusions are completed, an include processor will validate the infoset against the original document's DTD if it contains a doctype declaration.

4.3 IDs

IDs and IDREFS intersection with the inclusion mechanism surfaces a few issues with respect to to XML and inclusion infoset validation.

If an attribute declares an ID that has already been declared, processing is the same as if duplicate IDs had been encountered in a single XML document. This condition would be discovered during infoset validation, after all inclusions are performed. For example, processing could be halted and an approprate error surfaced.

ID rewriting is a possiblity for inclusion of documents with nodes containing IDs. The following condition may occur: An including document contains an ID. The inclusion specified is to the subnode of a separate document. The separate document contains the same ID outside the scope of the inclusion, and the inclusion scope contains an IDREF to the ID. It is unclear whether this should be an error condition or not. It is conceivable that authors would design their modularity to use this aspect of IDs. It is also possible that IDs should be re-written to be local to the scope of the document.

This proposal suggests that ID rewriting should not be performed. In the previous use-case, the document will infoset validate if the infoset after inclusion contains an IDREF to an ID that is in the document.

4.4 Relation to other XML standards

The relationship between XInclude and othr XML standards is defined by the concept of a 'XInclude processor'. Such a processor leverages XML 1.0 and XML Namespaces in it's syntax, and uses the XML Infoset to describe a specific processing model. In general, XInclude processing should occur between the generation of an Infoset by a processor, and the consumption of that infoset by a higher-level application, so that the inclusion results are transparent to those applications.

Although XInclude may be implemented as an independent layer, it also may be implemented at a lower level with the same results, but with potentially greater performance.

The relationship between XInclude and DTD or XML Schema validation needs additional exploration (as noted by issues within this document). In particular DTD validation as defined in XML 1.0 does not support validation of the result infoset within this 'layered' strategy.