Proposal for the resolution of LC345

On the 2005-Oct-06 WG conference call,  it was realised that as part of addressing LC345 by reworking HTTP serializations at the F2F in Palo Alto, the capability for serializing instance data in parts of the HTTP request for application/xml was lost. It was agreed that we should not lose this capability and to explore how to provide it in the reworked HTTP serializations.

To address this, we should generalize the usage of the {http location} property for all HTTP serializations, as opposed to its specific use for the application/x-www-form-urlencoded serialization. Below is outlined a proposal to generalize this usage:

A. In Part, Section 6.8, add the following text:

6.8.1 Serialization of the instance data in parts of the HTTP request

In HTTP binding, part of the instance data MAY be serialized in the HTTP request IRI, and another part MAY be serialized in the HTTP message body. If the Binding Operation component uses the IRI style, and the value of the {http location} property of the Binding Operation component is present, this value is used as a template which is combined with the {address} property of the endpoint element to form the full IRI to be used in an HTTP request, as specified in section 6.5.2 Relationship to WSDL Component Model.

The resulting IRI MUST be mapped to an URI for use in the HTTP Request as per section 3.1 "Mapping of IRIs to URIs" of the IRI specification [IETF RFC 3987].

6.8.1.1 Construction of the request IRI using the {http location} property

The {http location} property, if present, MAY cite local names of elements from the instance data of the message to be serialized in request IRI by enclosing the element name within curly braces (e.g. "temperature/{town/}"):

• When constructing the request IRI, each pair of curly braces (and enclosed element name) is replaced by the possibly empty single value of the corresponding element. It is an error for this element to carry an xs:nil attribute whose value is "true".
• A double curly brace (i.e. "{{" or "}}") MAY be used to include a single, literal curly brace in the request IRI.

An element MUST NOT be cited more than once within the {http location} property.

Strings enclosed within single curly braces MUST be element names from the instance data of the input message, possibly followed by a slash; any other strings enclosed within single curly braces are a fatal error.

6.8.1.2 Serialization of content of the instance data not cited in the {http location} property

If not all elements from the instance data are cited in the {http location} property, or if the property is not present on the Binding Operation component, then additional serialization rules apply.

The remainder of the instance data is serialized as a query string as defined in 6.8.1.3.1 Construction of the query string.

If the HTTP method used for the request, as specified by the {http method}, does not allow a message body, then this query string is serialized as parameters in the request IRI (see 6.8.1.3.2 Serialization in the request IRI), otherwise it is serialized in the message body (see 6.8.1.3.3 Serialization in the message body).

6.8.1.2.1 Construction of the query string

For elements of the instance data not cited in the {http location} property, a query string is constructed as follows.

Non-nil elements with a possibly empty single value of the instance data not cited are serialized as query parameters in the order they appear in the instance data.

It is an error for the instance data to contain elements with an xs:nil attribute whose value is "true".

Each parameter pair is separated by the value of the {http query parameter separator} property.

• Uncited elements with single values (non-list) are serialized as a single name-value parameter pair. The name of the parameter is the local name of the uncited element, and the value of the parameter is the value of the uncited element.
• Uncited elements with list values are serialized as one name-value parameter pair per list value. The name of each parameter is the local name of the uncited element, and the value of each parameter is the corresponding value in the list. The order of the list values is preserved.

Example 6-1. Query string generation

The following instance data of an input message

<data>

  <town>Fréjus</town>

  <date>@@@@-@@-@@</date>

  <unit>C</unit>

</data>

with the following value of the {http location} property:

'temperature/{town}'

and the following value of the {http query parameter separator} property:

'&'

will produce the following query string:

date=@@@@-@@-@@&unit=C

B. In Part 2, Section 6.8, update the subsection on "Serialization as "application/x-www-form-urlencoded" as follows:

6.8.2 Serialization as "application/x-www-form-urlencoded"

This serialization format is designed to allow a client or Web service to produce an IRI based on the instance data of a message and serialize a query string in the HTTP message body as application/x-www-form-urlencoded.

It may only be used when binding Interface Operation whose {style} property has a value of "http://www.w3.org/@@@@/@@/wsdl/style/iri" as defined in 4.2 IRI Style, i.e. this serialization format may only be used to serialize the HTTP request corresponding to the initial message of an interface operation.

Because the IRI Style constrains the instance data not to contain multiple children elements declared with the same local name, elements can be serialized in the request IRI with their local names unambiguously.

For the HTTP binding defined in this section (6. WSDL HTTP Binding Extension), "application/x-www-form-urlencoded" MAY be used as a value for the {http input serialization} property of the Binding Operation component, but MUST NOT be used as a value as a value for the {http output serialization} or {http fault serialization} properties.

6.8.2.1 Serialization in the request IRI

Non-nil elements with a possibly empty single value of the instance data from the input message NOT cited by the {http location} property are serialized as query parameters appended to the request IRI (e.g. Example 6-1) in the order they appear in the instance data.

It is an error for the instance data to contain elements with an xs:nil attribute whose value is "true".

If the {http location} property is not present, or if it is present and its value does not contain a "?" (question mark) character, one is appended. If it does already contain a question mark character, then the value of the {http query parameter separator} property is appended. Each parameter pair is separated by the value of the {http query parameter separator} property.

• Uncited elements with single values (non-list) are serialized as a single name-value parameter pair. The name of the parameter is the local name of the uncited element, and the value of the parameter is the value of the uncited element.
• Uncited elements with list values are serialized as one name-value parameter pair per list value. The name of each parameter is the local name of the uncited element, and the value of each parameter is the corresponding value in the list. The order of the list values is preserved.

• Finally, the query string computed in 6.8.1.2.1 Construction of the query string is
• appended.
• 
  

6.8.2.2 Serialization in the message body

In addition to the serialization in the request IRI of the elements cited in the {http location} property, the entire instance data is serialized in the message body following the rules of the "application/xml" (see 6.8.2 Serialization as application/xml ).

Finally, the query string computed in 6.8.1.2.1 Construction of the query string is used as the value of the HTTP message body.

Example 6-2. Instance data serialized in a IRI and in a message body

The following instance data of an input message

<data>

  <town>Fréjus</town>

  <date>2004-01-16</date>

  <unit>C</unit>

  <value>24</value>

</data>

with the following operation element:

<operation ref='t:data'

    whttp:inputSerialization='application/x-www-form-urlencoded'

    whttp:location='temperature/{town/}'

    whttp:method='POST' />

and the following endpoint element

<endpoint name='e' binding='t:b'

    address='http://ws.example.com/service1/' />

will serialize the message in an IRI as follows:

http://ws.example.com/service1/temperature/Fréjus

which will be %-encoded as a URI as follows:

http://ws.example.com/service1/temperature/Fr%C3%A9jus

and in the message as follow:

Content-Type: application/xml

Content-Length: xxx

<data>

  <town>Fréjus</town>

  <date>2004-01-16</date>

  <unit>C</unit>

  <value>24</value>

</data>

C. In Part 2, Section 6.8, update the subsection on "Serialization as "application/xml" as follows:

6.8.3 Serialization as "application/xml"

The instance data of the input, output or fault message is serialized as an XML document in the message body of the HTTP request, following the serialization defined in [Canonical XML], including the serialization of a query string in the HTTP message body. 

The Content-Type HTTP header MUST have the value application/xml, or a media type compatible with application/xml. Other HTTP headers, such as Content-Encoding or Transfer-Encoding, MAY be used.

If the HTTP request method used, specified in the {http method} of the Binding Operation component bound, does allow an HTTP message body (e.g. "POST" and "PUT"), then the following rules apply.

The Content-Type HTTP header field must have the value application/xml.

Example 6-4. Instance data serialized in the message body

The instance data defined in Example 6-1 with the following operation declaration:

<operation ref='t:data'

    whttp:inputSerialization='application/xml'

    whttp:location='temperature/{town/}'

    whttp:method='POST' />

and the following endpoint declaration:

<endpoint name='e' binding='t:b'

    address='http://ws.example.com/service1/' />

will serialize the message in the HTTP request as follow:

POST http://ws.example.com/service1/temperature/Fr%C3%A9jus HTTP/1.1

Host: ws.example.com

Content-Type: application/xml

Content-Length: …

date=@@@@-@@-@@&unit=C

D. In Part 2, Section 6.8, update the subsection on "Serialization as "multipart/form-data" as follows:

6.8.4 Serialization as "multipart/form-data"

This format is for legacy compatibility to permit the use of XForms clients with [IETF RFC 2388] servers. This serialization format may only be used when binding Interface Operation whose {style} property has a value of "http://www.w3.org/@@@@/@@/wsdl/style/multipart" as defined in 4.3 Multipart style, i.e. this serialization format may only be used to serialize the initial message of an interface operation. 

Specifically, for the HTTP binding defined in this section (6. WSDL HTTP Binding Extension), "multipart/form-data" MAY be used as a value for the {http input serialization} property of the Binding Operation component, but MUST NOT be used as a value as a value for the {http output serialization} or {http fault serialization} properties.

Each element in the sequence is serialized into a part as follows:

1. The Content-Disposition header MUST have the value form-data, and its name parameter is the local name of the element.
2. The Content-Type header MUST have the value:
• application/xml (or a media type compatible with application/xml) if the element has a complex type;
• application/octet-stream if the element is of type xs:base64Binary, xs:hexBinary, or a derived type;
• text/plain if the element has a simple type; The charset MUST be set appropriately. UTF-8 or UTF-16 MUST be at least supported.
3. If the type is xs:base64Binary, xs:hexBinary, xs:anySimpleType or a derived type, the content of the part is the content of the element. If the type is a complex type, the element is serialized following the rules defined in the 6.8.2 Serialization as application/xml .

It is an error for the instance data to contain elements with an xs:nil attribute whose value is "true".

If the HTTP request method used, specified in the {http method} of the Binding Operation component bound, does allow an HTTP message body (e.g. "POST" and "PUT"), then the following rules apply.

The Content-Type HTTP header field must have the value multipart/form-data.

Example 6-5. Example of multipart/form-data

The following instance data of an input message:

<data>

  <town>

    <name>Fréjus</name>

    <country>France</country>

  </town>

  <date>2004-01-16</date>

</data>

with the following operation element

<operation ref='t:data'

    whttp:location='temperature/{town/}'

    whttp:method='POST'

    whttp:inputSerialization='multipart/form-data'/>

will serialize the message as follow:

Content-Type: multipart/form-data; boundary=AaB03x

Content-Length: xxx

--AaB03x

Content-Disposition: form-data; name="town"

Content-Type: application/xml

<town>

  <name>Fréjus</name>

  <country>France</country>

</town>

--AaB03x

Content-Disposition: form-data; name="date"

Content-Type: text/plain; charset=utf-8

2004-01-16

--AaB03x--