Pages

1/16/2008

MIME Binding

MIME Binding

WSDL includes a way to bind abstract types to concrete messages in some MIME format. Bindings for the following MIME types are defined:

  • multipart/related
  • text/xml
  • application/x-www-form-urlencoded (the format used to submit a form in HTML)
  • Others (by specifying the MIME type string)

The set of defined MIME types is both large and evolving, so it is not a goal for WSDL to exhaustively define XML grammar for each MIME type. Nothing precludes additional grammar to be added to define additional MIME types as necessary. If a MIME type string is sufficient to describe the content, the mime element defined below can be used.

5.11 MIME Binding example

Example 7. Using multipart/related with SOAP

This example describes that a GetCompanyInfo SOAP 1.1 request may be sent to a StockQuote service via the SOAP 1.1 HTTP binding. The request takes a ticker symbol of type string. The response contains multiple parts encoded in the MIME format multipart/related: a SOAP Envelope containing the current stock price as a float, zero or more marketing literature documents in HTML format, and an optional company logo in either GIF or JPEG format.

<definitions .... >

<types>

<schema .... >

<element name="GetCompanyInfo">

<complexType>

<all>

<element name="tickerSymbol " type="string"/>

</all>

</complexType>

</element>

<element name="GetCompanyInfoResult">

<complexType>

<all>

<element name="result" type="float"/>

</all>

</complexType>

</element>

<complexType name="ArrayOfBinary">

<complexContent>

<restriction base="soapenc:Array">

<attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]"/>

</restriction>

<complexContent>

</complexType>

</schema>

</types>

<message name="m1">

<part name="body" element="tns:GetCompanyInfo"/>

</message>

<message name="m2">

<part name="body" element="tns:GetCompanyInfoResult"/>

<part name="docs" type="xsd:string"/>

<part name="logo" type="tns:ArrayOfBinary"/>

</message>

<portType name="pt1">

<operation name="GetCompanyInfo">

<input message="m1"/>

<output message="m2"/>

</operation>

</portType>

<binding name="b1" type="tns:pt1">

<operation name="GetCompanyInfo">

<soap:operation soapAction="http://example.com/GetCompanyInfo"/>

<input>

<soap:body use="literal"/>

</input>

<output>

<mime:multipartRelated>

<mime:part>

<soap:body parts="body" use="literal"/>

</mime:part>

<mime:part>

<mime:content part="docs" type="text/html"/>

</mime:part>

<mime:part>

<mime:content part="logo" type="image/gif"/>

<mime:content part="logo" type="image/jpeg"/>

</mime:part>

</mime:multipartRelated>

</output>

</operation>

</binding>

<service name="CompanyInfoService">

<port name="CompanyInfoPort"binding="tns:b1">

<soap:address location="http://example.com/companyinfo"/>

</port>

</service>

</definitions>

5.2 How the MIME Binding extends WSDL

The MIME Binding extends WSDL with the following extension elements:

<mime:content part="nmtoken"? type="string"?/>

<mime:multipartRelated>

<mime:part> *

<-- mime element -->

</mime:part>

</mime:multipartRelated>

<mime:mimeXml part="nmtoken"?/>

They are used at the following locations in WSDL:

<definitions .... >

<binding .... >

<operation .... >

<input .... >

<-- mime elements -->

</input>

<output .... >

<-- mime elements -->

</output>

</operation>

</binding>

</definitions>

MIME elements appear under input and output to specify the MIME format. If multiple appear, they are considered to be alternatives.

5.3 mime:content

To avoid having to define a new element for every MIME format, the mime:content element may be used if there is no additional information to convey about the format other than its MIME type string.

<mime:content part="nmtoken"? type="string"?/>

The part attribute is used to specify the name of the message part. If the message has a single part, then the part attribute is optional. The type attribute contains the MIME type string. A type value has two portions, separated by a slash (/), either of which may be a wildcard (*). Not specifying the type attribute indicates that all MIME types are acceptable.

If the return format is XML, but the schema is not known ahead of time, the generic mime element can be used indicating text/xml:

<mime:content type="text/xml"/>

A wildcard (*) can be used to specify a family of mime types, for example all text types.

<mime:content type="text/*"/>

The following two examples both specify all mime types:

<mime:content type="*/*"/>

<mime:content/>

5.4 mime:multipartRelated

The multipart/related MIME type aggregates an arbitrary set of MIME formatted parts into one message using the MIME type "multipart/related". The mime:multipartRelated element describes the concrete format of such a message:

<mime:multipartRelated>

<mime:part> *

<-- mime element -->

</mime:part>

</mime:multipartRelated>

The mime:part element describes each part of a multipart/related message. MIME elements appear within mime:part to specify the concrete MIME type for the part. If more than one MIME element appears inside a mime:part, they are alternatives.

5.5 soap:body

When using the MIME binding with SOAP requests, it is legal to use the soap:body element as a MIME element. It indicates the content type is "text/xml", and there is an enclosing SOAP Envelope.

5.6 mime:mimeXml

To specify XML payloads that are not SOAP compliant (do not have a SOAP Envelope), but do have a particular schema, the mime:mimeXml element may be used to specify that concrete schema. The part attribute refers to a message part defining the concrete schema of the root XML element. The part attribute MAY be omitted if the message has only a single part. The part references a concrete schema using the element attribute for simple parts or type attribute for composite parts (see section 2.3.1).

<mime:mimeXml part="nmtoken"?/>

No comments: