Menu

A Preview of WS-I Basic Profile 1.1

September 16, 2003

Anish Karmarkar

Introduction

On 12th August 2003 WS-I (Web Services Interoperability Organization) announced the release of the final specification of Basic Profile 1.0 a set of recommendations on how to use web services specifications to maximize interoperability. For developers, users, and vendors of web services and web services tools this is a big leap forward to achieving interoperability in the emerging and fast changing world of web services. But what else has WS-I been working on?

WS-I recognizes the fact that Basic Profile 1.0 is just a beginning and that it's a long road toward web services maturity and interoperability. In its mission toward accelerating the adoption of web services and promoting interoperability, the Basic Profile Working Group, which developed Basic Profile 1.0, is tasked with generating Basic Profile 1.1 to incorporate attachments. The charter for the WG says:

The working group is also charged with addressing the issue of incorporating support for attachments in a follow-on minor revision of the Web Services Basic Profile, henceforth to be named Web Services Basic Profile 1.1. The Web Services Basic Profile 1.1 shall have as its foundation the Web Services Basic Profile 1.0 plus:

     SOAP Messages with Attachments, W3C Note, 11 December 2000"

Basic Profile 1.1, as the name indicates, is the next version of Basic Profile. It builds on 1.0, adding support for SOAP Messages with Attachments (SwA) and WSDL 1.1's Section 5 MIME bindings. As part of the process of releasing a Profile, other Working Groups within WS-I develop sample applications and test tools for the Profile. This ensures that the Profile is implementable and "debugged" before its final release. Like Basic Profile 1.0, Basic Profile 1.1 will be released with sample applications and test tools.

This article provides a preview of Basic Profile 1.1 based on the latest, as of this article, Basic Profile 1.1 Working Group Draft. The Basic Profile Working Group has been working on Basic Profile 1.1 since January 2003. In the course of its development the WG identified more than 70 technical issues that needed to be resolved. Only a very few minor ones remain. Please remember that this preview is based upon a Working Group Draft; as a work in progress can (and almost certainly will) be modified as the draft Profile is reviewed and refined.

Attachments, SwA and Interoperability

As web services begin to be used and deployed for serious applications, it is critical to have an interoperable attachment specification profiled along with SOAP 1.1, and WSDL 1.1. There are several reasons for the necessity of attachments when carrying large amount of data, either binary or other XML documents. Some of the advantages of attachments include smaller message size, smaller memory requirements, smaller processing time (no need to convert binary data to base-64), and, most importantly, streaming. Attachments allow applications to use appropriate APIs (such as the JavaBeans Activation Framework) to process data in a streaming fashion. This makes a big difference in performance, for example, when BLOBS and CLOBS from an application database are shipped inside a SOAP Envelope. The advantages of attachments are well documented in SwA, SOAP 1.2 Attachment Feature, XML, SOAP and Binary Data, Proposed Infoset Addendum to SOAP Messages with Attachments, and SOAP Message Transmission Optimization Mechanism. The XMLP WG is also working on attachment technology for SOAP 1.2.

Basic Profile 1.0 facilitates interoperability at a basic level -- SOAP 1.1, WSDL 1.1, UDDIv2 (see UDDI Version 2.04 API Specification and UDDI Version 2.03 Data Structure Reference), etc. But one thing that is missing from Basic Profile 1.0 is support for attachments. The use of attachments affects web services interoperability with regard to packaging, formatting and serialization.

The most widely implemented and accepted attachment technology is MIME. SwA combines MHTML and content-id URIs (CID) for referencing MIME parts in SOAP. Basic Profile 1.1 has selected SwA as the attachment technology and WSDL 1.1 Section 5 MIME bindings for describing SwA. Basic Profile 1.1, as with Basic Profile 1.0, clarifies, fixes, and subsets the relevant specs to make it more interoperable and removes ambiguities. This addresses a real need that developers and users of web services have when dealing with large binary data and transporting it within a SOAP 1.1 Envelope.

The direction that Basic Profile 1.1 has taken fits very nicely with the direction that XMLP WG has taken with respect to attachments for SOAP 1.2, as documented in SOAP Message Transmission Optimization Mechanism (MTOM). Both use MIME and are based on SwA. MTOM goes a step further by including attachments as part of the Infoset (since SOAP 1.2 is built around Infoset), thus making the SOAP 1.2 processing model applicable to the attachments as well. The messages on the wire in both cases will look very similar. MTOM is an evolutionary approach to attachment technology, similar to the transition from SOAP 1.1 to SOAP 1.2.

Describing Attachments

Basic Profile 1.1 adds support for attachments in a backward compatible way, as required by the charter. What that means is that all Basic Profile 1.0 artifacts (DESCRIPTION, MESSAGE, INSTANCE, etc.) that were conformant with Basic Profile 1.0 will be conformant with Basic Profile 1.1. This is ensured by removing or modifying the requirements in Basic Profile 1.0 which restricted the binding to SOAP HTTP binding, allowing either SOAP HTTP binding or MIME binding.

SwA is quite a robust specification, but the WSDL 1.1 Section 5 MIME bindings are underspecified, which leads to interoperability problems. Basic Profile 1.1 ties the MIME binding of section 5 in WSDL 1.1 to SwA. The MIME bindings have been interpreted to mean things other than SwA. It also fixes ambiguities in the MIME binding as well as bugs in the MIME binding schema.

The WSDL 1.1 snippet below illustrates what one can do with Basic Profile 1.1 for rpc/literal style (please note that the namespace prefixes are bound to the same namespace URIs as in Section 1.2 of WSDL 1.1):

<wsdl:message name="msg-in">
    <wsdl:part name="photo-reference" type="xsd:anyURI"/>
    <wsdl:part name="photo-attachment" type="xsd:base64Binary"/>
</wsdl:message>

<wsdl:message name="msg-out">
    <wsdl:part name="result" type="xsd:string"/>
</wsdl:message>

<wsdl:portType name="my-portType">
    <wsdl:operation name="my-operation">
        <wsdl:input message="tns:msg-in"/>
        <wsdl:output message="tns:msg-out"/>
    </wsdl:operation>
</wsdl:portType>

<wsdl:binding name="my-binding" type="tns:my-portType">
    <soap:binding style="rpc" 
        transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="my-operation">
        <soap:operation soapAction="http://example.com/soapaction"/>
        <wsdl:input>
            <mime:multipartRelated>
                <mime:part>
                    <soap:body parts="photo-reference"
                        use="literal" 
                        namespace="http://example.com/some-namespace"/>
                </mime:part>
                <mime:part>
                    <mime:content part="photo-attachment"
                        type="application/octetstream"/>
                </mime:part>
            </mime:multipartRelated>
        </wsdl:input>
        <wsdl:output>
            <soap:body use="literal"
                namespace="http://example.com/some-namespace"/>
        </wsdl:output>
    </wsdl:operation>
 </wsdl:binding>

In the snippet above, the photo-reference part of the input message is bound to the SOAP Body and the photo-attachment part of the input message is bound to a separate MIME part. An example input message for the my-binding binding would be

MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=boundary; type=text/xml;
        start="<my-root-part@example.com>"
Content-Description: This is an optional message description.

--boundary
Content-Type: text/xml; charset="UTF-8"
Content-Transfer-Encoding: 8bit
Content-ID: <my-root-part@example.com>

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
    <env:Body xmlns:types="http://example.com/some-namespace">
        <types:my-operation>
            <photo-reference>cid:my-cool-photo@example.com</photo-reference>
        </types:my-operation>
    </env:Body>
</env:Envelope>

--boundary
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-ID: <my-cool-photo@example.com>

...binary photograph...
--boundary--

Note that the input message is bound to the MIME binding, whereas the output message is bound to the Basic Profile 1.0 SOAP HTTP binding. Such mixing is allowed by Basic Profile 1.1. In fact, Basic Profile 1.1 goes further and says that if the binding used is MIME, but the SOAP Body is the only MIME part listed, then the sender may choose to send the message using the SOAP HTTP binding (if there are no attachments) or the MIME binding.

Here is an equivalent example, which results in the same input and output wire messages, that uses document/literal as the style instead of rpc/literal (please note that the namespace prefix types is bound to the namespace URI http://example.com/some-namespace):

    <wsdl:types>
    <schema targetNamespace="http://example.com/some-namespace"
            xmlns="http://www.w3.org/2000/10/XMLSchema"
            elementFormDefault="unqualified">
        <element name="my-operation">
            <complexType>
                <sequence>
                    <element name="photo-reference" type="xsd:anyURI"/>
                </sequence>
            </complexType>
        </element>
        <element name="my-operationResponse">
            <complexType>
                <sequence>
                    <element name="result" type="xsd:string"/>
                <sequence>
            </complexType>
        </element>
    </schema>
</wsdl:types>

<wsdl:message name="msg-in-doc">
    <wsdl:part name="photo-reference-wrapper"
        element="types:my-operation"/>
    <wsdl:part name="photo-attachment"
        type="xsd:base64Binary"/>
</wsdl:message>
<wsdl:message name="msg-out-doc">
    <wsdl:part name="result-wrapper"
        element="types:my-operationResponse"/>
</wsdl:message>

<wsdl:portType name="my-portType-doc">
    <wsdl:operation name="my-operation-doc">
        <wsdl:input message="tns:msg-in-doc"/>
        <wsdl:output message="tns:msg-out-doc"/>
    </wsdl:operation>
</wsdl:portType>

<wsdl:binding name="my-binding-doc" type="tns:my-portType-doc">
    <soap:binding style="document"
        transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="my-operation-doc">
        <soap:operation soapAction="http://example.com/soapaction"/>
        <wsdl:input>
            <mime:multipartRelated>
                <mime:part>
                    <soap:body parts="photo-reference-wrapper"
                        use="literal"/>
                </mime:part>
                <mime:part>
                    <mime:content part="photo-attachment"
                        type="application/octetstream"/>
                </mime:part>
            </mime:multipartRelated>
        </wsdl:input>
        <wsdl:output>
            <soap:body use="literal" />
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

Referencing Attachments

These examples allow a web service to describe attachments, but the description says nothing about how attachments are referenced from the SOAP Envelope, which is a very common use case. Consider the case where the binary data is just too large to be inlined in the SOAP Envelope. SwA allows one to ship the data as an attachment, but this data will have to be referred to from the SOAP Envelope. Such a design would allow the higher application layers to not care whether the data is inlined or sent as an attachment. (For example in Java one could use the javax.activation.DataHandler to do this).

Basic Profile 1.1 solves the problem of describing the referrer-reference relationship by defining a type swaRef, in the (temporary) namespace http://ws-i.org/profiles/basic/1.1/xsd, which is a restriction of xsd:anyURI:

<xsd:schema targetNamespace="http://ws-i.org/profiles/basic/1.1/xsd"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xsd:simpleType name="swaRef">
        <xsd:restriction base="xs:anyURI" />
    </xsd:simpleType>
</xsd:schema>

Basic Profile 1.1 requires that a value of this type must resolve within the MIME package; that is, the URI that is the value of this type in the instance document must dereference to a MIME part within the same MIME package.

This makes the relationship between the referrer and the reference statically available to tools, which can then generate code artifacts that allow rich semantics (for example, generating stream oriented interfaces to access the attached data). Applications are allowed to use other mechanisms to express such a referrer-reference relationship. swaRef provides a uniform mechanism to identify references that point to attachments and therefore facilitate interoperability.

In the rpc/literal example above, the type of part photo-reference of the input message can now be changed to type swaRef. Similarly, for the document/literal example above, the type of the element photo-reference in the wsdl:types section can now be changed to type swaRef. The fact that the element photo-reference in the SOAP Envelope points to a MIME part within the same MIME package is now statically available in the WSDL description. The rpc/literal example above can be modified to use this new type as follows (please note that the namespace prefix bp11 is bound to the namespace URI http://ws-i.org/profiles/basic/1.1/xsd):

<wsdl:message name="msg-in">
    <wsdl:part name="photo-reference" type="bp11:swaRef"/>
    <wsdl:part name="photo-attachment" type="xsd:base64Binary"/>
</wsdl:message>

<wsdl:message name="msg-out">
    <wsdl:part name="result" type="xsd:string"/>
</wsdl:message>

<wsdl:portType name="my-portType">
    <wsdl:operation name="my-operation">
        <wsdl:input message="tns:msg-in"/>
        <wsdl:output message="tns:msg-out"/>
    </wsdl:operation>
</wsdl:portType>

<wsdl:binding name="my-binding" type="tns:my-portType">
    <soap:binding style="rpc" 
        transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="my-operation">
        <soap:operation soapAction="http://example.com/soapaction"/>
        <wsdl:input>
            <mime:multipartRelated>
                <mime:part>
                    <soap:body parts="photo-reference"
                        use="literal"
                        namespace="http://example.com/some-namespace"/>
                </mime:part>
                <mime:part>
                    <mime:content part="photo-attachment"
                        type="application/octetstream"/>
                </mime:part>
            </mime:multipartRelated>
        </wsdl:input>
        <wsdl:output>
            <soap:body use="literal"
                namespace="http://example.com/some-namespace"/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

A WSDL processor processing this WSDL fragment now knows that the URI within the SOAP Body is a reference to a MIME part in the same MIME package and can generate appropriate APIs to access the binary data that is sent as a separate MIME part. In the previous case, when swaRef was not used, the WSDL processor had no way of knowing whether the URI value in the SOAP message will resolve locally or be resolvable at all.

Summary

Interoperable attachments is one of the features that is frequently demanded by developers and users of web services. The Basic Profile Working Group addresses this need by including SwA in Basic Profile 1.1, resolving ambiguities, and by filling in the gaps of existing specifications. Furthermore, Basic Profile 1.1 also enables language binding tools to generate appropriate APIs to take full advantage of attachments.

Acknowledgments

The author would like to thank Eric Rajkovic and Umit Yalcinalp for reviewing the initial version of this document and providing much appreciated feedback.

References

WS-I Final Specification "BasicProfile Version 1.0a", Keith Ballinger, David Ehnebuske, Martin Gudgin, Mark Nottingham, Prasad Yendluri, 8 August 2003.

WS-I "Working Group Charter: Web Services Basic Profile", Tom Glover, Christopher Ferris, Christopher Kurt, Keith Ballinger, 21 January 2003.

IETF "Content-ID and Message-ID Uniform Resource Locators", E. Levinson, March 1997.

Sun "JavaBeans Activation Framework Specification Version 1.0a", Bart Calder, Bill Shannon, 27 May 1999.

IETF "MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)", J. Palme, A. Hopmann, N. Shelness, March 1999.

W3C Working Draft "SOAP Message Transmission Optimization Mechanism", Noah Mendelsohn, Mark Nottingham, Hervé Ruellan, 21 July 2003.

"Proposed Infoset Addendum to SOAP Messages with Attachments", Adam Bosworth, Don Box, Martin Gudgin, Mark Jones, Franz-Josef Fritz, Amy Lewis, Jean-Jacques Moreau, Mark Nottingham, David Orchard, Hervé Ruellan, Jeffrey Schlimmer, Volker Wiechers, TBD.

"XML, SOAP and Binary Data", Adam Bosworth, Don Box, Martin Gudgin, Mark Nottingham, David Orchard, Jeffrey Schlimmer, 26 February 2003.

W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Frystyk Nielsen, Satish Thatte, Dave Winer, 8 May 2000.

W3C Recommendation "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 24 June 2003.

W3C Recommendation "SOAP Version 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 24 June 2003.

W3C Working Draft "SOAP 1.2 Attachment Feature", Henrik Frystyk Nielsen, Hervé Ruellan, 24 September 2002.

W3C Note "SOAP Messages with Attachments", John J. Bartin, Satish Thatte, Henrik Frystyk Nielsen, 11 December 2000.

OASIS UDDI Committee Specification "UDDI Version 2.04 API Specification", Tom Bellwood (Editor), 19 July 2002.

OASIS UDDI Committee Specification "UDDI Version 2.03 Data Structure Reference", Claus von Riegen (Editor), 19 July 2002.

Web Services Interoperability Organization.

W3C Note "Web Services Description Language (WSDL) 1.1", Erik Christensen, Francisco Curbera, Greg Meredith, Sanjiva Weerawarana, 15 March 2001.

W3C XML Protocol Working Group.