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