Ednote: This is an editors' copy that has absolutely no standing. The purpose of this editors copy is to show several sections rewritten from the perspective of the XML Infoset[14]. The original text for each paragraph that has been rewritten appears in strike-out style after the new text
The XML Protocol Protocol Working Group has, in
keeping with its charter, produced a set of requirements and usage scenarios
that have been published as a Working Draft. To better evaluate SOAP/1.1
against these requirements and usage scenarios, the Working Group has produced
an abstract model and a glossary of terms and concepts used by the Working
Group. In addition, the Working Group has produced an issues
list that describes issues and concerns raised by mapping its requirements
and the XMLP abstract model against the SOAP/1.1 specification as well
as issues raised on the <xml-dist-app@w3.org>
mailing list against SOAP/1.1.
The current name for this specification is SOAP
version 1.2, this first Working Draft being based on SOAP/1.1 as per the
Working Group's charter (see change log in appendix
D)
Comments on this document should be sent to xmlp-comments@w3.org (public archives). It is inappropriate to send discussion emails to this address.
Discussion of this document takes place on the public <xml-dist-app@w3.org> mailing list (Archives) per the email communication rules in the XML Protocol Working Group Charter.
This is a public W3C Working Draft. It is a draft
document and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use W3C Working Drafts as reference
material or to cite them as other than "work in progress". A list of all
W3C technical reports can be found at http://www.w3.org/TR/.
SOAP consists of four parts:
The SOAP encoding rules (see section 5) defines a serialization mechanism that can be used to exchange instances of application-defined datatypes.
The SOAP RPC representation (see section 7) defines a convention that can be used to represent remote procedure calls and responses.
The SOAP binding (see section 6) defines a convention for exchanging SOAP envelopes between peers using an underlying protocol for transport.
This specification defines two SOAP bindings that describe how a SOAP message can be carried in HTTP [5] messages either with or without the experimental HTTP Extension Framework [6].
boxcarring or batching of messages;
objects-by-reference (which requires distributed garbage collection);
activation (which requires objects-by-reference).
The namespace prefixes "env" and "enc" used in the prose sections of this document are associated with the SOAP namespace names "http://www.w3.org/2001/06/soap-envelope" and "http://www.w3.org/2001/06/soap-encoding" respectively.
The namespace prefixes "xs" and "xsi" used in the prose sections of this document are associated with the namespace names "http://www.w3.org/2001/XMLSchema" and "http://www.w3.org/2001/XMLSchema-instance" respectively, both of which are defined in the XML Schemas specification [10,11].
Note that the choice of any namespace prefix is arbitrary and not semantically significant.
Namespace URIs of the general form "http://example.org/..." and "http://example.com/..." represent an application-dependent or context-dependent URI [4].
This specification uses the augmented Backus-Naur Form (BNF) as described in RFC-2616 [5].
Editorial notes are indicated with yellow background (may not appear in all media) and prefixed with "Ednote".
<env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"> <env:Header> <n:alertcontrol xmlns:n="http://example.org/alertcontrol"> <n:priority>1</n:priority> <n:expires>2001-06-22T14:00:00-05:00</n:expires> </n:alertcontrol> </env:Header> <env:Body> <m:alert xmlns:m="http://example.org/alert"> <m:msg>Pick up Mary at school at 2pm</m:msg> </m:alert> </env:Body> </env:Envelope>
Examples 1 and 2 show a sample SOAP/HTTP request and a sample SOAP/HTTP response. The SOAP/HTTP request contains a block called GetLastTradePrice which takes a single parameter, the ticker symbol for a stock. As in the previous example, the GetLastTradePrice element is not defined by SOAP itself. The service's response to this request contains a single parameter, the price of the stock. The SOAP Envelope element is the top element of the XML document representing the SOAP message. XML namespaces are used to disambiguate SOAP identifiers from application specific identifiers.
POST /StockQuote HTTP/1.1 Host: www.stockquoteserver.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://example.org/2001/06/quotes" <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <env:Body> <m:GetLastTradePrice env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" xmlns:m="http://example.org/2001/06/quotes"> <symbol>DIS</symbol> </m:GetLastTradePrice> </env:Body> </env:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <env:Body> <m:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" xmlns:m="http://example.org/2001/06/quotes"> <Price>34.5</Price> </m:GetLastTradePriceResponse> </env:Body> </env:Envelope>
The formal set of conventions governing the format and processing
rules of a SOAP message and basic control of interaction
among applications generating and accepting
SOAP messages for the purpose of exchanging information along a SOAP
message path.
The formal set of rules for carrying a SOAP message within or on
top of another protocol (underlying protocol) for the purpose of transmission.
Typical SOAP bindings include carrying a SOAP message within an HTTP message,
or on top of TCP.
A SOAP node processes a SOAP message according
to the formal set of conventions defined by SOAP. The
SOAP node is responsible for enforcing the rules that govern the exchange
of SOAP messages and accesses the services provided by the underlying protocols
through SOAP bindings. Non-compliance with SOAP conventions can cause a
SOAP node to generate a SOAP fault (see also SOAP
receiver and SOAP sender).
A SOAP message is the basic unit of communication between peer SOAP
nodes.
The outermost syntactic construct or structure of a SOAP
message defined by SOAP within which all other
syntactic elements of the message are enclosed.
A syntactic construct or structure used to delimit data that logically
constitutes a single computational unit as seen by a SOAP
node. A SOAP block is identified by the fully qualified name of the
outer element for the block, which consists of the namespace URI and the
local name. A block encapsulated within the SOAP header
is called a header block and a block encapsulated within a SOAP
body is called a body block.
A collection of zero or more SOAP blocks which
may be targeted at any SOAP receiver within the SOAP message
path.
A collection of zero, or more SOAP blocks targeted
at the ultimate SOAP receiver within the SOAP
message path.
A special SOAP block which contains fault information
generated by a SOAP node.
Figure 1: Encapsulation model illustrating the parts of a SOAP message
A SOAP sender is a SOAP node that transmits
a SOAP message.
A SOAP receiver is a SOAP node that accepts
a SOAP message.
The set of SOAP senders and SOAP
receivers through which a single SOAP message passes.
This includes the initial SOAP sender, zero or more
SOAP intermediaries, and the ultimate
SOAP receiver.
The SOAP sender that originates a SOAP
message as the starting point of a SOAP message path.
A SOAP intermediary is both a SOAP receiver
and a SOAP sender, target-able from within a SOAP
message. It processes a defined set of blocks in a SOAP
message along a SOAP message path. It acts in order
to forward the SOAP message towards the ultimate
SOAP receiver.
The SOAP receiver that the initial
sender specifies as the final destination of the SOAP
message within a SOAP message path. A SOAP
message may not reach the ultimate recipient because of a SOAP
fault generated by a SOAP node along the SOAP
message path.
A set of abstract constructs that can be used to describe common
data types and link relationships in data.
The syntactic representation of data described by the SOAP
data model within one or more SOAP blocks in a SOAP
message.
SOAP implementations can be optimized to exploit the unique characteristics of particular network systems. For example, the HTTP binding described in section 6 provides for SOAP response messages to be delivered as HTTP responses, using the same connection as the inbound request.
A SOAP node receiving a SOAP message MUST perform processing, generate SOAP faults, SOAP responses, and if appropriate send additional SOAP messages, as provided by the remainder of this specification.
While the purpose of a SOAP actor name is to identify a SOAP node, there are no routing or message exchange semantics associated with the SOAP actor name. For example, SOAP Actors MAY be named with a URI useable to route SOAP messages to an appropriate SOAP node. Conversely, it is also appropriate to use SOAP actor roles with names that are related more indirectly to message routing (e.g. "http://example.org/banking/anyAccountMgr") or which are unrelated to routing (e.g. a URI meant to identify "all cache management software"; such a header might be used, for example, to carry an indication to any concerned software that the containing SOAP message is idempotent, and can safely be cached and replayed.)
SOAP header blocks carry optional env:actor attributes (see section 4.2.2) that are used to target them to the appropriate SOAP node(s). SOAP header blocks with no env:actor attribute and the SOAP body are implicitly targeted at the anonymous SOAP actor, implying that they are to be processed by the ultimate SOAP receiver. We refer to the (implicit or explicit) value of the SOAP actor attribute as the SOAP actor for the corresponding SOAP block (either a SOAP header block or a SOAP body block).
We say that a SOAP block is targeted to a SOAP node if the SOAP actor (if present) on the block matches (see [8]) a role played by the SOAP node, or in the case of a SOAP block with no actor Attribute Information Item (including SOAP body blocks), if the SOAP node has assumed the role of the anonymous SOAP actor.
We say that a SOAP block is targeted to a SOAP node if the SOAP actor (if present) on the block matches (see [8]) a role played by the SOAP node, or in the case of a SOAP block with no actor attribute (including SOAP body blocks), if the SOAP node has assumed the role of the anonymous SOAP actor.
We presume that specifications for a wide variety of header functions will be developed over time, and that each SOAP node MAY include the software necessary to implement one or more such extensions. We say that a SOAP header block is understood by a SOAP node if the software at that SOAP node has been written to fully conform to and implement the semantics conveyed by the fully qualified name of the outer-most element of that block.
SOAP header blocks carry optional Attribute Information Items with a local name of mustUnderstand and a namespace name of http://www.w3.org/2001/06/soap-envelope (see section 4.2.3). When the value of such an Attribute Information Item is true, the SOAP block is said to be mandatory. For such SOAP blocks the targeted SOAP node MUST: either process the SOAP block according to the semantics conveyed by the combination of local name and namespace name of the outer-most Element Information Item of that block; or not process the SOAP message at all, and fail (see section 4.4).
When a SOAP header block is tagged with a SOAP mustUnderstand attribute with a value of "1", the targeted SOAP node MUST: either process the SOAP block according to the semantics conveyed by the fully qualified name of the outer-most element of that block; or not process the SOAP message at all, and fail (see section 4.4).
Process SOAP blocks targeted at the SOAP node, generating SOAP faults if necessary. A SOAP node MUST process SOAP blocks identified as mandatory. A SOAP node MAY process or ignore SOAP blocks not so identified. In all cases where a SOAP block is processed, the SOAP node must understand the SOAP block and must do such processing in a manner fully conformant with the specification for that SOAP block. Faults, if any, must also conform to the specification for the processed SOAP block. It is possible that the processing of particular SOAP block would control or determine the order of processing for other SOAP blocks. For example, one could create a SOAP header block to force processing of other SOAP header blocks in lexical order. In the absence of such a SOAP block, the order of processing is at the discretion of the SOAP node. SOAP nodes can make reference to any information in the SOAP envelope when processing a SOAP block. For example, a caching function can cache the entire SOAP message, if desired.
Process SOAP blocks targeted at the SOAP node, generating SOAP faults if necessary. A SOAP node MUST process SOAP blocks identified as env:mustUnderstand="1". A SOAP node MAY process or ignore SOAP blocks not so identified. In all cases where a SOAP block is processed, the SOAP node must understand the SOAP block and must do such processing in a manner fully conformant with the specification for that SOAP block. Faults, if any, must also conform to the specification for the processed SOAP block. It is possible that the processing of particular SOAP block would control or determine the order of processing for other SOAP blocks. For example, one could create a SOAP header block to force processing of other SOAP header blocks in lexical order. In the absence of such a SOAP block, the order of processing is at the discretion of the SOAP node. SOAP nodes can make reference to any information in the SOAP envelope when processing a SOAP block. For example, a caching function can cache the entire SOAP message, if desired.
All SOAP messages are encoded using XML (see [7] for more information on XML).
A SOAP application MUST ensure that all Element Information Items and Attribute Information Items in messages that it generates are correctly namespace qualified. A SOAP application MUST be able to process SOAP namespace information in messages that it receives. It MUST discard messages that have incorrect namespace information (see section 4.4)
A SOAP application SHOULD include the proper SOAP namespace on all elements and attributes defined by SOAP in messages that it generates. A SOAP application MUST be able to process SOAP namespaces in messages that it receives. It MUST discard messages that have incorrect namespaces (see section 4.4) and it MAY process SOAP messages without SOAP namespaces as though they had the correct SOAP namespaces.
SOAP defines the following namespaces (see [8] for more information on XML namespaces):
The SOAP serialization has the namespace identifier "http://www.w3.org/2001/06/soap-encoding"
The SOAP mustUnderstand fault namespace identifier "http://www.w3.org/2001/06/soap-faults"
The SOAP upgrade namespace identifier "http://www.w3.org/2001/06/soap-upgrade"
A SOAP message MUST NOT contain a Document Type Declaration. A SOAP message MUST NOT contain Processing Instruction Information Items. [7]
A SOAP message MUST NOT contain a Document Type Declaration. A SOAP message MUST NOT contain Processing Instructions. [7]
SOAP uses unqualified Attribute Information Items with a local name of id and a type of IDhttp://www.w3.org/2001/XMLSchema to specify the unique identifier of an encoded element. SOAP uses unqualified Attribute Information Items with a local name of href and a type of anyURI in the http://www.w3.org/2001/XMLSchema to specify a reference to such a value, in a manner conforming to the XML Specification [7], XML Schema Specification [11], and XML Linking Language Specification [9].
SOAP uses the local, unqualified "id" attribute of type "ID" to specify the unique identifier of an encoded element. SOAP uses the local, unqualified attribute "href" of type "anyURI" to specify a reference to that value, in a manner conforming to the XML Specification [7], XML Schema Specification [11], and XML Linking Language Specification [9].
Ednote: I don't quite know
what to do with respect to the following paragraph. The exceptions for
mustUnderstand and actor are almost incompatible with an Infoset approach.
The rest of the paragraph is redundant from an infoset perspective.
With the exception of the SOAP mustUnderstand
attribute (see section 4.2.3) and the SOAP
actor attribute (see section 4.2.2), it is
generally permissible to have attributes and their values appear in XML
instances or alternatively in schemas, with equal effect. That is, declaration
in a DTD or schema with a default or fixed value is semantically equivalent
to appearance in an instance.
A SOAP message MUST NOT impose any XML schema processing (assessment and validation) requirement on the part of any receiving SOAP node. Therefore, SOAP REQUIRES that all Attribute Information Items, whether specified in this specification or whether they belong to a foreign namespace be carried in the serialized SOAP envelope.
A SOAP message is an XML document that consists of a mandatory SOAP envelope, an optional SOAP Header, and a mandatory SOAP Body. This XML document is referred to as a SOAP message for the rest of this specification. The namespace identifier for the elements and attributes defined in this section is "http://www.w3.org/2001/06/soap-envelope".
The document Element Information Item has:
A SOAP Header. This is a generic mechanism for adding features to a SOAP message in a decentralized manner without prior agreement between the communicating parties (a SOAP sender, a SOAP receiver, and possibly one or more SOAP intermediaries). SOAP defines a few attributes that can be used to indicate who should deal with a feature and whether it is optional or mandatory (see section 4.2)
A SOAP Body. This is a container for mandatory information intended for the ultimate SOAP receiver (see section 4.3). SOAP defines a SOAP fault for reporting errors.
The grammar rules are as follows:
The element MUST be present in a SOAP message
The element MAY contain namespace declarations as well as additional attributes. If present, such additional attributes MUST be namespace-qualified. Similarly, the element MAY contain additional sub-elements. If present these sub-elements MUST be namespace-qualified and MUST come immediately after the SOAP Body.
The element MAY be present in a SOAP message. If present, the element MUST be the first immediate child element of a SOAP envelope.
The element MAY contain a set of SOAP header blocks, each being an immediate child element of the SOAP Header. All immediate child elements of the SOAP Header MUST be namespace-qualified.
The element MUST be present in a SOAP message and MUST be an immediate child element of a SOAP Envelope. It MUST come immediately after the SOAP Header, if present. Otherwise, it MUST be the first immediate child element of the SOAP envelope.
The element MAY contain a set of SOAP body blocks, each being an immediate child element of the SOAP Body. Immediate child elements of the SOAP Body MAY be namespace-qualified. At most one child element MAY be a SOAP fault. The SOAP fault is used to carry error information (see section 4.4).
The EncodingStyle Attribute Information Item has:
Ednote: The following sentence conflicts with the definition of the Body EII
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.
This attribute MAY appear on any element, and is scoped to that element's contents and all child elements not themselves containing such an attribute, much as an XML namespace declaration is scoped. There is no default encoding defined for a SOAP message.
The Attribute Information Item is a whitespace delimited list where each item in the list is of type anyURI in the namespace http://www.w3.org/2001/XMLSchema. Each item in the list identifies a set of serialization rules that can be used to deserialize the SOAP message. The sets of rules should be listed in the order most specific to least specific.
The attribute value is an ordered list of one or more URIs identifying the serialization rule or rules that can be used to deserialize the SOAP message indicated in the order of most specific to least specific. Example 3 shows three sample values for the encodingStyle attribute.
encodingStyle="http://www.w3.org/2001/06/soap-encoding" encodingStyle="http://example.org/encoding/restricted http://example.org/encoding/" encodingStyle=""
The serialization rules defined by SOAP in section 5 are identified by the URI "http://www.w3.org/2001/06/soap-encoding". SOAP messages using this particular serialization SHOULD indicate this using the SOAP encodingStyle attribute. In addition, all URIs syntactically beginning with "http://www.w3.org/2001/06/soap-encoding" indicate conformance with the SOAP encoding rules defined in section 5 (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.
SOAP does not define a traditional versioning model based on major and minor version numbers. A SOAP message MUST contain a SOAP envelope associated with the "http://www.w3.org/2001/06/soap-envelope" namespace. If a SOAP message is received by a SOAP node in which the SOAP envelope is associated with a different namespace, the SOAP node MUST treat this as a version error and generate a VersionMismatch SOAP fault (see section 4.4). A SOAP VersionMismatch fault message MUST use the SOAP/1.1 envelope namespace "http://schemas.xmlsoap.org/soap/envelope/" (see Appendix C).
All child Element Information Items of the SOAP Header are called SOAP header blocks.
Each such Element Information Item;
The encoding rules for SOAP header blocks are as follows:
The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the SOAP header blocks (see section 4.1.1).
The SOAP actor attribute (see section 4.2.2) and SOAP mustUnderstand attribute (see section 4.2.3) MAY be used to indicate which SOAP node will process the SOAP header block, and how it will be processed (see section 4.2.1).
The SOAP Header attributes defined in this section determine how a SOAP receiver should process an incoming SOAP message, as described in section 2. A SOAP sender generating a SOAP message SHOULD only use the SOAP Header attributes on immediate child elements of the SOAP Header. A SOAP receiver MUST ignore all SOAP Header attributes that are not applied to an immediate child element of the SOAP Header.
An example is a SOAP header block with an element identifier of "Transaction", a "mustUnderstand" value of "1", and a value of 5, as shown in Example 4.
<env:Header xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <t:Transaction xmlns:t="http://example.org/2001/06/tx" env:mustUnderstand="1" > 5 </t:Transaction> </env:Header>
A SOAP message travels from an initial SOAP sender to an ultimate SOAP receiver, potentially passing through a set of SOAP intermediaries along a SOAP message path. Both intermediaries as well as the ultimate SOAP receiver are identified by a URI.
Not all parts of a SOAP message may be intended for the ultimate SOAP receiver. They may be intended instead for one or more SOAP intermediaries on the SOAP message path. However, a SOAP intermediary MUST NOT forward further a SOAP header block intended for it. This would be considered as a breach of contract, the contract being only between the SOAP node which generated the SOAP header block, and the SOAP intermediary itself. However, the SOAP intermediary MAY instead insert a similar SOAP header block, which effectively sets up a new contract between that SOAP intermediary and the SOAP node at which the SOAP header block is targeted.
SOAP defines an actor Attribute Information Item that can 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 proerties:
The SOAP actor global attribute can be used to indicate the SOAP node at which a particular SOAP header block is targeted. The value of the SOAP actor attribute is a URI. The special URI "http://www.w3.org/2001/06/soap-envelope/actor/next" indicates that the SOAP header block is intended for the very first SOAP node that processes the message. This is similar to the hop-by-hop scope model represented by the Connection header field in HTTP.
Omitting the SOAP actor Attribute Information Item indicates that the SOAP header block is targeted at the ultimate SOAP receiver.
Omitting the SOAP actor attribute indicates that the SOAP header block is targeted at the ultimate SOAP receiver.
This Attribute Information Item has no default value.
Ednote: I don't quite know
what to do with respect to the following paragraph. It is incompatible
with an Infoset approach.
This attribute MUST appear
in the SOAP message itself in order to be effective, and not in an eventual
corresponding XML Schema (see section 3 and
4.2.1).
The SOAP mustUnderstand Attribute Information Item can be used to indicate whether the processing of a SOAP header block is mandatory or optional at the target SOAP node. The target SOAP node itself is defined by the SOAP actor Attribute Information Item (see section 4.2.2).
The mustUnderstand Attribute Information Item has:
The SOAP mustUnderstand global attribute can be used to indicate whether the processing of a SOAP header block is mandatory or optional at the target SOAP node. The target SOAP node itself is defined by the SOAP actor attribute (see section 4.2.2). The value of the SOAP mustUnderstand attribute is either "1" or "0". The absence of this attribute is semantically equivalent to its presence with the value "0", which means processing the block is optional.
When a SOAP header block has a SOAP mustUnderstandAttribute Information Item with a value of "1", the targeted SOAP node MUST: either process the SOAP block according to the semantics conveyed by the combination of local name and namespace name of the outer-most Element Information Item of that block; or not process the SOAP message at all, and fail (see section 4.4).
When a SOAP header block has no SOAP mustUnderstandAttribute Information Item or has such anAttribute Information Item with a value of false then processing of the block is optional.
When a SOAP header block is tagged with a SOAP mustUnderstand attribute with a value of "1", the targeted SOAP node MUST: either process the SOAP block according to the semantics conveyed by the fully qualified name of the outer-most element of that block; or not process the SOAP message at all, and fail (see section 4.4).
The SOAP mustUnderstand Attribute Information Item allows for robust evolution.Element Information Items that have an SOAP mustUnderstand Attribute Information Item with a value of "1" MUST be presumed to somehow modify the semantics of their parent or peer elements. This ensures that this change in semantics will not be silently (and, presumably, erroneously) ignored by those who may not fully understand it.
The SOAP mustUnderstand attribute allows for robust evolution. Elements tagged with the SOAP mustUnderstand attribute with a value of "1" MUST be presumed to somehow modify the semantics of their parent or peer elements. Tagging elements in this manner assures that this change in semantics will not be silently (and, presumably, erroneously) ignored by those who may not fully understand it.
Ednote: I don't quite know
what to do with respect to the following paragraph. It is incompatible
with an Infoset approach.
This attribute MUST appear in the SOAP
message itself in order to be effective, and not in an eventual corresponding
XML Schema (see section 3 and 4.2.1).
The SOAP Body element provides a simple mechanism for exchanging mandatory information intended for the ultimate SOAP receiver of a SOAP message. Typical uses of SOAP Body include marshalling RPC calls and error reporting.
The SOAP Body element is an immediate child element of a SOAP envelope. If a SOAP Header is present then the SOAP Body MUST immediately follow the SOAP Header, otherwise it MUST be the first immediate child element of the SOAP envelope.
All child Element Information Items of the SOAP Body Element Information Item are called SOAP body blocks.
Each such Element Information Item;
The encoding rules for SOAP body blocks are as follows:
The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the SOAP body blocks (see section 4.1.1).
While both SOAP Header and SOAP Body are defined as independent elements, they are in fact related. The relationship between a SOAP body block and a SOAP header block is as follows: a SOAP body block is semantically equivalent to a SOAP header block targeted at the anonymous actor and with a SOAP mustUnderstand attribute with a value of "1". The anonymous actor is indicated by omitting the actor attribute (see section 4.2.2).
The fault Element Information Item has;
The faultcode Element Information Item has;
The faultstring Element Information Item has;
The faultactor Element Information Item has;
The detail Element Information Item has;
The absence of the detail Element Information Item indicates that a SOAPfault 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;
The faultcode element is intended for use by software to provide
an algorithmic mechanism for identifying the fault. The faultcode MUST
be present in a SOAP fault and the faultcode value MUST be a qualified
name as defined in [8], section 3. SOAP defines a
small set of SOAP fault codes covering basic SOAP faults (see section
4.4.1)
The faultstring element is intended to provide a human readable
explanation of the fault and is not intended for algorithmic processing.
The faultstring element is similar to the 'Reason-Phrase' defined by HTTP
(see [5], section 6.1).
It MUST be present in a SOAP fault and SHOULD provide at least some information
explaining the nature of the fault.
The faultactor element is intended to provide information about
which SOAP node on the SOAP message path caused the fault to happen (see
section 2). It is similar to the SOAP actor
attribute (see section 4.2.2) but instead
of indicating the target of a SOAP header block, it indicates the source
of the fault. The value of the faultactor attribute is a URI identifying
the source. SOAP nodes that do not act as the ultimate SOAP receiver MUST
include the faultactor element in the SOAP fault. The ultimate SOAP receiver
MAY use the faultactor element to indicate explicitly that it generated
the fault (see also the detail element below).
The detail element 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, see section 4.4.2
for an example.
The absence of the detail element in the SOAP fault indicates that the 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 immediate child elements of the detail element are called detail entries, and each detail entry is encoded as an independent element within the detail element.
The encoding rules for detail entries are as follows (see also example 10):
The SOAP encodingStyle attribute MAY be used to indicate the encoding style used for the detail entries (see section 4.1.1).
The SOAP faultcode values defined in this section MUST be used in the SOAP faultcode element when describing faults defined by this specification. The namespace identifier for these SOAP faultcode values is "http://www.w3.org/2001/06/soap-envelope". Use of this space is recommended (but not required) in the specification of methods defined outside of the present specification.
The default SOAP faultcode values are defined in an extensible manner that allows for new SOAP faultcode values to be defined while maintaining backwards compatibility with existing SOAP faultcode values. The mechanism used is very similar to the 1xx, 2xx, 3xx etc basic status classes classes defined in HTTP (see [5] section 10). However, instead of integers, they are defined as XML qualified names (see [8] section 3). The character "." (dot) is used as a separator of SOAP faultcode values indicating that what is to the left of the dot is a more generic fault code value than the value to the right. This is illustrated in Example 5.
Client.Authentication
| Name | Meaning |
|---|---|
| VersionMismatch | The processing party found an invalid namespace for the SOAP envelope element (see section 4.1.2) |
| MustUnderstand | An immediate child element of the SOAP Header element that was either not understood or not obeyed by the processing party contained a SOAP mustUnderstand attribute with a value of "1" (see section 4.2.3) |
| Client | The Client class of errors indicate 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 section 4.4 for a description of the SOAP Fault detail sub-element. |
| Server | The Server class of errors indicate 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 section 4.4 for a description of the SOAP Fault detail sub-element. |
Each such header block Element Information Item has;
Each such header block has a local name of Misunderstood and a namespace name of "http://www.w3.org/2001/06/soap-faults". Each block has an unqualified attribute with a local name of qname whose value is the QName of a header block which the faulting node failed to understand.
For example, the message shown in Example 6 will result in the fault message shown in Example 7 if the recipient of the initial message does not understand the two header elements abc:Extension1 and def:Extension2.
<env:Envelope xmlns:env='http://www.w3.org/2001/06/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>
<env:Envelope xmlns:env='http://www.w3.org/2001/06/soap-envelope' xmlns:f='http://www.w3.org/2001/06/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>MustUnderstand</faultcode> <faultstring>One or more mandatory headers not understood</faultstring> </env:Fault> </env:Body> </env:Envelope>
Note that there is no requirement that the namespace prefix returned in the value of the qname attribute match the namespace prefix of the original header element. Provided the prefix maps to the same namespace name the faulting node may use any prefix.
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.
The namespace identifier for the elements and attributes defined in this section is "http://www.w3.org/2001/06/soap-encoding". The encoding samples shown assume all namespace declarations are at a higher element level.
Use of the data model and encoding style described in this section is encouraged but not required; other data models and encodings can be used in conjunction with SOAP (see section 4.1.1).
To describe encoding, the following terminology is used:
A "simple value" is one without named parts. Examples of simple values are particular strings, integers, enumerated values etc.
A "compound value" is an aggregate of relations to other values. Examples of Compound Values are particular purchase orders, stock reports, street addresses, etc.
Within a compound value, each related value is potentially distinguished by a role name, ordinal or both. This is called its "accessor." Examples of compound values include particular Purchase Orders, Stock Reports etc. Arrays are also compound values. It is possible to have compound values with several accessors each named the same, as for example, RDF does.
An "array" is a compound value in which ordinal position serves as the only distinction among member values.
A "struct" is a compound value in which accessor name is the only distinction among member values, and no accessor has the same name as any other.
A "simple type" is a class of simple values. Examples of simple types are the classes called "string," "integer," enumeration classes, etc.
A "compound type" is a class of compound values. An example of a compound type is the class of purchase order values sharing the same accessors (shipTo, totalCost, etc.) though with potentially different values (and perhaps further constrained by limits on certain values).
Within a compound type, if an accessor has a name that is distinct within that type but is not distinct with respect to other types, that is, the name plus the type together are needed to make a unique identification, the name is called "locally scoped." If however the name is based in part on a Uniform Resource Identifier, directly or indirectly, such that the name alone is sufficient to uniquely identify the accessor irrespective of the type within which it appears, the name is called "universally scoped."
Given the information in the schema relative to which a graph of values is serialized, it is possible to determine that some values can only be related by a single instance of an accessor. For others, it is not possible to make this determination. If only one accessor can reference it, a value is considered "single-reference". If referenced by more than one, actually or potentially, it is "multi-reference." Note that it is possible for a certain value to be considered "single-reference" relative to one schema and "multi-reference" relative to another.
Syntactically, an element may be "independent" or "embedded." An independent element is any element appearing at the top level of a serialization. All others are embedded elements.
The rules for serialization are as follows:
For each element containing a value, the type of the value MUST be represented by at least one of the following conditions: (a) the containing element instance contains an xsi:type attribute, (b) the containing element instance is itself contained within an element containing a (possibly defaulted) enc:arrayType attribute or (c) or the name of the element bears a definite relation to the type, that type then determinable from a schema.
A simple value is represented as character data, that is, without any subelements. Every simple value must have a type that is either listed in the XML Schemas Specification, part 2 [11] or whose source type is listed therein (see also section 5.2).
A Compound Value is encoded as a sequence of elements, each accessor represented by an embedded element whose name corresponds to the name of the accessor. Accessors whose names are local to their containing types have unqualified element names; all others have qualified names (see also section 5.4).
A multi-reference simple or compound value is encoded as an independent element containing a local, unqualified attribute named "id" and of type "ID" per the XML Specification [7]. Each accessor to this value is an empty element having a local, unqualified attribute named "href" and of type "uri-reference" per the XML Schema Specification [11], with a "href" attribute value of a URI fragment identifier referencing the corresponding independent element.
Strings and byte arrays are represented as multi-reference simple types, but special rules allow them to be represented efficiently for common cases (see also section 5.2.1 and 5.2.3). An accessor to a string or byte-array value MAY have an attribute named "id" and of type "ID" per the XML Specification [7]. If so, all other accessors to the same value are encoded as empty elements having a local, unqualified attribute named "href" and of type "uri-reference" per the XML Schema Specification [11], with a "href" attribute value of a URI fragment identifier referencing the single element containing the value.
It is permissible to encode several references to a value as though these were references to several distinct values, but only when from context it is known that the meaning of the XML instance is unaltered.
Arrays are compound values (see also section 5.4.2). SOAP arrays are defined as having a type of "enc:Array" or a type derived there from.
SOAP arrays have one or more dimensions (rank) whose members are distinguished by ordinal position. An array value is represented as a series of elements reflecting the array, with members appearing in ascending ordinal sequence. For multi-dimensional arrays the dimension on the right side varies most rapidly. Each member element is named as an independent element (see rule 2).
SOAP arrays can be single-reference or multi-reference values, and consequently may be represented as the content of either an embedded or independent element.
SOAP arrays MUST contain a "enc:arrayType" attribute whose value specifies
the type of the contained elements as well as the dimension(s) of the array.
The value of the "enc:arrayType" attribute is defined as follows:
| arrayTypeValue | = | atype asize |
| atype | = | QName *( rank ) |
| rank | = | "[" *( "," ) "]" |
| asize | = | "[" #length "]" |
| length | = | 1*DIGIT |
The "atype" construct is the type name of the contained elements expressed as a QName as would appear in the "type" attribute of an XML Schema element declaration and acts as a type constraint (meaning that all values of contained elements are asserted to conform to the indicated type; that is, the type cited in enc:arrayType must be the type or a supertype of every array member). In the case of arrays of arrays or "jagged arrays", the type component is encoded as the "innermost" type name followed by a rank construct for each level of nested arrays starting from 1. Multi-dimensional arrays are encoded using a comma for each dimension starting from 1.
The "asize" construct contains a comma separated list of zero, one, or more integers indicating the lengths of each dimension of the array. A value of zero integers indicates that no particular quantity is asserted but that the size may be determined by inspection of the actual members.
For example, an array with 5 members of type array of integers would have an arrayTypeValue value of "int[][5]" of which the atype value is "int[]" and the asize value is "[5]". Likewise, an array with 3 members of type two-dimensional arrays of integers would have an arrayTypeValue value of "int[,][3]" of which the atype value is "int[,]" and the asize value is "[3]".
A SOAP array member MAY contain a "enc:offset" attribute indicating
the offset position of that item in the enclosing array. This can be used
to indicate the offset position of a partially represented array (see section
5.4.2.1). Likewise, an array member MAY contain a "enc:position" attribute
indicating the position of that item in the enclosing array. This can be
used to describe members of sparse arrays (see section
5.4.2.2). The value of the "enc:offset" and the "enc:position" attribute
is defined as follows:
| arrayPoint | = | "[" #length "]" |
with offsets and positions based at 0.
A NULL value or a default value MAY be represented by omission of the accessor element. A NULL value MAY also be indicated by an accessor element containing the attribute xsi:null with value '1' or possibly other application-dependent attributes and values.
| Type | Example |
|---|---|
| int | 58502 |
| float | 314159265358979E+1 |
| negativeInteger | -32768 |
| string | Louis "Satchmo" Armstrong |
The datatypes declared in the XML Schema specification may be used directly in element schemas. Types derived from these may also be used. For example, for the following schema:
<!-- schema document --> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" > <xs:element name="age" type="xs:int" /> <xs:element name="height" type="xs:float" /> <xs:element name="displacement" type="xs:negativeInteger" /> <xs:element name="color" > <xs:simpleType base="xsd:string"> <xs:restriction base="xs:string" > <xs:enumeration value="Green"/> <xs:enumeration value="Blue"/> </xs:restriction> </xs:simpleType> </xs:element> </xs:schema>
<!-- Example instance elements --> <age>45</age> <height>5.9</height> <displacement>-450</displacement> <color>Blue</color>
If a simple value is encoded as an independent element or member of a heterogenous array it is convenient to have an element declaration corresponding to the datatype. Because the "XML Schema Part 2: Datatypes" Specification [11] includes type definitions but does not include corresponding element declarations, the enc schema and namespace declares an element for every simple datatype. These MAY be used.
<enc:int xmlns:enc="http://www.w3.org/2001/06/soap-encoding" id="int1">45</enc:int>
A string MAY be encoded as a single-reference or a multi-reference value.
The containing element of the string value MAY have an "id" attribute. Additional accessor elements MAY then have matching "href" attributes.
For example, two accessors to the same string could appear, as follows:
<greeting id="String-0">Hello</greeting> <salutation href="#String-0"/>
<greeting>Hello</greeting> <salutation>Hello</salutation>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" > <xs:import namespace="http://www.w3.org/2001/06/soap-encoding" /> <xs:element name="greeting" type="enc:string" /> <xs:element name="salutation" type="enc:string" /> </xs:schema>
"Enumeration" as a concept indicates a set of distinct names. A specific enumeration is a specific list of distinct values appropriate to the base type. For example the set of color names ("Green", "Blue", "Brown") could be defined as an enumeration based on the string built-in type. The values ("1", "3", "5") are a possible enumeration based on integer, and so on. "XML Schema Part 2: Datatypes" [11] supports enumerations for all of the simple types except for boolean. The language of "XML Schema Part 1: Structures" Specification [10] can be used to define enumeration types. If a schema is generated from another notation in which no specific base type is applicable, use "string". In the following schema example "EyeColor" is defined as a string with the possible values of "Green", "Blue", or "Brown" enumerated, and instance data is shown accordingly.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://example.org/2001/06/samples" targetNamespace="http://example.org/2001/06/samples" > <xs:element name="EyeColor" type="tns:EyeColor" /> <xs:simpleType name="EyeColor" > <xs:restriction base="xs:string" > <xs:enumeration value="Green" /> <xs:enumeration value="Blue" /> <xs:enumeration value="Brown" /> </xs:restriction> </xs:simpleType> </xs:schema>
<p:EyeColor xmlns:p="http://example.org/2001/06/samples" >Brown</p:EyeColor>
In particular, the containing element of the array of bytes value MAY have an "id" attribute. Additional accessor elements MAY then have matching "href" attributes.
The recommended representation of an opaque array of bytes is the 'base64' encoding defined in XML Schemas [10][11], which uses the base64 encoding algorithm defined in 2045 [13]. However, the line length restrictions that normally apply to base64 data in MIME do not apply in SOAP. A "enc:base64" subtype is supplied for use with SOAP.
<picture xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xsi:type="enc:base64" > aG93IG5vDyBicm73biBjb3cNCg== </picture>
For example, a polymorphic accessor named "cost" with a value of type "xsd:float" would be encoded as follows:
<cost xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:float">29.95</cost>
<cost>29.95</cost>
A "struct" is a compound value in which accessor name is the only
distinction among member values, and no accessor has the same name as any
other.
An "array" is a compound value in which ordinal position serves
as the only distinction among member values.
The following is an example of a struct of type "Book":
<e:Book xmlns:e="http://example.org/2001/06/books" > <author>Henry Ford</author> <preface>Prefactory text</preface> <intro>This is a book.</intro> </e:Book>
<xs:element name="Book" xmlns:xs='http://www.w3.org/2001/XMLSchema' > <xs:complexType> <xs:sequence> <xs:element name="author" type="xs:string" /> <xs:element name="preface" type="xs:string" /> <xs:element name="intro" type="xs:string" /> </xs:sequence> </xs:complexType> </xs:element>
<e:Book xmlns:e="http://example.org/2001/06/books" > <title>My Life and Work</title> <author href="#Person-1"/> </e:Book> <e:Person xmlns:e="http://example.org/2001/06/books" id="Person-1" > <name>Henry Ford</name> <address href="#Address-2"/> </e:Person> <e:Address xmlns:e="http://example.org/2001/06/books" id="Address-2" > <email>mailto:henryford@hotmail.com</email> <web>http://www.henryford.com</web> </e:Address>
<e:Book xmlns:e="http://example.org/2001/06/books" > <title>My Life and Work</title> <author> <name>Henry Ford</name> <address> <email>mailto:henryford@hotmail.com</email> <web>http://www.henryford.com</web> </address> </author> </e:Book>
<e:Book xmlns:e="http://example.org/2001/06/books" > <title>My Life and Work</title> <firstauthor href="#Person-1"/> <secondauthor href="#Person-2"/> </e:Book> <e:Person xmlns:e="http://example.org/2001/06/books" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="Person-1" > <name>Henry Ford</name> <address xsi:type="e:ElectronicAddressType"> <email>mailto:henryford@hotmail.com</email> <web>http://www.henryford.com</web> </address> </e:Person> <e:Person xmlns:e="http://example.org/2001/06/books" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" id="Person-2"> <name>Samuel Crowther</name> <address xsi:type="e:StreetAddressType"> <street>Martin Luther King Rd</street> <city>Raleigh</city> <state>North Carolina</state> </address> </e:Person>
<e:Book xmlns:e="http://example.org/2001/06/books" > <title>Paradise Lost</title> <firstAuthor href="http://www.dartmouth.edu/~milton/" /> </e:Book>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://example.org/2001/06/books" targetNamespace="http://example.org/2001/06/books" > <xs:element name="Book" type="tns:BookType" /> <xs:complexType name="BookType" > <xs:annotation> <xs:documentation> <info> Either the following group must occur or else the href attribute must appear, but not both. </info> </xs:documentation> </xs:annotation> <xs:sequence minOccurs="0" maxOccurs="1" > <xs:element name="title" type="xs:string" /> <xs:element name="firstAuthor" type="tns:PersonType" /> <xs:element name="secondAuthor" type="tns:PersonType" /> </xs:sequence> <xs:attribute name="href" type="xs:anyURI" /> <xs:attribute name="id" type="xs:ID" /> <xs:anyAttribute namespace="##other" /> </xs:complexType> <xs:element name="Person" type="tns:PersonType" /> <xs:complexType name="PersonType" > <xs:annotation> <xs:documentation> <info> Either the following group must occur or else the href attribute must appear, but not both. </info> </xs:documentation> </xs:annotation> <xs:sequence minOccurs="0" maxOccurs="1" > <xs:element name="name" type="xs:string" /> <xs:element name="address" type="tns:AddressType" /> </xs:sequence> <xs:attribute name="href" type="xs:anyURI" /> <xs:attribute name="id" type="xs:ID" /> <xs:anyAttribute namespace="##other" /> </xs:complexType> <xs:element name="Address" base="tns:AddressType" /> <xs:complexType name="AddressType" abstract="true" > <xs:annotation> <xs:documentation> <info> Either one of the following sequences must occur or else the href attribute must appear, but not both. </info> </xs:documentation> </xs:annotation> <xs:choice> <xs:sequence minOccurs="0" maxOccurs="1" > <xs:element name="email" type="xs:string" /> <xs:element name="web" type="xs:anyURI" /> </xs:sequence> <xs:sequence minOccurs='0' maxOccurs='1' > <xs:element name="street" type="xs:string" /> <xs:element name="city" type="xs:string" /> <xs:element name="state" type="xs:string"/> </xs:sequence> </xs:choice> <xs:attribute name="href" type="xs:anyURI"/> <xs:attribute name="id" type="xs:ID"/> <xs:anyAttribute namespace="##other"/> </xs:complexType> <xs:complexType name="StreetAddressType"> <xs:annotation> <xs:documentation> <info> Either the second sequence in the following group must occur or else the href attribute must appear, but not both. </info> </xs:documentation> </xs:annotation> <xs:complexContent> <xs:restriction base="tns:AddressType" > <xs:sequence> <xs:sequence minOccurs="0" maxOccurs="0" > <xs:element name="email" type="xs:string" /> <xs:element name="web" type="xs:anyURI" /> </xs:sequence> <xs:sequence minOccurs="0" maxOccurs="1"> <xs:element name="street" type="xs:string" /> <xs:element name="city" type="xs:string" /> <xs:element name="state" type="xs:string"/> </xs:sequence> </xs:sequence> <xs:attribute name="href" type="xs:anyURI"/> <xs:attribute name="id" type="xs:ID"/> <xs:anyAttribute namespace="##other"/> </xs:restriction> </xs:complexContent> </xs:complexType> <xs:complexType name="ElectronicAddressType"> <xs:annotation> <xs:documentation> <info> Either the first sequence in the following group must occur or else the href attribute must appear, but not both. </info> </xs:documentation> </xs:annotation> <xs:complexContent> <xs:restriction base="tns:AddressType" > <xs:sequence> <xs:sequence minOccurs="0" maxOccurs="1"> <xs:element name="email" type="xs:string" /> <xs:element name="web" type="xs:anyURI" /> </xs:sequence> <xs:sequence minOccurs="0" maxOccurs="0"> <xs:element name="street" type="xs:string" /> <xs:element name="city" type="xs:string" /> <xs:element name="state" type="xs:string"/> </xs:sequence> </xs:sequence> <xs:attribute name="href" type="xs:anyURI"/> <xs:attribute name="id" type="xs:ID"/> <xs:anyAttribute namespace="##other"/> </xs:restriction> </xs:complexContent> </xs:complexType> </xs:schema>
The representation of the value of an array is an ordered sequence of elements constituting the items of the array. Within an array value, element names are not significant for distinguishing accessors. Elements may have any name. In practice, elements will frequently be named so that their declaration in a schema suggests or determines their type. As with compound types generally, if the value of an item in the array is a single-reference value, the item contains its value. Otherwise, the item references its value via an "href" attribute.
The following example is a schema fragment and an array containing integer array members:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" > <xs:import namespace="http://www.w3.org/2001/06/soap-encoding" /> <xs:element name="myFavoriteNumbers" type="enc:Array" /> </xs:schema>
<myFavoriteNumbers xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" enc:arrayType="xs:int[2]" > <number>3</number> <number>4</number> </myFavoriteNumbers>
As previously noted, the enc schema contains declarations of elements with names corresponding to each simple type in the "XML Schema Part 2: Datatypes" Specification [11]. It also contains a declaration for "Array". Using these, we might write:
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:xs="http://www.w3.org/2001/XMLSchema" enc:ArrayType="xs:int[2]" > <enc:int>3</enc:int> <enc:int>4</enc:int> </enc:Array>
Types of member elements can be specified using the xsi:type attribute in the instance, or by declarations in the schema of the member elements, as the following two arrays demonstrate respectively:
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xs:anyType[4]"> <thing xsi:type="xs:int">12345</thing> <thing xsi:type="xs:decimal">6.789</thing> <thing xsi:type="xs:string"> Of Mans First Disobedience, and the Fruit Of that Forbidden Tree, whose mortal tast Brought Death into the World, and all our woe, </thing> <thing xsi:type="xs:anyURI"> http://www.dartmouth.edu/~milton/reading_room/ </thing> </enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" enc:arrayType="xs:anyType[4]" > <enc:int>12345</enc:int> <enc:decimal>6.789</enc:decimal> <enc:string> Of Mans First Disobedience, and the Fruit Of that Forbidden Tree, whose mortal tast Brought Death into the World, and all our woe, </enc:string> <enc:anyURI> http://www.dartmouth.edu/~milton/reading_room/ </enc:anyURI > </enc:Array>
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:xyz="http://example.org/2001/06/Orders" enc:arrayType="xyz:Order[2]"> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </enc:Array>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" enc:arrayType="xs:string[][2]" > <item href="#array-1"/> <item href="#array-2"/> </enc:Array> <enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" id="array-1" enc:arrayType="xs:string[2]"> <item>r1c1</item> <item>r1c2</item> <item>r1c3</item> </enc:Array> <enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" id="array-2" enc:arrayType="xs:string[2]"> <item>r2c1</item> <item>r2c2</item> </enc:Array>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:tns="http://example.org/2001/06/numbers" targetNamespace="http://example.org/2001/06/numbers" > <xs:simpleType name="phoneNumberType" > <xs:restriction base="xs:string" /> </xs:simpleType> <xs:element name="ArrayOfPhoneNumbers" type="tns:ArrayOfPhoneNumbersType" /> <xs:complexType name="ArrayOfPhoneNumbersType" > <xs:complexContent> <xs:restriction base="enc:Array" > <xs:sequence> <xs:element name="phoneNumber" type="tns:phoneNumberType" maxOccurs="unbounded" /> </xs:sequence> <xs:attributeGroup ref="enc:arrayAttributes" /> <xs:attributeGroup ref="enc:commonAttributes" /> </xs:restriction> </xs:complexContent> </xs:complexType> </xs:schema>
<abc:ArrayOfPhoneNumbers xmlns:abc="http://example.org/2001/06/numbers" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" enc:arrayType="abc:phoneNumberType[2]" > <phoneNumber>206-555-1212</phoneNumber> <phoneNumber>1-888-123-4567</phoneNumber> </abc:ArrayOfPhoneNumbers>
<enc:Array xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" enc:arrayType="xs:string[2,3]" > <item>r1c1</item> <item>r1c2</item> <item>r1c3</item> <item>r2c1</item> <item>r2c2</item> <item>r2c3</item> </enc:Array>
The following is an example of a schema fragment and an array of phone numbers embedded in a struct of type "Person" and accessed through the accessor "phone-numbers":
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:tns="http://example.org/2001/06/numbers" targetNamespace="http://example.org/2001/06/numbers" > <xs:import namespace="http://www.w3.org/2001/06/soap-encoding" /> <xs:simpleType name="phoneNumberType" > <xs:restriction base="xs:string" /> </xs:simpleType> <xs:element name="ArrayOfPhoneNumbers" type="tns:ArrayOfPhoneNumbersType" /> <xs:complexType name="ArrayOfPhoneNumbersType" > <xs:complexContent> <xs:restriction base="enc:Array" > <xs:sequence> <xs:element name="phoneNumber" type="tns:phoneNumberType" maxOccurs="unbounded" /> </xs:sequence> <xs:attributeGroup ref="enc:arrayAttributes" /> <xs:attributeGroup ref="enc:commonAttributes" /> </xs:restriction> </xs:complexContent> </xs:complexType> <xs:element name="Person"> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string" /> <xs:element name="phoneNumbers" type="tns:ArrayOfPhoneNumbersType" /> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>
<def:Person xmlns:def="http://example.org/2001/06/numbers" xmlns:enc="http://www.w3.org/2001/06/soap-encoding" > <name>John Hancock</name> <phoneNumbers enc:arrayType="def:phoneNumber[2]"> <phoneNumber>206-555-1212</phoneNumber> <phoneNumber>1-888-123-4567</phoneNumber> </phoneNumbers> </def:Person>
<xyz:PurchaseOrder xmlns:xyz="http://example.org/2001/06/Orders" > <CustomerName>Henry Ford</CustomerName> <ShipTo> <Street>5th Ave</Street> <City>New York</City> <State>NY</State> <Zip>10010</Zip> </ShipTo> <PurchaseLineItems xmlns:enc="http://www.w3.org/2001/06/soap-encoding" enc:arrayType="xyz:Order[2]"> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </PurchaseLineItems> </xyz:PurchaseOrder>
The following is an example of an array of size five that transmits only the third and fourth element counting from zero:
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:xs="http://www.w3.org/2001/XMLSchema" enc:arrayType="xs:string[6]" enc:offset="[3]" > <item>The fourth element</item> <item>The fifth element</item> </enc:Array>
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:xs="http://www.w3.org/2001/XMLSchema" enc:arrayType="xs:string[,][4]" > <enc:Array href="#array-1" enc:position="[2]" /> </enc:Array> <enc:Array id="array-1" enc:arrayType="xs:string[10,10]" > <item enc:position="[2,2]">Third row, third col</item> <item enc:position="[7,2]">Eighth row, third col</item> </enc:Array>
<enc:Array xmlns:enc="http://www.w3.org/2001/06/soap-encoding" xmlns:xs="http://www.w3.org/2001/XMLSchema" enc:arrayType="xs:string[,][4]" > <enc:Array enc:position="[2]" enc:arrayType="xs:string[10,10]" > <item enc:position="[2,2]">Third row, third col</item> <item enc:position="[7,2]">Eighth row, third col</item> </enc:Array> </enc:Array>
Similarly, the rules cited are sufficient to allow serialization of compound types having a mixture of accessors distinguished by name and accessors distinguished by both name and ordinal position. (That is, having some accessors repeated.) This does not require that any schema actually contain such types, but rather says that if a type-model schema does have such types, a corresponding XML syntactic schema and instance may be generated.
<xyz:PurchaseOrder xmlns:xyz="http://example.org/2001/06/Orders" > <CustomerName>Henry Ford</CustomerName> <ShipTo> <Street>5th Ave</Street> <City>New York</City> <State>NY</State> <Zip>10010</Zip> </ShipTo> <PurchaseLineItems> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </PurchaseLineItems> </xyz:PurchaseOrder>
<PurchaseLineItems> <Order> <Product>Apple</Product> <Price>1.56</Price> </Order> <Order> <Product>Peach</Product> <Price>1.48</Price> </Order> </PurchaseLineItems>
The SOAP root attribute MAY appear on any subelement within the SOAP Header and SOAP Body elements. The attribute does not have a default value.
SOAP naturally follows the HTTP request/response message model by providing a SOAP request message in a HTTP request and SOAP response message in a HTTP response. Note, however, that SOAP intermediaries are NOT the same as HTTP intermediaries. That is, an HTTP intermediary addressed with the HTTP Connection header field cannot be expected to inspect or process the SOAP entity body carried in the HTTP request.
HTTP applications MUST use the media type "text/xml" according to RFC 2376 [3] when including SOAP messages in HTTP exchanges.
| soapaction | = | "SOAPAction" ":" [ <"> URI-reference <"> ] |
| URI-reference | = | <as defined in RFC 2396 [4]> |
The presence and content of the SOAPAction header field can be used by servers such as firewalls to appropriately filter SOAP request messages in HTTP. The header field value of empty string ("") means that the intent of the SOAP message is provided by the HTTP Request-URI. No value means that there is no indication of the intent of the message.
Examples:
SOAPAction: "http://electrocommerce.org/abc#MyMessage" SOAPAction: "myapp.sdl" SOAPAction: "" SOAPAction:
If an error occurs while processing the request, the SOAP HTTP server MUST issue an HTTP 500 "Internal Server Error" response and include a SOAP message in the response containing a SOAP fault (see section 4.4) indicating the SOAP processing error.
Whether to use the Extension Framework or plain HTTP is a question of policy and capability of the communicating parties. Clients can force the use of the experimental HTTP Extension Framework by using a mandatory extension declaration and the "M-" HTTP method name prefix. Servers can force the use of the HTTP Extension Framework by using the 510 "Not Extended" HTTP status code. That is, using one extra round trip, either party can detect the policy of the other party and act accordingly.
The extension identifier used to identify SOAP using the Extension Framework is
http://www.w3.org/2001/06/soap-envelope
POST /StockQuote HTTP/1.1 Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://electrocommerce.org/abc#MyMessage" <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > . . . </env:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > . . . </env:Envelope>
M-POST /StockQuote HTTP/1.1 Man: "http://www.w3.org/2001/06/soap-envelope"; ns=NNNN Content-Type: text/xml; charset="utf-8" Content-Length: nnnn NNNN-SOAPAction: "http://electrocommerce.org/abc#MyMessage" <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > . . . </env:Envelope>
HTTP/1.1 200 OK Ext: Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > . . . </env:Envelope>
Although it is anticipated that this representation is likely to be used in combination with the encoding style defined in section 5, other representations are possible. The SOAP encodingStyle attribute (see section 4.3.2) can be used to indicate the encoding style of the RPC invocation and/or the response using the representation described in this section.
Using SOAP for RPC is orthogonal to the SOAP protocol binding (see section 6). In the case of using HTTP as the protocol binding, an RPC invocation maps naturally to an HTTP request and an RPC response maps to an HTTP response. However, using SOAP for RPC is not limited to the HTTP protocol binding.
To invoke an RPC, the following information is needed:
A procedure or method name
An optional procedure or method signature
The parameters to the procedure or method
Optional header data
The invocation is viewed as a single struct containing an accessor for each [in] or [in/out] parameter. The struct is both named and typed identically to the procedure or method name.
Each [in] or [in/out] parameter is viewed as an accessor, with a name corresponding to the name of the parameter and type corresponding to the type of the parameter. These appear in the same order as in the procedure or method signature.
An RPC response is modeled as a struct.
The response is viewed as a single struct containing an accessor for the return value and each [out] or [in/out] parameter. The first accessor is the return value followed by the parameters in the same order as in the procedure or method signature.
Each parameter accessor has a name corresponding to the name of the parameter and type corresponding to the type of the parameter. The name of the return value accessor is not significant. Likewise, the name of the struct is not significant. However, a convention is to name it after the procedure or method name with the string "Response" appended.
An invocation fault is encoded using a SOAP fault (see section 4.4). If a protocol binding adds additional rules for fault expression, those MUST also be followed.
Applications MAY process invocations with missing parameters but also MAY return a fault.
Because a result indicates success and a fault indicates failure, it is an error for an RPC response to contain both a result and a fault.
An example of the use of a header block is the passing of a transaction ID along with a message. Since the transaction ID is not part of the signature and is typically held in an infrastructure component rather than application code, there is no direct way to pass the necessary information with the invocation. By adding a header block with a fixed name, the transaction manager on the receiving side can extract the transaction ID and use it without affecting the coding of remote procedure calls.
[3] IETF "RFC 2376: XML Media Types", E. Whitehead, M. Murata, July 1998. Available at http://www.ietf.org/rfc/rfc2376.txt
[4] IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt
[5] IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. Available at http://www.ietf.org/rfc/rfc2616.txt
[6] IETF "RFC 2774: An HTTP Extension Framework", H. Nielsen, P. Leach, S. Lawrence, February 2000. Available at http://www.ietf.org/rfc/rfc2774.txt
[7] W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. Available at http://www.w3.org/TR/2000/REC-xml-20001006
[8] W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. Available at http://www.w3.org/TR/1999/REC-xml-names-19990114
[9] W3C Proposed Recommendation "XML Linking Language (XLink) Version 1.0", Steve DeRose, Eve Maler, David Orchard, 20 December 2000. Available at http://www.w3.org/TR/2000/PR-xlink-20001220/
[10] W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. Available at http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/
[11] W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/
[13] IETF "RFC2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", N. Freed, N. Borenstein, November 1996. Available at http://www.ietf.org/rfc/rfc2045.txt
POST /StockQuote HTTP/1.1 Host: www.stockquoteserver.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://example.org/2001/06/quotes" <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <env:Header> <t:Transaction xmlns:t="http://example.org/2001/06/tx" env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" env:mustUnderstand="1" > 5 </t:Transaction> </env:Header> <env:Body > <m:GetLastTradePrice env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <m:symbol>DEF</m:symbol> </m:GetLastTradePrice> </env:Body> </env:Envelope>
POST /StockQuote HTTP/1.1 Host: www.stockquoteserver.com Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "http://example.org/2001/06/quotes" <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <env:Body> <m:GetLastTradePriceDetailed env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <Symbol>DEF</Symbol> <Company>DEF Corp</Company> <Price>34.1</Price> </m:GetLastTradePriceDetailed> </env:Body> </env:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <env:Header> <t:Transaction xmlns:t="http://example.org/2001/06/tx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:int" env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" env:mustUnderstand="1" > 5 </t:Transaction> </env:Header> <env:Body> <m:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <Price>34.5</Price> </m:GetLastTradePriceResponse> </env:Body> </env:Envelope>
HTTP/1.1 200 OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <env:Body> <m:GetLastTradePriceResponse env:encodingStyle="http://www.w3.org/2001/06/soap-encoding" xmlns:m="http://example.org/2001/06/quotes" > <PriceAndVolume> <LastTradePrice>34.5</LastTradePrice> <DayVolume>10000</DayVolume> </PriceAndVolume> </m:GetLastTradePriceResponse> </env:Body> </env:Envelope>
HTTP/1.1 500 Internal Server Error Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope"> <env:Body> <env:Fault> <faultcode>env:MustUnderstand</faultcode> <faultstring>SOAP Must Understand Error</faultstring> </env:Fault> </env:Body> </env:Envelope>
HTTP/1.1 500 Internal Server Error Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <env:Envelope xmlns:env="http://www.w3.org/2001/06/soap-envelope" > <env:Body> <env:Fault> <faultcode>env:Server</faultcode> <faultstring>Server Error</faultstring> <detail> <e:myfaultdetails xmlns:e="http://example.org/2001/06/faults" > <message>My application didn't work</message> <errorcode>1001</errorcode> </e:myfaultdetails> </detail> </env:Fault> </env:Body> </env:Envelope>
Members of the Working Group are (at the time of writing, and by alphabetical order): Yasser al Safadi (Philips Research), Vidur Apparao (Netscape), Don Box (DevelopMentor), David Burdett (Commerce One), Charles Campbell (Informix Software), Alex Ceponkus (Bowstreet), Michael Champion (Software AG), David Clay (Oracle), Ugo Corda (Xerox), Paul Cotton (Microsoft Corporation), Ron Daniel (Interwoven), Glen Daniels (Allaire), Doug Davis (IBM), Ray Denenberg (Library of Congress), Paul Denning (MITRE Corporation), Frank DeRose (TIBCO Software, Inc.), Brian Eisenberg (Data Channel), David Ezell (Hewlett-Packard), James Falek (TIBCO Software, Inc.), David Fallside (IBM), Chris Ferris (Sun Microsystems), Daniela Florescu (Propel), Dan Frantz (BEA Systems), Dietmar Gaertner (Software AG), Scott Golubock (Epicentric), Rich Greenfield (Library of Congress), Martin Gudgin (Develop Mentor), Hugo Haas (W3C), Marc Hadley (Sun Microsystems), Mark Hale (Interwoven), Randy Hall (Intel), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), Yin-Leng Husband (Compaq), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric Industrial Co., Ltd.), Scott Isaacson (Novell, Inc.), Kazunori Iwasa (Fujitsu Software Corporation), Murali Janakiraman (Rogue Wave), Mario Jeckle (Daimler-Chrysler Research and Technology), Eric Jenkins (Engenia Software), Mark Jones (AT&T), Jay Kasi (Commerce One), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Jacek Kopecky (IDOOX s.r.o.), Alan Kropp (Epicentric), Yves Lafon (W3C), Tony Lee (Vitria Technology Inc.), Michah Lerner (AT&T), Richard Martin (Active Data Exchange), Noah Mendelsohn (Lotus Development), Nilo Mitra (Ericsson Research Canada), Jean-Jacques Moreau (Canon), Masahiko Narita (Fujitsu Software Corporation), Mark Needleman (Data Research Associates), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), Mark Nottingham (Akamai Technologies), David Orchard (JamCracker), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Andreas Riegg (Daimler-Chrysler Research and Technology), Hervé Ruellan (Canon), Marwan Sabbouh (MITRE Corporation), Shane Sesta (Active Data Exchange), Miroslav Simek (IDOOX s.r.o.), Simeon Simeonov (Allaire), Nick Smilonich (Unisys), Soumitro Tagore (Informix Software), James Tauber (Bowstreet), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Randy Waldrop (WebMethods), Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Stuart Williams (Hewlett-Packard), Amr Yassin (Philips Research) and Dick Brooks (Group 8760). Previous members were: Eric Fedok (Active Data Exchange) Susan Yee (Active Data Exchange) Alex Milowski (Lexica), Bill Anderson (Xerox), Ed Mooney (Sun Microsystems), Mary Holstege (Calico Commerce), Rekha Nagarajan (Calico Commerce), John Evdemon (XML Solutions), Kevin Mitchell (XML Solutions), Yan Xu (DataChannel) Mike Dierken (DataChannel) Julian Kumar (Epicentric) Miles Chaston (Epicentric) Bjoern Heckel (Epicentric) Dean Moses (Epicentric) Michael Freeman (Engenia Software) Jim Hughes (Fujitsu Software Corporation) Francisco Cubera (IBM), Murray Maloney (Commerce One), Krishna Sankar (Cisco), Steve Hole (MessagingDirect Ltd.) John-Paul Sicotte (MessagingDirect Ltd.) Vilhelm Rosenqvist (NCR) Lew Shannon (NCR) Henry Lowe (OMG) Jim Trezzo (Oracle) Peter Lecuyer (Progress Software) Andrew Eisenberg (Progress Software) David Cleary (Progress Software) George Scott (Tradia Inc.) Erin Hoffman (Tradia Inc.) Conleth O'Connell (Vignette) Waqar Sadiq (Vitria Technology Inc.) Tom Breuel (Xerox) David Webber (XMLGlobal Technologies) Matthew MacKenzie (XMLGlobal Technologies) and Mark Baker (Sun Microsystems).
This document is based on the SOAP/1.1 specification whose authors were: Don Box (Develop Mentor), David Ehnebuske (IBM), Gopal Kakivaya (Microsoft Corp.), Andrew Layman (Microsoft Corp.) Noah Mendelsohn (Lotus Development Corp.), Henrik Frystyk Nielsen (Microsoft Corp.), Satish Thatte (Microsoft Corp.) and Dave Winer (UserLand Software, Inc.).
We also wish to thank all the people who have contributed to discussions on xml-dist-app@w3.org.
The SOAP/1.1 specification says the following on versioning in section 4.1.2:
"SOAP does not define a traditional versioning model based on major and minor version numbers. A SOAP message MUST have an Envelope element associated with the "http://schemas.xmlsoap.org/soap/envelope/" namespace. If a message is received by a SOAP application in which the SOAP Envelope element is associated with a different namespace, the application MUST treat this as a version error and discard the message. If the message is received through a request/response protocol such as HTTP, the application MUST respond with a SOAP VersionMismatch faultcode message (see section 4.4) using the SOAP "http://schemas.xmlsoap.org/soap/envelope/" namespace."That is, rather than a versioning model based on shortnames (typically version numbers), SOAP uses a declarative extension model which allows a sender to include the desired features within the SOAP envelope construct. SOAP says nothing about the granularity of extensions nor how extensions may or may not affect the basic SOAP processing model. It is entirely up to extension designers be it either in a central or a decentralized manner to determine which features become SOAP extensions.
The SOAP extensibility model is based on the following four basic assumptions:
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"> <env:Header> <V:Upgrade xmlns:V="http://www.w3.org/2001/06/soap-upgrade"> <envelope qname="ns1:Envelope" xmlns:ns1="http://www.w3.org/2001/06/soap-envelope"/> </V:Upgrade> </env:Header> <env:Body> <env:Fault> <faultcode>env:VersionMismatch</faultcode> <faultstring>Version Mismatch</faultstring> </env:Fault> </env:Body> </env:Envelope>
| Date | Author | Description |
|---|---|---|
| 20010629 | MJG | Amended description of routing and intermediaries in Section 2.1 |
| 20010629 | JJM | Changed "latest version" URI to end with soap12 |
| 20010629 | JJM | Remove "previous version" URI |
| 20010629 | JJM | Removed "Editor copy" in <title> |
| 20010629 | JJM | Removed "Editor copy" in the title. |
| 20010629 | JJM | Added "Previous version" to either point to SOAP/1.1, or explicitly mention there was no prior draft. |
| 20010629 | JJM | Pre-filed publication URIs. |
| 20010629 | JJM | Incorporated David's suggested changes for the examples in section 4.1.1 to 4.4.2 |
| 20010629 | JJM | Fixed some remaining typos. |
| 20010629 | MJH | Fixed a couple of typos. |
| 20010628 | MJG | Made various formatting, spelling and grammatical fixes. |
| 20010628 | MJG | Moved soap:encodingStyle from soap:Envelope to children of soap:Header/soap:Body in examples 1, 2, 47, 48, 49 and 50 |
| 20010628 | MJG | Changed text in Section 2.1 from 'it is both a SOAP sender or a SOAP receiver' to 'it is both a SOAP sender and a SOAP receiver' |
| 20010628 | MJG | Fixed caption on Example 24 |
| 20010628 | MJH | Fixed a couple of capitalisation errors where the letter A appeared as a capital in the middle of a sentence. |
| 20010628 | MJH | Updated figure 1, removed ednote to do so. |
| 20010622 | HFN | Removed the introductory text in terminology section 1.4.3 as it talks about model stuff that is covered in section 2. It was left over from original glossary which also explained the SOAP model. |
| 20010622 | HFN | Moved the definition of block to encapsulation section in terminology |
| 20010622 | HFN | Removed introductory section in 1.4.1 as this overlaps with the model description in section 2 and doesn't belong in a terminology section |
| 20010622 | HFN | Removed reference to "Web Characterization Terminology & Definitions Sheet" in terminology section as this is not an active WD |
| 20010622 | HFN | Added revised glossary |
| 20010622 | HFN | Added example 0 to section 1.3 and slightly modified text for example 1 and 2 to make it clear that HTTP is used as a protocol binding |
| 20010622 | MJG | Added http://example.com/... to list of application/context specific URIs in section 1.2 |
| 20010622 | MJG | Updated examples in section 4.1.1 to be encodingStyle attributes rather than just the values of attributes |
| 20010622 | MJG | Added table.norm, td.normitem and td.normtext styles to stylesheet. Used said styles for table of fault code values in section 4.4.1 |
| 20010622 | MJG | In Appendix C, changed upgrade element to Upgrade and env to envelope. Made envelope unqualified. Updated schema document to match. |
| 20010622 | MJG | Moved MisunderstoodHeader from envelope schema into seperate faults schema. Removed entry in envelope schema change table in Appendix D.2 that refered to additon of said element. Modified example in section 4.4.2 to match. Added reference to schema document to section 4.4.2 |
| 20010622 | MJH | Added binding as a component of SOAP in introduction. Fixed a couple of typos and updated a couple of example captions. |
| 20010622 | MJG | Made BNF in section 6.1.1 into a table. |
| 20010622 | MJG | Made BNFs in section 5.1 clause 8 into tables. Added associated 'bnf' style for table and td elements to stylesheet |
| 20010622 | MJG | Amended text regarding namespace prefix mappings in section 1.2 |
| 20010622 | MJG | Added link to schema for the http://www.w3.org/2001/06/soap-upgrade namespace to Appendix C. Updated associated ednote. |
| 20010622 | MJG | Added reference numbers for XML Schema Recommendation to text prior to schema change tables in Appendix D.2 and linked said numbers to local references in this document |
| 20010622 | MJG | Reordered entries in schema change classification table in Appendix D.2 |
| 20010622 | MJG | Changed type of mustUnderstand and root attributes to standard boolean and updated schema change tables in Appendix D.2 accordingly |
| 20010622 | JJM | Manually numbered all the examples (53 in total!) |
| 20010622 | JJM | Added caption text to all the examples |
| 20010622 | JJM | Replaced remaining occurrences of SOAP/1.2 with SOAP Version 1.2 (including <title>) |
| 20010621 | HFN | Added ednote to section 4.2.2 and 4.2.3 that we know they have to be incorporated with section 2 |
| 20010621 | HFN | Added version transition appendix C |
| 20010621 | HFN | Applied new styles to examples |
| 20010621 | HFN | Changed term "transport" to "underlying protocol |
| 20010621 | HFN | Changed example URNs to URLs of the style http://example.org/... |
| 20010621 | MJH | Updated the Acknowledgements section. |
| 20010621 | JJM | Added new style sheet definitions (from XML Schema) for examples, and used them for example 1 and 2. |
| 20010621 | JJM | Incorporated David Fallside's comments on section Status and Intro sections. |
| 20010620 | HFN | Changed the status section |
| 20010620 | HFN | Changed title to SOAP Version 1.2 and used that first time in abstract and in body |
| 20010620 | HFN | Removed question from section 2.4 as this is an issue and is to be listed in the issues list |
| 20010620 | HFN | Moved change log to appendix |
| 20010615 | JJM | Renamed default actor to anonymous actor for now (to be consistent) |
| 20010615 | JJM | Fixed typos in section 2 |
| 20010614 | JJM | Updated section 2 to adopt the terminology used elsewhere in the spec. |
| 20010613 | MJH | Updated mustUnderstand fault text with additions from Martin Gudgin. |
| 20010613 | MJH | Added schema changes appendix from Martin Gudgin. |
| 20010613 | MJH | Added mustUnderstand fault text from Glen Daniels. |
| 20010612 | MJH | Fixed document <title>. |
| 20010612 | MJH | Moved terminology subsection from message exchange model section to introduction section. |
| 20010612 | MJH | Fixed capitalisation errors by replacing "... A SOAP ..." with "... a SOAP ..." where appropriate. |
| 20010612 | MJH | Removed trailing "/" from encoding namespace URI. |
| 20010612 | MJH | Fixed links under namespace URIs to point to W3C space instead of schemas.xmlsoap.org. |
| 20010612 | MJH | Removed some odd additional links with text of "/" pointing to the encoding schema following the text of the encoding namespace URI in several places. |
| 20010611 | MJH | Incorporated new text for section 2. |
| 20010611 | JJM | Changed remaining namespaces, in particular next. |
| 20010609 | JJM | Changed the spec name from XMLP/SOAP to SOAP. |
| 20010609 | JJM | Changed the version number from 1.1 to 1.2. |
| 20010609 | JJM | Changed the namespaces from http://schemas.xmlsoap.org/soap/ to http://www.w3.org/2001/06/soap-. |
| 20010609 | JJM | Replaced the remaining XS and XE prefixes to env and enc, respectively. |
| 20010601 | MJH | Updated the examples in section 1, 6 and appendix A with text suggested by Martin Gudgin to comply with XML Schema Recommendation. |
| 20010601 | JJM | Updated the examples in section 4 and 5 with text suggested by Martin Gudgin, to comply with XML Schema Recommendation. |
| 20010531 | HFN | Removed appendices C and D and added links to live issues list and separate schema files. |
| 20010531 | MJH | Added this change log and updated schemas in appendix C to comply with XML Schema Recommendation. |
| Class | Meaning |
|---|---|
| Addition | New constructs have been added to the schema |
| Clarification | The meaning of the schema has been changed to more accurately match the specification |
| Deletion | Constructs have been removed from the schema |
| Name | The schema has been changed due to a datatype name change in the XML Schema specification |
| Namespace | A namespace name has been changed |
| Semantic | The meaning of the schema has been changed |
| Style | Style changes have been made to the schema |
| Syntax | The syntax of the schema has been updated due to changes in the XML Schema specification |
The table below lists the changes to the envelope schema.
| Class | Description |
|---|---|
| Namespace | Updated to use the http://www.w3.org/2001/XMLSchema namespace |
| Namespace | Value of targetNamespace attribute changed to http://www.w3.org/2001/06/soap-envelope |
| Clarification | Changed element and attribute wildcards in Envelope complex type to namespace="##other" |
| Clarification | Changed element and attribute wildcards in Header complex type to namespace="##other" |
| Clarification | Added explicit namespace="##any" to element and attribute wildcards in Body complex type |
| Clarification | Added explicit namespace="##any" to element and attribute wildcards in detail complex type |
| Clarification | Added an element wildcard with namespace="##other" to the Fault complex type |
| Name | Changed item type of encodingStyle from uri-reference to anyURI |
| Name | Changed type of actor attribute from uri-reference to anyURI |
| Name | Changed type of faultactor attribute from uri-reference to anyURI |
| Semantic | Added processContents="lax" to all element and attribute wildcards |
| Semantic | Changed type of the mustUnderstand attribute from restriction of boolean that only allowed 0 or 1 as lexical values to the standard boolean in the http://www.w3.org/2001/XMLSchema namespace. The lexical forms 0, 1, false, true are now allowed. |
| Style | Where possible comments have been changed into annotations |
| Syntax | Changed all occurences of maxOccurs="*" to maxOccurs="unbounded" |
| Syntax | Added <xs:sequence> to all complex type definitions derived implicitly from the ur-type |
| Syntax | Added <xs:sequence> to all named model group definitions |
The table below lists the changes to the encoding schema.
| Class | Description |
|---|---|
| Namespace | Updated to use the http://www.w3.org/2001/XMLSchema namespace |
| Namespace | Value of targetNamespace attribute changed to http://www.w3.org/2001/06/soap-encoding |
| Semantic | Changed type of the root attribute from restriction of boolean that only allowed 0 or 1 as lexical values to the standard boolean in the http://www.w3.org/2001/XMLSchema namespace. The lexical forms 0, 1, false, true are now allowed. |
| Addition | Added processContents="lax" to all element and attribute wildcards |
| Syntax | Changed base64 simple type to be a vacuous restriction of the base64Binary type in the http://www.w3.org/2001/XMLSchema namespace |
| Syntax | Updated all complex type definitions with simple base types to new syntax |
| Syntax | Added <xs:sequence> to all complex type definitions derived implicitly from the ur-type |
| Syntax | Added <xs:sequence> to all named model group definitions |
| Deletion | Removed the timeDuration datatype |
| Addition | Added duration datatype derived by extension from the duration datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Deletion | Removed the timeInstant datatype |
| Addition | Added dateTime datatype derived by extension from the dateTime datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added gYearMonth datatype derived by extension from the gYearMonth datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added gYear datatype derived by extension from the gYear datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added gMonthDay datatype derived by extension from the gMonthDay datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added gDay datatype derived by extension from the gDay datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added gDay datatype derived by extension from the gDay datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Deletion | Removed the binary datatype |
| Addition | Added hexBinary datatype derived by extension from the hexBinary datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added base64Binary datatype derived by extension from the base64Binary datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Deletion | Removed the uriReference datatype |
| Addition | Added anyURI datatype derived by extension from the anyURI datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added normalizedString datatype derived by extension from the normalizedString datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Addition | Added token datatype derived by extension from the token datatype in the http://www.w3.org/2001/XMLSchema namespace. |
| Clarification | Added explicit namespace="##any" to all element and attribute wildcards which did not previously have an explicit namespace attribute |
| Style | Where possible comments have been changed into annotations |
In addition several changes occured in the names of datatypes in the
XML Schema specification and some datatypes were removed. The following
table lists those changes.
| Datatype | Class | Description |
|---|---|---|
| timeDuration | Renamed | New name is duration |
| timeInstant | Renamed | New name is dateTime |
| recurringDuration | Removed | The recurringDuration datatype no longer exists. |
| recurringInstant | Removed | The recurringInstant datatype no longer exists. |
| binary | Removed | The binary datatype has been replaced by the hexBinary and base64Binary datatypes. |
| month | Renamed | New name is gYearMonth |
| timePeriod | Removed | The timePeriod datatype no longer exists |
| year | Renamed | New name is gYear |
| century | Removed | The century datatype no longer exists |
| recurringDate | Renamed | New name is gMonthDay |
| recurringDay | Renamed | New name is gDay |