The SOAP Message Structure | Programming MicrosoftВ® .NET XML Web Services (Pro-Developer)

A SOAP message is composed of two required sections—the <Envelope> section and the <Body> section—and an optional <Header> section. The <Envelope> section contains both the <Body> section and the optional <Header> section. Both the <Envelope> and <Body> elements belong to the SOAP envelope namespace, which is found at http://schemas.xmlsoap.org/soap/envelope (in SOAP 1.1) or http://www.w3.org/2002/12/soap-envelope (in SOAP 1.2). A traditional SOAP message conforming to both the 1.1 and 1.2 versions of the standard has the structure shown in Figure 2-1.

Figure 2-1: The traditional SOAP message structure

The first thing to note about the diagram is that although it is far from being a fully formed SOAP message, each element in the message is prefixed by the soap: namespace. This namespace is defined in the <Envelope> element and applies to all elements contained in the SOAP namespace. We’ve chosen to call the SOAP namespace soap because this is the default namespace that Microsoft Visual Studio .NET uses when it automatically creates SOAP messages. All elements prefixed with soap: belong within the envelope namespace.

Also note that the SOAP body can contain two sections. One section contains the details of the method call or response and the name of the XML payload. Another section contains fault information. SOAP parcels up the message (the document or the RPC) in an XML document within the <Envelope> element using namespaces to identify parts of the body.

Namespaces

Namespaces play a big part in SOAP. They are used to combat the problems of ambiguity between two or more XML documents by preventing clashes in element and attribute names. This is done by prefixing the element or attribute name with additional identifying text, such as the soap: prefix we just used (for example, <soap:body>). The namespaces themselves are arbitrary URIs that must be specified when a prefix mapping for the namespace is defined, as in our SOAP 1.1 envelope namespace, xmlns:soap="http://schemas.xmlsoap.org/soap/envelope”.

Namespaces are pervasive in SOAP: there are namespaces for the SOAP envelope, the elements in the SOAP body, the method’s request and response, and even the Web service itself. There are also namespaces that define the schema documents that apply to the SOAP message. We won’t digress into a full-blown explanation of how they work— see Appendix A for a refresher on XML Schema definition language (XSD) if you need reminding. Instead, we’ll concentrate on the namespaces that apply to SOAP.

The SOAP 1.1 standard defines two namespaces, the SOAP envelope namespace (http://schemas.xmlsoap.org/soap/envelope/) and the SOAP serialization namespace (http://schemas.xmlsoap.org/soap/encoding/). We’ll use the soap: prefix to identify the contents of the SOAP envelope throughout this chapter. To validate our SOAP messages and XML documents, we’ll also use the common xsd: prefix to specify a namespace for our schema document and we’ll use the xsi: prefix for the schema instance documents. The XML Schema belongs to the http://www.w3.org/2001/XMLSchema namespace, and the XML Schema instance belongs to the http://www.w3.org/2001/XMLSchema-instance namespace. These namespaces contain elements defined in the XML Schema standard; you should specify them in the SOAP envelope whenever prefix name mappings are defined.

Namespaces in SOAP 1.2

SOAP’s use of namespaces has been improved in SOAP 1.2; version 1.1 left room for ambiguity between elements. For instance, when developing an application, I tested the SOAP returned, which used a <title> element, and wrote it straight to the screen along with the HTML. The browser immediately assumed that this was the HTML <title> element and wrote it to the title bar. Namespace qualification would have resolved this. In SOAP 1.2, all subelements within the namespace body should be qualified. The namespaces all have new URIs in SOAP 1.2 as well. (The URI for the envelope is http:/ /www.w3.org/2002/12/soap-envelope.) Apart from these two points, nothing else has changed. The namespaces can be relative or absolute URIs, just as before. For more information about namespaces, we suggest you check out http://www.w3.org/TR/REC- xml-names/.

The namespace differences aren’t the only differences between the two versions of the SOAP standard. In fact, it’s worth a brief digression to consider the current state of the standard because we’ll discuss it again during the course of the chapter.