Appendices

3.8 Serialization format of instance data

Serialization format of instance data

The following serialization formats can be used to encode the instance_data corresponding to the input and output message, as well as the media types and HTTP headers associated.

Other serialization formats may be used. Those MAY place restrictions on the style of the interface operation bound.

Serialization as application/x-www-form-urlencoded [top]

Serialization as application/x-www-form-urlencoded

This serialization format is designed to allow a Web Service to produce a URI based on the instance_data of input messages. It may only be used for interface operation using the URI Style format as defined in [URI Style].

Elements from the instance data can be inserted into the path of the request URI, or a query parameter, as shown in the example below:

Instance data serialized in a URI

The following instance data of an input message

<data>
  <town>Fréjus</town>
  <date>2004-01-16</date>
  <unit>C</unit>
</data>

with the following operation element

<operation ref='t:io'
    whttp:location='temperature/{town}'
    whttp:method='GET' />

and the following endpoint element

<endpoint name='e' binding='t:b'
    address='http://ws.example.com/service1' />

will serialize the message in the URI as follow:

http://ws.example.com/service1/temperature/Fr%C3%A9jus?date=2004-01-16&unit=C

NOTE:
Element name and element content MUST be URI escaped when inserted into the request, as defined in "[Serialization as application/x-www-form-urlencoded]" ([XForms10], Section 11.6).

Case of elements cited in whttp:location attribute[top]

Case of elements cited in whttp:location attribute

Ed. Note: URIPath Feedback Requested The inclusion of elements of the instance data in the path of the request URI, whilst supported by WSDL 1.1, is not supported by XForms 1.0. Hence this mechanism MAY be removed in a future version of this specification. Feedback on this issue from users and implementers is highly encouraged.

The location attribute information item MAY cite elements instance_data of the input message to be serialized in the path of the request URI ("URI Syntactic Components", [RFC2396], Section 3) by enclosing the element name within curly braces (e.g. location="temperature/{town}"):

When constructing the request URI, each pair of curly braces (and enclosed element name) is replaced by the corresponding content of the element.
A double curly brace (i.e. "{{" or "}}") MAY be used to include a single, literal curly brace in the request URI.

An element MUST NOT be cited more than once within the location attribute information item.

An element name MAY be followed by a slash (i.e. "/") inside curly braces (e.g. location="temperature/{town/}") to indicate that no other element must be serialized in the request URI (see [Case elements NOT cited in ]).

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.

Case elements NOT cited in whttp:location attribute[top]

Case elements NOT cited in whttp:location attribute

If not all elements from the instance_data are cited in the whttp:location attribute, then additional serialization rules apply.

If an element name appears in the whttp:location attribute information item followed by a slash, then the instance data must be serialized in the message body (see [Serialization in the message body]), otherwise the elements not cited must be serialized as parameters in the request URI (see [Serialization in the request URI]).

Serialization in the request URI[top]

Serialization in the request URI

All elements of the instance_data from the input message NOT cited by the location attribute information item are serialized as query parameters appended to the request URI (e.g. [Instance data serialized in a URI]).

If the location attribute does not contain a '?' (question mark) character, one is appended. If it does already contain a question mark character, then an "&" separator character is appended. Each parameter pair is separated by the "&" separator character.

Uncited elements with single values (non-list) are serialized as a single name-value parameter pair. The name of the parameter is the 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 name of the uncited element, and the value of each parameter is the corresponding value in the list.

Serialization in the message body[top]

Serialization in the message body

In addition to the serialization in the request URI of the elements cited in the whttp:location attribute, the entire instance_data is serialized in the message body following the rules of the application/xml (see [Serialization as ]).

Instance data serialized in a URI 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:io'
    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 the URI as follow:

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>

Serialization as application/xml [top]

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].

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.

Serialization as multipart/form-data [top]

Serialization as multipart/form-data

This format is for legacy compatibility to permit the use of XForms clients with [RFC2388] servers. This serialization format may only be used for interface operations using the Multipart Style format as defined in [Multipart style].

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

The Content-Disposition header MUST have the value form-data, and its name parameter is the local name of the element.
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.
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 [Serialization as ].

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>