4 SOAP Envelope

Team-Fly

---

 

	XML, Web Services, and the Data Revolution By Frank  P.  Coyle
	Table of Contents
	Appendix  B.   SOAP Version 1.2 Part 1: Messaging Framework

---

A SOAP message has an XML Infoset that consists of a document information item with exactly one child, which is an element information item as described below.

The document element information item has:

• A local name of Envelope ;

• A namespace name of http://www.w3.org/2001/12/soap-envelope;

• Zero or more namespace qualified attribute information items;

• One or two element information item children in order as follows :

  1. An optional Header element information item, see 4.2 SOAP Header ;

  2. A mandatory Body element information item, see 4.3 SOAP Body ;

4.1 Envelope Encoding and Versioning

4.1.1 SOAP encodingStyle Attribute

SOAP defines an encodingStyle attribute information item which can be used to indicate the encoding rules used to serialize a SOAP message.

The encodingStyle attribute information item has:

• A local name of encodingStyle

• A namespace name of http://www.w3.org/2001/12/soap-envelope

Editorial note: MJG 20010802

The following sentence conflicts with the definition of the Body

It may appear on any element information item in the SOAP message. Its scope is that of its owner element information item and that element information item's descendants, unless a descendant itself owns such an attribute information item.

The encodingStyle attribute information item is of type anyURI in the namespace http://www.w3.org/2001/XMLSchema . Its value identifies a set of serialization rules that can be used to deserialize the SOAP message.

Example: Example values for the encodingStyle attribute

 encodingStyle="http://www.w3.org/2001/12/soap-encoding" encodingStyle="http://example.org/encoding/" encodingStyle="" 

The serialization rules defined by SOAP (see [1]SOAP Encoding) are identified by the URI "http://www.w3.org/2001/12/soap-encoding". SOAP messages using this particular serialization SHOULD indicate this using the SOAP encodingStyle attribute information item. In addition, all URIs syntactically beginning with "http://www.w3.org/2001/12/soap-encoding" indicate conformance with the SOAP encoding rules defined in [1](SOAP Encoding), though with potentially tighter rules added.

A value of the zero-length URI ("") explicitly indicates that no claims are made for the encoding style of contained elements. This can be used to turn off any claims from containing elements.

4.1.2 Envelope Versioning Model

SOAP does not define a traditional versioning model based on major and minor version numbers . If a SOAP message is received by a SOAP 1.2 node in which the document element information item does NOT have a namespace name of http://www.w3.org/2001/12/soap-envelope the SOAP node MUST treat this as a version error and generate a VersionMismatch SOAP fault (see 4.4 SOAP Fault ). See A Version Transition From SOAP/1.1 to SOAP Version 1.2 for further details.

Any other malformation of the message structure MUST be treated as a Sender SOAP fault.

4.2 SOAP Header

SOAP provides a flexible mechanism for extending a SOAP message in a decentralized and modular way without prior knowledge between the communicating parties. Typical examples of extensions that can be implemented as SOAP header blocks are authentication, transaction management, payment, etc.

The Header element information item has:

• A local name of Header

• A namespace name of http://www.w3.org/2001/12/soap-envelope

• Zero or more namespace qualified attribute information item children.

• Zero or more namespace qualified element information item children.

All child element information items of the SOAP Header are called SOAP header blocks.

Each SOAP header block element information item:

• MUST be namespace qualified;

• MAY have an encodingStyle attribute information item

• MAY have an actor attribute information item

• MAY have a mustUnderstand attribute information item

4.2.1 Use of Header Attributes

The SOAP header block attribute information items defined in this section determine how a SOAP receiver should process an incoming SOAP message, as described in 2 SOAP Message Exchange Model .

A SOAP sender generating a SOAP message SHOULD only use the SOAP header block attribute information items on child element information items of the SOAP Header element information item.

A SOAP receiver MUST ignore all SOAP header block attribute information items that are applied to other descendant element information items of the SOAP Header element information item.

Example: Example header with a single header block

 <env:Header xmlns:env="http://www.w3.org/2001/12/soap-envelope" >   <t:Transaction xmlns:t="http://example.org/2001/06/tx" env:  mustUnderstand="1" >     5   </t:Transaction> </env:Header> 

SOAP header block attribute information items MUST appear in the SOAP message itself in order to be effective; default values which may be specified in an XML Schema or other description language do not affect SOAP processing (see 3 Relation to XML ).

4.2.2 SOAP actor Attribute

As described in 2 SOAP Message Exchange Model , not all parts of a SOAP message may be intended for the ultimate SOAP receiver. The actor attribute information item is to be used to indicate the SOAP node at which a particular SOAP header block is targeted .

The actor attribute information item has the following Infoset properties:

• A local name of actor ;

• A namespace name of http://www.w3.org/2001/12/soap-envelope;

• A specified property with a value of true.

The type of the actor attribute information item is anyURI in the namespace http://www.w3.org/2001/XMLSchema. The value of the actor attribute information item is a URI that names a role that a SOAP node may assume.

Omitting the SOAP actor attribute information item implicitly targets the SOAP header block at the ultimate SOAP receiver. An empty value for this attribute is equivalent to omitting the attribute completely, i.e. targeting the block at the ultimate SOAP recipient.

4.2.3 SOAP mustUnderstand Attribute

As described in 2.4 Understanding SOAP Headers , the SOAP mustUnderstand attribute information item is used to indicate whether the processing of a SOAP header block is mandatory or optional at the target SOAP node.

The mustUnderstand attribute information item has the following Infoset properties:

• A local name of mustUnderstand;

• A namespace name of http://www.w3.org/2001/12/soap-envelope;

• A specified property with a value of true.

The type of the mustUnderstand attribute information item is boolean in the namespace http://www.w3.org/2001/XMLSchema. Omitting this attribute information item is defined as being semantically equivalent to including it with a value of "false".

4.3 SOAP Body

The SOAP Body element information item provides a simple mechanism for exchanging mandatory information intended for the ultimate SOAP receiver of a SOAP message. Example uses of SOAP Body include marshalling RPC calls and error reporting.

The Body element information item has:

• A local name of Body

• A namespace name of http://www.w3.org/2001/12/soap-envelope

• Zero or more element information item children.

Editorial note: MJG 20010802

The description of Body does not allow additional attributes.

All child element information items of the SOAP Body element information item:

Editorial note: MJG 20011025

The requirement that direct children of the SOAP body be namespace qualified is a change from previous drafts. The XML Protocol Working Group solicits feedback from implementors on this change.

• MUST be namespace qualified.

• MAY have an encodingStyle attribute information item

SOAP defines one particular direct child of the SOAP body, the SOAP fault, which is used for reporting errors (see 4.4 SOAP Fault ).

4.4 SOAP Fault

The SOAP Fault element information item is used to carry error and/or status information within a SOAP message. If present, the SOAP Fault MUST appear as a direct child of the SOAP body and MUST NOT appear more than once within a SOAP Body.

The Fault element information item has:

• A local name of Fault ;

• A namespace name of http://www.w3.org/2001/12/soap-envelope ;

• Two or more child element information items in order as follows:

  1. A mandatory faultcode element information item, see 4.4.1 SOAP faultcode Element ;

  2. A mandatory faultstring element information item, see 4.4.2 SOAP faultstring Element ;

  3. An optional faultactor element information item, see 4.4.3 SOAP faultactor Element ;

  4. An optional detail element information item, see 4.4.4 SOAP detail Element .

4.4.1 SOAP faultcode Element

The faultcode element information item has:

• A local name of faultcode ;

• A namespace name which is empty

The type of the faultcode element information item is QName in the http://www.w3.org/2001/XMLSchema namespace. It is intended for use by software to provide an algorithmic mechanism for identifying the fault. SOAP defines a small set of SOAP fault codes covering basic SOAP faults (see 4.4.5 SOAP Fault Codes )

4.4.2 SOAP faultstring Element

The faultstring element information item has:

• A local name of faultstring ;

• A namespace name which is empty.

The type of the faultstring element information item is string in the http://www.w3.org/2001/XMLSchema namespace. It is intended to provide a human readable explanation of the fault and is not intended for algorithmic processing. This element information item is similar to the 'Reason-Phrase' defined by HTTP[2] and SHOULD provide at least some information explaining the nature of the fault.

4.4.3 SOAP faultactor Element

The faultactor element information item has:

• A local name of faultactor ;

• A namespace name which is empty

The type of the faultactor element information item is anyURI in the http://www.w3.org/2001/XMLSchema namespace. It is intended to provide information about which SOAP node on the SOAP message path caused the fault to happen (see 2 SOAP Message Exchange Model ). It is similar to the SOAP actor attribute information item (see 4.2.2 SOAP actor Attribute ) but instead of indicating the target of a SOAP header block, it indicates the source of the fault. The value of the faultactor element information item identifies the source of the fault. SOAP nodes that do not act as the ultimate SOAP receiver MUST include this element information item The ultimate SOAP receiver MAY include this element information item to indicate explicitly that it generated the fault.

4.4.4 SOAP detail Element

The detail element information item has:

• A local name of detail ;

• A namespace name which is empty;

• Zero or more attribute information items;

• Zero or more child element information items.

The detail element information item is intended for carrying application specific error information related to the SOAP Body . It MUST be present when the contents of the SOAP Body could not be processed successfully. It MUST NOT be used to carry error information about any SOAP header blocks. Detailed error information for SOAP header blocks MUST be carried within the SOAP header blocks themselves .

The absence of the detail element information item indicates that a SOAP Fault is not related to the processing of the SOAP Body . This can be used to find out whether the SOAP Body was at least partially processed by the ultimate SOAP receiver before the fault occurred, or not.

All child element information items of the detail element Information Item are called detail entries.

Each such element information item:

• MAY be namespace qualified;

• MAY have an encodingStyle attribute information item.

The SOAP encodingStyle attribute information item is used to indicate the encoding style used for the detail entries (see 4.1.1 SOAP encodingStyle Attribute ).

4.4.5 SOAP Fault Codes

Editorial note: MJG 20011130

Previous versions of this specification supported a hierarchical notation for fault codes using a 'dot' notation. This support has been removed in this draft and will also be omitted from the next version of this specification unless significant evidence for the contrary is provided.

SOAP faultcode values are XML qualified names [7]. The faultcodes defined in this section MUST be used as values for the SOAP faultcode element information item when describing faults defined by SOAP 1.2 Part 1 (this document). The namespace identifier for these SOAP faultcode values is "http://www.w3.org/2001/12/soap-envelope". Other specifications may define their own fault codes. Use of this namespace is recommended (but not required) in the specification of such faultcodes.

The faultcode values defined by this specification are listed in the following table.

Name	Meaning
VersionMismatch	The processing party found an invalid namespace for the SOAP Envelope element information item (see 4.1.2 Envelope Versioning Model )
MustUnderstand	An immediate child element information item of the SOAP Header element information item that was either not understood or not obeyed by the processing party contained a SOAP mustUnderstand attribute information item with a value of "true" (see 4.2.3 SOAP mustUnderstand Attribute )
DTDNotSupported	The SOAP message contained a Document Type Definition (see 3 Relation to XML ).
DataEncodingUnknown	A header or body targetted at the current SOAP node is scoped (See 4.1.1 SOAP encodingStyle Attribute ) with a data encoding that the current node does not support.
Sender	A Sender faultcode indicates that the message was incorrectly formed or did not contain the appropriate information in order to succeed. For example, the message could lack the proper authentication or payment information. It is generally an indication that the message should not be resent without change. See also 4.4 SOAP Fault for a description of the SOAP fault detail sub-element .
Receiver	The Receiver faultcode indicates that the message could not be processed for reasons not directly attributable to the contents of the message itself but rather to the processing of the message. For example, processing could include communicating with an upstream SOAP node, which did not respond. The message may succeed at a later point in time. See also 4.4 SOAP Fault for a description of the SOAP fault detail sub-element.

4.4.6 MustUnderstand Faults

When a SOAP node generates a MustUnderstand fault, it SHOULD provide, in the generated fault message, header blocks as described below which detail the qualified names (QNames, per the XML Schema Datatypes specification[5]) of the particular header block(s) which were not understood.

Each such header block element information item has:

• A local name of Misunderstood ;

• A namespace name of http://www.w3.org/2001/12/soap-faults ;

• A qname attribute information item as desribed below.

The qname attribute information item has the following Infoset properties:

• A local name of qname ;

• A namespace name which is empty;

• A specified property with a value of true.

The type of the qname attribute information item is QName in the http://www.w3.org/2001/XMLSchema namespace. Its value is the QName of a header block which the faulting node failed to understand.

Consider the following message:

Example: SOAP envelope that will cause a SOAP MustUnderstand fault if Extension1 or Extension2 are not understood

 <?xml version="1.0" ?> <env:Envelope xmlns:env='http://www.w3.org/2001/12/  soap-envelope'>   <env:Header>     <abc:Extension1 xmlns:abc='http://example.org/2001/06/ext'                        env:mustUnderstand='1' />     <def:Extension2 xmlns:def='http://example.com/stuff'                        env:mustUnderstand='1' />   </env:Header>   <env:Body>   . . .   </env:Body> </env:Envelope> 

The above message would result in the fault message shown below if the recipient of the initial message does not understand the two header elements abc:Extension1 and def:Extension2 .

Note that when serializing the qname attribute information item there must be an in-scope namespace declaration for the namespace name of the misunderstood header and the value of the attribute information item must use the prefix of such a namespace declaration.

Note also that there is no guarantee that each MustUnderstand error contains ALL misunderstood header QNames. SOAP nodes MAY generate a fault after the first header block that causes an error containing details about that single header block only, alternatively SOAP nodes MAY generate a combined fault detailing all of the MustUnderstand problems at once.

Example: SOAP fault generated as a result of not understanding Extension1 and Extension2

 <?xml version="1.0" ?> <env:Envelope xmlns:env='http://www.w3.org/2001/12/soap-envelope'                       xmlns:f='http://www.w3.org/2001/12/  soap-faults' >   <env:Header>     <f:Misunderstood qname='abc:Extension1'                           xmlns:abc='http://example.org/2001/06/  ext' />     <f:Misunderstood qname='def:Extension2'                           xmlns:def='http://example.com/stuff' />   </env:Header>   <env:Body>     <env:Fault>       <faultcode>env:MustUnderstand</faultcode>       <faultstring>One or more mandatory headers not understood</  faultstring>     </env:Fault>   </env:Body> </env:Envelope> 

---

Team-Fly

Top