XInclude differs from the linking features described in the , 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.

There are a number of differences between XInclude and 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.

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.

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.

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 xi:include element has the following attributes:

Attributes from other namespaces may be placed on the xi:include element. Unqualified attribute names are reserved for future versions of this specification, and must be ignored by XInclude 1.0 processors.

The content of the xi:include element may include an xi:fallback element. Other content 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 analizing 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:

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

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

The value of the href attribute is interpreted as an IURI reference. An internationalized URI reference, or IURI, is a URI reference that directly uses characters. IURI references allow a superset of the characters of fully escaped URI references, but must have normal occurrences of the percent sign (%) escaped because it is the character used for escaping in URIs and IURIs. Also see (non-normative).

The base URI for relative IURIs is the base URI of the xi:include element as specified in . The IURI resulting from resolution to absolute IURI form is called the include location.

The set of characters allowed in an href attribute is the same as for XML, namely . However, some Unicode characters are disallowed from URI references. Thus the disallowed characters in URI references must ultimately be encoded and escaped by the XInclude or other processor when the URI is resolved.

When parse="xml", the include location is dereferenced and the resource is fetched, coerced to text/xml, and an infoset is created.

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 unsuppored encoding, the resource is determined through implementation-specific mechanisms not to be XML, or a syntax error in an ) result in a resource error. Resources that contain non-well-formed XML result in a fatal error.

xi:include elements in this infoset are recursively processed to create the acquired infoset.

When the resource is coerced to text/xml, the fragment part of the URI reference is interpreted as an XPointer, regardless of the media type of the resource. The XPointer indicates a portion of the acquired infoset as the target for inclusion. XPointers of the forms described in and must be supported. XInclude processors optionally support other forms of XPointer such as that described in .

The is not specified in terms of the , but instead is based on the 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.

When parse="text", the include location is dereferenced and the resource is fetched. 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 a syntax error in a fragment identifer) result in a resource error.

The fetched resource is treated as plain text and converted to a set of character information items without attempting to parse the resource as XML. This feature facilitates the inclusion of working XML examples, as well as other text-based formats.

The encoding of such a resource is determined by:

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.

A range of characters (the selected range) may be identified by a fragment identifier. The syntax of the fragment identifier is interpreted using the syntax of the fragment identifier for the media type text/plain. In the absence of a fragment identifier, the selected range contains all the characters in the resource except the initial byte order mark (BOM) if one is present. A BOM is the character U+FEFF when it appears as the first character in resource encoded in UTF-8, UTF-16 or UTF-32. UTF-16BE and UTF-16LE will not contain a BOM.

The set of characters in the selected range is converted to a set of top-level included items by creating a character information item with the character code set to the character code representing the character in ISO 10646 encoding, and the element content whitespace set to false.

describes the required treatment of non-normalized Unicode text.

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

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

Each top-level included item is assigned an extension property included with the boolean value "true". Information items which were not processed as top-level included items will have no value for the included property. This property might be used by applications which require knowledge of where inclusion has been performed.

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 must be 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.

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.

An application conforms to XInclude if it:

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

This specification conforms to the . The following information items must be present in the input infosets to enable correct processing:

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

XInclude also extends the infoset with the boolean property included, which may appear on the following types of information items in the result: