10.3 Attributes in SOAP messages
SOAP defines three attributes in the namespace http://schemas.xmlsoap.org/soap/envelope/. These attributes are listed in the following sections in alphabetical order with a description and examples.
10.3.1 actor
soap:actor='anyURI'
The actor attribute is used to annotate an extension element. It specifies a URI identifying the intermediary for which the annotated extension element is intended. If the value of the attribute is the URI http://schemas.xmlsoap.org/soap/actor/next, then the extension is intended for the next intermediary in the chain, which in the case of the initial sender will be the first one. If the attribute is not present, then the extension element is intended for the ultimate recipient of the message.
ExamplesUse of the actor attribute
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Header> <x:x xmlns:x='http://example.org/Extensions/' soap:actor='http://example.org/Nodes/Fireball/XL5'> <!-- extension detail goes here --> </x:x> </soap:Header> <soap:Body> <!-- message payload goes here --> </soap:Body> </soap:Envelope>
An extension element intended for a specific intermediary in the chain
Use of the actor attribute to target the first intermediary
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Header> <x:x xmlns:x='http://example.org/Extensions/' soap:actor='http://schemas.xmlsoap.org/soap/actor/next'> <!-- extension detail goes here --> </x:x> </soap:Header> <soap:Body> <!-- message payload goes here --> </soap:Body> </soap:Envelope>
An example extension intended for the first intermediary in the chain
10.3.2 encodingStyle
soap:encodingStyle='list of anyURI'
The encodingStyle attribute indicates to the recipient of a SOAP message which serialization format was used to encode a given element and its descendants. This attribute may appear on any element. Descendant elements may override the value of an encodingStyle attribute specified on an ancestor. Elements that use the encoding style described in Section 5 of the SOAP specification should use the URI http://schemas.xmlsoap.org/soapencoding/ as the value of this attribute. Several URIs may be provided, in which case the URIs identifying the more specific encoding rules should appear before those identifying less specific encoding rules.
Example Use of encodingStyle attribute
<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <!-- header and body go here --> </soap:Envelope>
A message that uses the encoding rules described in Section 5 of the SOAP _specification
10.3.3 mustUnderstand
soap:mustUnderstand='boolean'
The mustUnderstand attribute indicates to the recipient of a SOAP message whether processing of an extension element is mandatory. If the attribute has the value 1, then the recipient must recognize the extension element and process it accordingly. If the recipient does not recognize the element, it must report a fault. If the attribute has the value 0 (the default), then processing of the extension element is optional.
Examples Use of mustUnderstand attribute
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Header> <x:x xmlns:x='http://example.org/Extensions/' soap:mustUnderstand='1' > <!-- extension detail goes here --> </x:x> </soap:Header> <soap:Body> <!-- message payload goes here --> </soap:Body> </soap:Envelope>
A mandatory extension as specified by the mustUnderstand attribute with a value of 1.
An optional extension
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <soap:Header> <x:x xmlns:x='http://example.org/Extensions/' soap:mustUnderstand='0' > <!-- extension detail goes here --> </x:x> </soap:Header> <soap:Body> <!-- message payload goes here --> </soap:Body> </soap:Envelope>
An optional extension as specified by the mustUnderstand attribute with a value of 0.