INTERNET-DRAFT D. Box DevelopMentor G. Kakivaya A. Layman S. Thatte Microsoft Corporation D. Winer Userland Software Document: 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 [13]. 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 [11]. Box, Kakivaya, et al. HTTP -- June, 2000 1 SOAP: Simple Object Access Protocol November, 1999 The namespace prefix "SOAP" is used in this document to represent whatever prefix actually appears in the XML instance and is associated with the SOAP namespace URI "urn:schemas-xmlsoap- org:soap.v1". The prefix "xsd" represents whatever prefix is associated with the XML Schemas Specification URI [12]. 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. 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 SOAP Calls 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. Box, Kakivaya, et al. HTTP -- June, 2000 2 SOAP: Simple Object Access Protocol November, 1999 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: Some-Namespace-URI#GetLastTradePrice DIS 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 34.5 4. Relation to HTTP In SOAP, the mechanism used for all communication is HTTP [1]. A central design goal of SOAP is that SOAP be usable strictly on top of today's 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 Box, Kakivaya, et al. HTTP -- June, 2000 3 SOAP: Simple Object Access Protocol November, 1999 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 request containing a XML encoded method call. To disambiguate the headers it adds to HTTP, SOAP permits use of the HTTP Extension Framework specification [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 payloads that have namespaces; the receiver MUST return an “Invalid Request” fault for requests that have incorrect 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. 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 [9]. 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. Box, Kakivaya, et al. HTTP -- June, 2000 4 SOAP: Simple Object Access Protocol November, 1999 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 [2]. A SOAP invocation MUST first try the invocation by using POST. If the POST invocation fails, it SHOULD 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 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. Given this algorithm, firewalls can effectively force the use of M- POST for SOAP invocations by prohibiting POST invocations of Content-Type "text/xml" containing the HTTP header SOAPMethodName. 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 SHOULD 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 Box, Kakivaya, et al. HTTP -- June, 2000 5 SOAP: Simple Object Access Protocol November, 1999 header-prefix is not used. For example, the SOAPMethodName header introduced by SOAP would have an M-POST value of "01- SOAPMethodName" and a POST value of “SOAPMethodName”. b) The request SHOULD include a header "SOAPMethodName" whose value indicates the method to be invoked on the target. The value consists of a URI followed by a "#", followed by a method name (which MUST not include the "#" character). The URI used for the interface MUST match the implied or specified namespace qualification of the method name element in the SOAP:Body part of the payload. For example: SOAPMethodName: http://electrocommerce.org/abc#MyMethod * The server MUST return an "Invalid Request" SOAP:Fault if the required HTTP headers are missing or does not match the payload exactly. Match means the URI and method name in the HTTP header exactly match the namespace URI AND LocalPart of the first element in the SOAP:Body. 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 are HTTP request and response respectively whose content is an XML document that consists of the root, (optional) header, and (mandatory) body elements. This XML document is referred to as SOAP payload in the rest of this specification. The SOAP payload is 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. The encoding rules are as follows: 1) Root element a) The element tag is "SOAP:Envelope". b) SOAP defines a global attribute "SOAP:encodingStyle" indicating any serialization rules used in lieu of those described 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” Box, Kakivaya, et al. HTTP -- June, 2000 6 SOAP: Simple Object Access Protocol November, 1999 is defined and all URIs beginning with this one indicate conformance with section 8 (though 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. The root element may contain additional sub elements provided these are namespace qualified and follow the body. 2) SOAP payload headers a) The element tag is "SOAP:Header". If present, this element MUST be the first element under the root. b) It contains a list of header entries. Each MUST be 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. or 4) Response a) The element tag is “SOAP:Body”. b) 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. or 5) Fault a) The element tag is “SOAP:Body”. b) The Body element contains a first sub element that is the SOAP: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. Box, Kakivaya, et al. HTTP -- June, 2000 7 SOAP: Simple Object Access Protocol November, 1999 If a server receives a version it cannot handle, it must return a “Version Mismatch” SOAP:fault. Processing requests in the face of missing parameters 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 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 “SOAP:encodingStyle” 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: 5 6.5.1. The "SOAP:mustUnderstand" Attribute Box, Kakivaya, et al. HTTP -- June, 2000 8 SOAP: Simple Object Access Protocol November, 1999 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 7.1, "Results from a Method Call." The SOAP:mustUnderstand attribute allows for robust semantic extensibility and change. Headers tagged with SOAP:mustUnderstand="1" MUST be presumed to somehow modify the semantics of their parent or peer elements. 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 * 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, that resource is called 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 Box, Kakivaya, et al. HTTP -- June, 2000 9 SOAP: Simple Object Access Protocol November, 1999 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 Requests 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. 5 Box, Kakivaya, et al. HTTP -- June, 2000 13 SOAP: Simple Object Access Protocol November, 1999 34.5 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 5 200 SOAP Must Understand Error 1 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 Box, Kakivaya, et al. HTTP -- June, 2000 15 SOAP: Simple Object Access Protocol November, 1999 My application didn't work 1001 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 its scoping element. An embedded element is contained within a non-scoping element. Examples of scoping element in this specification are “SOAP:Header” and “SOAP:Body”. Box, Kakivaya, et al. HTTP -- June, 2000 16 SOAP: Simple Object Access Protocol November, 1999 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 typically gives the name of the type. 2. A call or response/fault 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 sub elements. 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 Specification [3]. 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 [9], 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 Specification [3]. Each accessor to this value is an empty element having an attribute named "href" and of type "URI" per the XML Linking Language Specification [9], 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 Box, Kakivaya, et al. HTTP -- June, 2000 17 SOAP: Simple Object Access Protocol November, 1999 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]. 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 after the type of array element. The elements are represented as a list with the dimension on the right side varying rapidly. The 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 "]", with offsets and positions based at 0. 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 [12]. However, its presence is mandatory on elements whose tag name combined with implicit or explicit namespace does not unambiguously identify the type of the element. 12. A NULL value is indicated by an attribute named "xsd:null" with value of '1'. 13. In many cases, it is necessary to package multiple related elements as a single element, for instance in cases where the elements are linked together via hrefs. SOAP defines another attribute “SOAP:Package” whose value can be “0” or “1”. If “1” the element acts as a scoping element for contained sub elements. 8.2. Simple Types For simple types, SOAP adopts the types found in the section "Built- in datatypes" of the “XML Schema Part 2: Datatypes” Specification [12], along with the corresponding recommended representation thereof. Examples include: integer: 58502 real: 314159265358979E+1 negative-integer: -32768 Strings and arrays of bytes are encoded as multi-reference simple types. 8.2.1. String Box, Kakivaya, et al. HTTP -- June, 2000 18 SOAP: Simple Object Access Protocol November, 1999 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: Hello 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: Hello Hello 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”: Henry Ford 32 Brown 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 [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. Polymorphic Accessor 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 Polymorphic accessor MUST contain a "xsd:type" attribute that describes the type of the actual value. For example, a Polymorphic parameter named "cost" with a type of float would be encoded as follows: 29.95 Box, Kakivaya, et al. HTTP -- June, 2000 19 SOAP: Simple Object Access Protocol November, 1999 as contrasted with a cost parameter whose type is invariant, as follows: 29.95 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 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: Henry Ford Prefatory text This is a 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. My Life and Work Henry Ford
Box, Kakivaya, et al. HTTP -- June, 2000 20 SOAP: Simple Object Access Protocol November, 1999
henryford@hotmail.com www.henryford.com
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: My Life and Work Henry Ford
henryford@hotmail.com www.henryford.com
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: My Life and Work Henry Ford
henryford@hotmail.com www.henryford.com
Thomas Cook
Martin Luther King Rd Raleigh North Carolina
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 Box, Kakivaya, et al. HTTP -- June, 2000 21 SOAP: Simple Object Access Protocol November, 1999 values MUST have a "xsd: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. 3 4 The following example is an array of Variants containing an integer and a string. 23 some string The following is an example of a two-dimensional array of strings. r1c1 r1c2 r1c3 r2c1 r2c2 r2c3 The following is an example of an array of two arrays, each of which is an array of strings. r1c1 r1c2 r1c3 Box, Kakivaya, et al. HTTP -- June, 2000 22 SOAP: Simple Object Access Protocol November, 1999 r2c1 r2c2 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”: John Hancock 111-2222 999-0000 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: Apple 1.56 Peach 1.48 A single-reference array is encoded as an embedded element whose tag name is the accessor name. Henry Ford 5th Ave New York NY 10010 Apple 1.56 Peach 1.48 Box, Kakivaya, et al. HTTP -- June, 2000 23 SOAP: Simple Object Access Protocol November, 1999 8.4.2.1. Partially transmitted arrays SOAP provides support for partially transmitted arrays, known as "varying" arrays, in some contexts [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: The third element The fourth element 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: The third element" The eighth element Assuming that the only reference to array-1 occurs in the enclosing array, this example could also have been encoded as follows: The third element" The eighth element 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 Box, Kakivaya, et al. HTTP -- June, 2000 24 SOAP: Simple Object Access Protocol November, 1999 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 This 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/ [13] RFC2026: The Internet Standards Process -- Revision 3, http://info.internet.isi.edu/in-notes/rfc/files/rfc2026.txt. 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 Box, Kakivaya, et al. HTTP -- June, 2000 25 SOAP: Simple Object Access Protocol November, 1999 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 Box, Kakivaya, et al. HTTP -- June, 2000 26 SOAP: Simple Object Access Protocol November, 1999 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. Box, Kakivaya, et al. HTTP -- June, 2000 27