SOAP 1.2

1.1 Design Goals

1.2 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [5].

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[6],[7].

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[8].

This specification uses the augmented Backus-Naur Form (BNF) as described in [4].

1.3 Examples of SOAP Messages

<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>

SOAP messages may be bound to different underlying protocols and used in a variety of message exchange patterns. The following two examples show SOAP used in connection with HTTP as the underlying protocol taking advantage of the request/response mechanism provided by HTTP (6 Using SOAP in HTTP).

The following example shows a sample SOAP/HTTP request. 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>

The following example shows the SOAP message sent by the StockQuote service in response to the request shown in the preceeding example.

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>

More examples are available in B SOAP Envelope Examples.

1.4 SOAP Terminology

1.4.2 Data Encapsulation Concepts

SOAP message

A SOAP message is the basic unit of communication between peer SOAP nodes.

SOAP envelope

The outermost syntactic construct or structure of a SOAP message defined by SOAP within which all other syntactic elements of the message are enclosed.

SOAP block

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.

SOAP header

A collection of zero or more SOAP blocks which may be targeted at any SOAP receiver within the SOAP message path.

SOAP body

A collection of zero, or more SOAP blocks targeted at the ultimate SOAP receiver within the SOAP message path.

SOAP fault

A special SOAP block which contains fault information generated by a SOAP node.

The following diagram illustrates how a SOAP message is composed.

2.1 SOAP Nodes

2.2 SOAP Actors and SOAP Nodes

2.3 Targeting SOAP Header Blocks

SOAP header blocks carry optional attribute information items with a local name of actor and a namespace name of http://www.w3.org/2001/06/soap-envelope (see 4.2.2 SOAP actor Attribute) that are used to target them to the appropriate SOAP node(s). SOAP header blocks with no such attribute information item 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 [9]) 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.

2.4 Understanding SOAP Headers

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 4.2.3 SOAP mustUnderstand Attribute). 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 4.4 SOAP Fault).

2.5 Processing SOAP Messages

1. Generate a single SOAP MustUnderstand fault (see 4.4.2 MustUnderstand Faults) if one or more SOAP blocks targeted at the SOAP node are mandatory and are not understood by that node. If such a fault is generated, any further processing MUST NOT be done.

2. Process SOAP blocks targeted at the SOAP node, generating SOAP faults (see 4.4 SOAP Fault 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.

If the SOAP node is a SOAP intermediary, the SOAP message pattern and results of processing (e.g. no fault generated) MAY require that the SOAP message be sent further along the SOAP message path. Such relayed SOAP messages MUST contain all SOAP header blocks and the SOAP body blocks from the original SOAP message, in the original order, except that SOAP header blocks targeted at the SOAP intermediary MUST be removed (such SOAP blocks are removed regardless of whether they were processed or ignored). Additional SOAP header blocks MAY be inserted at any point in the SOAP message, and such inserted SOAP header blocks MAY be indistinguishable from one or more just removed (effectively leaving them in place, but emphasizing the need to reinterpret at each SOAP node along the SOAP message path.)

4.1 Envelope Encoding and Versioning

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

4.2 SOAP Header

<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>

4.3 SOAP Body

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

4.4 SOAP Fault

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

The faultstring element information item has:

• A local name of faultstring;

• A namespace name which is empty.

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

The faultactor element information item has:

• A local name of faultactor

• A namespace name which is empty

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

The detail element information item has:

• A local name of detail;

• A namespace name which is empty;

• Zero or more attribute information items;

• Zero or more child element information items.

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

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

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

Each such element information item:

• MAY be namespace qualified;

• MAY have an encodingStyle attribute information item.

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

Client.Authentication

<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>

5.1 Rules for Encoding Types in XML

XML allows very flexible encoding of data. SOAP defines a narrower set of rules for encoding. This section defines the encoding rules at a high level, and the next section describes the encoding rules for specific types when they require more detail. The encodings described in this section can be used in conjunction with the mapping of RPC calls and responses specified in 7 Using SOAP for RPC.

To describe encoding, the following terminology is used:

1. A "value" is a string, the name of a measurement (number, date, enumeration, etc.) or a composite of several such primitive values. All values are of specific types.

2. A "simple value" is one without named parts. Examples of simple values are particular strings, integers, enumerated values etc.

3. A "compound value" is an aggregate of relations to other values. Examples of Compound Values are particular purchase orders, stock reports, street addresses, etc.

4. 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.

5. An "array" is a compound value in which ordinal position serves as the only distinction among member values.

6. 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.

7. A "simple type" is a class of simple values. Examples of simple types are the classes called "string," "integer," enumeration classes, etc.

8. 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).

9. 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."

10. 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.

11. 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.

Although it is possible to use the xsi:type attribute such that a graph of values is self-describing both in its structure and the types of its values, the serialization rules permit that the types of values MAY be determinate only by reference to a schema. Such schemas MAY be in the notation described by "XML Schema Part 1: Structures" [6] and "XML Schema Part 2: Datatypes" [7] or MAY be in any other notation. Note also that, while the serialization rules apply to compound types other than arrays and structs, many schemas will contain only struct and array types.

The rules for serialization are as follows:

1. All values are represented as element content. A multi-reference value MUST be represented as the content of an independent element. A single-reference value SHOULD NOT be (but MAY be).

2. 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.

3. 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[7] or whose source type is listed therein (see also 5.2 Simple Types).

4. 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 5.4 Compound Types).

5. 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 [10]. 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[7], with a href attribute value of a URI fragment identifier referencing the corresponding independent element.

6. 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 5.2.1 Strings and 5.2.3 Array of Bytes ). An accessor to a string or byte-array value MAY have an attribute named id and of type "ID" per the XML Specification[10]. 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[7], with a href attribute value of a URI fragment identifier referencing the single element containing the value.

7. 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.

8. Arrays are compound values (see also 5.4.2 Arrays). 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:

   Value of enc:arrayType

   [1]	arrayTypeValue	::=	atype asize
   [2]	atype	::=	QName *( rank )
   [3]	rank	::=	"[" *( "," ) "]"
   [4]	asize	::=	"[" #length "]"
   [5]	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 5.4.2.1 PartiallyTransmitted Arrays). 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 5.4.2.2 SparseArrays). The value of the enc:offset and the enc:position attribute is defined as follows:

   Value of enc:offset and enc:position

   [6]

   arrayPoint

   ::=

   "[" #length "]"

   with offsets and positions based at 0.

9. 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.

Note that rule 2 allows independent elements and also elements representing the members of arrays to have names which are not identical to the type of the contained value.

5.2 Simple Types

For simple types, SOAP adopts all the types found in the section "Built-in datatypes" of the "XML Schema Part 2: Datatypes" Specification[7], both the value and lexical spaces. Examples include:

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>

the following elements would be valid instances:

<!-- Example instance elements -->
<age>45</age>
<height>5.9</height>
<displacement>-450</displacement>
<color>Blue</color>

All simple values MUST be encoded as the content of elements whose type is either defined in "XML Schema Part 2: Datatypes" Specification[7], or is based on a type found there by using the mechanisms provided in the XML Schema specification.

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[7] 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>

<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>

<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>

<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>

5.3 Polymorphic Accessor

<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>

5.4 Compound Types

<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>

<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>

<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>

<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>

<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>

<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>

<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>

5.5 Default Values

5.6 SOAP root Attribute

6.1 SOAP HTTP Request

Although SOAP might be used in combination with a variety of HTTP request methods, this binding only defines SOAP within HTTP POST requests (see 7 Using SOAP for RPC for how to use SOAP for RPC).

SOAPAction: "http://electrocommerce.org/abc#MyMessage"
SOAPAction: "myapp.sdl"
SOAPAction: ""
SOAPAction:

6.2 SOAP HTTP Response

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 4.4 SOAP Fault) indicating the SOAP processing error.

6.3 The HTTP Extension Framework

6.4 SOAP HTTP Examples

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>

7.1 RPC and SOAP Body

RPC invocations and responses are both carried in the SOAP Body element (see 4.3 SOAP Body) using the following representation:

• An RPC invocation is modeled as a struct.

• 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.

• Invocation faults are handled according to the rules in 7.3 RPC Faults. If a protocol binding adds additional rules for fault expression, those MUST also be followed.

As noted above, RPC invocation and response structs can be encoded according to the rules in 5 SOAP Encoding, or other encodings can be specified using the encodingStyle attribute (see 4.1.1 SOAP encodingStyle Attribute).

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.

7.2 RPC and SOAP Header

7.3 RPC Faults

The RPC representation introduces additional SOAP fault codes to those described in 4.4.1 SOAP Fault Codes. The namespace identifier for these SOAP faultcode element information item values is "http://www.w3.org/2001/06/rpc" and the namespace prefix rpc: is used in this section to indicate association with this namespace.

Errors arising during RPC invocations are reported according to the following rules (in order of precedence):

1. A soap-env:Server fault SHOULD be generated when the server cannot handle the message because of some temporary condition, e.g. when it is out of memory. This does not apply to temporary conditions of the application, e.g. a database being unavailable or a record not present.

2. A soap-env:DataEncodingUnknown fault SHOULD be generated when the arguments are encoded in a data encoding unknown to the server.

3. An rpc:ProcedureNotPresent fault MUST be generated when the server cannot find the procedure specified.

4. An rpc:BadArguments fault MUST be generated when the server cannot parse the arguments or when there is a mismatch between what the server expects and what the client has sent.

5. Other faults arising in an extension or from the application SHOULD be generated as described in 4.4 SOAP Fault. Procedure level errors, i.e. those that might normally be expected when executing a procedure, SHOULD be indicated in a successful RPC response containing some application-dependent indication of a failure.

In all cases the values of the detail and faultstring element information items are implementation defined. They MAY be specified by some external document.

9.1 Normative References

1

XML Protocol Comments Archive (See http://lists.w3.org/Archives/Public/xmlp-comments/.)

2

XML Protocol Discussion Archive (See http://lists.w3.org/Archives/Public/xml-dist-app/.)

3

XML Protocol Charter (See http://www.w3.org/2000/09/XML-Protocol-Charter.)

4

IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. (See http://www.ietf.org/rfc/rfc2616.txt.)

5

IETF "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)

6

W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)

7

W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)

8

IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. (See http://www.ietf.org/rfc/rfc2396.txt.)

9

W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114.)

10

W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (See http://www.w3.org/TR/2000/REC-xml-20001006.)

11

W3C Proposed Recommendation "XML Linking Language (XLink) Version 1.0", Steve DeRose, Eve Maler, David Orchard, 20 December 2000. (See http://www.w3.org/TR/2000/PR-xlink-20001220/.)

12

IETF "RFC 2376: XML Media Types", E. Whitehead, M. Murata, July 1998. (See http://www.ietf.org/rfc/rfc2376.txt.)

9.2 Informative References

13

W3C Candidate Recommendation "XML Information Set", John Cowan, Richard Tobin, 14 May 2001. (See http://www.w3.org/TR/2001/CR-xml-infoset-20010514.)

14

IETF "RFC2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", N. Freed, N. Borenstein, November 1996. (See http://www.ietf.org/rfc/rfc2045.txt.)

15

W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer, 8 May 2000. (See http://www.w3.org/TR/SOAP/.)

16

IETF "RFC 2774: An HTTP Extension Framework", H. Nielsen, P. Leach, S. Lawrence, February 2000. (See http://www.ietf.org/rfc/rfc2774.txt.)

17

IETF "RFC 2026: The Internet Standards Process -- Revision 3", section 4.2.3, S. Bradner, October 1996. (See http://www.ietf.org/rfc/rfc2026.txt.)