SOAP Syntax

A SOAP message is an ordinary XML document. It contains the following elements

  • An Envelope element – It  identifies the XML document as a SOAP message
  • A Header element – It contains header information
  • A Body element – It contains call and response information
  • A Fault element – It containins errors and status information

Rules

An SOAP message,

  • MUST be encoded using XML
  • MUST use the SOAP Envelope namespace
  • MUST use the SOAP Encoding namespace
  • Must NOT contain a DTD reference
  • Must NOT contain XML Processing Instructions

 SOAP Message Syntax or The SOAP Envelope Element

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap "
soap:encodingStyle="http://www.w3.org/2001/12/soape">

<soap:Header>
...
</soap:Header>

<soap:Body>
...
<soap:Fault>
...
</soap:Fault>
</soap:Body>

</soap:Envelope>

 

The encodingStyle Attribute

It helps to define the data types used in the document.  The attribute may shows on SOAP element and it applies to the elements contents and all child elements. A SOAP message has no default encoding.

Syntax

soap:encodingStyle=”URI

Example


<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
...
Message information goes here
...
</soap:Envelope>

The SOAP Header Element

SOAP header is optional. It includes the below information’s.Application-specific information (like authentication, payment, etc) about the SOAP message.The Header element must be present on the first child element of the Envelope element. All immediate child elements of the Header element must be namespace-qualified.


<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>
<m:Trans xmlns:m="http://www.w3schools.com/transaction/"
soap:mustUnderstand="1">234
</m:Trans>
</soap:Header>
...
...
</soap:Envelope>

 

The mustUnderstand Attribute

The SOAP mustUnderstand attribute helps to

  • indicate whether a header entry is mandatory or optional for the recipient to process.

If you add mustUnderstand=”1″ to a child element of the Header element it indicates that the receiver processing the Header must recognize the element. If the receiver does not recognize the element it will fail when processing the Header.

Syntax

soap:mustUnderstand=”0|1″

Example


<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>
<m:Trans xmlns:m="http://www.w3schools.com/transaction/"
soap:mustUnderstand="1">234
</m:Trans>
</soap:Header>
...
...
</soap:Envelope>

 

The actor Attribute

A SOAP message may travel from a sender to a receiver by passing different endpoints along the message path. However, not all parts of a SOAP message may be intended for the ultimate endpoint, instead, it may be intended for one or more of the endpoints on the message path.

The SOAP actor attribute is used to address the Header element to a specific endpoint.

Syntax

soap:actor=”URI

Example

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Header>
<m:Trans xmlns:m="http://www.w3schools.com/transaction/"
soap:actor="http://www.w3schools.com/appml/">234
</m:Trans>
</soap:Header>
...
...
</soap:Envelope>

The SOAP Body Element

The required SOAP Body element includes

  • the actual SOAP message intended for the ultimate endpoint of the message.
  • Immediate child elements of the SOAP Body element may be namespace-qualified.

Example

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Body>
<m:GetPrice xmlns:m="http://www.w3schools.com/prices">
<m:Item>Apples</m:Item>
</m:GetPrice>
</soap:Body>

</soap:Envelope>

The example above requests the price of apples. Note that the m:GetPrice and the Item elements above are application-specific elements. They are not a part of the SOAP namespace.

A SOAP response could look something like this:


<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

<soap:Body>
<m:GetPriceResponse xmlns:m="http://www.w3schools.com/prices">
<m:Price>1.90</m:Price>
</m:GetPriceResponse>
</soap:Body>

</soap:Envelope>

The SOAP Fault Element

SOAP Fault element helps to indicate error messages.

If a Fault element is present, it must appear as a child element of the Body element. A Fault element can only appear once in a SOAP message.

The SOAP Fault element has the following sub elements:

<faultcode>:- A code for identifying the fault

<faultstring>:- A human readable explaination of the fault

<faultactor>:- Information about who caused the fault to happen

<detail>:- Holds application specific error information related ti the Body element

SOAP Fault Codes

The faultcode values defined below must be used in the fault code element when describing faults:

VersionMismatch:- Found an invalid namespace for the SOAP Envelope element

MustUnderstand:- An immediate child element of the Header element, with the mustUnderstand attribute set to “1”, was not understood

Client:- The message was incorrectly formed or contained incorrect information

Server:- There was a problem with the server so the message could not proceed