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

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.

3.1. The Include Location

The value of the href attribute is interpreted as a URI reference. The set of characters allowed in an href attribute 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 number sign (#) 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 base URI for relative URIs is the base URI of the include element as specified in XML Base [XML Base]. [Definition: ] The URI resulting from resolution to absolute URI form is called the include location.

3.2. Included Items when parse="xml"

When parse="xml", the include location is dereferenced and the resource is fetched. This resource is treated as an XML resource, and is parsed into an information set. [Definition: ] Include elements in this infoset are recursively processed to create the acquired infoset.

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 a syntax error in an XPointer) result in an error. Resources that contain non-well-formed XML result in an error.

The fragment part of the URI reference is interpreted as an XPointer [XPointer] when parse="xml". The XPointer indicates that a subresource, or part of the acquired resource, is the target for inclusion.

The set of included items is derived from the acquired infoset as follows:

3.3. Included Items when parse="text"

When parse="text", the include location is dereferenced and the resource is fetched. This resource is treated as a plain text resource.

[Definition: ] 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 document.

The set of characters in the selected range is converted to a set of included items as follows:

• An entity start marker information item. The [entity] property is set to an entity declaration information item with the following property values:

  • [entity type] is "external general entity".

    Issue (XInclude-66-entity-type): This seems a bit untrue. Should we define a new type of entity instead of reusing an old one?

  • [name] is null.

  • [system identifier] is the include location for the include.

  • [public identifier] is null.

  • [base URI] is the include location for the include.

  • [notation] is null.

  • [content] is null.

  • [charset] The name of the character encoding in which the entity is expressed.

    Issue (XInclude-62-text-encoding): How is the encoding determined for text? We don't want to look inside the text for a format-specific indication. Is it adequate to state "This property is derived from a MIME header"?

• For each character in the selected range, a character information item is created. The character code is set to the character code representing the character in ISO 10646 encoding. The [element content whitespace] flag is set to false.

• An entity end marker information item. The [entity] property is set to the [entity] property of the corresponding entity start marker.

Resources that resolve to something other than text when parse="text" result in an error.

3.4. Creating the Result Infoset

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

The information item for the 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 removing the include element information item from it. In place of the include element, the following information items are inserted in order:

• An Include Start Marker information item. The [parent] property of this item is set to the include parent. The [include element] property is set to the information item representing the include element.

• The included items. The [parent] property of each included item is set to the include parent.

• An Include End Marker information item. The [parent] property of this item is set to the include parent. The [include element] property is set to the information item representing the include element.

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

In the following example, the second include always points to the first <xinclude:include> element and not to itself, regardless of the order in which the includes are processed.

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

<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.5. Infoset Extensions

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, the XML Information Set, 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.