Please refer to the errata for this document, which may include some normative corrections.
See also translations.
Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
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).
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 document is published as a Working Group Note; the XML Core Working Group has been closed and this document is no longer maintained.
Publication as a Working Group Note 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.
XInclude 1.1 adds some upward-compatible enhancements to the XInclude 1.0 Recommendation as discussed in the XInclude 1.1 Requirement and Use Cases document. The three key enhancements can be summarized as follows:
added support for a fragment identifier into text/plain content,
additional processing to allow for “annotating” the post-included infoset with further information, and
allow implementations the flexibility to support additional parse
values.
This document has been produced by the W3C XML Core Working Group as part of the XML Activity. The Working Group expects to advance this Candidate Recommendation to Recommendation Status. We expect to exit the CR period with at least two interoperable implementations of all the features being added as part of XInclude 1.1. We will not exit CR before 25 August 2015 by which time we do expect to have sufficient implementation experience.
Please send comments about this document to the public www-xml-xinclude-comments@w3.org mailing-list; archives are available.
Publication as a Candidate Recommendation 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.
Known implementations are documented in the XInclude Implementation Report at http://www.w3.org/XML/2013/10/xinclude-11-impl-report/. A Test Suite is maintained at http://www.w3.org/XML/2013/10/xinclude-11-test-suite/ 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 was produced by a group operating under the 5 February 2004 W3C Patent Policy. 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.
This document is governed by the 14 October 2005 W3C Process Document.
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.
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.
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.
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.
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.
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.
[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 errors must be handled as described in 4.6 Fallback Behavior; recoverable errors must be handled as specified.
XInclude 1.1 defines two namespaces:
The namespace http://www.w3.org/2001/XInclude
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 namespace http://www.w3.org/2001/XInclude/local-attributes
is used for copying
attributes that are not in a namespace, see
4.3 Attribute Copying when processing XML.
For convenience, within this specification, the
prefix xila
is used when referring to elements within
this namespace.
The following (non-normative) XML schema [XML Schemas]
illustrates the content model of the xi
namespace:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xi="http://www.w3.org/2001/XInclude"
targetNamespace="http://www.w3.org/2001/XInclude"
finalDefault="extension">
<xs:element name="include" type="xi:includeType" />
<xs:complexType name="includeType" mixed="true">
<xs:choice minOccurs="0" maxOccurs="unbounded" >
<xs:element ref="xi:fallback" />
<xs:any namespace="##other" processContents="lax" />
<xs:any namespace="##local" processContents="lax" />
</xs:choice>
<xs:attribute name="href" use="optional" type="xs:anyURI"/>
<xs:attribute name="parse" use="optional" default="xml"
type="xs:string" />
<xs:attribute name="xpointer" use="optional" type="xs:string"/>
<xs:attribute name="fragid" use="optional" type="xs:string"/>
<xs:attribute name="set-xml-id" use="optional" type="xs:string"/>
<xs:attribute name="encoding" use="optional" type="xs:string"/>
<xs:attribute name="accept" use="optional" type="xs:string"/>
<xs:attribute name="accept-language" use="optional" type="xs:string"/>
<xs:anyAttribute namespace="##other" processContents="lax"/>
</xs:complexType>
<xs:element name="fallback" type="xi:fallbackType" />
<xs:complexType name="fallbackType" mixed="true">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element ref="xi:include"/>
<xs:any namespace="##other" processContents="lax"/>
<xs:any namespace="##local" processContents="lax"/>
</xs:choice>
<xs:anyAttribute namespace="##other" processContents="lax" />
</xs:complexType>
</xs:schema>
The xi:include
element has the following
attributes:
A value which, after appropriate escaping (see 4.1.1 Escaping of href attribute values)
has been performed, results in a URI reference or an
IRI reference
specifying the location of the resource to
include. The href
attribute is optional; the
absence of this attribute is the same as specifying
href=""
, that is, the reference is to the same
document. If the href
attribute is absent when
XML processing is specified, the xpointer
or 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. 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.
Therefore, in XInclude, subresources of the included resource
are identified by a separate xpointer
or fragid
attribute
which is applied after the casting takes place.
Indicates how to parse the included resource.
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.
With two exceptions,
the value of the parse
attribute must
conform to the requirements of a media type,
see [IETF RFC 4288]. The exceptions are “xml
”
which must be treated as
“application/xml
” and “text
”,
which must be treated as
“text/plain
”.
Implementations must process
the value of the parse
attribute with standard
media type rules: if the media type is recognized, process it as that media type;
if the suffix is recognized, process it in accordance with that suffix; and finally,
if the family is recognized, process it in accordance with that family.
Note:
In accordance with these rules, a media type of “application/unknown+xml
”
will be treated as XML (i.e. application/xml
),
whereas a media type of “text/unknown
” will
be treated as text (i.e. text/plain
).
A value of “xml
”, “application/xml
”,
or a value with the “+xml
” suffix
indicates that the resource must
be parsed as XML and the infosets merged. A value of
“text
”, “text/plain
”, or a value in the
“text
” family
indicates
that the resource must be included
as the character information items. This attribute is optional.
When omitted, the value of “application/xml
” is implied.
Values that specify neither XML processing nor text processing are
implementation-defined.
Implementations must treat
values of the parse
attribute that it
does not recognize
as a
recoverable error
and handle the xi:include
element as described in
4.6 Fallback Behavior.
Note:
For interoperability between validating and non-validating systems, whitespace should not appear in the parse attribute.
When the parse
attribute specifies XML
processing, the XPointer (see [XPointer Framework])
contained in the xpointer
attribute is evaluated to identify
a portion of the resource to include.
See 3.1.1 The xpointer and fragid attributes for more information.
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 XML processing, the value
is interpreted as an XPointer (see [XPointer Framework]); for
text processing,
it is interpreted as a [IETF RFC 5147] fragment identifier. For other values
of parse
, implementations
should process fragment identifiers per the
relevant media type
(i.e., media types registered per [IETF RFC 4288]),
but the interpretation
is not defined by this specification.
See 3.1.1 The xpointer and fragid attributes for more information.
The set-xml-id
attribute applies only when parsing XML.
It is a fatal error to specify the
set-xml-id
attribute when text processing is specified. If
the set-xml-id
attribute is specified on
xi:include
:
When the value of the set-xml-id
attribute is not the empty
string, an
xml:id
attribute will be added to all
top-level included items
that are element
information items.
The value of the xml:id
attribute will be the value of the
set-xml-id
attribute on the xi:include
element.
If a
top-level included item
has an xml:id
attribute, its value will be changed to the
value of the set-xml-id
attribute.
When the value of the set-xml-id
attribute is the empty string,
the xml:id
attribute will be removed from all
top-level included items,
if it is present.
For non-XML processing, 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
processing the resource as XML.
The value of the accept
attribute may be used by
the XInclude processor to aid in content negotiation. When the
XInclude processor fetches a resource via HTTP, it
should place the
value of the accept
attribute, if one exists, in
the HTTP request as an Accept
header as
described in section 14.1 of [IETF RFC 2616]. Values containing
characters outside the range #x20 through #x7E are disallowed
in HTTP headers, and must
be flagged as fatal errors.
The value of the accept-language
attribute may be used by
the XInclude processor to aid in content negotiation. When the
XInclude processor fetches a resource via HTTP, it
should place the
value of the accept-language
attribute, if one exists, in
the HTTP request as an Accept-Language
header as
described in section 14.4 of [IETF RFC 2616]. Values containing
characters outside the range #x20 through #x7E are disallowed
in HTTP headers, and must
be flagged as fatal errors.
http://www.w3.org/2001/XInclude/local-attributes
namespaceThese attributes are used for copying values into attributes that are not in any namespace, see 4.3 Attribute Copying when processing XML.
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.1
processors.
The children property of the
xi:include
element may
include a single xi:fallback
element; the appearance of
more than one xi:fallback
element, an
xi:include
element, or any other element from the
XInclude namespace is a fatal error.
Other content (text, processing instructions, comments, elements not
in the XInclude namespace, descendants of child elements) is not
constrained by this specification and is ignored by the XInclude
processor, that is, it has no effect on include processing, and does
not appear in the children
properties of the result infoset. Such content might be used by
applications analyzing a pre-inclusion infoset, or be made available
to an application post-inclusion through means other than the normal
infoset properties.
The following (non-normative) DTD fragment illustrates a sample
declaration for the xi:include
element:
<!ELEMENT xi:include (xi:fallback?)> <!ATTLIST xi:include xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude" xmlns:xila CDATA #FIXED "http://www.w3.org/2001/XInclude/local-attributes" href CDATA #IMPLIED parse CDATA "application/xml" xpointer CDATA #IMPLIED fragid CDATA #IMPLIED set-xml-id CDATA #IMPLIED encoding CDATA #IMPLIED accept CDATA #IMPLIED accept-language CDATA #IMPLIED >
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
specifies XML processing,
then the xpointer
attribute is used; otherwise the
fragid
attribute is used.
The xpointer
attribute must not be present when
text processing is specified.
It is a fatal error
to specify
the xpointer
attribute when
text processing is specified.
The xpointer
and fragid
attribute are optional.
When neither is specified:
the href
attribute must be
present and
the entire resource is included.
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.
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 an
xi: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.1
processors.
The following (non-normative) DTD fragment illustrates a sample
declaration for the xi:fallback
element:
<!ELEMENT xi:fallback ANY> <!ATTLIST xi:fallback xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude" >
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.
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 text, or it may be unable to access another
part of the document when
parsing as XML and using 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.
href
attribute valuesThe value of this attribute is an XML resource identifier 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].
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 can use the accept
and accept-language
attributes
to increase the probability that the resource is provided in the
expected format.
When processing 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
those in the
XPointer
Registry. An error
in the XPointer is a resource
error.
The set of top-level included items is derived from the acquired infoset as follows.
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.
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.
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.
The inclusion target might be a location set that represents a point. In this case the set of included items is empty.
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.
It is a fatal error for the inclusion target to be an attribute node or a namespace node.
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 processing 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 processing XML.
An xi:include
element pointing to any include
element or ancestor thereof which has already been processed
at a higher level.
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.
The effect of attribute copying depends on the namespace
of the attribute on the xi:include
element.
If the attribute is not in a namespace or is in the xml:
namespace, it is ignored by attribute copying.
If the attribute is in the http://www.w3.org/2001/XInclude/local-attributes
namespace, it
is copied without its namespace onto every
top-level included item that is an element
information item. In other words an attribute with the local name
foo
and the namespace name http://www.w3.org/2001/XInclude/local-attributes
on the xi:include
element will be copied as an attribute
with the local name foo
in no namespace.
Any other attributes
that appear on the
xi:include
element will be copied onto every
top-level included item that is an element
information item.
In all cases when an attribute is copied, if the element
information item already has an attribute with the same
name, its value is changed to the value specified on the
xi:include
element.
What this means in practice is that an author can use namespace
qualified attributes on the xi:include
elements to pass
information through to the XIncluded document. Subsequent processing
on the XIncluded document can use this information to repair any
errors introduced. For example, an attribute could be used to indicate
how duplicate IDs are to be repaired.
Also, while attributes in xml:
namespace
are not copied, it is possible to use the set-xml-id
attribute to change xml:id
attributes on XIncluded
elements.
When processing 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 as follows (terminology as defined in sections 2.2 and 2.3 of [IETF RFC 7303]):
If external (out-of-band) information supplies encoding information, it is used.
Otherwise, by cases, depending on whether, and if so what, MIME information is available:
For XML MIME entities:
follow the guidelines given in section 3.2 of [IETF RFC 7303] or its successors;
For MIME entities which are not XML MIME entities:
As determined by a BOM (see Section 3.3 of [IETF RFC 7303]) if it is present;
In the absence of a BOM (Section 3.3), as determined by the charset parameter if it is present.
In the absence of a charset parameter, the value of the
encoding
attribute on the xi:include
element, if it exists.
Otherwise, UTF-8
For non-MIME entities:
If external (out-of-band) information identifies them as XML, then according to section 4.3.3 of [XML 1.0];
If it is not identified as XML, the value of the
encoding
attribute on the xi:include
element, if it 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.
parse
When processing as neither XML nor text, the include location is dereferenced and the resource is fetched and transformed into information items through some implementation-defined process.
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.
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 processing text.
Likewise, it can contain a simple string when processing XML.
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.
<x xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="something.xml"/> <xi:include xpointer="element(x/1)" parse="application/xml"/> </x>
An XInclude processor may, at
user option, suppress xml:base
and/or xml:lang
fixup.
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.
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.
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.
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.
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.
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.
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.
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.
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 schemes other than element() might not be supported by all conformant XInclude implementations.
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.
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>
The following XML document includes a "working example" into a document.
<?xml version='1.0'?> <document xmlns:xi="http://www.w3.org/2001/XInclude"> <p>This document has been accessed <xi:include href="count.txt" parse="text/plain"/> times.</p> </document>
where count.txt contains:
324387
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>This document has been accessed 324387 times.</p> </document>
The following XML document includes a "working example" into a document.
<?xml version='1.0'?> <document xmlns:xi="http://www.w3.org/2001/XInclude"> <p>The following is the source of the "data.xml" resource:</p> <example><xi:include href="data.xml" parse="text/plain"/></example> </document>
data.xml contains:
<?xml version='1.0'?> <data> <item><![CDATA[Brooks & Shields]]></item> </data>
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>The following is the source of the "data.xml" resource:</p> <example><?xml version='1.0'?> <data> <item><![CDATA[Brooks & Shields]]></item> </data></example> </document>
The following illustrates the results of including fragments of
another XML document. Assume the base URI of the document is
http://www.example.com/JoeSmithQuote.xml
.
<?xml version='1.0'?> <price-quote xmlns:xi="http://www.w3.org/2001/XInclude"> <prepared-for>Joe Smith</prepared-for> <good-through>20040930</good-through> <xi:include href="price-list.xml" xpointer="w002-description"/> <volume>40</volume> <xi:include href="price-list.xml" xpointer="element(w002-prices/2)"/> </price-quote>
price-list.xml references a DTD which declares the id
attributes as type ID
, and contains:
<?xml version='1.0'?> <!DOCTYPE price-list SYSTEM "price-list.dtd"> <price-list xml:lang="en-us"> <item id="w001"> <description id="w001-description"> <p>Normal Widget</p> </description> <prices id="w001-prices"> <price currency="USD" volume="1+">39.95</price> <price currency="USD" volume="10+">34.95</price> <price currency="USD" volume="100+">29.95</price> </prices> </item> <item id="w002"> <description id="w002-description"> <p>Super-sized widget with bells <i>and</i> whistles.</p> </description> <prices id="w002-prices"> <price currency="USD" volume="1+">59.95</price> <price currency="USD" volume="10+">54.95</price> <price currency="USD" volume="100+">49.95</price> </prices> </item> </price-list>
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'?> <price-quote xmlns:xi="http://www.w3.org/2001/XInclude"> <prepared-for>Joe Smith</prepared-for> <good-through>20040930</good-through> <description id="w002-description" xml:lang="en-us" xml:base="http://www.example.com/price-list.xml"> <p>Super-sized widget with bells <i>and</i> whistles.</p> </description> <volume>40</volume> <price currency="USD" volume="10+" xml:lang="en-us" xml:base="http://www.example.com/price-list.xml">54.95</price> </price-quote>
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/plain" fragid="line=2,6" href="code.pl"/></pre> <p>There are four of them.</p> </document>
where code.pl contains:
#!/usr/bin/perl -- # --*-Perl-*-- use strict; use English; use Getopt::Std; use vars qw($opt_p $opt_q $opt_u $opt_m); my $usage = "Usage: $0 [-q] [-u|-p|-m] file [ file ... ]\n"; die $usage if ! getopts('qupm'); die $usage if ($opt_p + $opt_u + $opt_m) != 1; my $file = shift @ARGV || die $usage; my $opt = '-u' if $opt_u; $opt = '-p' if $opt_p; $opt = '-m' if $opt_m; while ($file) { print "Converting $file to $opt linebreaks.\n" if !$opt_q; open (F, "$file"); binmode F; read (F, $_, -s $file); close (F); s/\r\n/\n/sg; s/\r/\n/sg; if ($opt eq '-p') { s/\n/\r\n/sg; } elsif ($opt eq '-m') { s/\n/\r/sg; } open (F, ">$file"); binmode F; print F $_; close (F); $file = shift @ARGV; }
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.
<?xml version='1.0'?> <document xmlns:xi="http://www.w3.org/2001/XInclude"> <p>This example includes a range of characters.</p> <pre><xi:include parse="text/plain" fragid="char=100,200;length=758,UTF-8" href="code.pl"/></pre> </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 a range of characters.</p> <pre>_q $opt_u $opt_m); my $usage = "Usage: $0 [-q] [-u|-p|-m] file [ file ... ]\n"; die $usage if ! ge</pre> </document>
The following XML document includes the same element twice, using attribute copying to allow a subsequent process to distinguish them.
<?xml version='1.0'?> <document xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:eg="http://example.org/namespace/example"> <p>This example includes a “definition” paragraph from some document twice using attribute copying.</p> <xi:include eg:root="one" href="src.xml" xpointer="element(def)"/> <xi:include eg:root="two" href="src.xml" xpointer="element(def)"/> </document>
where src.xml
contains:
<document> <para>Some paragraph.</para> <para xml:id="def">Some definition.</para> <para>Some other paragraph.</para> </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" xmlns:eg="http://example.org/namespace/example"> <p>This example includes a “definition” paragraph from some document twice using attribute copying.</p> <para eg:root="one" xml:id="def">Some definition.</para> <para eg:root="two" xml:id="def">Some definition.</para> </document>
The following example demonstrates how set-xml-id
can be
used to change xml:id
values. As before, the following XML document includes
the same element twice, using attribute copying to allow a subsequent
process to distinguish them.
<?xml version='1.0'?> <document xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:eg="http://example.org/namespace/example"> <p>This example shows attribute replacement.</p> <xi:include eg:root="one" set-xml-id="inc1" href="src-2.xml" xpointer="element(note)"/> <xi:include eg:root="two" set-xml-id="inc2" href="src-2.xml" xpointer="element(note)"/> </document>
where src-2.xml
contains:
<document> <note xml:id="note"><p>Consider the <phrase xml:id="wombat">Wombat</phrase>.</p></note> </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" xmlns:eg="http://example.org/namespace/example"> <p>This example shows attribute replacement.</p> <note eg:root="one" xml:id="inc1"><p>Consider the <phrase xml:id="wombat">Wombat</phrase>.</p></note> <note eg:root="two" xml:id="inc2"><p>Consider the <phrase xml:id="wombat">Wombat</phrase>.</p></note> </document>
Observe that the xml:id
attribute on the
included note
element has been replaced by
the set-xml-id
value
from the xi:include
element.
The set-xml-id
attribute
has
no effect on descendants. Subsequent fixup will still be required in
order to make this document valid. Additional fixup would also be
required if the resulting document contained any IDREF pointers to the now
missing “note
” ID.
The following XML document relies on the fallback mechanism to
succeed in the event that the resources example.txt
and
fallback-example.txt
are not available.
<?xml version='1.0'?> <div> <xi:include href="example.txt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:fallback><xi:include href="fallback-example.txt" parse="text/plain"> <xi:fallback><a href="mailto:bob@example.org">Report error</a></xi:fallback> </xi:include></xi:fallback> </xi:include> </div>
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:
<?xml version='1.0'?> <div> <a href="mailto:bob@example.org">Report error</a> </div>
The following XML document specifies the encoding of the included text document. See 4.4 Included Items when processing text.
<?xml version='1.0'?> <document xmlns:xi="http://www.w3.org/2001/XInclude"> <p>This document is about <xi:include href="city.txt" parse="text/plain" encoding="ISO-8859-1"/>.</p> </document>
where city.txt contains:
München
(Encoded in ISO-8859-1, of course.)
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>This document is about München.</p> </document>