SCDJWS Study Guide: SOAP


Printer-friendly version Printer-friendly version | Send this 
article to a friend Mail this to a friend


Previous Next vertical dots separating previous/next from contents/index/pdf Contents

The Basic Structure of SOAP

SOAP messages are transmitted between applications and may pass through a number of intermediaries as they travel from the initial sender to the ultimate recipient.

A SOAP message, represented by the Envelope element, contains an optional Header and a mandatory Body child element. The Body element can contain a number of body entries (The optional Fault child element of Body element is present only in messages that report a processing exception).

The Envelope element identifies the XML as being a SOAP message and must be the root element of the SOAP message. The Body element contains the message payload which is the actual application data being exchanged between applications. The Header element provides an extension hook that allows SOAP to be extended in arbitrary ways. If a Header element is presented, it must be the immediate child of the Envelop element and precede the Body element. 

The structure of a Basic SOAP message is shown in the following Listing:

<?xml version=”1.0” encoding=”UTF-8”?>
<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'>
 <soap:Header>
   <!-- extensions of Header blocks go here -->
 </soap:Header>
 <soap:Body>
   <!-- message payload goes here -->
 </soap:Body>
</soap:Envelope>


The element of SOAP message is shown in the following table:

Element
Parent
Use
Description
Envelope
None
1
Root element of the SOAP message.
    Header
Envelope
?
Encloses header entrues.
        Header entries
Header
*
Header entries provide additional information on the message’s content. For example, digital signatures, authorization data, and so on.
    Body
Envelope
1
Encloses the message's body entries
        Body entries
Body
*
Body entries make up the content of the message. Their element names depend on the message’s content.
        Fault
Body
?
entry used to report a problem. When used, no other body entry can be present.
            faultcode
Fault
1
Indicates the reason for the fault. Intended for application use.
            faultstring
Fault
?
Human-readable version of the fault reason.
            faultactor
Fault
?
Indicates which entity along the message path raised the fault.
            detail
Fault
?
Encloses detail entries
                detail entries
detail
*
Contain application-specific information about the fault.


SOAP has its own XML schema, namespace http://schemas.xmlsoap.org/soap/envelope, and processing rules.

As can be seen, SOAP messages rely heavily on XML Namespaces. All of the elements in our XML document are prefixed with the namespace soap, and there is a good reason why the SOAP specification uses namespaces so extensively. In order for a SOAP message to carry any arbitrary XML payload, all the elements of the message must be scoped in some fashion to avoid conflicts in the names of elements.

The Namespaces in XML Recommendation can be found at http://www.w3.org/TR/REC-xml-names/.

The namespace prefix soap is used on most of the elements in the above message. The prefix is associated with the namespace URI http://schemas.xmlsoap.org/soap/envelope/, and it identifies the elements that are part of a standard SOAP message. Like all namespace prefixes, the choice of soap is irrelevant. The namespace prefix could have been something else entirely. The namespace prefix could also be eliminated completely if the namespace is the default namespace for the document.

  • A SOAP message may have an XML declaration <?xml …?>, which states the version of XML used and the encoding format. The version of XML must be 1.0 and the encoding must be either UTF-8 (default) or UTF-16. The XML declaration must at the first line of the SOAP message document.
  • A SOAP message adheres to the SOAP 1.1 XML schema, which requires that elements and attributes be fully qualified (use prefixes or default namespaces).
  • The Envelope element is the root element of the SOAP message. It contains one and only one Body element preceded by zero or one Header element. If the Header element is used, it must be the immediate child of the Envelope element.
  • The Envelope element can not contain any other children elements other than Header and Body elements.

The interpretation of sibling elements following the soap:Body element is unclear. Therefore, such elements are disallowed. [WS-I Basic Profile 1.0]


R1011
A MESSAGE MUST NOT have any element children of soap:Envelope following the soap:Body.

All the attributes that the SOAP envelope schema defines are global (they are not associated with a particular element). Also, each element in a SOAP message is free to use any attribute, regardless of where it’s defined, either in SOAP’s schema or another one, which is one of SOAP’s extensibility features. This means that elements are free to use any number of attributes. The following table describes the attributes that the SOAP specification defines.

Attribute
Value
Description
actor
A URI
Specifies the entity that is to process the element. When absent, the actor is the ultimate recipient of the message. This attribute is used mainly to assign header entries to specific entities.
mustUnderstand
0 or 1
Indicates whether the element’s actor must process the element. When set to 1 and if the actor is unable to process the element, the actor must respond with a Fault.
encodingStyle
A list of URIs
Indicates the encoding style used for the element’s content.
 

The soap:mustUnderstand attribute has a restricted type of “xsd:Boolean” that takes only “0” or “1”. Therefore, only those two values are allowed. [WS-I Basic Profile 1.0]


R1013
A MESSAGE containing a soap:mustUnderstand attribute Must only use the lexical forms “0” and “1



Previous Next vertical dots separating previous/next from contents/index/pdf Contents

  |   |