XSD guide
XSD include vs import
Use xs:include for one namespace and xs:import across namespaces, then make schema resolution deterministic in local and deployed environments.
7 min read · Updated 2026-08-21
The short answer
Use xs:include to assemble schema documents for the same target namespace. Use xs:import when referenced components belong to a different target namespace. In both cases, treat schemaLocation as a resolver hint and test the complete schema set through the same catalog used in production.Include extends the current namespace
An included schema normally has the same targetNamespace as the including schema. A no-namespace schema can also be included as a chameleon schema, adopting the includer's namespace, but that flexibility makes reuse and diagnostics harder to reason about.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="urn:example:catalog"
targetNamespace="urn:example:catalog">
<xs:include schemaLocation="catalog-types.xsd"/>
<xs:element name="catalog" type="tns:CatalogType"/>
</xs:schema>Import crosses a namespace boundary
An import names the external target namespace, while schemaLocation suggests where its schema document can be found. Bind that namespace to a prefix and use qualified type or element references in the importing schema.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:money="urn:example:money"
targetNamespace="urn:example:orders">
<xs:import namespace="urn:example:money" schemaLocation="money.xsd"/>
<xs:element name="total" type="money:Amount"/>
</xs:schema>Control schema resolution explicitly
Relative schema locations depend on a stable base URI. Uploading or copying only the top-level XSD loses that context, while network fetching introduces availability and security risks. Package the schema set or map namespace URIs through a catalog.
- Keep import and include declarations before component definitions.
- Preserve relative directory structure when shipping a schema set.
- Disable arbitrary network resolution and allow only known schema sources.
- Test that a clean environment can resolve the set without editor caches.
Prove the fix
- Validate the complete schema setConfirm imported types resolve before testing a large production instance.
- Review xs:includeCheck same-namespace composition and required schemaLocation behavior.
- Review xs:importCheck cross-namespace composition and qualified references.
Related guides
- How to validate XML against an XSDSeparate parsing from schema validation, load the complete schema set, and reduce validation errors to the smallest failing instance.
- XSD sequence vs choiceWhen child order is fixed, when alternatives are exclusive, and how minOccurs and maxOccurs change the meaning of an XSD compositor.
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.