Export (0) Print
Expand All

Web Services Inspection Language (WS-Inspection) 1.0

 

Authors:
Keith Ballinger, Microsoft
Peter Brittenham, IBM
Ashok Malhotra, Microsoft
William A. Nagy, IBM
Stefan Pharies, Microsoft

Copyright © 2001 International Business Machines Corporation, Microsoft Corporation

Abstract

The WS-Inspection specification provides an XML format for assisting in the inspection of a site for available services and a collection of rules for how inspection-related information should be made available for consumption. A WS-Inspection document provides a means for aggregating references to pre-existing service description documents which have been authored in any number of formats. These inspection documents are then made available at the point-of-offering of the service as well as through references which may be placed within a content medium such as HTML.

Status

This draft represents the current thinking with regard to locating and inspecting services within IBM and Microsoft. It consolidates concepts found in ADS and DISCO (earlier proposals in this space).

Table of Contents

1 Introduction
   1.1 Design Goals
   1.2 WS-Inspection Document Examples
   1.3 Notational Conventions
2.0 Inspection Document Definition
   2.1 WS-Inspection Document Structure
      2.1.1 Language Extensibility and Bindings
      2.1.2 Documentation
   2.2 Services
      2.2.1 Text Descriptions of Services
      2.2.2 Service Names
      2.2.3 Service Description References
   2.3 Links to Other Inspection Documents and Related Aggregation Information Sources
3.0 WSDL Binding
   3.1 How the WSDL Binding Extends the WS-Inspection Specification
   3.2 wsilwsdl:reference
      3.2.1 wsilwsdl:referencedService
      3.2.2 wsilwsdl:implementedBinding
4.0 UDDI Binding
   4.1 How the UDDI Binding Extends the WS-Inspection Specification
   4.2 wsiluddi:businessDescription
   4.3 wsiluddi:serviceDescription
5.0 Developing Additional Bindings
6.0 Inspection Document Publication
   6.1 Fixed Name Inspection Documents
   6.2 Linked Inspection Documents
      6.2.1 Linking to Inspection Documents within HTML
7.0 References
A 1 Notes on URIs
   A 1.1 XML Namespaces and Schema Locations
   A 1.2 Relative URIs
A 2 The Complete WS-Inspection Grammar
A 3 Schemas
   A 3.1 WS-Inspection Schema
   A 3.2 WSDL Binding Schema
   A 3.3 UDDI v1 Binding Schema
   A 3.4 UDDI v2 Binding Schema

1. Introduction

Recently, a number of specifications have been developed which seek to describe Web Services at varying levels. The proposed standards for describing services at a functional level, WSDL [1], and for describing them from a more business-centric perspective, the UDDI [2] schema, are but two examples. What is missing, however, is the ability to tie together, at the point of offering of the service, these various sources of information in a manner which is both simple to create as well as to utilize. The WS-Inspection specification addresses this need by defining an XML grammar which facilitates the aggregation of references to different types of service description documents, and then provides a well-defined pattern of usage for instances of this grammar. By doing this, the WS-Inspection specification provides a means by which to inspect sites for service offerings.

Because there have already been attempts made to gather together and publish much of the description information at a single location, the WS-Inspection specification also provides a means by which these existing repositories can be referenced and utilized, so as not to have to duplicate information if the duplication is not desired.

1.1 Design Goals

The two major design goals of the WS-Inspection specification are simplicity and extensibility. For the most part, a WS-Inspection document is nothing more than an aggregation of pointers to service description documents. This makes WS-Inspection documents fairly easy to write and maintain. Because a WS-Inspection document may point to a variety of service description document formats, WS-Inspection documents may be created in such a way as to allow the consumer of the document to pick and choose from the available descriptions, and to only access those which they are capable of understanding. As new description formats arise, new references can be added to existing WS-Inspection documents without requiring that a modification be made to the base WS-Inspection schema.

1.2 WS-Inspection Document Examples

The following is an example of a simple WS-Inspection document for a single service which provides stock quote information. The service has a corresponding HTTP accessible WSDL document which describes its interface.

<?xml version="1.0"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
  <service>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/stockquote.wsdl" />
  </service>
</inspection>

The next, more complex example, shows the WS-Inspection document for two sample services which happen to be providing financial tools. The first, a stock quote service, has two available descriptions; one in an HTTP-accessible WSDL document, and the other in a UDDI directory. The second service is described by only an anonymous FTP-accessible WSDL document. The WS-Inspection document also contains a link to another WS-Inspection document.

<?xml version="1.0"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
            xmlns:wsiluddi="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/">
  <service>
    <abstract>A stock quote service with two descriptions</abstract>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/stockquote.wsdl"/>
    <description referencedNamespace="urn:uddi-org:api">
       <wsiluddi:serviceDescription location="http://www.example.com/uddi/inquiryapi">
         <wsiluddi:serviceKey>4FA28580-5C39-11D5-9FCF-BB3200333F79</wsiluddi:serviceKey>
       </wsiluddi:serviceDescription>
    </description>
  </service>
  <service>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="ftp://anotherexample.com/tools/calculator.wsdl"/>
  </service>
  <link referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
        location="http://example.com/moreservices.wsil"/>
</inspection>

A detailed description of the elements used in these two examples can be found in Section 2.

Note: For these examples, the referenced WSDL documents are assumed to each contain a single WSDL service element. See Section 3 for more information.

1.3 Notational Conventions

  1. The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [3].
  2. The following namespace prefixes are used throughout this document:
    prefix namespace URI definition
    wsil http://schemas.xmlsoap.org/ws/2001/10/inspection/ WS-Inspection namespace for the WS-Inspection framework.
    wsilwsdl http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/ WS-Inspection namespace for the WS-Inspection WSDL binding.
    wsiluddi http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/ WS-Inspection namespace for the WS-Inspection UDDI binding.
    uddi urn:uddi-org:api API and document namespace defined by the UDDI v1 specification.
    uddiv2 urn:uddi-org:api_v2 API and document namespace defined by the UDDI v2 specification.
    (other) (various) All other namespace prefixes are samples only. In particular, URIs starting with "http://example.com" represent some application-dependent or context-dependent URI [4].
  3. This specification uses an informal syntax to describe the XML grammar of a WS-Inspection document:
    • The syntax appears as an XML instance, but the values indicate the data types instead of values.
    • Characters are appended to elements and attributes as follows: "?" (0 or 1), "*" (0 or more), "+" (1 or more).
    • Elements names ending in "...…" (such as <element...…/> or <element...…>) indicate that elements/attributes irrelevant to the context are being omitted.
    • Grammar in bold has not been introduced earlier in the document, or is of particular interest in an example.
    • <-- extensibility element --> is a placeholder for elements from some "other" namespace (like ##other in XSD).
    • The XML namespace prefixes (defined above) are used to indicate the namespace of the element being defined.
    • Examples starting with <?xml contain enough information to conform to this specification; others examples are fragments and require additional information to be specified in order to conform.

2.0 Inspection Document Definition

This section describes the core elements of the WS-Inspection language. Binding extensions for WSDL and UDDI are included in Sections 3 and 4.

2.1 WS-Inspection Document Structure

A WS-Inspection document contains an inspection element at the root, and references to individual service descriptions or links to collections of service descriptions as descendants. The grammar of a WS-Inspection document is as follows:

<wsil:inspection>
  <wsil:abstract xml:lang=""? ... /> * 
  <wsil:service> *
    <wsil:abstract xml:lang=""? ... /> *
    <wsil:name xml:lang=""? ... /> *
    <wsil:description referencedNamespace="uri" location="uri"?> *
      <wsil:abstract xml:lang=""? ... /> * 
      <-- extensibility element --> ?
    </wsil:description>
  </wsil:service>
  <wsil:link referencedNamespace="uri" location="uri"?/>  *
    <wsil:abstract xml:lang=""? ... /> * 
    <-- extensibility element --> ?
  </wsil:link>
</wsil:inspection>

with the additional constraint that the inspection element MUST contain at least one service child or one link child, and MAY contain a combination of both. A more exact definition of the grammar, which includes the above constraint, may be found in Appendix 2. Each of the aforementioned elements is described in the corresponding section below.

2.1.1 Language Extensibility and Bindings

In the WS-Inspection specification, the term binding refers to the process of associating specific description format/retrieval related information with a more abstract WS-Inspection entity. For example, hints describing what type of information may be found in a referenced document of a particular type, or information concerning the retrieval of such documents require the use of description format specific bindings. The WS-Inspection specification allows elements representing a specific technology (referred to here as extensibility elements) under both description and link elements. Extensibility elements MUST use an XML namespace different from that of the base WS-Inspection language.

Extensibility elements allow innovation in the area of service description without having to revise the base WS-Inspection specification. This document recommends that specifications defining such description formats also define any necessary WS-Inspection extensions required to reference them.

See Sections 3 and 4 for examples of extensibility elements defined as part of the base WS-Inspection specification.

2.1.2 Documentation

The WS-Inspection specification uses the optional abstract element as a container where a small textual description can be placed. The content of this element is intended for human consumption. The abstract element is allowed inside any base WS-Inspection language element which allows child elements.

An optional xml:lang attribute, as defined in [5], may be specified on the element to indicate the language in which the abstract has been written. Multiple abstract elements which have the same value for the xml:lang attribute MAY appear as siblings.

2.2 Services

The service element acts as the delineator between collections of description references for services. An inspection element may contain any number of service elements within it. Each service element MAY have one or more abstract elements and one or more name elements, and MUST have at least one description element, but MAY have more.

2.2.1 Text Descriptions of Services

One or more abstract elements may be used within a service element to provide a location where a small textual description about the service can be placed. The content of this abstract is intended for human consumption, and is only intended to provide a small fragment of useful information about the service. Upon receiving a WS-Inspection document, a tool may use this field to ask the user if they wish to gain more information about the service, without requiring that any of the referenced descriptions be obtained beforehand. It is not the purpose of this element to replace a more complete service description language.

More complex sets of documentation MAY be added through the use of description elements which point to full fledged description documents.

2.2.2 Service Names

The name element may be used to associate a name with a particular service. As with the abstract element, the name element is intended only for human consumption, and as such is not guaranteed to be unique.

An optional xml:lang attribute may be specified on the element to indicate the language in which the name has been written. Multiple name elements which have the same value for the xml:lang attribute MAY appear as siblings.

2.2.3 Service Description References

The most useful part of the inspection is the information contained within the description elements. These elements can be used to provide pointers to service description documents of various forms, allowing the consumer to process only the ones that they find useful. The referencedNamespace attribute identifies the namespace to which the referenced document belongs. For example, the value of the referencedNamespace attribute on a description element which points to a WSDL document would be "http://schemas.xmlsoap.org/wsdl/". Consumers of WS-Inspection documents may use the referencedNamespace attribute to determine whether or not it is of value to them to retrieve the referenced description document.

The optional location attribute MAY be used to provide the actual reference to the description. The value of the location attribute MUST be a valid URL, and the description MUST be retrievable from that URL using the primary access mechanism for the scheme specified in the URL (e.g. for an HTTP URL, the document must be retrievable by performing an HTTP GET on the provided URL.) If the document cannot be retrieved using the primary access mechanism, or if more information is necessary to perform the retrieval, then that information MUST be specified using the extensibility mechanism.

One extensibility element MAY appear under the description element to provide any additional information which is needed to retrieve or process the service description, or any hints about the contents of the description document which may prove useful for the consumer deciding whether or not that particular service description should be retrieved. The extensibility element used MUST be the supported binding, if one exists, for the document namespace specified by the referencedNamespace attribute of the parent description element. A binding is "supported" if its definition is included as part of this specification, or if it is agreed upon by the controlling body of the specification for the description mechanism which is being bound to. If there is no supported binding for a particular description mechanism, then interoperability is not guaranteed.

While every attempt should be made to insure that the information contained within a WS-Inspection document is accurate, consumers of the document MUST NOT assume that the information provided matches exactly what is in the referenced document. While bindings may be used to provide hints about referenced documents, they MUST NOT be used as the final source of service description information.

Authors of WS-Inspection documents need make every attempt to make sure that the information contained within the documents is accurate, but consumers of the documents MUST NOT assume that the information provided matches exactly what is in the referenced document. The final decision must be made by retrieving and processing the referenced document.

2.3 Links to other Inspection Documents and Related Aggregation Information Sources

The link element allows WS-Inspection documents to reference additional aggregations of service descriptions, such as other WS-Inspection documents or UDDI repositories.

A hierarchy of WS-Inspection documents could be created, for example, using link elements of the following form:

<wsil:link referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
           location="uri of WS-Inspection document">

Because many service descriptions will be published only within other information registries, such as UDDI, the link element may be used to prevent service providers from having to create inspection documents with large numbers of service elements which contain only single description elements, all pointing back to the same location in the information registry. By using link elements of the following form:

<wsil:link referencedNamespace="uri" location="uri"?>
  <-- extensibility element -->
</wsil:link>

the service provider is able to indicate to the consumer of the WS-Inspection link that they should look in the indicated location for additional service description aggregations. This gives the provider the ability to reference the pre-existing information while still allowing it to be discovered through the WS-Inspection inspection process.

The link element MUST only be used to reference well-defined service description aggregations, such as WS-Inspection documents and UDDI businessEntities.

The referencedNamespace attribute on the link element identifies the namespace of the linked aggregation source. The optional location attribute MAY be used to provide the actual link to the source if it is retrievable from the provided URL using the primary access mechanism for the scheme specified in the URL. If the aggregation cannot be retrieved using the primary access mechanism, then that information MUST be specified using the extensibility mechanism.

One extensibility element MAY appear under the link element to provide any additional information which is needed to retrieve the aggregation which has been linked. The extensibility element MUST be a supported binding for the document namespace specified by the referencedNamespace attribute of the parent link element. See Section 2.2.3 for a definition of supported bindings.

The WS-Inspection specification does not specify a pattern for processing the link elements: a consumer MAY follow the links as they so desire, and a service provider MUST NOT assume that they will be followed at all. In addition, the WS-Inspection specification does not impose any restrictions upon the structure created by the references, so it is up to the processor of WS-Inspection documents to make sure that circular references are not followed endlessly.

The following example shows a WS-Inspection document which contains two links to other WS-Inspection documents:

<?xml version="1.0"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
  <link referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
        location="http://example.com/financial/services.wsil"/>
  <link referencedNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
        location="http://example.com/purchasing/poservices.wsil"/>
</inspection>

3.0 WSDL Binding

The WS-Inspection specification includes a binding for WSDL 1.1 which provides the following capabilities:

  • Indication of the type(s) of WSDL bindings which appear in the referenced WSDL document.
  • Specification of which WSDL service is being referenced if multiple exist within the same document.
  • Indication of whether or not a particular referenced WSDL document is providing endpoint information.

Note that use of the WSDL binding is OPTIONAL if the referenced WSDL document has one or no service elements. In those cases, a reference to a WSDL document MAY be made with only the description element. If the referenced WSDL document has more than one service element, then the WSDL binding MUST be used to indicate which service element is being referenced.

The WS-Inspection specification allows references to be made to any WSDL document, irrespective of the contents of that document. Any portion of a WSDL description for a single service which is contained in a retrievable unit, e.g. a single file, may be referenced. The only constraint which is imposed is that two referenced WSDL documents within the same WS-Inspection service MAY NOT contain conflicting information. This mechanism MUST NOT be used as a substitute for the WSDL import element; they are not equivalent.

Because WSDL is a description format and does not specify a retrieval mechanism for its documents, this binding only applies to the WS-Inspection description element.

3.1 How the WSDL Binding Extends the WS-Inspection Specification

The WSDL binding extends the WS-Inspection specification using the following extension element:

<inspection xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/ ...>
  <service ...>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="uri">
      <wsilwsdl:reference endpointPresent="boolean"?>
        <wsilwsdl:referencedService>qname</wsilwsdl:referencedService> ?
        <wsilwsdl:implementedBinding>qname</wsilwsdl:implementedBinding> *
      </wsilwsdl:reference>
    </description>
  </service>
</inspection>

The interpretation of the WSDL extension, including additional restrictions, is described in the following section.

3.2 wsilwsdl:reference

The WS-Inspection WSDL binding element reference acts as the container element for the rest of the binding information. The reference element MAY have an endpointPresent attribute, a single referencedService child, and/or one or more implementedBinding children, but MUST have at least one of the three.

The endpointPresent attribute MAY be used to indicate whether or not the referenced WSDL document contains endpoint information. If the attribute has a boolean value of true (or 1), then the referenced WSDL document MUST contain a service element. If the attribute has a boolean value of false (or 0), then the referenced WSDL document MUST NOT contain a service element. A WS-Inspection consumer that is looking only for service endpoint information may choose to examine this attribute to determine whether or not a referenced WSDL document should be retrieved.

The following example shows a WS-Inspection document for the stock quote service that appeared in Section 1.2. In this case, the WSDL document which describes the service is assumed to be split into three files, with the "main" file importing the other two.

<?xml version="1.0"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
            xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/">
  <service>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/stockquote/main.wsdl">
    </description>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/stockquote/bindings.wsdl">
       <wsilwsdl:reference endpointPresent="false"/>
    </description>
  </service>
</inspection>

Notice that references have only been created for two of the three WSDL files. As was stated earlier, The WS-Inspection specification does not impose any restrictions upon what WSDL information is referenced.

3.2.1 wsilwsdl:referencedService

Although WSDL allows multiple services to be described within a single document, WS-Inspection references are made at a per-service level. If a referenced WSDL document contains more than one WSDL service element, then the WS-Inspection WSDL binding's referencedService element MUST be used to specify which service is being referenced. The QName specified by the referencedService element MUST be a valid QName corresponding to a service in the referenced WSDL document.

The following example shows a WS-Inspection document for the stock quote and calculator services that appeared in Section 1.2. In this case, the WSDL document is assumed to contain descriptions for multiple financial services.

<?xml version="1.0"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
            xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/">
  <service>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/finance.wsdl">
       <wsilwsdl:reference>
         <wsilwsdl:referencedService 
            xmlns:ns1="http://example.com/finance.wsdl">
               ns1:StockQuoteService
         <wsilwsdl:referencedService>  
       </wsilwsdl:reference>
    </description>
  </service>
  <service>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/finance.wsdl">
       <wsilwsdl:reference>
         <wsilwsdl:referencedService 
            xmlns:ns1="http://example.com/finance.wsdl">
               ns1:CalculatorService
         <wsilwsdl:referencedService>  
       </wsilwsdl:reference>
    </description>
  </service>
</inspection>

3.2.2 wsilwsdl:implementedBinding

The implementedBinding element MAY be used to indicate the type(s) of bindings which appear in a referenced WSDL document. A reference element MAY have multiple implementedBinding elements as children. The QName specified by the implementedBinding element MUST be a valid QName corresponding to a binding in the referenced WSDL document.

The following example shows a WS-Inspection document for the stock quote and calculator services that appeared in the example in Section 1.2. The first service has a reference to a WSDL description which implements two bindings: http://example.com/stockquote.wsdl/StockQuoteSoapBinding and http://example.com/stockquote.wsdl/StockSymbolLookupSoapBinding. The second service also has a reference to a WSDL description, but it does not provide any additional information about the bindings contained within that document.

<?xml version="1.0"?>
<inspection xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
            xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/">
  <service>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/stockquote.wsdl">
       <wsilwsdl:reference>
         <wsilwsdl:implementedBinding 
            xmlns:ns1="http://example.com/stockquote.wsdl">
               ns1:StockQuoteSoapBinding
         </wsilwsdl:implementedBinding>
         <wsilwsdl:implementedBinding 
            xmlns:ns1="http://example.com/stockquote.wsdl">
               ns1:StockSymbolLookupSoapBinding
         </wsilwsdl:implementedBinding>
       </wsilwsdl:reference>
    </description>
  </service>
  <service>
    <description referencedNamespace="http://schemas.xmlsoap.org/wsdl/"
                 location="http://example.com/tools/calculator.wsdl"/>
  </service>
</inspection>

4.0 UDDI Bindings

Many service descriptions will be stored in UDDI registries, so the WS-Inspection specification provides a set of usage patterns for references to this information. This is accomplished using a set of UDDI extensibility elements that provide references to UDDI businessEntity or businessService entries from the version 1 and version 2 UDDI specifications. The bindings for the two versions are identical, except for the schemas which are used to represent them. The referencedNamespace attribute on a link or description element which references a version 1 UDDI document has a value of "urn:uddi-org:api", while it has a value of "urn:uddi-org:api_v2" for a version 2 document.

4.1 How the UDDI Binding Extends the WS-Inspection Specification

The UDDI binding extends the WS-Inspection specification using the following extension elements:

<inspection (xmlns:wsiluddi://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/
             | xmlns:wsiluddi://schemas.xmlsoap.org/ws/2001/10/inspection/uddiv2/) ... >
  <link ... >
    <wsiluddi:businessDescription location="uri"?>
      <wsiluddi:discoveryURL useType="nmtoken"> ?
      <wsiluddi:businessKey> ?
    </wsiluddi:businessDescription>
  </link>  

  <service ... >
    <description ... >
      <wsiluddi:serviceDescription location="uri"?>
        <wsiluddi:discoveryURL useType="nmtoken"> ?
        <wsiluddi:serviceKey> ?
      </wsiluddi:serviceDescription>
    </description>
  </service>
</inspection>

The interpretation of these UDDI extensions are described in the following sections.

4.2 wsiluddi:businessDescription

Users who choose to register their service descriptions in UDDI can create WS-Inspection references which instruct consumers to use UDDI to discover service description information. The WS-Inspection link element, together with UDDI extensibility elements, describes the record which should be retrieved. For UDDI, the link element will contain only the referencedNamespace attribute. The location attribute is not used with the link element when it contains a UDDI businessDescription element. The following example illustrates this usage:

<?xml version="1.0"?>
<inspection targetNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
    xmlns:wsiluddi="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/"
    xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
  <link referencedNamespace="urn:uddi-org:api">
    <wsiluddi:businessDescription location="http://www.example.com/uddi/inquiryapi">
      <wsiluddi:businessKey>3C9CADD0-5C39-11D5-9FCF-BB3200333F79</wsiluddi:businessKey>
      <wsiluddi:discoveryURL useType="businessEntity">
        http://www.example.com/uddi?3C9CADD0-5C39-11D5-9FCF-BB3200333F79
      </wsiluddi:discoveryURL>
    </wsiluddi:businessDescription>
  </link>
</inspection>

When using the UDDI extension elements, the link element must contain a reference to the UDDI namespace. This indicates that the extensibility elements contained with this element are used to reference a UDDI businessEntity. The WS-Inspection extension is specified using the businessDescription element. This element must contain either a UDDI businessKey element, a UDDI discoveryURL element, or both.

The value of the businessKey element is to be used in conjunction with the UDDI get_businessDetail message. To use the businessKey, the businessDescription element must contain a location attribute. The value of this attribute is the URL for the UDDI registry inquiry interface, and is used to issue a HTTP POST with the get_businessDetail message to the registry. The response to this message is the UDDI businessEntity record that is associated with the business key.

If a discoveryURL element is present, the UDDI businessEntity record may be retrieved via an HTTP GET issued against the URL that is specified in the value of this element. If both a businessKey element and a discoveryURL element are present, then the consumer of the WS-Inspection document may choose which method is used to retrieve the record.

4.3 wsiluddi:serviceDescription

References to single service descriptions which exist within UDDI may also be referenced through WS-Inspection documents. By using the description element along with added extensibility elements, the correct record can be retrieved. The following example illustrates this usage:

<?xml version="1.0"?>
<inspection targetNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
    xmlns:wsiluddi="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/"
    xmlns="http://schemas.xmlsoap.org/ws/2001/10/inspection/">
  <service>
    <name>UDDI Service Description</name>
    <description referencedNamespace="urn:uddi-org:api">
      <wsiluddi:serviceDescription location="http://www.example.com/uddi/inquiryapi">
        <wsiluddi:serviceKey>4FA28580-5C39-11D5-9FCF-BB3200333F79</wsiluddi:serviceKey>
        <wsiluddi:discoveryURL useType="businessEntity">
          http://www.example.com/uddi?3C9CADD0-5C39-11D5-9FCF-BB3200333F79
        </wsiluddi:discoveryURL>
      </wsiluddi:serviceDescription>
    </description>
  </service>
</description>

The WS-Inspection description element contains a reference to a single UDDI service description using the serviceDescription extension element. The UDDI serviceKey element must appear as a child of the serviceDescription element. The value of the serviceKey element is used in conjunction with the UDDI get_serviceDetail message to retrieve the UDDI service description.

The UDDI discoveryURL element may also appear as a child of the serviceDescription element. If present, it may be used to retrieve a UDDI businessEntity via HTTP GET. A single service description is extracted from the UDDI businessEntity using the specified serviceKey.

5.0 Developing Additional Bindings

As is the case with the most common uses of WSDL documents, a reference to most description documents can be made using a simple description element, as illustrated in Section 2.2.3, without requiring that any additional information be present. As was previously mentioned, however, there are some instances, such as with UDDI, in which the description element or link element cannot alone provide enough information to allow for the retrieval of the desired information. There are also instances, such as with many WSDL documents, where it is useful to be able to provide additional information about the referenced document. Although this specification has created bindings for two of the most prevalent service description mechanisms, WSDL in Section 3.0 and UDDI in Section 4.0, it is not feasible for it to do so for all of the other pre-existing description mechanisms. It is therefore left to the community to determine when new bindings need to be developed, and to agree upon their format and usage. The following are a few guidelines to help in the design of these new bindings:

  • Each binding MAY have one root element for extending the description element, and one for extending the link element, but MUST NOT have more than one for each. The binding MAY use the same root element for extending both.
  • The binding MUST limit the amount of information about the referenced description which is exposed. It is not the intention of the WS-Inspection document to replace the description document.
  • The binding MAY use elements from the description language for which it was created where appropriate, but SHOULD limit the amount by which their associated semantics are altered.

6.0 Inspection Document Publication

The WS-Inspection grammar only provides a partial solution to the problem of advertising services. The second necessary component is that of providing a consistent means of locating and accessing the inspections which have been created. If the WS-Inspection documents cannot be easily located, then they provide minimal added value. To this end, the WS-Inspection specification provides two methods of usage for inspection documents, describing where they should be placed, and how they should be found. The two usage patterns are defined in the following sections.

6.1 Fixed Name Inspection Documents

WS-Inspection documents, when available, need to be able to be easily located. If a URL is obtained,which does not directly correspond to a WS-Inspection document, and perhaps not directly to any type of document, then it would be desirable to use what has been given and still be able to retrieve any inspection related documents which have been made available at that location. To this end, a WS-Inspection document named inspection.wsil MAY be placed wherever the most common entry points to websites/applications deployed on the server may be.

For example, the company example.com would create an inspection.wsil file in the root of its web server (available through http://example.com/inspection.wsil). If they offer services through http://example.com/financial and http://example.com/shipping then they may also put inspection.wsil files accessible under each of those URIs as well. It is possible that the inspection.wsil file at the root level may only contain pointers to the other WS-Inspection files.

The inspection.wsil documents do not necessarily have to be static documents; they MAY be dynamically generated upon request.

By providing a consistently named WS-Inspection file, applications can be easily modified to inspect sites for available services.

6.2 Linked Inspection Documents

Besides assisting those who are actively inspecting sites, the WS-Inspection specification also allows for a mechanism to inform users about service inspection related documents through other types of content, such as HTML pages. The exact mechanism by which the inspection documents are referenced is dependent upon the content type, but a binding for HTML is described in the following section.

6.2.1 Linking to Inspections Documents within HTML

WS-Inspection documents can be linked to in HTML pages through the use of a META tag carrying the value of serviceInspection in its name attribute. The corresponding content attribute on the tag must be a valid URI indicating the location of a WS-Inspection document. Typically, one would include this tag on highly visible pages, like the root document of the server. It is possible to reference multiple WS-Inspection documents by including several META tags within the same HTML page. The document at the location specified in the content attribute MUST be a WS-Inspection document, it cannot be another HTML document.

The following example shows an HTML fragment which has references to three WS-Inspection documents:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
  <HEAD>
    <META name="serviceInspection" content="localservices.wsil">
    <META name="serviceInspection" content="http://www.example.com/calculators.wsil">
    <META name="serviceInspection" content="ftp://www.anotherexample.com/translators.wsil">
  </HEAD>
  <BODY>
   ...
  </BODY>
</HTML>

7.0 References

[1] Web Services Description Language (WSDL) 1.1 "http://www.w3.org/TR/2001/NOTE-wsdl-20010315"
[2] Universal Description, Discovery, and Integration (UDDI) 2.0 "http://www.uddi.org"
[3] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997
[4] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, MIT/LCS, U.C. Irvine, Xerox Corporation, August 1998.
[5] Extensible Markup Language (XML) 1.0 "http://www.w3.org/TR/2001/NOTE-wsdl-20010315"

A 1 Notes on URIs

This section does not directly contribute to the specification, but provides background that may be useful when implementing the specification.

A 1.1 XML Namespaces and Schema Locations

It is a common misperception to equate the targetNamespace of an XML schema or the value of the xmlns attribute in XML instances with the location of the corresponding schema. Since namespaces are in fact URIs, and URIs may be locations, and you may be able to retrieve a schema from that location, it does not mean that is the only schema that is associated with that namespace. There can be multiple schemas associated with a particular namespace, and it is up to a processor of XML to determine which one to use in a particular processing context.

A 1.2 Relative URIs

Throughout this document you see fully qualified URIs used in WS-Inspection documents. The use of a fully qualified URI is simply to illustrate the referencing concepts. The use of relative URIs is completely allowed and is warranted in many cases. For information on processing relative
URIs, see http://www.normos.org/ietf/rfc/rfc2396.txt.

A 2 The Complete WS-Inspection Grammar

<wsil:inspection>
  <wsil:abstract xml:lang=""? ... /> * 
[  <wsil:service>  
     <wsil:abstract xml:lang=""? ... /> *
     <wsil:name xml:lang=""? ... /> *
     <wsil:description referencedNamespace="uri" location="uri"?> *
       <wsil:abstract xml:lang=""? ... /> * 
       <-- extensibility element --> ?
     </wsil:description>
   </wsil:service>
|
   <wsil:link referencedNamespace="uri" location="uri"?/>
     <wsil:abstract xml:lang=""? ... /> * 
     <-- extensibility element --> ?
   </wsil:link> ] +
</wsil:inspection>

A3 Schemas

A 3.1 WS-Inspection Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
  xmlns:wsil="http://schemas.xmlsoap.org/ws/2001/10/inspection/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">

  <complexType name="typeOfAbstract">
    <simpleContent>
      <extension base="xsd:string">
        <attribute ref="xml:lang" use="optional"/>
      </extension>
    </simpleContent>
  </complexType>

  <complexType name="itemWithAbstracts" abstract="true">
    <sequence>
      <element name="abstract" type="wsil:typeOfAbstract" minOccurs="0" 
         maxOccurs="unbounded"/>
    </sequence>
  </complexType>
  
  <complexType name="nameType">
    <simpleContent>
      <extension base="xsd:string">
        <attribute ref="xml:lang" use="optional"/>
      </extension>
    </simpleContent>
  </complexType>

  <complexType name="referenceType">
    <complexContent>
      <extension base="wsil:itemWithAbstracts">
        <attribute name="referencedNamespace" type="anyURI" use="required"/>
        <attribute name="location" type="anyURI" use="optional"/>
      </extension>
    </complexContent>
  </complexType>
  
  <complexType name="descriptionType">
    <complexContent>
      <extension base="wsil:referenceType">
        <sequence>
          <any namespace="##other" minOccurs="0" processContents="lax"/>
        </sequence>
      </extension>
    </complexContent>
  </complexType>

  <complexType name="linkType">
    <complexContent>
      <extension base="wsil:referenceType">
        <sequence>
          <any namespace="##other" minOccurs="0" processContents="lax"/>
        </sequence>
      </extension>
    </complexContent>
  </complexType>
  
  <complexType name="serviceType">
    <complexContent>
      <extension base="wsil:itemWithAbstracts">
        <sequence>
          <element name="name" type="wsil:nameType" minOccurs="0" 
               maxOccurs="unbounded"/>
          <element name="description" type="wsil:descriptionType" 
               minOccurs="1" maxOccurs="unbounded"/>
        </sequence>
      </extension>
    </complexContent>
  </complexType>
            
  <element name="inspection">
    <complexType>
      <complexContent>
        <extension base="wsil:itemWithAbstracts">
          <sequence minOccurs='1' maxOccurs='unbounded'>
            <choice>
              <element name="service" type="wsil:serviceType"/>
              <element name="link" type="wsil:linkType"/>
            </choice>
          </sequence>
        </extension>
      </complexContent>
    </complexType>
  </element>

</schema>

A 3.2 WSDL Binding Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/"
  xmlns:wsilwsdl="http://schemas.xmlsoap.org/ws/2001/10/inspection/wsdl/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">

  <complexType name="reference">
    <sequence>
      <element name="referencedService" type="xsd:QName" minOccurs="0"/>
      <element name="implementedBinding" type="xsd:QName" minOccurs="0" maxOccurs="unbounded" />
    </sequence>
    <attribute name="endpointPresent" type="xsd:boolean" use="optional"/>
  </complexType>

  <element name="reference" type="wsilwsdl:reference" />

</schema>

A 3.3 UDDI v1 Binding Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/"
  xmlns:wsiluddi="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddi/"
  xmlns:uddi="urn:uddi-org:api"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">

  <import namespace="urn:uddi-org:api" schemaLocation="http://www.uddi.org/schema/2001/uddi_v1.xsd"/>

  <complexType name="descriptionType">
    <sequence>
      <element name="discoveryURL" type="uddi:DiscoveryUrl" minOccurs="0"/>
    </sequence>
    <attribute name="location" type="anyURI" use="optional"/>
  </complexType>

  <!-- This element is to be used as a child of a WS-Inspection link -->
  <element name="businessDescription">
    <complexType>
      <complexContent>
        <extension base="wsiluddi:descriptionType">
          <sequence>
            <element name="businessKey" type="xsd:string" minOccurs="0"/>
          </sequence>
        </extension>
      </complexContent>
    </complexType>
  </element>

  <!-- This element is to be used as a child of a WS-Inspection description -->
  <element name="serviceDescription">
    <complexType>
      <complexContent>
        <extension base="wsiluddi:descriptionType">
          <sequence>
            <element name="serviceKey" type="xsd:string"/>
          </sequence>
        </extension>
      </complexContent>
    </complexType>
  </element>

</schema>

A 3.4 UDDI v2 Binding Schema

<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddiv2/"
  xmlns:wsiluddi="http://schemas.xmlsoap.org/ws/2001/10/inspection/uddiv2/"
  xmlns:uddi="urn:uddi-org:api_v2"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">

  <import namespace="urn:uddi-org:api_v2" schemaLocation="http://www.uddi.org/schema/2001/uddi_v2.xsd"/>

  <complexType name="descriptionType">
    <sequence>
      <element name="discoveryURL" type="uddi:discoveryURL" minOccurs="0"/>
    </sequence>
    <attribute name="location" type="anyURI" use="optional"/>
  </complexType>

  <!-- This element is to be used as a child of a WS-Inspection link -->
  <element name="businessDescription">
    <complexType>
      <complexContent>
        <extension base="wsiluddi:descriptionType">
          <sequence>
            <element name="businessKey" type="uddi:businessKey" minOccurs="0"/>
          </sequence>
        </extension>
      </complexContent>
    </complexType>
  </element>

  <!-- This element is to be used as a child of a WS-Inspection description -->
  <element name="serviceDescription">
    <complexType>
      <complexContent>
        <extension base="wsiluddi:descriptionType">
          <sequence>
            <element name="serviceKey" type="uddi:serviceKey"/>
          </sequence>
        </extension>
      </complexContent>
    </complexType>
  </element>

</schema>
Show:
© 2014 Microsoft