Copyright© 2002 International Business Machines Corporation, Microsoft
The WS-Inspection specification provides an XML format for assisting in the inspection of a site for available services and a set 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 for the service as well as through references which may be placed within a content medium such as HTML.
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).
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
Specifications have been proposed to describe
Web Services at different levels and from
various perspectives. It is the goal of the
proposed Web Services Description Language
(WSDL) [1] to describe services at a functional level.
The Universal Description, Discovery, and
Integration (UDDI) [2] schema aims at providing a more business-centric
perspective. What has not yet been provided
by these proposed standards is the ability
to tie together, at the point of offering
for a service, these various sources of information
in a manner which is both simple to create
and use. 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.
Repositories already exist where descriptive
information about Web services has been gathered
together. The WS-Inspection specification
provides mechanisms with which these existing
repositories can be referenced and utilized,
so that the information contained in them
need not be duplicated if such a duplication
is not desired.
The two major design goals of the WS-Inspection specification are simplicity and extensibility. A WS-Inspection document essentially an aggregation of pointers to service description documents. WS-Inspection documents are, as a result, 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 that allow the consumer of the document to pick and choose from the available descriptions and to access only those which they are able to understand. 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.
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 example shows the WS-Inspection document for two services which provide financial tools. The first service, providing stock quotes, has two available descriptions; one in an HTTP accessible WSDL document, and the other in a UDDI directory. The second service, providing a calculator, 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 is provided in Section 2.
Note: For these examples, the referenced WSDL documents are each assumed to contain a single WSDL service element. See Section 3 for more information.
| 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]. |
This section describes the core elements of the WS-Inspection language. Binding extensions for WSDL and UDDI are covered in Sections 3 and 4.
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>
There is an 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 elements in this example is described in a corresponding section below.
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 to proceed with 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.
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.
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.
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.
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 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.
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 consumers 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 to which it is being bound. 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 be 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 documents. The final decision must be made by retrieving and processing the referenced document.
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. 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 by using link elements of the following form:
<wsil:link referencedNamespace="uri" location="uri"?> <-- extensibility element --> </wsil:link>
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 interminably.
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>
The WS-Inspection specification includes a binding for WSDL 1.1 and provides the following capabilities:
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.
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.
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.
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 referencedService element of the WS-Inspection WSDL binding 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>
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>
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.
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.
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 by 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 an 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.
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.
A reference to most description documents in the most common WS-Inspection 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:
The WS-Inspection grammar only provides a partial solution to the problem of advertising services. A second component is required that provides a consistent means of locating and accessing the inspections that 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 two subsections.
WS-Inspection documents, when available,
must 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 where the most
common entry points to websites or applications
deployed on the server are located.
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.
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.
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>
[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"
This section does not directly contribute to the specification, but provides background that may be useful when implementing the specification.
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. Namespaces are in fact URIs, and URIs may be locations. So you may be able to retrieve a schema from that location. But this 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.
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.
<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>
<?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>
<?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>
<?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>
<?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>