XML Inclusions (XInclude) Version 1.0 (Second Edition)

XML Inclusions (XInclude) Version 1.0 (Second Edition)
XML Inclusions (XInclude) Version 1.0 (Second Edition)
W3C Recommendation 15 November 2006
This version:
Latest version:
Previous versions:
Editors:
Jonathan Marsh, Microsoft

David Orchard, BEA Systems

Daniel Veillard

- Second Edition
Please refer to the
errata
for this document, which may
include some normative corrections.
See also
translations
This document is also available in these non-normative formats:
XML
and
XHTML with color-coded revision indicators
W3C
MIT
ERCIM
Keio
), All Rights Reserved. W3C
liability
trademark
and
document use
rules apply.
Abstract
This document specifies a processing model and syntax for general
purpose inclusion. Inclusion is accomplished by merging a
number of XML information sets into a single composite infoset.
Specification of the XML documents (infosets) to be merged and
control over the merging process is expressed in XML-friendly
syntax (elements, attributes, URI references).
Status of this Document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current
W3C publications and the latest revision of this technical report can be found
in the
W3C technical reports index
at
This document has been produced by the
W3C XML Core Working Group
as part
of the
XML Activity
The English version of this specification is the only normative version. However,
for translations of this document, see
This document is a W3C Recommendation. This second edition is not a
new version of XInclude. As a convenience to readers, it incorporates
the changes dictated by the accumulated errata (available at
to the
First
Edition of XInclude 1.0
, dated 20 December 2004, which it supersedes.
Please report errors in this document to the public
www-xml-xinclude-comments@w3.org
mailing-list;
archives
are available.
The errata list for this edition is available at
Known implementations are documented in the
XInclude Implementation Report at
. A
Test Suite is maintained at
to
help in assessing conformance to this specification. The latest
release of the Test Suite includes new test cases which implementers
can use to check their conformance to the changes included in this new
edition.
This document has been reviewed by W3C Members, by software
developers, and by other W3C groups and interested parties, and is
endorsed by the Director as a W3C Recommendation. It is a stable
document and may be used as reference material or cited from another
document. W3C's role in making the Recommendation is to draw attention
to the specification and to promote its widespread deployment. This
enhances the functionality and interoperability of the Web.
This document is governed by the
24 January 2002 CPP
as amended by the
W3C Patent Policy Transition Procedure
. W3C maintains a
public list of any patent
disclosures
made in connection with the deliverables of the group;
that page also
includes instructions for disclosing a patent. An individual who has
actual knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance
with
section 6 of the W3C Patent Policy
Table of Contents
Introduction
1.1
Relationship to XLink
1.2
Relationship to XML External Entities
1.3
Relationship to DTDs
1.4
Relationship to XML Schemas
1.5
Relationship to Grammar-Specific Inclusions
Terminology
Syntax
3.1
xi:include Element
3.2
xi:fallback Element
Processing Model
4.1
The Include Location
4.1.1
Escaping of href attribute values
4.1.2
Using XInclude with Content Negotiation
4.2
Included Items when parse="xml"
4.2.1
Document Information Items
4.2.2
Multiple Nodes
4.2.3
Range Locations
4.2.4
Point Locations
4.2.5
Element, Comment, and Processing Instruction Information Items
4.2.6
Attribute and Namespace Declaration Information Items
4.2.7
Inclusion Loops
4.3
Included Items when parse="text"
4.4
Fallback Behavior
4.5
Creating the Result Infoset
4.5.1
Unparsed Entities
4.5.2
Notations
4.5.3
references Property Fixup
4.5.4
Namespace Fixup
4.5.5
Base URI Fixup
4.5.6
Language Fixup
4.5.7
Properties Preserved by the Infoset
Conformance
5.1
Markup Conformance
5.2
Application Conformance
5.3
XML Information Set Conformance
Appendices
References
References
(Non-Normative)
Examples
(Non-Normative)
C.1
Basic Inclusion Example
C.2
Textual Inclusion Example
C.3
Textual Inclusion of XML Example
C.4
Fragment Inclusion Example
C.5
Range Inclusion Example
C.6
Fallback Example
1 Introduction
Many programming languages provide an inclusion mechanism to
facilitate modularity. Markup languages also often have need of
such a mechanism. This specification introduces a generic mechanism
for merging XML documents (as represented by their information sets)
for use by applications that need such a facility. The syntax
leverages existing XML constructs - elements, attributes, and URI
references.
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.
2 Terminology
Definition
: The key words
must
must not
required
shall
shall not
should
should not
recommended
may
and
optional
in this specification are to be interpreted
as described in
[IETF RFC 2119]
.]
Definition
: The term
information
set
refers to the output of an
[XML 1.0]
or
[XML 1.1]
processor, expressed as a
collection of information items and properties as defined by the
[XML Information Set]
specification.] In this document
the term
infoset
is used as a synonym for
information set
Definition
: The term
fatal
error
refers to the presence of factors that prevent normal
processing from continuing.]
Definition
: The term
resource error
refers to a failure of an attempt to
fetch a resource from a URL.] XInclude
processors
must
stop processing
when encountering errors other than
resource errors
, which
must
be handled as described in
4.4 Fallback Behavior
3 Syntax
XInclude defines a namespace associated with the URI
. 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:
xmlns:xi="http://www.w3.org/2001/XInclude"
targetNamespace="http://www.w3.org/2001/XInclude"
finalDefault="extension">

type="xi:parseType" />

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:

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:

xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude"
4 Processing Model
Inclusion as defined in this document is a specific type of
[XML Information Set]
transformation.
Definition
: The
input for the inclusion transformation consists of a
source
infoset
.]
Definition
: The output, called the
result
infoset
, is a new infoset which merges the source infoset
with the infosets of resources identified by URI references or IRI references
appearing in
xi:include
elements.] Thus a
mechanism to resolve URIs or IRIs and return the identified resources as
infosets is assumed. Well-formed XML entities that do not have
defined infosets (e.g. an external entity with multiple
top-level elements) are outside the scope of this specification,
either for use as a
source
infoset
or the
result
infoset
xi:include
elements in the source infoset serve
as inclusion transformation instructions.
Definition
: The
information items located by the
xi:include
element
are called the
top-level included items
].
Definition
: The
top-level included items
together with their attributes, namespaces, and descendants,
are called the
included items
]. The
result infoset
is
essentially a copy of the
source
infoset
, with each
xi:include
element
and its descendants replaced by its corresponding
included items
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.1.1 Escaping of
href
attribute values
The value of this attribute is an XML resource identifer as
defined in
[XML 1.1]
section 4.2.2 "External Entities", which
is interpreted as [
Definition
: an IRI Reference as defined in RFC 3987
[IETF RFC 3987]
],
after the escaping procedure described in
[XML 1.1]
section
4.2.2 is applied. If necessary for the implementation, the value may be
further converted to a URI reference as described in
[XML 1.1]
4.1.2 Using XInclude with Content Negotiation
The use of a mechanism like HTTP
[IETF RFC 2616]
content
negotiation introduces an additional level of potential complexity
into the use of XInclude. Developers who use XInclude in situations
where content negotiation is likely or possible should be aware of
the possibility that they will be including content that may differ
structurally from the content they expected, even if that content
is XML. For example, a single URI or IRI may variously return a raw XML
representation of the resource, an XSL-FO
[XSL-FO]
representation, or an XHTML
[XHTML]
representation,
as well as versions in different character encodings or languages.
Authors whose XInclude processing depends on the receipt of
a particular vocabulary of XML should use the
accept
and
accept-language
attributes
to increase the probability that the resource is provided in the
expected format.
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).
Note:
The specifics of how an infoset is created are intentionally
unspecified, to allow for flexibility by implementations and to
avoid defining a particular processing model for components of
the XML architecture. Particulars of whether DTD or XML schema
validation are performed, for example, are not constrained by
this specification.
Note:
The character encodings of the including and included
resources can be different. This does not affect the resulting
infoset, but might need to be taken into account during any
subsequent serialization.
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
Note:
The distinction between a resource error and a fatal error
is somewhat implementation-dependent. Consider an include
location returning an HTML document, perhaps as an error page.
One processor might determine that no infoset can be created
from the resource (by examining the media type, for example)
and raise a resource error, enabling fallback behavior.
Another processor with no such heuristics might attempt to
parse the non-XML resource as XML and encounter a
well-formedness (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.2.1 Document Information Items
The
inclusion target
might be a
document information item
(for instance, no specified
xpointer
attribute, or an
XPointer specifically locating the document root.) In this case,
the set of
top-level
included items
is the
children
of the
acquired infoset's
document information item, except for the
document type declaration information item
child, if one exists.
Note:
The XML Information Set specification does not provide for
preservation of white space outside the document element.
XInclude makes no further provision to preserve this white
space.
4.2.2 Multiple Nodes
The
inclusion target
might consist of more than a single node. In this case the set of
top-level included
items
is the set of information items from the
acquired infoset
corresponding to the nodes referred to by the XPointer, in the order
in which they appear in the acquired infoset.
4.2.3 Range Locations
The
inclusion target
might
be a location set that represents a range or a set of ranges.
Each range corresponds to a set of information items in the
acquired infoset
Definition
: An information item is
said to be
selected
by a range if it occurs after
(in document order) the starting point of the range and before
the ending point of the range.]
Definition
: An
information item is said to be
partially selected
by
a range if it contains only the starting point of the range, or
only the ending point of the range.] By definition, a
character information item cannot be
partially selected
The set of
top-level
included items
is the union, in document order with
duplicates removed, of the information items either
selected
or
partially selected
by the range. The
children
property of
selected
information items is not modified. The
children
property of
partially selected
information items is the set of information items that are in
turn either
selected
or
partially selected
and so on.
4.2.4 Point Locations
The
inclusion target
might be a location set that represents a point. In this case the
set of
included items
is
empty.
4.2.5 Element, Comment, and Processing Instruction Information Items
The
inclusion target
might be an element node, a comment node, or a processing instruction
node, respectively representing an
element
information item
, a
comment information
item
, or a
processing instruction information
item
. In this case the set of
top-level included items
consists of the information item corresponding to the element, comment, or
processing instruction node in the
acquired
infoset
4.2.6 Attribute and Namespace Declaration Information Items
It is a
fatal error
for the
inclusion target
to be an
attribute node or a namespace node.
4.2.7 Inclusion Loops
When recursively processing an
xi:include
element, it is a
fatal error
to process
another
xi:include
element with an
include location
and
xpointer
attribute value that have already been processed in the
inclusion chain.
In other words, the following are all legal:
An
xi:include
element
may
reference the document
containing the include element, when
parse="text"
An
xi:include
element
may
identify a different
part of the same local resource (same
href
different
xpointer
).
Two non-nested
xi:include
elements
may
identify a resource which
itself contains an
xi:include
element.
The following are illegal:
An
xi:include
element pointing to itself or any
ancestor thereof, when
parse="xml"
An
xi:include
element pointing to any include
element or ancestor thereof which has already been processed
at a higher level.
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 indicates,
according to XML Media Types
[IETF RFC 3023]
, that the
resource is XML, for example
text/xml
or
application/xml
or matches
text/*+xml
or
application/*+xml
, then the
encoding is determined as specified in
[XML 1.0]
or
[XML 1.1]
section 4.3.3, as appropriate, 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.
When the first character is U+FEFF and is interpreted as a
Byte-Order Mark, it should be discarded. It is interpreted as a BOM in UTF-8,
UTF-16, and UTF-32 encodings; it is not interpreted as a BOM in the UTF-16LE,
UTF-16BE, UTF-32LE, and UTF-32BE encodings.
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.
Note:
Fallback content is not dependent on the value of the
parse
attribute. The
xi:fallback
element can contain markup even when
parse="text"
Likewise, it can contain a simple string when
parse="xml"
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.


parse="xml"/>

An XInclude processor
may
, at
user option, suppress
xml:base
and/or
xml:lang
fixup.
4.5.1 Unparsed Entities
Any
unparsed entity information
item
appearing in the
references
property of an attribute on the
included
items
or any descendant thereof is added to the
unparsed entities
property of the
result infoset
's
document information item
, if
it is not a duplicate of an existing member. Duplicates do not appear
in the result infoset.
Unparsed entity items with the same
name
system identifier
public identifier
declaration base URI
notation name
, and
notation
are
considered to be duplicate. An application
may
also be able to detect that
unparsed entities are duplicate through other means. For instance,
the URI resulting from combining the system identifier
and the declaration base URI is the same.
It is a
fatal error
to
include unparsed entity items with the same name, but which are not
determined to be duplicates.
4.5.2 Notations
Any
notation information item
appearing in the
references
property of an attribute in the
included
items
or any descendant thereof is added to the
notations
property of the
result infoset
's
document information item
, if
it is not a duplicate of an existing member. Likewise,
any notation referenced by an unparsed entity added as described
in
4.5.1 Unparsed Entities
, is added unless it is
a duplicate. Duplicates do not appear in the result infoset.
Notation items with the same
name
system identifier
public identifier
, and
declaration base URI
are
considered to be duplicate. An application
may
also be able to detect that notations are duplicate through other means. For
instance, the URI resulting from combining the system identifier
and the declaration base URI is the same.
It is a
fatal error
to
include notation items with the same name, but which are not
determined to be duplicates.
4.5.3
references
Property Fixup
During inclusion, an
attribute information
item
whose
attribute type
property is IDREF or IDREFS has a
references
property with zero or more element values from the source or included
infosets. These values
must
be
adjusted to correspond to element values that occur in the result
infoset. During this process, XInclude also corrects inconsistencies
between the
references
property and the
attribute type
property, which might arise in the following circumstances:
A document fragment contains an IDREF pointing to an element
in the included document but outside the part being included.
In this case there is no element in the result infoset that
corresponds to the element value in the original
references
property.
A document or document fragment is not self-contained.
That is, it contains IDREFs which do not refer to an element within
that document or document fragment, with the intention that these
references will be realized after inclusion. In this case,
the value of the
references
property is unknown or has no value.
The result infoset has ID clashes - that is, more than one
attribute with
attribute type
ID with the same
normalized value
In this case, attributes with
attribute
type
IDREF or IDREFS with the same
normalized value
might have different values for their
references
properties.
In resolving these inconsistencies, XInclude takes the
attribute type
property as
definitive. In the result infoset, the value of the
references
property of an
attribute information item
whose
attribute type
property
is IDREF or IDREFS is adjusted as follows:
For each token in the
normalized
value
property, the
references
property contains an
element information
item
with the same properties as the
element information item
in the result
infoset with an attribute with
attribute
type
ID and
normalized
value
equal to the token. The order of the elements in
the
references
property is
the same as the order of the tokens appearing in the
normalize value
. If for any of the
token values, no element or more than one element is found, the
references
property has no value.
4.5.4 Namespace Fixup
The
in-scope namespaces
property ensures that namespace scope is preserved through inclusion.
However, after inclusion, the
namespace
attributes
property might not provide the full list of
namespace declarations necessary to interpret qualified names in
attribute or element content in the result. It is therefore not
recommended that XInclude processors expose
namespace attributes
in the
result. If this is unavoidable, the implementation
may
add
attribute information items
to the
namespace attributes
property
in order to approximate the information conveyed by
in-scope namespaces
4.5.5 Base URI Fixup
The base URI property of the acquired infoset is not changed as
a result of merging the infoset, and remains unchanged after merging.
Thus relative URI references in the included infoset resolve to the same
URI despite being included into a document with a potentially
different base URI in effect.
xml:base
attributes are added
to the result infoset to indicate this fact.
Each
element information item
in
the
top-level included
items
which has a different
base
URI
than its
include parent
has an
attribute information item
added to its
attributes
property. This attribute has the following properties:
namespace name
of
local name
of
base
prefix
of
xml
normalized value
equal to either the
base
URI
of the element, or an equivalent URI reference
relative to the
base URI
of the include parent. The circumstances in which a relative
URI is desirable, and how to compute such a relative URI,
are implementation-dependent.
specified
flag
indicating that this attribute was actually specified in the
start-tag of its element.
An
attribute type
of
CDATA
references
property
with no value.
An
owner element
of the
information item of the element.
If an
xml:base
attribute information item is already
present, it is replaced by the new attribute.
4.5.6 Language Fixup
While the
xml:lang
attribute is described as inherited
by XML, the XML Information Set makes no provision for preserving the
inheritance of this property through document composition such as XInclude
provides. This section introduces a
language
property which records the scope of
xml:lang
information in
order to preserve it during inclusion.
An XInclude processor
should
augment
the
source infoset
and the
acquired infoset
by adding
the
language
property to each
element information item
. The value of
this property is the
normalized value
of the
xml:lang
attribute appearing on that element if one
exists, with
xml:lang=""
resulting in no value, otherwise it
is the value of the
language
property
of the element's parent element if one exists, otherwise the property
has no value.
Each
element information item
in the
top-level included items
which has a different value of
language
than its
include parent
(taking
case-insensitivity into account per
[IETF RFC 3066]
), or that has
a value if its
include parent
is
document information item
, has an
attribute information item
added to its
attributes
property. This attribute
has the following properties:
namespace name
of
local name
of
lang
prefix
of
xml
normalized value
equal to
the
language
property of the
element. If the
language
property
has no value, the normalized value is the empty string.
specified
flag indicating
that this attribute was actually specified in the start-tag of its
element.
An
attribute type
of
CDATA
references
property with
no value.
An
owner element
of the
information item of the element.
If an
xml:lang
attribute information item is already present,
it is replaced by the new attribute.
Note:
The
xml:space
attribute is not treated specially by
XInclude.
4.5.7 Properties Preserved by the Infoset
As an infoset transformation, XInclude operates on the logical
structure of XML documents, not on their text serialization. All
properties of an information item described in
[XML Information Set]
other than those specifically modified by this specification are
preserved during inclusion. The
include history
and
language
properties introduced in this specification is also preserved.
Extension properties such as
[XML Schemas]
Post Schema Validation Infoset (PSVI)
properties are discarded by default. However, an XInclude
processor
may
, at user option,
preserve these properties in the resulting infoset if they
are correct according to the specification describing the
semantics of the extension properties.
For instance, the PSVI
validity
property describes the conditions of ancestors and descendants.
Modification of ancestors and descendants during the XInclude
process can render the value of this property inaccurate. By
default, XInclude strips this property, but by user option the
property could be recalculated to obtain a semantically accurate
value. Precisely how this is accomplished is outside the scope
of this specification.
5 Conformance
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.
A References
IETF RFC 2119
RFC 2119: Key
words for use in RFCs to Indicate Requirement Levels
Internet Engineering Task Force, 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)
IETF RFC 3629
RFC 3629: UTF-8,
a transformation format of ISO 10646
Internet Engineering Task Force, 2003. (See http://www.ietf.org/rfc/rfc3629.txt.)
IETF RFC 2396
RFC 2396:
Uniform Resource Identifiers
. Internet Engineering
Task Force, 1995. (See http://www.ietf.org/rfc/rfc2396.txt.)
IETF RFC 2732
RFC 2732:
Format for Literal IPv6 Addresses in URL's
Internet Engineering Task Force, 1999. (See http://www.ietf.org/rfc/rfc2732.txt.)
IETF RFC 3023
RFC 3023:
XML Media Types
Internet Engineering Task Force, 2001. (See http://www.ietf.org/rfc/rfc3023.txt.)
IETF RFC 3987
RFC 3987:
Internationalized Resource Identifiers (IRIs)
Internet Engineering Task Force, 2005. (See http://www.ietf.org/rfc/rfc3987.txt.)
Unicode
The Unicode Consortium.
The
Unicode Standard, Version 4.0.
Reading, Mass.: Addison-Wesley,
2003, as updated from time to time by the publication of new versions. (See
for the latest version
and additional information on versions of the standard and of the Unicode
Character Database).
XML 1.0
Tim Bray, Jean Paoli, C.M. Sperberg-McQueen, Eve Maler, François Yergeau, editors.
Extensible Markup
Language (XML) 1.0 (Third Edition)
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml-20040204/.)
XML 1.1
Tim Bray, Jean Paoli, C.M. Sperberg-McQueen, Eve Maler, François Yergeau,
John Cowan, editors.
Extensible Markup
Language (XML) 1.1
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml11-20040204/.)
XML Base
Jonathan Marsh, editor.
XML Base
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xmlbase-20010627/.)
XML Information Set
John Cowan and Richard Tobin, editors.
XML Information
Set (Second Edition)
. World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.)
Namespaces in XML
Tim Bray, Dave Hollander, and Andrew Layman, editors.
Namespaces in XML
World Wide Web Consortium, 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114/.)
Namespaces in XML 1.1
Tim Bray, Dave Hollander, Andrew Layman, Richard Tobin, editors.
Namespaces in XML 1.1
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/2004/REC-xml-names11-20040204/.)
XPointer Framework
Paul Grosso, Eve Maler, Jonathan Marsh, Norman Walsh, editors.
XPointer Framework
World Wide Web Consortium, 2003. (See http://www.w3.org/TR/2003/REC-xptr-framework-20030325/.)
XPointer element() scheme
Paul Grosso, Eve Maler, Jonathan Marsh, Norman Walsh, editors.
XPointer element()
Scheme
World Wide Web Consortium, 2003. (See http://www.w3.org/TR/2003/REC-xptr-element-20030325/.)
B References (Non-Normative)
IETF RFC 2616
RFC 2616:
Hypertext Transfer Protocol -- HTTP/1.1
Internet Engineering Task Force, 1999. (See http://www.ietf.org/rfc/rfc2616.txt.)
IETF RFC 3066
RFC 3066:
Tags for the Identification of Languages
Internet Engineering Task Force, 2001. (See http://www.ietf.org/rfc/rfc3066.txt.)
XML Inclusion Proposal
Jonathan Marsh, David Orchard, editors.
XML
Inclusion Proposal (XInclude).
World Wide Web Consortium, 2004. (See http://www.w3.org/TR/1999/NOTE-xinclude-19991123.)
XML Linking Language
Steve DeRose, Eve Maler, David Orchard, and Ben Trafford, editors.
XML Linking Language (XLink).
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xlink-20010627/.)
XPointer xpointer() Scheme
Steve DeRose, Ron Daniel, Eve Maler, editors.
XPointer
xpointer() Scheme
World Wide Web Consortium, 2002. (See http://www.w3.org/TR/2002/WD-xptr-xpointer-20021219/.)
XPath 1.0
James Clark, Steve DeRose, editors.
XML Path Language (XPath)
Version 1.0.
World Wide Web Consortium, 1999. (See http://www.w3.org/TR/1999/REC-xpath-19991116.)
Character Model
Martin J. Dürst, François Yergeau, Misha Wolf, Asmus Freytag, Tex Texin.
Character Model for the
World Wide Web 1.0: Normalization
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/charmod-norm/.)
XML Schemas
Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, editors.
XML Schema Part 1:
Structures.
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)
XSL-FO
Sharon Adler
et al
Extensible Stylesheet
Language (XSL)
World Wide Web Consortium, 2001. (See http://www.w3.org/TR/2001/REC-xsl-20011015/.)
XHTML
Steven Pemberton
et al
XHTML 1.0 The Extensible
HyperText Markup Language (Second Edition)
World Wide Web Consortium, 2002. (See http://www.w3.org/TR/2002/REC-xhtml1-20020801/.)
C Examples (Non-Normative)
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

120 Mz is adequate for an average home user.