Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท XML and SOAP Messages

SOAP Styles and Encoding

Learn the SOAP binding styles RPC/encoded, RPC/literal, document/literal and document/literal wrapped, why WS-I chose wrapped, and how to dispatch each style in code.

SOAP says only that a message has an Envelope with a Body. It does not say how a function call or a business document must be laid out inside the Body. Two choices, made in the WSDL binding, decide that: the style (rpc or document) and the use (encoded or literal). Four combinations exist, and knowing them explains many odd-looking messages and many interoperability bugs.

Style: RPC or document

  • RPC style treats the message as a remote procedure call. The first child of Body is an element named after the operation, and its children are the parameters by name.
  • Document style treats the message as a document. The Body contains whatever XML the schema defines. Nothing in the message names the operation; the receiver infers it (by the root element name, by SOAPAction, or from the schema).

Use: encoded or literal

  • Encoded uses SOAP's own data-type rules (Section 5 encoding): each value carries an xsi:type attribute such as xsi:type="xsd:int", and graphs of objects are serialized with id/href references. It was designed for passing programming-language objects around.
  • Literal means the content follows an XML Schema exactly, as written. No type attributes are needed, because the schema already tells the receiver the types.

Encoded was popular around 2000, but different vendors implemented it differently and interoperability was poor. The WS-I Basic Profile (an industry interoperability rule set) forbade it. Today nearly all services use literal.

One call, four encodings

This program writes the same call, GetPrice(product="tea", quantity=3), in the four combinations so you can compare.

Node.js Four styles of the same call

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at rpc/literal and document/literal wrapped: on the wire they are almost the same. The difference is in the WSDL: wrapped document style defines the wrapper element GetPrice in an XML Schema, so validators and code generators can use it.

The four combinations compared

Combination Operation name visible in body? Validatable with a schema? WS-I Basic Profile Notes
RPC/encoded yes no not allowed Legacy. Interoperability problems.
RPC/literal yes partly (parts only) allowed Simple; the wrapper element is not in a schema.
Document/literal no yes allowed Ambiguous when two operations have the same input element.
Document/literal wrapped yes (by convention) yes allowed Best of both; the usual choice of Java and .NET tools.

Wrapped is a convention, not a separate setting in the WSDL: the input message has a single part, the element has the same name as the operation, and its children are the parameters. Frameworks detect it and generate nice method signatures from it.

Dispatching on the wire

A service receiving a document/literal message needs a rule to find the operation. The usual one: use the name of the first Body child (works for rpc and wrapped). Another: use SOAPAction. This dispatcher shows both, and why unwrapped document style can get ambiguous.

Node.js Dispatching by body element and by SOAPAction

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The unwrapped Query message cannot be routed by the body alone. Only the SOAPAction hint saves it. If two operations used the same input element and the same action, they would be indistinguishable, which is the main reason wrapped style became standard.

Which should you choose?

For a new service: document/literal wrapped. Every mainstream toolkit (JAX-WS, WCF, Apache CXF, Spring-WS, .NET) generates it by default, it validates against a schema, and it works with the Basic Profile. Use rpc/literal only when a partner requires it. Never choose RPC/encoded for something new, but be able to recognize it, because old banking and ERP interfaces still use it: the giveaway is xsi:type attributes and an encodingStyle attribute.

You rarely write the style by hand: you set it in the WSDL binding (style="document" and use="literal") or with an annotation such as @SOAPBinding(style = DOCUMENT, use = LITERAL, parameterStyle = WRAPPED) in Java. WSDL bindings and ports shows where the settings live.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the literal use mean?

    Literal content follows the schema exactly. Encoded content carries type attributes and uses SOAP's own data model.
  2. 2. Which combination is forbidden by the WS-I Basic Profile?

    RPC/encoded caused interoperability problems and is not allowed by the Basic Profile.
  3. 3. In document/literal wrapped style, the first child of Body is named after...

    The wrapper element has the operation's name, and its children are the parameters.
  4. 4. Why can plain document/literal be ambiguous?

    Without a wrapper named after the operation, the receiver must use other hints such as SOAPAction.

Summary

  • Style (rpc or document) and use (encoded or literal) define how a payload is laid out in the Body.
  • RPC/encoded is legacy; recognize it by xsi:type attributes, and avoid it.
  • Document/literal wrapped is the modern default: schema-described, operation-named, tool-friendly.
  • Dispatch by the first Body child, falling back to SOAPAction.

Next: WSDL Structure