SOAP Version 1.2 Part 2: Adjuncts

1.1 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 [3].

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/09/soap-envelope" and "http://www.w3.org/2001/09/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[4],[5].

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

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

1.2 Examples of SOAP Messages

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. Note that 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.example.org
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/09/soap-envelope" >
 <env:Body>
  <m:GetLastTradePrice
        env:encodingStyle="http://www.w3.org/2001/09/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/09/soap-envelope" >
 <env:Body>
  <m:GetLastTradePriceResponse
        env:encodingStyle="http://www.w3.org/2001/09/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 A SOAP Envelope Examples.

1.3 SOAP Terminology

4.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 5 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" [4] and "XML Schema Part 2: Datatypes" [5] 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[5] or whose source type is listed therein (see also 4.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 4.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 [8]. 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[5], 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 4.2.1 Strings and 4.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[8]. 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[5], 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 4.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 4.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 4.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:nil with value "1 or true" 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.

4.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[5], 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[5], 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[5] 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/09/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/09/soap-encoding" >

  <xs:import namespace="http://www.w3.org/2001/09/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/09/soap-encoding"
         xsi:type="enc:base64" >
   aG93IG5vDyBicm73biBjb3cNCg==
</picture>

4.3 Polymorphic Accessor

Many languages allow accessors that can polymorphically access values of several types, each type being available at run time. A polymorphic accessor instance MUST contain an xsi:type attribute that describes the type of the actual value.

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>

as contrasted with a cost accessor whose value's type is invariant, as follows:

<cost>29.95</cost>

4.4 Compound Types

SOAP defines types corresponding to the following structural patterns often found in programming languages:

Struct

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.

Array

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

SOAP also permits serialization of data that is neither a Struct nor an Array, for example data such as is found in a Directed-Labeled-Graph Data Model in which a single node has many distinct accessors, some of which occur more than once. SOAP serialization does not require that the underlying data model make an ordering distinction among accessors, but if such an order exists, the accessors MUST be encoded in that sequence.

<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:[email protected]</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:[email protected]</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:[email protected]</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/09/soap-encoding" >
  <xs:import namespace="http://www.w3.org/2001/09/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/09/soap-encoding"
                   enc:arrayType="xs:int[2]" >
  <number>3</number>
  <number>4</number>
</myFavoriteNumbers>

<enc:Array xmlns:enc="http://www.w3.org/2001/09/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/09/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/09/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/09/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/09/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/09/soap-encoding"
           id="array-1"
           enc:arrayType="xs:string[3]">
   <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/09/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/09/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/09/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/09/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/09/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/09/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/09/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/09/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/09/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/09/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/09/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>

4.5 Default Values

An omitted accessor element implies either a default value or that no value is known. The specifics depend on the accessor, method, and its context. For example, an omitted accessor typically implies a Null value for polymorphic accessors (with the exact meaning of Null accessor-dependent). Likewise, an omitted Boolean accessor typically implies either a False value or that no value is known, and an omitted numeric accessor typically implies either that the value is zero or that no value is known.

4.6 SOAP root Attribute

The SOAP root attribute can be used to label serialization roots that are not true roots of an object graph so that the object graph can be deserialized. The attribute can have one of two values, either "true" or "false". True roots of an object graph have the implied attribute value of "true". Serialization roots that are not true roots can be labeled as serialization roots with an attribute value of "true". An element can explicitly be labeled as not being a serialization root with a value of "false".

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.

The SOAP root attribute information item is of type boolean from the namespace "http://www.w3.org/2001/XMLSchema".

5.1 RPC and SOAP Body

RPC invocations and responses are both carried in the SOAP Body element (see [1]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 return value accessor SHOULD be first, followed by the accessors for the parameters which SHOULD be in the same order as they appear 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 "result" and it is namespace-qualified with the namespace identifier "http://www.w3.org/2001/09/soap-rpc" The return value accessor MUST be present if the return value of the procedure is non-void. The return value accessor MUST NOT be present if the return value of the procedure is void.

• Invocation faults are handled according to the rules in 5.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 4 SOAP Encoding, or other encodings can be specified using the encodingStyle attribute (see [1]Encoding 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.

5.2 RPC and SOAP Header

Additional information relevant to the encoding of an RPC invocation but not part of the formal procedure or method signature MAY be expressed in the RPC encoding. If so, it MUST be expressed as a header block.

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.

5.3 RPC Faults

The RPC representation introduces additional SOAP fault codes to those described in [1]Fault Codes. The namespace identifier for these SOAP faultcode element information item values is "http://www.w3.org/2001/09/soap-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 decreasing 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.

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 [1](SOAP Faults).

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

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 5 Using SOAP for RPC for how to use SOAP for RPC).

6.2 SOAP HTTP Response

SOAP over HTTP follows the semantics of the HTTP Status codes for communicating status information in HTTP. For example, a 2xx status code indicates that the client's request including the SOAP component was successfully received, understood, and accepted etc.

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 [1]SOAP Faults) indicating the SOAP processing error.

6.3 The HTTP Extension Framework

6.4 Security Considerations

6.5 SOAP HTTP Examples

POST /StockQuote HTTP/1.1
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://www.example.org/abc#MyMessage"

<env:Envelope xmlns:env="http://www.w3.org/2001/09/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/09/soap-envelope" >
 . . .
</env:Envelope>

7.1 Normative References

1

W3C Working Draft "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/2001/WD-soap12-part1-20011002/.)

2

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

3

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

4

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

5

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

6

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

7

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

8

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

9

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

10

W3C Proposed Recommendation "XML Information Set", John Cowan, Richard Tobin, 10 August 2001. (See http://www.w3.org/TR/2001/PR-xml-infoset-20010810/.)

11

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

7.2 Informative References

12

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

13

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

14

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

15

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

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