Parsing and processing
XInclude
A standard way for one document to include another, by placing an xi:include element where the included content should appear.
XInclude is the sanctioned alternative to external entities: it composes documents without touching the DTD machinery, it can include a fragment by XPointer or a whole file as text, and it can declare a fallback for when the target is unavailable.
It is also a separate processing step. Unless a processor is explicitly asked to perform inclusion, the xi:include element is left exactly where it is — an ordinary element in a namespace, meaning nothing. That is a feature, and it is why a document can appear to lose content when moved between pipelines.
- Defined in
- XInclude 1.0
- Category
- Parsing and processing
- Also written
- xi:include, XML Inclusions
Shown, not asserted
All 2 claims are executed on every test run, against the same engines the tools use. If the behaviour changes, the test fails rather than this page quietly becoming wrong.
Inclusion is opt-in: our pipeline does not perform it, so the element is still there afterwards.
document.xml <x xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="b.xml"/></x>expression count(//*[local-name()='include'])What the engine returns
1And nothing was fetched — the element has no content of its own.
document.xml <x xmlns:xi="http://www.w3.org/2001/XInclude"><xi:include href="b.xml"/></x>expression string-length(string(/x))What the engine returns
0
What catches people out
- Whether inclusion happens is a processor setting, so the same document means different things in different pipelines.
- xi:fallback exists because the target may be missing. Without one, a failed include is an error rather than an empty result.
- Like any inclusion mechanism, it fetches what the document names. Treat a document that XIncludes remote resources with the same suspicion as external entities.
Where it bites
A definition on its own is trivia. These are the pages where this term decides whether a document works.
- XPathlocal-name()Used above, because the element is namespaced and the prefix is the document's choice.
- ToolsXML validatorThe pipeline whose behaviour is asserted here — it parses, it does not include.
Related terms
- External entityAn entity whose replacement text lives outside the document, named by a SYSTEM or PUBLIC identifier and fetched when the entity is referenced.
- NamespaceA URI that qualifies element and attribute names, so identically-named elements from different vocabularies can coexist in one document.
- XXE (XML external entity attack)An attack in which a submitted document declares an external entity so that a trusting parser reads a local file or makes a request on the attacker's behalf.
Get started
Bring order to the XML your team can't afford to ignore.
Create a free account and get a private workspace to search, validate, diff, and monitor your XML feeds, sitemaps, schemas, and vendor integrations.