Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples

An Introduction to WSIL

by Timothy Appnel

The Web Service Inspection Language (WSIL) is an XML document format to facilitate the discovery and aggregation of Web service descriptions in a simple and extensible fashion. While similar in scope to the Universal Description Discovery and Integration (UDDI) specification, WSIL is a complementary, rather than a competitive, model to service discovery.

Since its release, UDDI has been widely criticized for its implementation, and its relevance questioned repeatedly at this stage of Web services architecture development. Created by a group of IBM and Microsoft engineers and released in November 2001, WSIL is significant because of its simpler document-based approach, which is more lightweight and straightforward and better leverages existing Web architectures. This approach could lead to this specification's rise to prominence.

In this article, I will cover the core elements of the WSIL specification, including how WSIL inspection documents are located. Additionally, I will take a cursory look at the specification's extensibility with service descriptions such as WSDL, and point out some problematic issues in the specification. First, let's return to the complementary and contrasting approaches UDDI and WSIL employ in service discovery.

WSIL and UDDI: Same Space, Different Models.

WSIL and UDDI assist in the publishing and discovery of services, but their models are distinctly different. In this section, we'll go a bit deeper into these differences.

Related Reading

Java Web Services
By David A. Chappell, Tyler Jewell

UDDI implements service discovery using a centralized model of one or more repositories containing information on multiple business entities and the services they provide. You could compare UDDI to the Yellow Pages in your phone book, where multiple businesses are grouped and listed with a description of the goods or services they offer and how to contact them. The specification provides a high level of functionality through Simple Object Access Protocol (SOAP) by requiring specifically an infrastructure to be deployed with substantial overhead and costs associated to its use.

WSIL approaches service discovery in a decentralized fashion, where service description information can be distributed to any location using a simple extensible XML document format. Unlike UDDI, it does not concern itself with business entity information, nor does it specify a particular service description format. WSIL works under the assumption that you are already familiar with the service provider, and relies on other service description mechanisms such as the Web Services Description Language (WSDL).

WSIL documents are located using a few simple conventions using existing Web infrastructure. In many ways, WSIL is like a business card -- it represents a specific entity, its services, and contact info, and is typically delivered directly by whom it represents. The low functionality and lightweight nature of WSIL leaves the processing for the developer to implement. WSIL begins to break down and become too unwieldy to search or manage if a given document grows too large, or a collection of documents aggregates too deep. Eventually, development effort will diminish as WSIL toolkits are developed, like the one found in the Apache Software Foundation's Axis project [1].The low functionality of a simple XML document format also provides the flexibility for novel and innovative applications of this information to be easily created.

As you can see, while UDDI and WSIL are both mechanisms for Web services discovery, their models are quite different. Deciding which you should use depends on your situation. In many cases, it may be advantageous to use both. As you will see, WSIL can be used to "point" to UDDI repositories and the service descriptions therein.

The WSIL model is more RESTful than UDDI. In many ways, WSIL is like RDF Site Summary (RSS) for Web services. RSS is a file format with pointers to published content that can be syndicated and aggregated. WSIL is a file format with references to published Web services that can be discovered and bound.

WSIL Basics

The WSIL specification was designed to provide a means of service discovery that is simple, lightweight, and extensible. Furthermore, WSIL was designed so information could be easily authored, published, and maintained. The core WSIL specification elements consist of six tags. In this section I will review the basic WSIL document structure syntax before examining how, through the use of XML namespaces, WSIL can be extended to support additional infosets that some service descriptions and aggregations require for the discovery process. For more in-depth information about WSIL, read the WSIL 1.0 specification .

Example 1: A Simple WSIL File Example

<?xml version="1.0" encoding="UTF-8"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
   <abstract>Acme Industries Public Web Services</abstract>
      <name>Store Finder Service</name>
      <abstract>A service to perform a geographical search of Acme 
	        store locations.</abstract>
      <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
   <link referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/" 
         location="http://example.org/services/ecommerce.wsil" >
      <abstract>Acme Industries Public e-Commerce Services</abstract>

At the root of all WSIL documents is the inspection tag. This tag contains the namespace declarations for the document, in addition to all other service information and references tags. Since this is a relatively simple WSIL document, only the WSIL namespace is defined.

The abstract tag is an optional tag that can be inserted into any tagset that allows for children to provide a text description to document its parent. Here we provide a short text description ("Acme Industries Public Web Service") for the inspection file. Later in our files, we also use the abstract tag to provide some documentation on our service and the link to another inspection document. If the description had been written in a specific language, I could have optionally defined a xml:lang attribute, like in the XML 1.0 specification.

In this simple example, we are defining a reference to just one service description, such as a WSDL file, beginning with the service tagset. name, like the abstract tag, is an optional tag that allows authors to document the enclosing service with a descriptive name, such as "Store Finder Service." This name is for documentation purposes only and does not necessarily have to be unique. Also, like the abstract tag, name allows an optional xml.lang attribute to be defined in specifying the language used.

The description tagset is the workhorse of the service block, as it contains all of the information necessary to discover a specific service description. In our example, we are only referencing a WSDL file that defines a single service description, requiring no additional information for a consumer to retrieve. The description tag uses a required attribute of referencedNamespace to indicate the namespace of the service description. This namespace reference can be used in determining the relevance of the reference and whether to retrieve the service description at the end of the reference. The description also uses an optional location attribute to define a direct reference to the service's description. This mechanism is sufficient for our simple reference; however, WSIL's extensibility can be utilized to insert additional information into the description tagset for the consumer to retrieve the service description. A service block can have multiple description tags to provide consumers different service description options. For instance a service could define references to a WSDL file, a UDDI repository entry, and an HTML document.

Besides references to service descriptions, WSIL supports links to other aggregations of service pointers, such as another WSIL file or a UDDI repository. This is facilitated by the link tagset. Like the service block's description tag, the link tagset implements referencedNamespace and location in the same manner. Similarly, it can contain extended WSIL elements in enabling consumers to connect to this aggregation. In our example, we link to another WSIL document, presumably with service descriptions of Acme Industries e-commerce services.

Locating WSIL Files

Once an inspection document has been created, a consumer needs to be able to find it. WSIL's decentralized document-based model would make locating these files difficult if it were not for a couple of simple conventions defined in the specification.

The first convention employs the use of a fixed filename of inspection.wsil located in common entry points. Consumers would only need to ping a URL such as http://example.org/inspection.wsil or http://examples.org/services/inspection.wsil to discover the file's existence for retrieval.

The second convention employs embedded references in other documents, such as HTML or other WSIL documents. WSIL advocates use of a meta tag in an HTML document that establishes a link to the inspection documentation location. This is similar in nature to the way stylesheets, RSS syndication files, and weblog channel rolls can be autodiscovered. (However, they make use of the HTML's link, which is the appropriate tag to use for this function.)

A Hypothetical Use of WSIL by Google

Let's suppose for a moment that Google launched its Web services API without the fanfare with which it was greeted. How would Google "advertise" the availability of their services, particularly to other Web-services-aware applications? How would a service consumer discover and bind to Google's services?

First, Google would start by creating a WSIL document. Example 2 is what their inspection document might look like. In keeping it simple, I'm assuming once again the WSDL file contains only one service description.

Example 2: A Hypothetical WSIL for Google

<?xml version="1.0" encoding="UTF-8"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
   <abstract>The Google Search API</abstract>
      <abstract>Google Search</abstract>
      <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/" 
      <description referencedNamespace="http://www.w3.org/1999/xhtml" 

Note the two description tags in the service block. One points to a WSDL file, and the other to an a XHTML document, presumably with a description of the service. (This HTML document doesn't actually exist on Google's site, but it illustrates WSIL's ability to reference multiple, different service descriptions for different purposes.)

Once the inspection document has been created, Google could place it at http://www.google.com/inspection.wsil or perhaps http://api.google.com/inspection.wsil. Google could also embed the following HTML in its Web pages:

<meta name="serviceInspection" content="http://www.google.com/inspection.wsil" />

There is no cost to doing both. In fact, it's advantageous to do so, because it gives potential service consumers the option of locating the inspection document as they prefer.

WSIL Extensibility

The WSIL specification provides for a certain amount of extensibility through the use of XML namespaces. This extensible mechanism is important because it allows for the evolution of service descriptions and repositories without having to revise the base specification.

Currently, the WSIL specification defines extensions for WSDL and UDDI. Example 3 illustrates what an inspection file referencing a complex WSDL file or a UDDI repository might look like. In sticking to the basics, we won't go into the details of how these extensions are utilized.

Example 3: A Sample WSIL document With WSDL and UDDI Extensions

<?xml version="1.0" encoding="UTF-8"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
 xmlns:wsiluddi="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/" >
  <abstract>Acme Industries Public Web Services</abstract>
    <name>Store Finder Service</name>
      <abstract>A service to perform a geographical search of Acme 
	        store locations.</abstract>
      <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/" 
   <link referencedNamespace="urn:uddi-org:api">
      <abstract>Acme Industries Public e-Commerce Services</abstract>
         <wsiluddi:discoveryURL useType="businessEntity">

In this example, unlike the previous examples, we make reference to a WSDL file that is presumed to have multiple service descriptions, of which we identify StoreFinder as the reference description. We also provide a link to a UDDI repository that contains the service descriptions for Acme Industries.

Simplicity begins to give way to extensibility, but the utility and adaptability provided makes it a reasonable tradeoff.

Other bindings for service description mechanisms are easily authored by following a few simple rules, which are documented in section 5.0 of the WSIL 1.0 specification.

XMethods, a directory of publicly-available Web services, is an earlier adopter of WSIL and has developed a binding extension for its service. A section of their WSIL file is listed in example 5.

Example 4: A subset of XMethods.net's WSIL File

    <abstract>Develop Your Own Applications Using Google</abstract>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"  
    <description referencedNamespace="http://www.xmethods.net/">

The extension defined by the wsilxmethods provides a URI of a dynamically-generated HTML page detailing the service. The extension also provides the service's XMethod ID separately, which could be helpful in utilizing other functionality of the XMethods directory.

A Good Start That Is Far From Perfect

Hopefully, at this point you now understand the advantages and utility of WSIL in Web service discovery, and are interested in putting it to use. IBM and Microsoft have done an admirable job in developing WSIL, but it does suffer from issues that are commonplace in the initial release of a specification that was developed by a closed select committee.

Here I will note some of these issues that I found in my review of the specification. It is by no means a complete and thorough list, but simply my personal observations from working with markup languages over the years.


WSIL is a simple, lightweight mechanism for Web service discovery that complements, rather then competes with, UDDI. WSIL's model is a decentralized one that is document-based, and leverages the existing Web infrastructure already in place. While UDDI can be seen as a phone book, WSIL is more like a business card. Looking at it in another way, WSIL is like the RSS of Web services.

I find WSIL intriguing because of its simplicity and lightweight implementation. It's what the Web services space needs now. I would go so far as to argue that WSIL should have preceded UDDI as the solution we all need for services discovery, and is a logical stepping stone towards extensive Web services repository services for those who eventually require them.

As a low-function, lightweight specification that leaves the processing logic to the developer, I am equally as intrigued and enthusiastic about the potential for innovative and novel applications that will undoubtedly arise from the accessibility of this information. Who knows what our understanding of "service discovery" could be in a year or two?

Timothy Appnel has 13 years of corporate IT and Internet systems development experience and is the Principal of Appnel Internet Solutions, a technology consultancy specializing in Movable Type and TypePad systems.

[1] Axis contains the WSIL toolkit that IBM donated to the Apache Project. http://www.oreillynet.com/pub/wlg/2113

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.