skip to content

When a WSDL 1.1 contract is split across files, when do you use wsdl:import versus xsd:import, and what goes wrong when they are mixed up?

level: middleimportance: nice to knowfreq 8%

answer

  1. two import statements, two domains
  2. the Note's own example misleads
  3. schema imports live inside types
  4. no namespace coercion
  5. location is only a hint

basics

~20 s

wsdl:import brings in another WSDL description; XML Schema comes in through xsd:import inside an xsd:schema in wsdl:types. The WS-I Basic Profile requires that split, although the WSDL 1.1 Note's own example imports an XSD with wsdl:import.

solid answer

~50 s

WSDL 1.1 gives `wsdl:import` a `namespace` and a `location`, and the Note's authoring-style example uses it to pull in a `.xsd` file. The Note never says how a schema found that way should be processed, so the WS-I Basic Profile 1.1 fixed the rule: `wsdl:import` MUST only import another WSDL description (R2001), schemas MUST be imported with `xsd:import` (R2002), and that `xsd:import` MUST sit inside an `xsd:schema` in `wsdl:types` (R2003). It adds that the imported document's `targetNamespace` MUST equal the import's `namespace` (R2005), `location` MUST be non-empty (R2007) but is only a hint a consumer need not fetch (R2008), and a part may reference schema components only in the schema's own namespace or one it imports directly (R2102). Mixing them up yields a contract one consumer accepts and another rejects or resolves to missing types.

code

xml · 20 lines
xml
<definitions name="OrderService"
    targetNamespace="http://example.com/orders/service"
    xmlns:defs="http://example.com/orders/definitions"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns="http://schemas.xmlsoap.org/wsdl/">

  <!-- another WSDL: messages and portType -->
  <import namespace="http://example.com/orders/definitions"
          location="orders-abstract.wsdl"/>

  <types>
    <xsd:schema>
      <!-- import-only schema: no targetNamespace needed -->
      <xsd:import namespace="http://example.com/orders/schema"
                  schemaLocation="orders.xsd"/>
    </xsd:schema>
  </types>

  <!-- binding of defs:OrderPortType and the service follow -->
</definitions>

go deeper

for a junior

Remember the domains: wsdl:import is for WSDL files, xsd:import is for schemas and belongs inside an xsd:schema in types.

for a middle

Explain the Basic Profile rules — WSDL-only wsdl:import, schema import inside types, matching namespaces, location as a hint — and why the Note's own example breaks them.

for a senior

Diagnose a contract that generates with one toolkit and fails with another by checking import domains, coerced namespaces and nested-import references.

for a principal

Set a layering convention for published contracts — shared schemas, abstract definitions, bindings — so many teams can reuse them without import ambiguity.

## Why a WSDL gets split at all Real contracts are rarely one file. The **data model** (XML Schema) is often shared by several services, the **abstract definitions** (messages and portTypes) are owned by the service designer, and the **bindings and services** change per deployment. The WSDL 1.1 Note encourages exactly this layering in its section on authoring style, using imports to join the pieces. Two different import statements are involved, and they belong to two different languages. | Statement | Language | Imports | Where it sits | Location attribute | |---|---|---|---|---| | `wsdl:import` | WSDL 1.1 | another WSDL description (its messages, portTypes, bindings, services) | directly under `wsdl:definitions`, before the other WSDL elements | `location`, which the Profile requires to be non-empty | | `xsd:import` | XML Schema | schema components (elements, types) from another namespace | inside an `xsd:schema` element within `wsdl:types` | `schemaLocation`, optional in XML Schema | ## Where the confusion comes from The WSDL 1.1 Note's own Example 2 places `<import namespace="http://example.com/stockquote/schemas" location="http://example.com/stockquote/stockquote.xsd"/>` directly under `definitions`, so a WSDL import fetches an XSD file. The Note never says how a processor should treat a non-WSDL document there, which left the behaviour to each implementation. The **WS-I Basic Profile 1.1** calls that example incorrect and confines each import to its own domain. ## The Basic Profile's import rules The rule numbers below are from Basic Profile 1.1 and are kept unchanged in 1.2: - **R2001** — a description MUST only use the WSDL `import` statement to import another WSDL description. - **R2002** — to import XML Schema definitions, a description MUST use the XML Schema `import` statement. - **R2003** — that `xsd:import` MUST appear only within the `xsd:schema` element of the `types` section. - **R2005** — the `targetNamespace` of an imported WSDL MUST equal the `namespace` attribute on the importing `wsdl:import`; the Profile calls anything else *namespace coercion* and disallows it. - **R2007** — `wsdl:import` MUST carry a non-empty `location`. - **R2008** — a consumer MAY, but need not, retrieve the document at that location; the Profile calls the value a hint. - **R2022 / R2023** — `wsdl:import` elements come before all other WSDL elements except `documentation`, and `wsdl:types` comes next. - **R2102** — a QName reference to a schema component MUST use either the `targetNamespace` of the `xsd:schema` or a namespace that schema `xsd:import`s directly; namespaces reachable only through nested imports do not count. - **R2105** — every `xsd:schema` in `types` needs a `targetNamespace`, unless its only children are `xsd:import` and `xsd:annotation`. That exception is what makes the common "import-only" schema legal. ## What goes wrong when they are mixed up 1. **A schema imported with `wsdl:import`.** A Profile-conformant consumer has no schema bringing that namespace into scope, so a part such as `element="ord:OrderRequest"` refers to a namespace that, under R2102, it may not reference. Whether generation succeeds now depends on how lenient the consumer is — the classic "works with one toolkit, fails with another" contract. 2. **A nested import relied upon.** Schema A imports schema B, which imports schema C, and a message part references C directly. R2102 forbids that reference; the fix is to import C explicitly in the schema the WSDL references from. 3. **A coerced namespace.** The importer declares `namespace="urn:example:v2"` for a document whose `targetNamespace` is still `urn:example:v1`. R2005 forbids this, and the importer's QNames will not match the imported components. 4. **A location assumed to be fetched.** Because `location` is a hint (R2008), a consumer working offline or from a local catalogue may never fetch it, so a contract that only works when every location resolves over the network is fragile. ## How WSDL 2.0 settles the same question WSDL 2.0 keeps XSD's two-statement model and makes it explicit in its own language. `wsdl:include` brings in components from documents with the **same** target namespace, which MUST match. `wsdl:import` declares a **foreign** namespace: its `namespace` MUST NOT equal the importing document's own `targetNamespace`, its `location` is optional, and any document referencing a foreign component MUST import that namespace. Schemas still arrive through `xs:import` inside `types`. ## A reading habit for partner contracts - List every `wsdl:import` and confirm each `location` points at a WSDL whose `targetNamespace` equals the import's `namespace`. - List every `xsd:import` and confirm it sits inside an `xsd:schema` in `types`. - Check that each message part's prefix resolves to a schema's own namespace or one that schema imports directly. - Keep local copies of every imported document, since nothing obliges a consumer to fetch them at generation time.

  • Must a WSDL consumer download the document named in a wsdl:import location?
    No. The Basic Profile requires the `location` to be present and non-empty (R2007), but says a consumer MAY, but need not, retrieve it (R2008): the value is a hint, and a processor may locate a description for that namespace some other way, such as a local catalogue. A contract should therefore not depend on every location resolving over the network.
  • Why does WSDL 2.0 have both include and import?
    They mirror XML Schema's include and import. `wsdl:include` merges components from documents that share the including document's target namespace, and the namespaces MUST match. `wsdl:import` declares a foreign namespace whose components the document references; its namespace MUST differ from the document's own, and its location is optional because it is only a hint.

saying these in an interview costs you the question

  • wsdl:import is the correct way to pull an XSD file into a WSDL.
  • xsd:import can sit directly under wsdl:definitions, outside the types section.
  • Every consumer must fetch whatever a wsdl:import location points at.
  • An importer's namespace attribute can rename an imported WSDL's target namespace.
  • A message part may reference types reachable only through nested schema imports.