First published by IBM at http://www-106.ibm.com/developerworks/xml/library/x-tipxinc.html

In the types section of a WSDL file, you provide XML schema snippets to formalize the XML that is exchanged in the Web service. In most mainstream cases, this means the contents of the SOAP body. In the RPC style of Web services, this is usually a specialized XML format that maps W3C XML Schema (WXS) constructs to the SOAP encoding. This is usually very specific to the Web service, and not really useful outside it. This separation between the XML that is likely to be used at application level at either end-point and the format that ends up being transmitted across the wire is often key to criticism of RPC-style Web services, and the basis for advocacy of document/literal style. If you aren't familiar with document/literal style, see the introductions in Resources.

In document/literal style, the XML format that is most immediately meaningful to the processing on either side is simply bundled into the envelope and transmitted as is. This means that the schema details that go into the types section of the WSDL are often just a part of a more generally used schema. It may even be a globally well known schema such as XHTML, Docbook, or one of the many XML formats for business interchange, such as UBL or OAGIS. This means that embedding the schema into WSDL documents could open up synchronization or consistency problems. What happens when the overall schema changes and one does not catch up to all the WSDL that needs to be touched up accordingly? It could lead to subtle problems or big failures.

An infusion of inclusion
W3C XInclude specifies a processing model and syntax for expanding a reference to an external document into the actual XML in that document (or a part thereof). This process is called inclusion and is similar to, say, #include in C or C++. In technical terms, XML inclusion is accomplished by merging a number of XML information sets into a single composite Infoset. If a schema file is hosted somewhere, it can then be included in a WSDL file. As an example, say you want to send a document such as that in Listing 1 in a literal Web service.

<?xml version="1.0" encoding="iso-8859-1"?>
<labels>
  <label>
    <quote>
      Midwinter Spring is its own season
    </quote>
    <name>Thomas Eliot</name>
    <address>
      <street>3 Prufrock Lane</street>
      <city>Stamford</city>
      <state>CT</state>
    </address>
  </label>
  <label>
    <name>Ezra Pound</name>
    <address>
      <street>45 Usura Place</street>
      <city>Hailey</city>
      <state>ID</state>
    </address>
  </label>
</labels>
      

This format is formalized in a W3C XML Schema such as in Listing 2

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified"
>
  <xs:element name="labels">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" maxOccurs="unbounded" ref="label"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="label">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="0" ref="quote"/>
        <xs:element ref="name"/>
        <xs:element ref="address"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="quote">
    <xs:complexType mixed="true">
      <xs:sequence>
        <xs:element ref="emph"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="emph" type="xs:string"/>
  <xs:element name="name" type="xs:string"/>
  <xs:element name="address">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="street"/>
        <xs:element ref="city"/>
        <xs:element ref="state"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="street" type="xs:string"/>
  <xs:element name="city" type="xs:string"/>
  <xs:element name="state" type="xs:string"/>
</xs:schema>
      

Listing 3 is the types section from a WSDL file that includes the required portion of the schema definition.

  <types xmlns:xi="http://www.w3.org/2001/XInclude">
    <schema>
      <xi:include
        href="http://example.com/labels.xsd"
        xpointer="xmlns(xs=http://www.w3.org/2001/XMLSchema)
                  xpointer(/xs:schema/*)"
      />
    </schema>
  </types>
      

Just the bits I need, please
The example in Listing 3 is not just a straightforward inclusion of an entire file. I only need the element definitions from the schema file for the WSDL and so I use XPointer to extract this subset from the overall schema. XPointer defines several schemes for such extraction. The xmlns(...) scheme defines namespace mappings, and the xpointer(...) scheme specifies the expression that defines the subset of the document to be used. It is based on XPath, and the expression /xs:schema/* has the same meaning as in XPath, selecting only the children of the xs:schema element.

Warning: The XPointer syntax is the correct and current one as of the Working Draft dated 10 November 2003, but this is a change from the previous way of expressing XPointer in XInclude. In my testing, I found that tools have not yet been updated to this convention, so you may have to temporarily use the old equivalent, which I provide in Listing 4.

  <types xmlns:xi="http://www.w3.org/2001/XInclude">
    <schema>
      <xi:include
        href="http://example.com/labels.xsd#
                  xmlns(xs=http://www.w3.org/2001/XMLSchema)
                  xpointer(/xs:schema/*)"
      />
    </schema>
  </types>
      

Note: The part starting with "xmlns(" would normally be right after the hash rather than on the following line, but I added a line break for formatting.

Wrap-up
XInclude is simple and is supported by many XML tools. It is a handy tool for many situations, and can certainly help improve the maintenance of document/literal style WSDL documents.

Resources

• Get solid background on the document/literal style of Web services with "Reap the benefits of document style Web services" by James McCarthy (developerWorks, June 2002) and "Which style of WSDL should I use?" by Russell Butek (developerWorks, October 2003).
  
  
• Check out "Deploying Web services with WSDL" by Bilal Siddiqui (developerWorks, November 2001). This article covers an older version of WSDL.
  
  
• See the current specification Web Services Description Language (WSDL) Version 1.2. For an introduction that offers a peek at the future see WSDL Version 2.0 Part 0: Primer.
  
  
• Read Uche Ogbuji's developerWorks tutorial "Develop Python/XML with 4Suite, Part 4: Composition and updates", which introduces XInclude and XPointer, although it covers the earlier XInclude conventions (October 2002).
  
  
• Elliotte Rusty Harold's "Using XInclude" is a strong introduction, although it covers the earlier XInclude conventions.
  
  
• Take the ZVON tutorials on XInclude and XPointer. Again, the XInclude tutorial covers the earlier XInclude conventions.
  
  
• If you need more details, seek out the XML Inclusions (XInclude) 1.0 and XPointer Framework specifications on the W3C site.
  
  
• Find a broad array of articles, columns, tutorials, and tips on these two popular technologies at the developerWorks Web services and XML content areas.
  
  
• Learn how you can become an IBM Certified Developer in XML and related technologies.