Tip: Use XInclude to synchronize WSDL with source schemata

Importing the payload format for document/literal message descriptions

Uche Ogbuji (uche@ogbuji.net), Principal Consultant, Fourthought, Inc.

Uche Ogbuji is a consultant and co-founder of Fourthought Inc., a software vendor and consultancy specializing in XML solutions for enterprise knowledge management. Fourthought develops 4Suite, an open source platform for XML, RDF, and knowledge-management applications. Mr. Ogbuji is a computer engineer and writer born in Nigeria, living and working in Boulder, Colorado, USA. You can contact Mr. Ogbuji at uche@ogbuji.net.

Summary: In the document/literal style of Web services, the schemas of the interchange formats are often based on an existing document standard. This can cause problems synchronizing WSDL files with the standard schemata. This tip shows how to use XInclude to incorporate external schema fragments into a WSDL file.

View more content in this series

Tag this!

Date: 22 Jan 2004
Level: Intermediate
Activity: 1734 views

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.

Listing 1. A sample document to be sent 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

Listing 2. W3C XML Schema for literal document to be transmitted

<?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.

Listing 3. A portion of a WSDL file that uses XInclude to incorporate an XML schema

  <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.

Listing 4. Variation on Listing 3 that uses older XPointer conventions

  <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. For a complete list of XML tips to date, check out the tips summary page.
Learn how you can become an IBM Certified Developer in XML and related technologies.

About the author

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=XML, SOA and Web services

ArticleID=12363

ArticleTitle=Tip: Use XInclude to synchronize WSDL with source schemata

publish-date=01222004

author1-email=uche@ogbuji.net

author1-email-cc=