1.1 Relationship to XLink

XInclude differs from the linking features described in the [XML Linking Language], 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 information item 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 1.0] or [XML 1.1] external entities which make them complementary 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 - 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 references. Applications which generate XML output incrementally can benefit from not having to pre-declare inclusions.

Failure to load an external entity is normally a fatal error. XInclude allows the author to provide default content that will be used if the remote resource cannot be loaded.

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.

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 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 might 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.

3.1 xi:include Element

The xi:include element has the following attributes:

href

A value which, after appropriate escaping (see 4.1.1 Escaping of href attribute values) has been performed, results in a URI reference or an ·IRI reference· specifying the location of the resource to include. The href attribute is optional; the absence of this attribute is the same as specifying href="", that is, the reference is to the same document. If the href attribute is absent when parse="xml", the xpointer attribute ·must· be present. Fragment identifiers ·must not· be used; their appearance is a ·fatal error·. A value that results in a syntactically invalid URI or IRI ·should· be reported as a ·fatal error·, but some implementations may find it impractical to distinguish this case from a ·resource error·.

Note: A URI ending in # is considered by [IETF RFC 2396] to have an empty fragment identifier. Such a URI would result in a ·fatal error· as described above.

Note: A key feature of XInclude is that it allows a resource to be cast to a user-specifed type for inclusion (XML or text). The returned media type is therefore essentially ignored for the purposes of inclusion processing, and the syntax of the fragment identifier of the returned media type will generally not be applicable to the user-specified type. For parse="xml" inclusions, sub-resources are identified by a separate xpointer attribute, which is applied after the casting takes place. While this does not prevent subresources of XML documents to be identified by URI (See Architecture of the World Wide Web [Identification]), it does preclude the use of these identifiers directly within XInclude.

parse

Indicates whether to include the resource as parsed XML or as text. The parse attribute allows XInclude to give the author of the including document priority over the server of the included document in terms of how to process the included content. A value of "xml" indicates that the resource ·must· be parsed as XML and the infosets merged. A value of "text" indicates that the resource ·must· be included as the character information items. This attribute is optional. When omitted, the value of "xml" is implied (even in the absence of a default value declaration). Values other than "xml" and "text" are a ·fatal error·.

Note: For interoperability between validating and non-validating systems, whitespace should not appear in the parse attribute.

xpointer

When parse="xml", the XPointer (see [XPointer Framework]) contained in the xpointer attribute is evaluated to identify a portion of the resource to include. This attribute is optional; when omitted, the entire resource is included. The xpointer attribute ·must not· be present when parse="text". If the xpointer attribute is absent, the href attribute ·must· be present.

Note: Since the xpointer attribute is not a URI reference, %-escaping must not appear in the XPointer, nor is there any need for a processor to apply or reverse such escaping.

encoding

When parse="text", it is sometimes impossible to correctly detect the encoding of the text resource. The encoding attribute specifies how the resource is to be translated. The value of this attribute is an EncName as defined in XML specification, section 4.3.3, rule [81]. The encoding attribute has no effect when parse="xml".

accept

The value of the accept attribute may be used by the XInclude processor to aid in content negotiation. When the XInclude processor fetches a resource via HTTP, it ·should· place the value of the accept attribute, if one exists, in the HTTP request as an Accept header as described in section 14.1 of [IETF RFC 2616]. Values containing characters outside the range #x20 through #x7E are disallowed in HTTP headers, and ·must· be flagged as ·fatal errors·.

accept-language

The value of the accept-language attribute may be used by the XInclude processor to aid in content negotiation. When the XInclude processor fetches a resource via HTTP, it ·should· place the value of the accept-language attribute, if one exists, in the HTTP request as an Accept-Language header as described in section 14.4 of [IETF RFC 2616]. Values containing characters outside the range #x20 through #x7E are disallowed in HTTP headers, and ·must· be flagged as ·fatal errors·.

Attributes other than those listed above ·may· be placed on the xi:include element. Unprefixed attribute names are reserved for future versions of this specification, and ·must· be ignored by XInclude 1.0 processors.

The children property of the xi:include element ·may· include a single xi:fallback element; the appearance of more than one xi:fallback element, an xi:include element, or any other element from the XInclude namespace is a ·fatal error·. Other content (text, processing instructions, comments, elements not in the XInclude namespace, descendants of child elements) is not constrained by this specification and is ignored by the XInclude processor, that is, it has no effect on include processing, and does not appear in the children properties of the result infoset. Such content might be used by applications analyzing a pre-inclusion infoset, or be made available to an application post-inclusion through means other than the normal infoset properties.

The following (non-normative) DTD fragment illustrates a sample declaration for the xi:include element:

<!ELEMENT xi:include (xi:fallback?)>
<!ATTLIST xi:include
    xmlns:xi        CDATA       #FIXED    "http://www.w3.org/2001/XInclude"
    href            CDATA       #IMPLIED
    parse           (xml|text)  "xml"
    xpointer        CDATA       #IMPLIED
    encoding        CDATA       #IMPLIED
    accept          CDATA       #IMPLIED
    accept-language CDATA       #IMPLIED
>

3.2 xi:fallback Element

The xi:fallback element appears as a child of an xi:include element. It provides a mechanism for recovering from missing resources. When a ·resource error· is encountered, the xi:include element is replaced with the contents of the xi:fallback element. If the xi:fallback element is empty, the xi:include element is removed from the result. If the xi:fallback element is missing, a ·resource error· results in a ·fatal error·.

The xi:fallback element can appear only as a child of an xi:include element. It is a ·fatal error· for an xi:fallback element to appear in a document anywhere other than as the direct child of the xi:include (before inclusion processing on the contents of the element.) It is a ·fatal error· for the xi:fallback element to contain any elements from the XInclude namespace other than xi:include.

Attributes ·may· be placed on the xi:fallback element. Unprefixed attribute names are reserved for future versions of this specification, and ·must· be ignored by XInclude 1.0 processors.

The following (non-normative) DTD fragment illustrates a sample declaration for the xi:fallback element:

<!ELEMENT xi:fallback ANY>
<!ATTLIST xi:fallback
    xmlns:xi   CDATA   #FIXED   "http://www.w3.org/2001/XInclude"
>

4.1 The Include Location

The value of the href attribute, after escaping according to 4.1.1 Escaping of href attribute values, is interpreted as either a URI reference or an ·IRI reference·. The base URI for relative URIs or IRIs is the base URI of the xi:include element as specified in [XML Base]. [Definition:]  The URI or IRI resulting from resolution of the normalized value of the href attribute (or the empty string if no attribute appears) to absolute URI or IRI form is called the include location.

The absence of a value for the href attribute, either by the appearance of href="" or by the absence of the href attribute, represents a case which may be incompatible with certain implementation strategies. For instance, an XInclude processor might not have a textual representation of the ·source infoset· to include as parse="text", or it may be unable to access another part of the document using parse="xml" and an xpointer because of streamability concerns. An implementation ·may· choose to treat any or all absences of a value for the href attribute as ·resource errors·. Implementations ·should· document the conditions under which such ·resource errors· occur.

4.2 Included Items when parse="xml"

When parse="xml", the ·include location· is dereferenced, the resource is fetched, and an infoset is created by parsing the resource as if the media type were application/xml (including character encoding determination).

Resources that are unavailable for any reason (for example the resource doesn't exist, connection difficulties or security restrictions prevent it from being fetched, the URI scheme isn't a fetchable one, the resource is in an unsupported encoding, or the resource is determined through implementation-specific mechanisms not to be XML) result in a ·resource error·. Resources that contain non-well-formed XML result in a ·fatal error·.

[Definition:]   xi:include elements in this infoset are recursively processed to create the acquired infoset. For an intra-document reference (via xpointer attribute) the ·source infoset· is used as the acquired infoset.

[Definition:]  The portion of the ·acquired infoset· to be included is called the inclusion target. The document information item of the ·acquired infoset· serves as the ·inclusion target· unless the xpointer attribute is present and identifies a subresource. XPointers of the forms described in [XPointer Framework] and [XPointer element() scheme] ·must· be supported. XInclude processors optionally support other forms of XPointer such as that described in [XPointer xpointer() Scheme]. An error in the XPointer is a ·resource error·.

The [XPointer xpointer() Scheme] is not specified in terms of the [XML Information Set], but instead is based on the [XPath 1.0] Data Model, because the XML Information Set had not yet been developed. The mapping between XPath node locations and information items is straightforward. However, xpointer() assumes that all entities have been expanded. Thus it is a ·fatal error· to attempt to resolve an xpointer() scheme on a document that contains unexpanded entity reference information items.

The set of ·top-level included items· is derived from the ·acquired infoset· as follows.

4.3 Included Items when parse="text"

When parse="text", the ·include location· is dereferenced and the resource is fetched and transformed to a set of character information items. This feature facilitates the inclusion of working XML examples, as well as other text-based formats.

Resources that are unavailable for any reason (for example the resource doesn't exist, connection difficulties or security restrictions prevent it from being fetched, the URI scheme isn't a fetchable one, or the resource is in an unsupported encoding) result in a ·resource error·.

The encoding of such a resource is determined by:

• external encoding information, if available, otherwise
• if the media type of the resource is text/xml, application/xml, or matches the conventions text/*+xml or application/*+xml as described in XML Media Types [IETF RFC 3023], the encoding is recognized as specified in XML, otherwise
• the value of the encoding attribute if one exists, otherwise
• UTF-8.

Byte sequences outside the range allowed by the encoding are a ·fatal error·. Characters that are not permitted in XML documents also are a ·fatal error·.

Each character obtained from the transformation of the resource is represented in the ·top-level included items· as a character information item with the character code set to the character code in ISO 10646 encoding, and the element content whitespace set to false.

The [Character Model] discusses normalization of included text.

4.4 Fallback Behavior

XInclude processors ·must· perform fallback behavior in the event of a ·resource error·, as follows:

If the children of the xi:include element information item in the ·source infoset· contain exactly one xi:fallback element, the ·top-level included items· consist of the information items corresponding to the result of performing XInclude processing on the children of the xi:fallback element. It is a ·fatal error· if there is zero or more than one xi:fallback element.

4.5 Creating the Result Infoset

The result infoset is a copy of the source infoset, with each xi:include element processed as follows:

The information item for the xi:include element is found. [Definition:]  The parent property of this item refers to an information item called the include parent. The children property of the ·include parent· is modified by replacing the xi:include element information item with the ·top-level included items·. The parent property of each included item is set to the ·include parent·.

It is a fatal error to attempt to replace an xi:include element appearing as the document (top-level) element in the source infoset with something other than a list of zero or more comments, zero or more processing instructions, and one element.

Some processors may not be able to represent an element's in-scope namespaces property if it does not include bindings for all the prefixes bound in its parent's in-scope namespaces. Such processors ·may· therefore include additional namespace bindings inherited from the ·include parent· in the in-scope namespaces of the ·included items·.

The inclusion history of each ·top-level included item· is recorded in the extension property include history. The include history property is a list of element information items, representing the xi:include elements for recursive levels of inclusion. If an include history property already appears on a ·top-level included item·, the xi:include element information item is prepended to the list. If no include history property exists, then this property is added with the single value of the xi:include element information item.

The ·included items· will all appear in the result infoset. This includes unexpanded entity reference information items if they are present.

Intra-document references within xi:include elements are resolved against the source infoset. The effect of this is that the order in which xi:include elements are processed does not affect the result.

In the following example, the second include always points to the first xi:include element and not to itself, regardless of the order in which the includes are processed. Thus the result of this inclusion is two copies of something.xml, and does not produce an inclusion loop error.

<x xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="something.xml"/>
  <xi:include xpointer="xmlns(xi=http://www.w3.org/2001/XInclude)xpointer(x/xi:include[1])"
              parse="xml"/>
</x>

5.1 Markup Conformance

An element information item conforms to this specification if it meets the structural requirements for include elements defined in this specification. This specification imposes no particular constraints on DTDs or XML schemas; conformance applies only to elements and attributes.

5.2 Application Conformance

An application conforms to XInclude if it:

• supports [XML 1.0] and [Namespaces in XML] or [XML 1.1] and [Namespaces in XML 1.1], the [XML Information Set], [XML Base], the [XPointer Framework], and the [XPointer element() scheme];
• stops processing when a ·fatal error· is encountered;
• 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; and
• performs markup conformance testing according to all the conformance constraints appearing in this specification.

Support for the [XPointer xpointer() Scheme] is not mandatory for full XInclude conformance. Authors are advised that use of xpointer() and other XPointer schemes than element() might not be supported by all conformant XInclude implementations.

5.3 XML Information Set Conformance

This specification conforms to the [XML Information Set]. The following information items ·must· be present in the input infosets to enable correct processing:

• Document information items with children and base URI properties.
• Element information items with namespace name, local name, children, attributes, base URI and parent properties.
• Attribute information items with namespace name, local name and normalized value properties.

Additionally, XInclude processing might generate the following kinds of information items in the result:

• Character information items with character code, element content whitespace and parent properties.

XInclude extends the infoset with the property include history, which ·may· appear on the following types of information items in the result:

• Element information items.
• Processing instruction information items.
• Comment information items.
• Character information items.

XInclude also extends the infoset with the property language, which ·may· appear on element information items in the result.

C.1 Basic Inclusion Example

The following XML document contains an xi:include element which points to an external document. Assume the base URI of this document is http://www.example.org/document.xml.

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <p>120 Mz is adequate for an average home user.</p>
  <xi:include href="disclaimer.xml"/>
</document>

disclaimer.xml contains:

<?xml version='1.0'?>
<disclaimer>
  <p>The opinions represented herein represent those of the individual
  and should not be interpreted as official policy endorsed by this
  organization.</p>
</disclaimer>

The infoset resulting from resolving inclusions on this document is the same (except for the include history and language properties) as that of the following document:

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <p>120 Mz is adequate for an average home user.</p>
  <disclaimer xml:base="http://www.example.org/disclaimer.xml">
  <p>The opinions represented herein represent those of the individual
  and should not be interpreted as official policy endorsed by this
  organization.</p>
</disclaimer>
</document>

C.2 Textual Inclusion Example

The following XML document includes a "working example" into a document.

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <p>This document has been accessed
  <xi:include href="count.txt" parse="text"/> times.</p>
</document>

where count.txt contains:

324387

The infoset resulting from resolving inclusions on this document is the same (except for the include history and language properties) as that of the following document:

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <p>This document has been accessed
  324387 times.</p>
</document>

C.3 Textual Inclusion of XML Example

The following XML document includes a "working example" into a document.

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <p>The following is the source of the "data.xml" resource:</p>
  <example><xi:include href="data.xml" parse="text"/></example>
</document>

data.xml contains:

<?xml version='1.0'?>
<data>
  <item><![CDATA[Brooks & Shields]]></item>
</data>

The infoset resulting from resolving inclusions on this document is the same (except for the include history and language properties) as that of the following document:

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <p>The following is the source of the "data.xml" resource:</p>
  <example>&lt;?xml version='1.0'?&gt;
&lt;data&gt;
  &lt;item&gt;&lt;![CDATA[Brooks &amp; Shields]]&gt;&lt;/item&gt;
&lt;/data&gt;</example>
</document>

C.4 Fragment Inclusion Example

The following illustrates the results of including fragments of another XML document. Assume the base URI of the document is http://www.example.com/JoeSmithQuote.xml.

<?xml version='1.0'?>
<price-quote xmlns:xi="http://www.w3.org/2001/XInclude">
  <prepared-for>Joe Smith</prepared-for>
  <good-through>20040930</good-through>
  <xi:include href="price-list.xml" xpointer="w002-description"/>
  <volume>40</volume>
  <xi:include href="price-list.xml" xpointer="element(w002-prices/2)"/>
</price-quote>

price-list.xml references a DTD which declares the id attributes as type ID, and contains:

<?xml version='1.0'?>
<!DOCTYPE price-list SYSTEM "price-list.dtd">
<price-list xml:lang="en-us">
  <item id="w001">
    <description id="w001-description">
      <p>Normal Widget</p>
    </description>
    <prices id="w001-prices">
      <price currency="USD" volume="1+">39.95</price>
      <price currency="USD" volume="10+">34.95</price>
      <price currency="USD" volume="100+">29.95</price>
    </prices>
  </item>
  <item id="w002">
    <description id="w002-description">
      <p>Super-sized widget with bells <i>and</i> whistles.</p>
    </description>
    <prices id="w002-prices">
      <price currency="USD" volume="1+">59.95</price>
      <price currency="USD" volume="10+">54.95</price>
      <price currency="USD" volume="100+">49.95</price>
    </prices>
  </item>
</price-list>

The infoset resulting from resolving inclusions on this document is the same (except for the include history and language properties) as that of the following document:

<?xml version='1.0'?>
<price-quote xmlns:xi="http://www.w3.org/2001/XInclude">
  <prepared-for>Joe Smith</prepared-for>
  <good-through>20040930</good-through>
  <description id="w002-description" xml:lang="en-us"
               xml:base="http://www.example.com/price-list.xml">
    <p>Super-sized widget with bells <i>and</i> whistles.</p>
  </description>
  <volume>40</volume>
  <price currency="USD" volume="10+" xml:lang="en-us"
         xml:base="http://www.example.com/price-list.xml">54.95</price>
</price-quote>

C.5 Range Inclusion Example

The following illustrates the results of including a range specified by an XPointer. Assume the base URI of the document is http://www.example.com/document.xml.

<?xml version='1.0'?>
<document>
  <p>The relevant excerpt is:</p>
  <quotation>
    <include xmlns="http://www.w3.org/2001/XInclude"
       href="source.xml" xpointer="xpointer(string-range(chapter/p[1],'Sentence 2')/
             range-to(string-range(/chapter/p[2]/i,'3.',1,2)))"/>
  </quotation>
</document>

source.xml contains:

<chapter>
  <p>Sentence 1.  Sentence 2.</p>
  <p><i>Sentence 3.  Sentence 4.</i>  Sentence 5.</p>
</chapter>

The infoset resulting from resolving inclusions on this document is the same (except for the include history and language properties) as that of the following document:

<?xml version='1.0'?>
<document>
  <p>The relevant excerpt is:</p>
  <quotation>
    <p xml:base="http://www.example.com/source.xml">Sentence 2.</p>
  <p xml:base="http://www.example.com/source.xml"><i>Sentence 3.</i></p>
  </quotation>
</document>

C.6 Fallback Example

The following XML document relies on the fallback mechanism to succeed in the event that the resources example.txt and fallback-example.txt are not available..

<?xml version='1.0'?>
<div>
  <xi:include href="example.txt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude">
    <xi:fallback><xi:include href="fallback-example.txt" parse="text">
        <xi:fallback><a href="mailto:bob@example.org">Report error</a></xi:fallback>
      </xi:include></xi:fallback>
  </xi:include>
</div>

If neither example.txt nor fallback-example.txt are available, the infoset resulting from resolving inclusions on this document is the same (except for the include history and language properties) as that of the following document:

<?xml version='1.0'?>
<div>
  <a href="mailto:bob@example.org">Report error</a>
</div>