Network Working Group

HTTP Working Group	D. Box
Internet Draft	DevelopMentor

	G. Kakivaya
	A. Layman
	S. Thatte
	Microsoft Corporation

	D. Winer
	Userland Software



Document: <draft-http-soap-01.txt>	November 1999
Category: Informational

SOAP: Simple Object Access Protocol

Status of this Memo

This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 except that the right to produce derivative works is not granted.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress."

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

1. Abstract

SOAP defines an RPC mechanism using XML for client-server interaction across a network by using the following mechanisms:

* HTTP as the base transport

* XML documents for encoding of invocation requests and responses

2. Conventions used in this document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [1[1]].

The namespace prefix "SOAP" is used in this to represent whichever prefix actually appears in the XML instance and is associated with the SOAP namespace URI, "urn:schemas-xmlsoap-org:soap.v1".

Namespace URIs such of the general form "some URI" represent some application-dependent or context-dependent URI.

3. Introduction

SOAP defines an "XML-RPC" protocol for client-server interaction across a network by using the following mechanisms:

* HTTP as the base transport

* XML documents for encoding of invocation requests and responses

SOAP is both low-entry and high-function, capable of use for simple stateless remote procedure calls as well as rich object systems.

SOAP works with today's deployed World Wide Web and provides extensibility mechanisms for future enhancements. For example, SOAP supports submitting invocations using both POST and M-POST.

3.1. Goals

* Provide a standard object invocation protocol built on Internet standards, using HTTP as the transport and XML for data encoding.

* Create an extensible protocol and payload format that can evolve over time.

3.2. Non-Goals

Define all aspects of a distributed object system, including the following:

* Distributed garbage collection

* Bi-directional HTTP communications

* Boxcarring or pipelining of messages

* Objects-by-reference (which requires distributed garbage collection and bi-directional HTTP)

* Activation (which requires objects-by-reference)

3.3. Examples of a SOAP Call

The call is to a StockQuote server, and the method is GetLastTradePrice. The method takes one string parameter, ticker, and returns a float.

It uses the SOAP namespace to disambiguate SOAP keywords in the payload and a method namespace to disambiguate method keywords in the payload.

The root Envelope element tag name is used to disambiguate SOAP xml encodings from non SOAP xml encodings.

3.3.1. Call

Example #1:

Following is an example of the SOAP encoding required to make this method call. This example uses the familiar HTTP verb POST. SOAP also supports the use of the HTTP verb M-POST for extensibility. See section 6.1 for more information on M-POST.

POST /StockQuote HTTP/1.1

Host: www.stockquoteserver.com

Content-Type: text/xml

Content-Length: nnnn

SOAPMethodName: http://www.def.com/abc#GetLastTradePrice

<SOAP:Envelope xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1”>

<SOAP:Body>

<m:GetLastTradePrice

xmlns:m="Some Namespace URI”>

</m:GetLastTradePrice>

</SOAP:Body>

</SOAP:Envelope>

3.3.2. Response

Example #2:

Following is the return message containing the HTTP headers and XML body:

HTTP/1.1 200 OK

Content-Type: text/xml

Content-Length: nnnn

<SOAP:Envelope xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1”>

<SOAP:Body>

<m:GetLastTradePriceResponse xmlns:m="Some Namespace URI”>

</m:GetLastTradePriceResponse>

</SOAP:Body>

</SOAP:Envelope>

4. Relation to HTTP

In SOAP, the mechanism used for all communication is HTTP. (See [1].) Indeed, a central design goal of SOAP, perhaps the most important, is that SOAP be usable strictly on top of today's actually deployed World Wide Web infrastructure. That means SOAP has to live with and work in the face of various levels of HTTP implementation, the active use of firewalls and proxies, and so on. Some aspects of SOAP, such as the permitted use of HTTP methods beyond those of classic HTTP, are designed to anticipate, and thus make use of, some evolution and improvement in this base, but nothing in SOAP can require such fundamental changes in order for SOAP to function.

SOAP uses the Content-Type of "text/xml". This is used to specify the body of the HTTP message containing a XML encoded method call.

To disambiguate the headers it adds to HTTP, SOAP permits use of the HTTP Extension Framework specification (See [2]).

Unless otherwise indicated in this document, existing practices with respect to the handling of HTTP requests and responses are to be adhered to. Specifically, this includes the following:

* Redirection

* Caching

* Connection management

* Support for access authentication and security

5. Relation to XML

XML is used to encode the call and response bodies. See [3] for more information on XML.

All protocol tags SHOULD be scoped to the SOAP namespace. The sender SHOULD include namespaces in SOAP elements and attributes. The receiver MUST correctly process SOAP messages that have namespaces; this includes not processing messages that have wrong namespaces. The receiver MAY also process SOAP payloads without namespaces as though they had the correct namespaces.

The SOAP namespace has the proposed value "urn:schemas-xmlsoap-org:soap.v1”. See [6] for more information on XML namespaces.

No XML document forming the HTTP request of a SOAP invocation may require the use of an XML DTD in any manner.

SOAP uses the ID attribute "id" to specify the unique identifier of an encoded element. SOAP uses the attribute "href" to specify a reference to that value, in a manner conforming to the XML Linking Language specification working draft. See [9] for more information on XML Linking Language.

It is worth noting that the rules governing XML payload format in SOAP are entirely independent of the fact that the payload is carried over an HTTP transport.

6. Method Invocation

A method invocation is performed by creating the HTTP request header and body and processing the returned response header and body. The request and response headers consist of standard and extended HTTP headers.

The following sections will cover the use of standard HTTP headers and the definition of extended HTTP headers.

6.1. HTTP Verb Rules

SOAP allows two verb options within the Call HTTP header: POST or M-POST.

The verb M-POST is an extension verb based on in the HTTP Extension Framework specification. (See [2].) A SOAP invocation must first try the invocation by using POST.

If the POST invocation fails, it must retry using the HTTP method M-POST. The details of this mechanism are provided below. The purpose of supporting this extended invocation mechanism in SOAP is to provide a mechanism to unambiguously add headers to the HTTP protocol.

6.2. Using POST vs. M-POST vs

Since a design goal of the use of M-POST is to provide Internet firewalls and proxies greater administrative flexibility, careful attention must be paid as to when a SOAP client uses the POST method vs. the M-POST method. The rules are as follows:

When carrying out an invocation, a SOAP client must first try the invocation using the POST invocation style.

If that POST invocation fails with an HTTP status of "405 Method Not Allowed" the client SHOULD retry the request using the M-POST invocation style. If that M-POST invocation fails with an HTTP status of "501 Not Implemented" or "510 Not Extended", the client should fail the request. If any other HTTP error is returned, it should be processed according to the HTTP specification.

Further, if the subsequent M-POST succeeds, then in subsequent invocations to the same HTTP server, the client may omit the attempt at POST invocations for a period of 24 hours, thereby avoiding the need for an extra round-trip on each and every method invocation.

Given this algorithm, firewalls can effectively force the use of M-POST for SOAP invocations by prohibiting POST invocations of Content-Type "text/xml".

6.3. Method Invocation HTTP Headers

The payload and Content-Type of a method call are identical to a method response except in the following circumstances:

* The method call must contain additional HTTP header fields in the request:

a) If using the M-POST verb, a mandatory extension declaration must be present that refers to the namespace "urn:schemas-xmlsoap-org:soap.v1” . For the purposes of this section, suppose that said declaration chooses to map the namespace to the header-prefix "01". If the POST verb is used, the namespace header-prefix is not used. For example, aSOAPMethodName header would have an M-POST value of "01-SOAPMethodName" and a POST value of “SOAPMethodName”.

b) The request MUST include a header "SOAPMethodName" whose value indicates the method to be invoked on the target. The value consists of a URI indicating the interface name, followed by a "#", followed by a method name (which MUST not include the "#" character). For example:

SOAPMethodName: http://electrocommerce.org/abc#MyMethod

* The server must fail the request if the required headers are missing. The failure HTTP response status-line should contain the value "400", which means "Bad Request".

6.4. Method Invocation Body

A SOAP method invocation consists of a method call and optionally a method response. The method call and method response body consists of an HTTP header and the XML payload. The XML payload consists of the root, (optional) header, and (mandatory) body elements.

The body components are defined as follows:

* The SOAP root element is the top element in the XML tree.

* The SOAP payload headers contain additional information that needs to travel with the call.

* The method request is represented as an XML element with additional elements for parameters. It is the first child of the SOAP:Body element.

* The response is the return value or error/exception that is passed back to the client. It follows the same rules as a method request.

The encoding rules are as follows:

1) Root element

a) The element tag is "SOAP:Envelope".

b) SOAP defines a global attribute "SOAP:serializationPattern" indicating any serialization rules used in lieu of those required by the SOAP spec. This attribute may appear on any element, and is scoped to that element and all child elements not themselves containing such an attribute. Omission of this attribute indicates that section 8 has been followed (unless overridden by a parent element). The URI “urn:schemas-xmlsoap-org:soap.v1” is defined and all URIs beginning with this one indicate conformance with section 8 (with potentially tighter rules).

c) The root element may contain namespace declarations.

d) The root element may contain additional attributes, provided these are namespace-qualified.

2) SOAP payload headers

a) The element tag is "header".

b) It contains a list of header entries, each namespace-qualified.

3) Call

a) The element tag is “SOAP:Body”.

b) The Body element contains a first sub element whose name is the method name. This method request element in turn contains elements for each [in] and [in/out] parameter. The element names are the parameter names. See section 8 for details.

4) Response

a) The element tag is “SOAP:Body”.

a) The Body element contains a first sub element that in turn contains child elements for each [in/out] and [out] parameter. The element names are the parameter names. See section 8 for details.

5) Fault

a) The element tag is “Body”.

a) The Body element contains a first sub element that is the fault element, indicating information about the fault.

The version of SOAP used is indicated by the SOAP namespace URI. A server must use the version passed in the envelope of the call for encoding the response, or it must fail the request. In the case where the server accepts a version or level less than its maximum, it must respond to the client by using the same version and level. If a server receives a version it cannot handle, the HTTP response status-line should contain the value "400", which means "Bad Request", and contain a fault in the call response with the fault code SOAP_E_VERSION_MISMATCH.

Processing messages in the face of missing parameter names is application defined.

See section 7 for information on how to encode parameter values.

6.5. SOAP Payload Headers

In addition to the elements that specify direct, explicit information about the call or response, SOAP provides a way to pass extended, implicit information with the call through the use of the "header" element. It is referenced by and encoded as a child of the SOAP:Envelope XML element. It contains a collection of distinctly named entries.

An example of the use of the header element is the passing of an implicit transaction ID along with a call. 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 call. By adding an entry to the headers and giving it 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.

Each header entry is encoded as an embedded element. The encoding rules for a header are as follows:

1. The element's name identifies the header. Header elements always are namespace-qualified.

2. Unless indicated to the contrary by the value of a SOAP:serializationPattern attribute, header values are encoded according to the rules of section 8.

3. The element may contain an attribute "SOAP:mustUnderstand" specifying required understanding of the header by the destination.

An example is a header with an identifier of "TransactionID", a "mustUnderstand" value of true, and a value of 5. This would be encoded as follows:

<SOAP:Header>

<t:Transaction

xmlns:t=”some URI” SOAP:mustUnderstand="1">

</t:Transaction>

</SOAP:Header>

6.5.1. The "SOAP:mustUnderstand" Attribute

Header entries may have a global attribute "SOAP:mustUnderstand". This may have one of two values, either "1" or "0". The absence of such a "SOAP:mustUnderstand" attribute is semantically equivalent to its presence with the value "0".

If a header element is tagged with a "SOAP:mustUnderstand" attribute whose value is "1", the party processing the Request URI must understand the semantics (as conveyed by its element tag, contextual setting, and so on) and process correctly to those semantics.

If the SOAP implementation doesn't understand the element, it must return an error as specified in section [5.1], "Results from a Method Call."

The idea is to allow for robust semantic extensibility and change. Headers tagged with SOAP:mustUnderstand="1" can be presumed to somehow concretely change or modify the semantics of their element. Tagging the headers 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.

If the "SOAP:mustUnderstand" attribute is missing or has a value of "0", that element can safely be ignored.

For example: If the client passed along a transaction ID header, as in the above example, with a "SOAP:mustUnderstand" of "1", then the server should fail if it cannot process the transaction ID and comply with the transactional semantics.

6.6. Making a Method Call

To make a method call, the following information is needed:

* The URI of the target object

* An optional interface name

* A method name

* An optional method signature

* The parameters to the method

* Optional header data

The target URI of the HTTP request indicates the resource that the invocation is being made against; in this specification, we refer to that resource as the "server address," to distinguish it from other uses of URIs. Other than it be a valid URI, SOAP places no restriction on the form of an address. See [8] for more information on URIs.

The body of a SOAP method call must be of Content-Type 'text/xml'.

The SOAP protocol places no absolute restriction on the syntax or case-sensitivity of interface names, method names, or parameter names. Of course, individual SOAP servers will respond to only the names they support; the selection of these is at their own sole discretion. The one restriction is that the server must preserve the case of names.

6.6.1. Representation of Method Parameters

Method parameters are encoded as child elements of the call or response, encoded using the following rules:

1) The name of the parameter in the method signature is used as the name of the corresponding element.

2) Parameter values are expressed using the rules in section 8 of this document.

6.6.2. Sample Encoding of Call Messages

Example #3:

This sample is the same call as in section 3.3.1 but uses optional headers. It uses SOAP namespace to disambiguate SOAP keywords in the payload.

<SOAP:Envelope

xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1”

SOAP:serializationPattern="urn:schemas-xmlsoap-org:soap.v1">

<SOAP:Header>

<t:Transaction

xmlns:t=”some URI”

SOAP:mustUnderstand="1">

</t:Transaction>

</SOAP:Header>

<SOAP:Body>

<m:GetLastTradePrice xmlns:m="some other URI”>

</m:GetLastTradePrice>

</SOAP:Body>

</SOAP:Envelope>

Example #4:

The following request sends a struct:

<SOAP:Envelope

xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1” >

<SOAP:Body>

<m:GetLastTradePriceDetailed

xmlns:m="some other URI”>

</m:GetLastTradePriceDetailed>

</SOAP:Body>

</SOAP:Envelope>

7. Results of Method Calls

At the receiving site, a call request can have one of the following four outcomes:

a) The HTTP infrastructure on the receiving site was able to receive and process the request.

b) The HTTP infrastructure on the receiving site could not receive and process the request.

c) The SOAP infrastructure on the receiving site was able to decode the input parameters, dispatch to an appropriate server indicated by the server address, and invoke an application-level function corresponding semantically to the method indicated in the method call.

d) The SOAP infrastructure on the receiving site could not decode the input parameters, dispatch to an appropriate server indicated by the server address, and invoke an application-level function corresponding semantically to the interface or method indicated in the method call.

In the first case, the HTTP infrastructure passes the headers and body to the SOAP infrastructure.

In the second case, the result is an HTTP response containing an HTTP error in the status field and no XML body.

In the third case, the result of the method call consists of a response or fault message.

In the fourth case, the result of the method is a fault message indicating a fault that prevented the dispatching infrastructure on the receiving side from successful completion.

In the third and fourth cases, additional payload headers may for extensibility again be present in the results of the call.

7.1. Results from a Method Call

The results of the call are to be provided in the form of a call response. The HTTP response must be of Content-Type "text/xml".

Because a result indicates success and a fault indicates failure, it is an error for the method response to contain both a result and a fault.

7.2. __SOAP:fault and HTTP Status Codes

If the HTTP infrastructure successfully processes the method request, passes it to the SOAP infrastructure, and an error occurs, a fault indication is returned to the caller instead of a normal response. In this section, a simple fault element is defined. This element type MAY be used to return fault indications; alternatively an application-defined element type may be used.

The standard SOAP:fault structure consists of

struct fault

{

int faultcode;

String faultstring;

int runcode;

}

Three sub elements of this structure are defined, as follows:

* "faultcode", which must contain a qualified name value. If unqualified, the value is taken from the space of SOAP status codes, described below. If qualified, the prefix must match a declared namespace prefix. The faultcode is intended for use by software.

* "faultstring", which must contain a string value. The faultstring is intended for use by human users and must not be acted upon algorithmically by software. faultstring is similar to the 'Reason-Phrase' that may be present in HTTP responses. (See [1], section 6.1.)

* "runcode", which must contain a numeric value. The runcode is intended to indicate whether or not the request reached the destination server. There are three runcodes currently defined: 0 - Maybe, 1 - No, 2 - Yes.

Other subelements members beyond the three described above may be present, provided they are namespace-qualified.

If the fault specifies a server fault, as opposed to an HTTP fault, the HTTP status code must be "200" and the HTTP status message must be "OK". If it specifies an HTTP fault, the HTTP status code as defined in the HTTP specification [1] should be used.

If a method call fails to be processed because of a non-understood extension header element contained therein, the method invocation must return a fault. The fault must contain a 'faultcode' of SOAP_E_MUSTUNDERSTAND.

If a method response fails to be processed for similar reasons, an appropriate exceptional condition should be indicated to the application layer in an implementation-defined manner.

7.3. SOAP Status Codes

SOAP defines its own space of status codes. This space is used only by the SOAP infrastructure and is not expected to be used on HTTP failure. The reason this space is defined is to aid the conversion of existing protocols onto SOAP.

This status code space must be used for faultcodes contained in faults and in the method definitions defined in this specification that return status code values. Further, use of this space is recommended (but not required) in the specification of methods defined outside of the present specification.

The SOAP status code space consists of URIs, beginning “urn:schemas-xmlsoap-com:soap.v1/faultcode/” followed by numeric values drawn from the following ranges:

a) The HTTP Status Code Definitions, defined in Section 10 of RFC2068. (See [1].) Such values are three-digit numbers in the range 100-999 (decimal).

b) 0x8011FE00-0x8011FFFF (decimal: 2,148,662,784 - 2,148,663,295)

c) 0x0011FE00-0x0011FFFF (decimal: 1,179,136 - 1,179,647)

This specification at present defines the following status codes beyond those specified in [1]:

Name Value Meaning

==== ===== =======

SOAP_E_VERSION_MISMATCH 0x8011FE00 The call was using an unsupported SOAP version.

SOAP_E_MUSTUNDERSTAND 0x8011FE01 An XML element was received that contained an element tagged with mustUnderstand="1" that was not understood by the receiver.

7.4. Sample Encoding of Response Messages

Example #5:

The response from the example in section 3.3.2 would be:

HTTP/1.1 200 OK

Content-Type: text/xml

Content-Length: nnnn

<SOAP:Envelope

xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1” >

<SOAP:Body>

<m:GetLastTradePriceResponse

xmlns:m="some other URI”>

</m:GetLastTradePriceResponse>

</SOAP:Body>

</SOAP:Envelope>

Example #6:

The following response is similar to the one above, but uses optional headers.

HTTP/1.1 200 OK

Content-Type: text/xml

Content-Length: nnnn

<SOAP:Envelope

xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1” >

<SOAP:Header>

<t:Transaction

xmlns:t=”some URI”

xsd:type="int" mustUnderstand="1">

</t:Transaction>

</SOAP:Header>

<SOAP:Body>

<m:GetLastTradePriceResponse

xmlns:m="some other URI”>

</m:GetLastTradePriceResponse>

</SOAP:Body>

</SOAP:Envelope>

Example #7:

The following response returns a struct:

HTTP/1.1 200 OK

Content-Type: text/xml

Content-Length: nnnn

<SOAP:Envelope

xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1” >

<SOAP:Body>

<m:GetLastTradePriceResponse

xmlns:m="some other URI”>

34.5

</LastTradePrice>

10000

</DayVolume>

</return>

</m:GetLastTradePriceResponse>

</SOAP:Body>

</SOAP:Envelope>

Example #8:

If there was an error in the HTTP infrastructure, the response could be as follows:

HTTP/1.1 401 Unauthorized

Example #9:

If there was an error in the SOAP infrastructure processing the request on the server, the response could be as follows:

HTTP/1.1 200 OK

Content-Type: text/xml

Content-Length: nnnn

<SOAP:Envelope xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1”>

<SOAP:Body>

<SOAP:fault>

SOAP Must Understand Error

</faultstring>

</SOAP:fault>

<SOAP:Body>

</SOAP:Envelope>

Example #10:

If the application passed back its own fault element, the response would be as follows:

HTTP/1.1 200 OK

Content-Type: text/xml

Content-Length: nnnn

<SOAP:Envelope

xmlns:SOAP="urn:schemas-xmlsoap-org:soap.v1” >

<SOAP:Body>

<e:MyFaultType

xmlns:e="some other URI”>

SOAP Must Understand Error

</faultstring>

My application didn't work

</message>

</e:MyFaultType>

</SOAP:Body>

</SOAP:Envelope>

8. Types

SOAP uses a simple, traditional type system. A type either is a simple (scalar) type or is a compound type constructed as a composite of several parts, each with a type.

Because all types are contained or referenced within a call or response element, the encoding samples in this section assume all namespace declarations are at a higher element level.

8.1. Rules for Encoding Types in XML

XML allows very flexible encoding of data to represent a method call. 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.

To describe encoding, the following terminology is used:

1. A "type" includes integer, string, point, or street address. A type in SOAP corresponds to a scalar or structured type in a programming language or database. All values are of specific types.

2. A "compound type" is one that has distinct, named parts and whose encoding should reflect those named parts. A "simple type" is one without named parts. A structured type in a programming language is a compound type, and so is an array.

3. The name of a parameter or of a named part of a compound type is called an "accessor."

4. If only one accessor can reference it, a value is considered "single-reference" for a given schema. If referenced by more than one, actually or potentially in a given schema, it is "multi-reference." Therefore, it is possible for a certain type to be considered "single-reference" in one schema and "multi-reference" in another schema.

5. Syntactically, an element may be "independent" or "embedded." An independent element is contained immediately by the root element. An embedded element is contained within a non-root element.

The rules are as follows:

1. Elements may be used to reflect either accessors or instances of types. Embedded elements always reflect accessors. Independent elements always reflect instances of types. When reflecting an accessor, the name of the element gives the name of the accessor. When reflecting an instance of a type, the name of the element gives the name of the type.

2. A call or response is always encoded as an independent element.

3. Accessors are always encoded as embedded elements.

4. A value (simple or compound) is encoded as element content, either of an element reflecting an accessor to the value or of an element reflecting an instance of that type.

5. A simple value is encoded as character data that is, without any subelements.

6. Strings and byte arrays are multi-reference simple types, but special rules allow them to be represented efficiently for common cases. An accessor to a string or byte-array value may have an attribute named "id" and of type "ID" per the XML Specifications. If so, all other accessors to the same value are encoded as empty elements having an attribute named "href" and of type "URI" per the XML Linking Language Specifications, with the href containing a URI fragment identifier referencing the single element containing the value.

7. It is permissible to encode several references to a simple value as though these were references to several single-reference values, but only when from context it is known that the meaning of the XML instance is unaltered.

8. A compound value is encoded as a sequence of elements, each named according to the accessor it reflects. (See also section 8.4.1.)

9. A multi-reference simple or compound value is encoded as an independent element containing an attribute named "id" and of type "ID" per the XML Specifications. Each accessor to this value is an empty element having an attribute named "href" and of type "URI" per the XML Linking Language Specifications, with the href containing a URI fragment identifier referencing the corresponding independent element.

10. Arrays are compound types. Arrays can be of one or more dimensions(rank) whose elements are normally laid contiguously in memory. Arrays can be single-reference or multi-reference values. Single-reference embedded arrays are encoded using accessor elements. A multi-reference array is always encoded as an independent element whose tag name is the string “ArrayOf” prepended to the element type of the array. The independent element or the accessor must contain a "xsd:type" attribute that specifies the type and dimensions of the array and is encoded as the type of the array element, followed by "[", followed by comma-separated lengths of each dimension, followed by "]". The “xsd:type” attribute is described in the “XML Schema Part 2: Datatypes” Specification (see [12]).

11. Note that the array element itself can be an array. An array type is encoded as its element type, followed by "[", followed by rank encoded as a sequence of commas(one for each dimension), followed by "]". It may also contain an "offset" attribute to indicate the starting position of a partially represented array. Each element of an array is encoded using the accessor named "item". The elements are represented as a list with the dimension on the right side varying rapidly. The "item" accessor may contain the "position" attribute that conveys the position of the item in the enclosing array. Both "offset" and "Position" attributes are encoded as "[", followed by a comma-separated position in each dimension, followed by "]".

11. Any accessor element that contains its value directly may optionally have an attribute named "xsd:type" whose value indicates the type of the element's contained value as described in the “XML Schema Part 2: Datatypes” Specification (see [12]).

12. A NULL value is indicated by an attribute named "SOAP:Null" with value of '1'.

8.2. Simple Types

For simple types, SOAP adopts the types found in the section "Specific Datatypes" of the XML-Data Specification (see [4]), along with the corresponding recommended representation thereof. Examples include:

ui4: 58502

float: 314159265358979E+1

i2: -32768

Strings and arrays of bytes are encoded as multi-reference simple types.

8.2.1. String

A string is a multi-reference simple type. According to the rules of multi-reference simple types, 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>

However, if the fact that both accessors reference the same instance of the string is immaterial, they may be encoded as though single-reference, as follows:

<greeting>Hello</greeting>

<salutation>Hello</salutation>

8.2.2. Enums

An enum is a single reference type whose value is encoded as one of the possible enumeration strings. In the following example EyeColor is an enum with the possible values of “Green”, “Blue”, and “Brown”:

<Name>Henry Ford</Name>

<EyeColor>Brown</EyeColor>

</Person>

8.2.3. Array of Bytes

An array of bytes is encoded as a multi-reference simple type. The recommended representation of an opaque array of bytes is the 'bin.base64' encoding defined in XML DCD (see [5]), which simply references the MIME standard. However, the line length restrictions that normally apply to Base64 data in MIME do not apply in SOAP.

bin.base64: aG93IG5vdyBicm93biBjb3cNCg==

8.3. Variant

Many languages allow accessors that can polymorphically access values of several types, each type being available at run-time. When the value is single-reference, the type of this kind of accessor is often called "Variant". A Variant accessor must contain a "type" attribute that describes the type of the actual value.

For example, a Variant parameter named "cost" with a type of float would be encoded as follows:

as constrasted with a cost parameter whose type is invariant, as follows:

8.4. Compound Types

Beyond the simple types, SOAP defines support for the following constructed types:

* Records/structs

* arrays

Where appropriate and possible, the representation in SOAP of a value of a given type mirrors that used by practitioners of XML-Data and the common practice of the XML community at large.

8.4.1. Compound Values and References to Values

A compound value contains an ordered sequence of structural members. When the members have distinct names, as in an instance of a C or C++ "struct", this is called a "struct," and when the members do not have distinct names but instead are known by their ordinal position, this is called an "array.

The members of a compound value are encoded as accessor elements. For a struct, the accessor element name is the member name. For an array, the accessor element name is the element type name by default, but can also be application defined and the sequence of the accessor elements follows the ordinal sequence of the members.

The following is an example of a struct of type Book:

<Book>

<author>Henry Ford</author>

<preface>Prefatory text</preface>

</Book>

Below is an example of a type with both simple and compound members. It shows two levels of referencing.

Note that the "href" attribute of the Author accessor element is a reference to the value whose "id" attribute matches; a similar construction appears for the Address.

<Book>

</Book>

<name>Henry Ford</name>

</Person>

<email>henryford@hotmail.com</email>

<web>www.henryford.com</web>

</Address>

The form above is appropriate when the Person value and the Address value are multi-reference. If these were instead both single-reference, they should be embedded, as follows:

<Book>

<name>Henry Ford</name>

<email>henryford@hotmail.com</email>

<web>www.henryford.com</web>

</address>

</author>

</Book>

If instead there existed a restriction that no two persons can have the same address in a given schema and that an address can be either a Street-address or an Electronic-address, a Book with two authors would be encoded in such a schema as follows:

<Book>

</Book>

<name>Henry Ford</name>

<email>henryford@hotmail.com</email>

<web>www.henryford.com</web>

</address>

</Person>

<name>Thomas Cook</name>

<Street>Martin Luther King Rd</Street>

<City>Raliegh</City>

<State>North Carolina</State>

</address>

</Person>

8.4.1.1. Generic Records

There are cases where a struct is represented with its members named and values typed at run time. Even in these cases, the existing rules apply. Each member is encoded as an element with matching name, and each value is either contained or referenced. Contained values must have a "type" attribute giving the type of the value.

8.4.2. Arrays

The representation of the value of an array is an ordered sequence of elements constituting items of the array. The default tag name for each element is the element type..

As with compound types generally, if the type of an item in the array is a single-reference type, each item contains its value. Otherwise, the item references its value via an href attribute.

The following example is an array containing integer array members. The length attribute is optional.

</ArrayOfint>

The following example is an array of Variants containing an integer and a string.

<variant xsd:type="string" id="ref-0">some silly old string</variant>

</ArrayOfvariant>

The following is an example of a two-dimensional array of strings.

</ArrayOfstring>

The following is an example of an array of two arrays, each of which is an array of strings.

</ArrayOfArrayOfstring>

</ArrayOfstring>

</ArrayOfstring>

Finally, the following is an example of an array of phone numbers embedded in a struct of type Person and accessed through the accessor “phone-numbers”:

<name>John Hancock</name>

<phone-numbers xsd:type="string[2]">

</phone-numbers>

</Person>

A multi-reference array is always encoded as an independent element whose tag name is the string “ArrayOf” prepended to the element type of the array. For example an array of order structs encoded as an independent element:

<Order>

<Product>Apple</Product>

</Order>

<Order>

<Product>Peach</Product>

</Order>

</ArrayOfOrder>

A single-reference is encoded as an embedded element whose tag name is the accessor name.

<CustomerName> Henry Ford </CustomerName>

</ShipTo>

<Order>

<Product>Apple</Product>

</Order>

<Order>

<Product>Peach</Product>

</Order>

</PurchaseLineItems>

</PurchaseOrder>

8.4.2.1. Partially transmitted arrays

SOAP provides support for partially transmitted arrays, known as "varying" arrays, in some contexts. (See [7].) A partially transmitted array indicates in an "offset" attribute the zero-origin index of the first element transmitted; if omitted, the offset is taken as zero.

The following is an example of an array of size five that transmits only the third and fourth element:

<string>The third element</string>

<string>The fourth element</string>

</Arrayofstring>

8.4.2.2. Sparse Arrays

SOAP provides support for sparse arrays in some contexts. Each element contains a "position" attribute that indicates its position within the array. The following is an example of array of arrays of strings:

</ArrayOfArrayOfstring>

<string position="[2,2]">The second element"</item>

<string position="[7,2]">The seventh element</item>

</ArrayOfstring>

Assuming that the only reference to array-1 occurs in the enclosing array, this example could also have been encoded as follows:

<string position="[2,2]">The second element"</string>

<string position="[7,2]">The seventh element</string>

</ArrayOfstring>

</ArrayOfArrayOfstring>

8.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. Typically, an omitted accessor implies a Null value for Variant and for polymorphic accessors (with the exact meaning of Null accessor-dependent). Typically, an omitted Boolean accessor implies either a False value or that no value is known, and an omitted numeric accessor implies either that the value is zero or that no value is known.

9. Formal Syntax

The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in RFC-2234 [10].

10. Security Considerations

Not described in this document are methods for integrity and privacy protection. Such issues will be addressed more fully in a future version(s) of this document.

11. References

[1] RFC2068: Hypertext Transfer Protocol, http://info.internet.isi.edu/in-notes/rfc/files/rfc2068.txt. Also: http://www.w3.org/Protocols/History.html.

[2] HTTP Extension Framework, http://www.w3.org/Protocols/HTTP/ietf-http-ext.

[3] The XML Specification, http://www.w3.org/TR/WD-xml-lang.

[4] XML-Data Specification, http://www.w3.org/TR/1998/NOTE-XML-data.

[5] Document Content Description for XML, http://www.w3.ort/TR/NOTE-dcd.

[6] Namespaces in XML, http://www.w3.org/TR/REC-xml-names.

[7] Transfer Syntax NDR, in "DCE 1.1: Remote Procedure Call," http://www.rdg.opengroup.org/onlinepubs/9629399/toc.htm.

[8] RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax and Semantics, http://www.ietf.org/rfc/rfc2396.txt.

[9] XML Linking Language, http://www.w3.org/1999/07/WD-xlink-19990726.

[10] RFC-2234: Augmented BNF for Syntax Specifications: ABNF

[11] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997

[12] XML Schema Part 2: Datatypes, http://www.w3.org/TR/1999/WD-xmlschema-2-19991105/

12. Author's Addresses

Don Box

DevelopMentor

21535 Hawthorne Blvd., Fourth Floor

Torrance, CA 90503

Email: dbox@develop.com

Gopal Kavivaya

Microsoft

One Microsoft Way

Redmond, WA 98052

Email: gopalk@microsoft.com

Andrew Layman

Microsoft

One Microsoft Way

Redmond, WA 98052

Email: andrewl@microsoft.com

Satish Thatte

Microsoft

One Microsoft Way

Redmond, WA 98052

Email: satisht@microsoft.com

Dave Winer

UserLand Software, Inc.

P.O. Box 1218

Burlingame, CA 94011-1218

Email: dave@userland.com

Full Copyright Statement

"Copyright (C) The Internet Society (date). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into