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
http://www.w3.org/TR/.

This is a First Public Working
Draft of XInclude 1.1 for review by W3C Members and other interested
parties.

Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced
or obsoleted by other documents at any time. It is inappropriate to
cite this document as other than work in progress.

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.]
[Definition: The term
recoverable error refers to the presence of factors which
are erroneous, but for which this specification prescribes specific
recovery behavior.]
XInclude
processors must stop processing
when encountering
fatal
errors;
resource errorsmust be handled as described in
4.6 Fallback Behavior;
recoverable errorsmust be handled as specified.

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:

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 xpointeror fragid 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 xpointeror fragid
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
. Values other than "xml" and "text" are
implementation-defined.

The fragid attribute is a generalization of the xpointer
attribute. A fragid may be present regardless of the value of
the parse attribute.
The interpretation of the value of the attribute depends on
the value of parse. For parse="xml", the value
is interpreted as an XPointer (see [XPointer Framework]); for parse="text",
it is interpreted as a [IETF RFC 5147] fragment identifier. For other values
of parse, the interpretation is implementation-defined.

When parse="text", it is sometimes impossible to
correctly detect the encoding of the text resource. The
encodingattribute 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 are disallowed
in HTTP headers, andmust
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:

3.1.1 The xpointer and fragid attributes

The xpointer and fragid attributes identify a portion
of a resource to include.

If both xpointer and fragid are specified, they
should be the same. It is a
recoverable error if they
are not the same; to recover, if the parse attribute is explicitly “xml”
or if the value “xml” is implied, then the xpointer
attribute is used; otherwise the
fragid
attribute is used.

The xpointer
attribute must not be present when
parse="text". It is a fatal error
to specify
the xpointer attribute when parse="text".

The xpointer and fragid attribute are optional.
When neither is specified:

It is a fatal error
if neither the xpointer nor fragid attributes are present
and the href attribute is not present.

Neither the xpointer nor fragid attributes
contain a URI reference, and %-escaping is not done in XPointers, so '%' is
an ordinary character in the value of the xpointer and
fragid attributes.

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 content of xi:fallback elements is 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 xi:fallback element can appear only as a
child of an xi:include element. It is a
fatal error for an xi:fallback
element that is not being ignored 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 anxi:fallback element that is not being ignored 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 following (non-normative) DTD fragment illustrates a sample
declaration for the xi:fallback element:

4 Processing Model

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

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.

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.

4.2.4 Point Locations

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

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 Attribute Copying when parse="xml"

XInclude can introduce validity errors into a document. In particular, if a resource
containing element information items is included more than once, and if any of those
element information items have attributes of type ID, then the
result infoset
will contain multiple IDs with the same value.

Some applications will want to attempt to resolve these sorts of errors and
different applications will want to do so in different ways. In order to facilitate
this kind of processing, XInclude 1.1 introduces a new feature: attribute copying.

Any namespace qualified attribute that appears on the xi:include
element will be copied onto every
top-level
included item that is an element information item.

If the element information item already has an attribute with the same qualified
name, its value is changed to the value specified on the xi:include
element.

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

4.5 Included Items for other values of parse

When parse is neither “xml” nor “text”, the
the include location is dereferenced
and the resource is fetched and transformed into information items through some
implementation-defined process.

Note:

In this draft, there are no constraints specified for other values of
the parse attribute.
The Working Group is considering changes that would require other values to
be MIME content-type values with the proviso that the fragid value
should be consistent with the content-type.

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 cannot be transformed into information
items for some other reason) result in a
resource error.

The interpretation of fragid attributes for other values of parse
is implementation-defined.

Implementations may raise fatal errors; the
circumstances that result in such errors are implementation-defined.

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

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

A namespace name of
http://www.w3.org/XML/1998/namespace.

A local name of
base.

A prefix of
xml.

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

A specified flag
indicating that this attribute was actually specified in the
start-tag of its element.

An attribute type of
CDATA.

A 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.7.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
a document information item, has an
attribute information item added to its
attributes property. This attribute
has the following properties:

A namespace name of
http://www.w3.org/XML/1998/namespace.

A local name of
lang.

A prefix of xml.

A normalized value equal to
the language property of the
element. If the language property
has no value, the normalized value is the empty string.

A specified flag indicating
that this attribute was actually specified in the start-tag of its
element.

An attribute type of
CDATA.

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

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:

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
http://www.example.org/document.xml.

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
<p>120 Mz is adequate for an average home user.</p>
<xi:include href="disclaimer.xml"/>
</document>

disclaimer.xml contains:

<?xml version='1.0'?>
<disclaimer>
<p>The opinions represented herein represent those of the individual
and should not be interpreted as official policy endorsed by this
organization.</p>
</disclaimer>

The infoset resulting from resolving inclusions on this document
is the same (except for the include history
and language properties)
as that of the following document:

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
<p>120 Mz is adequate for an average home user.</p>
<disclaimer xml:base="http://www.example.org/disclaimer.xml">
<p>The opinions represented herein represent those of the individual
and should not be interpreted as official policy endorsed by this
organization.</p>
</disclaimer>
</document>

C.2 Textual Inclusion Example

The following XML document includes a "working example" into
a document.

C.6 Textual Inclusion Examples with RFC5147 Fragment Identifiers

The following XML document includes several lines of a code listing.

<?xml version='1.0'?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
<p>This example includes just the ‘use' lines from a Perl script.</p>
<pre><xi:include parse="text" frigid="line=2,6" href="code.pl"/></pre>
<p>There are four of them.</p>
</document>

The infoset resulting from resolving inclusions on this document
is the same (except for the include history
and language properties)
as that of the following document:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
<p>This example includes just the ‘use' lines from a Perl script.</p>
<pre>use strict;
use English;
use Getopt::Std;
use vars qw($opt_p $opt_q $opt_u $opt_m);
</pre>
<p>There are four of them.</p>
</document>

This XML document includes a range of characters from the same code listing.

If neither example.txt nor fallback-example.txt
are available, the infoset resulting from resolving inclusions on this document
is the same (except for the include history
and language properties)
as that of the following document: