4.1 The Include Location
The value of the href attribute is interpreted as
an IURI reference. [Definition: An
internationalized URI reference, or IURI,
is a URI reference that directly uses [Unicode] characters.]
IURI references allow a superset of the characters of fully escaped URI
references, but must have normal occurrences of the percent sign (%)
escaped because it is the character used for escaping in URIs and IURIs.
Also see [Internationalized URIs] (non-normative).
The base URI for relative IURIs is the base URI of the xi:include
element as specified in [XML Base].
[Definition: The
IURI resulting from resolution to absolute IURI form is called
the include location.]
The set of characters allowed in an href
attribute is the same as for XML, namely [Unicode].
However, some Unicode characters are disallowed from URI references.
Thus the disallowed characters in URI references must
ultimately be encoded and escaped by the XInclude or other processor
when the URI is resolved.
4.1.1 URI Escaping
The disallowed characters include all non-ASCII characters,
plus the excluded characters listed in Section 2.4 of
[IETF RFC 2396], except for the number sign (#) and percent
sign (%) characters and the square bracket characters re-allowed
in [IETF RFC 2732]. Disallowed characters are escaped as
follows:
-
Each disallowed character is converted to UTF-8 [IETF RFC 2279]
as one or more bytes.
-
Any bytes corresponding to a disallowed character are escaped
with the URI escaping mechanism (that is, converted to %HH, where HH
is the hexadecimal notation of the byte value).
-
The original character is replaced by the resulting character
sequence.
4.2 Included Items when parse="xml"
When parse="xml", the
include location
is dereferenced and the resource is fetched, coerced to text/xml, and an
infoset is created.
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 may 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, or a syntax error in an XPointer)
result in a resource error.
Resources that contain non-well-formed XML result in a
fatal error.
[Definition: xi:include
elements in this infoset are recursively processed
to create the acquired infoset.]
When the resource is coerced to text/xml, the fragment part of the URI
reference is interpreted as an [XPointer], regardless
of the media type of the resource. The XPointer indicates a
subresource as the target for inclusion.
XPointer 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 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
An include location
might identify the document information item
(for instance, a URI reference without an XPointer, 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
An include location
having an XPointer might identify a subresource that consists 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.
If the document (top-level) element in the source infoset is an
xi:include element, it is a
fatal error to attempt
to replace it with something other than a list of zero or more
comments, zero or more processing instructions, and one element.
4.2.3 Range Locations
An include location
having an XPointer might identify 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
An include location
having an XPointer might identify 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
An include location
having an XPointer might identify 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
An include location
having an XPointer might identify an attribute node or
a namespace node. An include location identifying such a node is a
fatal error.
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
that has 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.
-
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. Resources that are
unavailable for any reason (for example the resource doesn't exist,
connection difficulties or security restrictions prevent it from
being fetched, the URI scheme isn't a fetchable one, or a syntax
error in a fragment identifer) result in a
resource error.
The fetched resource is treated as plain text and converted to a
set of character information items without attempting to parse the
resource as XML. This feature facilitates the inclusion of working
XML examples, as well as other text-based formats.
The encoding of such a resource is determined by:
-
external encoding information, if available, otherwise
-
if the media type of the resource is text/xml,
application/xml, or matches the conventions
text/*+xml or application/*+xml as described
in XML Media Types [IETF RFC 3023], the encoding is
recognized as specified in XML 1.0, 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.
[Definition: A range
of characters (the selected range) may be identified
by a fragment identifier.] The syntax of the fragment
identifier is interpreted using the syntax of the fragment
identifier for the media type text/plain. In the absence of a
fragment identifier, the selected
range contains all the characters in the resource except
the initial byte order mark (BOM) if one is present. A BOM is the character
U+FEFF when it appears as the first character in resource encoded in
UTF-8, UTF-16 or UTF-32. UTF-16BE and UTF-16LE will not contain a BOM.
Note:
There is currently no standard defining fragment identifiers
for the media type text/plain.
The set of characters in the selected
range is converted to a set of
top-level included items
by creating a character information item with the
[character code] set to the
character code representing the character in ISO 10646 encoding, and the
[element content whitespace] set to
false.
[Character Model] describes the required treatment of
non-normalized Unicode text.
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.
Each top-level included item
is assigned an extension property [included] with
the boolean value "true". Information items which were not processed as
top-level included items will
have no value for the [included] property.
This property may be used by applications which require knowledge of where
inclusion has been performed.
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
must be 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.
<x xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="something.xml"/>
<xi:include href="#xmlns(xi=http://www.w3.org/2001/XInclude)
xpointer(x/xi:include[1])"
parse="xml"/>
</x>
|
4.5.1 Unparsed Entities
Any unparsed entity information
item appearing in the [references]
property of an attribute on the included
items or any descendent thereof is added to the
[unparsed entities]
property of the source infoset's
document information item, if
it is not a duplicate of an existing member.
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 different
[system identifier] or
[public identifier] properties.
4.5.2 Notations
Any notation information item
appearing in the [references]
property of an attribute in the included
items or any descendent 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.
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 different
[system identifier] or
[public identifier] properties.
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 may 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] may 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 first
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 no
element values are 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 may not provide the full list of namespace declarations necessary
to interpret qualified names in attribute or element content in the result.
An XInclude processor must fix up both the
[namespace attributes] and the
[in-scope namespaces] to ensure that
these two properties are complete and consistent.
Each [in-scope namespaces] in
the included items is
augmented with Namespace Information
Items corresponding to the Namespace Information Items
appearing on the include parent,
if any. Items with the same [prefix] as
an existing Namespace Information Item are omitted.
The [namespace attributes] property
requires similar fixup. An Attribute Information Item
is added to the [namespace attributes]
property of the top-level
included items, for each namespace the element has in scope which
is not already declared on the element or on its ancestors in the result
infoset.
For example, the following document:
<foo xmlns:x="uri1">
<xi:include href="common.xml#xpointer(a/b)"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
</foo>
|
including an element from common.xml:
<a xmlns:x="uri2">
<b>
<x:a/>
</b>
</a>
|
results in a document that could be serialized as:
<foo xmlns:x="uri1">
<b xmlns:x="uri2">
<x:a/>
</b>
</foo>
|
4.5.5 Base URI
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. If an
xml:base attribute information item is already present, it
is replaced by the new attribute. 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 the
[base URI] of the element.
-
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.
Note:
The xml:lang and xml:space attributes
are not treated specially by XInclude.
4.5.6 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.
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.