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 DTDs

XInclude defines no relationship to DTD validation. XInclude describes an infoset-to-infoset transformation and not a change in XML 1.0 parsing behavior. XInclude does not define a mechanism for DTD validation of the resulting infoset.

1.4. Relationship to XML Schemas

XInclude defines no relationship to the augmented infosets produced by applying an XML Schema. Such an augmented infoset can be supplied as the input infoset, or such augmentation may be applied to the infoset resulting from the inclusion.

1.5. 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. The attribute-based syntax facilitates incorporation of inclusion capabilities into other markup languages.

3.1. Include Elements

The existence of an include is asserted by an [Definition: ] include element , which is any element bearing the attributes required by this specification.

Each include element in the source infoset is examined, its xinclude:href attribute dereferenced and parsed into an infoset, and this infoset merged with the source infoset, as described in following sections.

The order in which include elements are processed is not defined by this specification. The effect of this is as if intra-document references within include elements must be resolved against the original infoset, instead of resolving against some intermediate state.

In the following example, the second include points to the <myinclude> element itself, not to it's replacement.

<x xmlns:xinclude="http://www.w3.org/1999/XML/xinclude">
  <myinclude xinclude:href="something.xml"/>
  <myinclude xinclude:href="#xpointer(x/myinclude[1])"
             xinclude:parse="text"/>
</x>

3.2. Acquiring the Resource to be Included

The value of the xinclude:href is a URI reference. The set of characters allowed in a xinclude:href is the same as for XML, namely [Unicode]. However, some Unicode characters are disallowed from URI references, and thus processors must encode and escape these characters to obtain a valid URI reference from the attribute value.

The disallowed characters include all non-ASCII characters, plus the excluded characters listed in Section 2.4 of [IETF RFC 2396], except for the crosshatch (#) and percent sign (%) characters and the square bracket characters re-allowed in [IETF RFC 2732]. Disallowed characters must be escaped as follows:

1. Each disallowed character is converted to UTF-8 [IETF RFC 2279] as one or more bytes.

2. Any octets corresponding to a disallowed character are escaped with the URI escaping mechanism (that is, converted to %HH, where HH is the hexadecimal notation of the byte value).

3. The original character is replaced by the resulting character sequence.

The URI reference is combined with the base URI of the include element as specified in XML Base [XML Base]. The resource identified by the full escaped and encoded URI reference is acquired and an infoset or collection of information items is created, either by parsing the resource as xml, or by treating the resource as a plain text file and converting it into a collection of character information items. 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 must take either the value "xml" or the value "text".

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" are specified result in an error.

When parse="xml" is specified, include elements in the infoset are recursively expanded.

<foo xmlns:x="uri1">
 <include xinclude: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 include elements with information items in the acquired infoset. The 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, and remains unchanged after merging. Thus relative URIs in the included infoset resolve to the same URI despite being included into a document with a potentially different base URI in effect.

5.1. Markup Conformance

An element information item is XInclude-conformant if it meets the syntactic requirements for include elements defined in this specification. This specification imposes no particular constraints on DTDs, conformance applies only to elements and attributes.

5.2. Application Conformance

An application conforms to XInclude if it:

• supports XML 1.0, XML Namespaces, and XML Base

• observes the mandatory conditions (must ) set forth in this specification, and for any optional conditions (should and may ) it chooses to observe, observes them in the way prescribed

• performs markup conformance testing according to all the conformance constraints appearing in this specification.