3 Syntax

XInclude defines a namespace associated with the URI http://www.w3.org/2001/XInclude. The XInclude namespace contains two elements with the local names include and fallback. For convenience, within this specification these elements are referred to as xi:include and xi:fallback respectively.

The following (non-normative) XML schema [XML Schemas] illustrates the content model of the xi namespace:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:xi="http://www.w3.org/2001/XInclude"
           targetNamespace="http://www.w3.org/2001/XInclude"
           finalDefault="extension">

  <xs:element name="include" type="xi:includeType" />

  <xs:complexType name="includeType" mixed="true">
    <xs:choice minOccurs='0' maxOccurs='unbounded' >
      <xs:element ref='xi:fallback' />
      <xs:any namespace='##other' processContents='lax' />
      <xs:any namespace='##local' processContents='lax' />
    </xs:choice>
    <xs:attribute name="href" use="optional" type="xs:anyURI"/>
    <xs:attribute name="parse" use="optional" default="xml"
                  type="xi:parseType" />
    <xs:attribute name="xpointer" use="optional" type="xs:string"/>
    <xs:attribute name="encoding" use="optional" type="xs:string"/>
    <xs:attribute name="accept" use="optional" type="xs:string"/>
    <xs:attribute name="accept-language" use="optional" type="xs:string"/>
    <xs:anyAttribute namespace="##other" processContents="lax"/>
  </xs:complexType>

  <xs:simpleType name="parseType">
    <xs:restriction base="xs:token">
      <xs:enumeration value="xml"/>
      <xs:enumeration value="text"/>
    </xs:restriction>
  </xs:simpleType>
  
  <xs:element name="fallback" type="xi:fallbackType" />

  <xs:complexType name="fallbackType" mixed="true">
    <xs:choice minOccurs="0" maxOccurs="unbounded">
      <xs:element ref="xi:include"/>
      <xs:any namespace="##other" processContents="lax"/>
      <xs:any namespace="##local" processContents="lax"/>
    </xs:choice>
    <xs:anyAttribute namespace="##other" processContents="lax" />
  </xs:complexType>

</xs:schema>

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, and %-escaping is not done in XPointers, '%' is an ordinary character in the value of the xpointer attribute.

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 should be a valid encoding name. 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 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 content of xi:fallback elements are ignored unless a resource error occurs while processing the surrounding xi:include element. In particular, apparent fatal errors caused by the presence, absence, or content of elements and attributes inside the xi:fallback element must not be reported in xi:fallback elements that are ignored.

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