Some thoughts on the AtomAPI WSDL

I stumbled across the AtomAPI WSDL and tried to validate it against the WS-I Basic Profile.

It fails on two errors, one of which may be a result of the other. Basically, the problem stems
from the fact that the wsdl:types contains a number of xs:schema elements (4 actually), and two
of these use xs:import to import the namespace defined in another of the inline xs:schema elements.

Technically, this violates R2004 of the BP1.0 since the import is importing a namespace defined in a document with a root element of wsdl:definitions.

R2004 A DESCRIPTION MUST NOT use the XML Schema "import" statement to import a Schema
from any document whose root element is not "schema" from the namespace "http://www.w3.org/2001/XMLSchema".

I should point out that there are those who believe that it should be permitted to import namespaces defined inline in the same wsdl:types section, but the BP1.0 does disallow this practice at present. I believe we're leaving it to the W3C WSD WG to address the issue of schema imports, etc. so at least for the time being, for WSDL1.1 you can expect that the AtomAPI WSDL as currently defined may pose a potential problem for WSDL processors.

However, that isn't what really concerns me (although I would like to see AtomAPI WSDL be WS-I BP1.0 conformant:-)

I notice that the target namespace of the Atom WSDL is defined as "http://schemas.xmlsoap.org/wsdl/http/". It isn't clear to me that this is such a good idea. That namespace belongs to the WSDL1.1 HTTP binding extension. It's a "well known" namespace too, at least as far as WSDL processors are concerned. But more importantly, the namespace authority is schemas.xmlsoap.org and unless the use of this namespace as defined in the WSDL and also in the AtomAPI spec is sanctioned by Developmentor, it is really an inappropriate usage.

I would have expected that the target namespace of the AtomAPI WSDL would have been a URI more along the lines of the namespace URI that is used for the Atom schema; e.g. "http://purl.org/atom/ns#".

The second concern I have concerns the way in which the WSDL incorporates support for WS-Security.
IMO, the WSDL unnecessarily defines the schema elements for WS-Security. It also is using the now obsolete namespace associated with the input specification to the OASIS TC. The URI for the recently approved WS-Security schema is "http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd". Note that most vendors' products will be upgrading their support for WS-Security to support the version of the spec that the OASIS WSS TC recently approved. Additionally, the WS-I Basic Security Profile will be based on the OASIS TC approved specs. I would think/hope that Atom would want to follow suit.

But I am curious as to why the WSS schema components are defined inline in the AtomAPI WSDL rather than simply being pulled in by reference (e.g. xs:import). I haven't taken the time to review carefully to see if there are actually differences between the AtomAPI defined WSS schema components and the published schema at the (old) namespace URI for secext and utility. I suppose I could understand if there were errors in the published schema and the intent was to address those errors. Was it the author's intent to constrain which child elements allowed by WS-Security were to be
used?

However, the real concern I have is that by defining the WSDL using the soap:header to specify use of the wss:Security element in the message you have made it a requirement that the wss:Security element be present as a SOAP header in each message for which this has been specified based upon WS-I BP1.0 requirement R2738. It isn't clear to me that it was the intent that every message carry a wss:Security SOAP header...

In truth, there's a reason that the OASIS TC hasn't defined a WSDL mapping for WS-Security. Basically, the details are still being sorted out as to how you associate policy (which is really what this amounts to) with a WSDL description. I would recommend that you use wsdl:documentation to indicate that the wss:Security SOAP header block MAY be sent on the messages for which you have currently specified a soap:header binding. Even if the intent was to mandate that a message carry a wss:Security element with the Username security token, then I believe you would still want a different means of describing/specifying this in the WSDL.

I've taken the liberty of noodling on the AtomAPI WSDL to address some of the concerns expressed above.

<?xml version="1.0" encoding="utf-8" ?>

<definitions 

 xmlns:ns="http://purl.org/atom/ns/wsdl#" 

 xmlns:types="http://purl.org/atom/ns/types#" 

 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 

 xmlns:s="http://www.w3.org/2001/XMLSchema" 

 xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" 

 targetNamespace="http://purl.org/atom/ns/wsdl#" 

 xmlns="http://schemas.xmlsoap.org/wsdl/">

 <types>

  <s:schema elementFormDefault="qualified" 

   xmlns:s1="http://purl.org/atom/ns#" 

   targetNamespace="http://purl.org/atom/ns/types#">

   <s:import namespace="http://purl.org/atom/ns#" 

    schemaLocation="Atom.xsd"/>

   <s:element name="PUT" type="s1:entryType" />

   <s:element name="POST">

    <s:complexType>

     <s:sequence>

      <s:element minOccurs="0" maxOccurs="1" ref="s1:entry" />

     </s:sequence>

    </s:complexType>

   </s:element>

   <s:element name="POSTResponse">

    <s:complexType>

     <s:sequence>

      <s:element minOccurs="0" maxOccurs="1" ref="s1:entry" />

     </s:sequence>

    </s:complexType>

   </s:element>

  </s:schema>

 </types>

 <message name="PUTSoapIn">

  <part name="PUT1" element="types:PUT" />

 </message>

 <message name="PUTSoapOut" />

 <message name="DELETESoapIn" />

 <message name="DELETESoapOut" />

 <message name="POSTSoapIn">

  <part name="parameters" element="types:POST" />

 </message>

 <message name="POSTSoapOut">

  <part name="parameters" element="types:POSTResponse" />

 </message>

 <portType name="AtomAPISoap">

  <operation name="PUT">

   <input message="ns:PUTSoapIn" />

   <output message="ns:PUTSoapOut" />

  </operation>

  <operation name="DELETE">

   <input message="ns:DELETESoapIn" />

   <output message="ns:DELETESoapOut" />

  </operation>

  <operation name="POST">

   <input message="ns:POSTSoapIn" />

   <output message="ns:POSTSoapOut" />

  </operation>

 </portType>

 <binding name="AtomAPISoap" type="ns:AtomAPISoap">

  <soap:binding transport="http://schemas.xmlsoap.org/soap/http" 

    style="document" />

  <operation name="PUT">

   <soap:operation 

    soapAction="http://purl.org/atom/ns/http/PUT" style="document" />

   <input>

    <documentation>

    Note: the input message MAY carry a wss:Security SOAP header 

    with the Username token.

    </documentation>

    <soap:body use="literal" />

   </input>

   <output>

    <soap:body use="literal" />

   </output>

  </operation>

  <operation name="DELETE">

   <soap:operation 

    soapAction="http://purl.org/atom/ns/http/DELETE" style="document" />

   <input>

    <documentation>

    Note: the input message MAY carry a wss:Security SOAP header with the 

    Username token.

    </documentation>

    <soap:body use="literal" />

   </input>

   <output>

    <soap:body use="literal" />

   </output>

  </operation>

  <operation name="POST">

   <soap:operation 

    soapAction="http://purl.org/atom/ns/http/POST" style="document" />

   <input>

    <documentation>

    Note: the input message MAY carry a wss:Security SOAP header with the 

    Username token.

    </documentation>

    <soap:body use="literal" />

   </input>

   <output>

    <soap:body use="literal" />

   </output>

  </operation>

 </binding>

 <service name="AtomAPI">

  <port name="AtomAPISoap" binding="ns:AtomAPISoap">

   <soap:address location="http://localhost/AtomApi.asmx" />

  </port>

 </service>

</definitions>