idnits 2.17.1 draft-box-http-soap-01.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document is more than 15 pages and seems to lack a Table of Contents. == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 1535 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 308 has weird spacing: '...esponse are H...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: 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: -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 1999) is 8928 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: '4' is defined on line 1400, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2068 (ref. '1') (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2396 (ref. '8') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2234 (ref. '10') (Obsoleted by RFC 4234) Summary: 10 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT D. Box 2 DevelopMentor 4 G. Kakivaya 5 A. Layman 6 S. Thatte 7 Microsoft 8 Corporation 10 D. Winer 11 Userland Software 13 Document: November 1999 14 Category: Informational 16 SOAP: Simple Object Access Protocol 18 Status of this Memo 20 This document is an Internet-Draft and is in full conformance with 21 all provisions of Section 10 of RFC2026 [13]. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as Internet- 26 Drafts. Internet-Drafts are draft documents valid for a maximum of 27 six months and may be updated, replaced, or obsoleted by other 28 documents at any time. It is inappropriate to use Internet- Drafts 29 as reference material or to cite them other than as "work in 30 progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 1. Abstract 40 SOAP defines an RPC mechanism using XML for client-server 41 interaction across a network by using the following mechanisms: 42 * HTTP as the base transport 43 * XML documents for encoding of invocation requests and responses 45 2. Conventions used in this document 47 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 48 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 49 this document are to be interpreted as described in RFC-2119 [11]. 51 Box, Kakivaya, et al. HTTP -- June, 2000 1 53 SOAP: Simple Object Access Protocol November, 1999 55 The namespace prefix "SOAP" is used in this document to represent 56 whatever prefix actually appears in the XML instance and is 57 associated with the SOAP namespace URI "urn:schemas-xmlsoap- 58 org:soap.v1". The prefix "xsd" represents whatever prefix is 59 associated with the XML Schemas Specification URI [12]. 61 Namespace URIs such of the general form "some-URI" represent some 62 application-dependent or context-dependent URI. 64 3. Introduction 66 SOAP defines an "XML-RPC" protocol for client-server interaction 67 across a network by using the following mechanisms: 68 * HTTP as the base transport 69 * XML documents for encoding of invocation requests and 70 responses 72 SOAP is both low-entry and high-function, capable of use for simple 73 stateless remote procedure calls as well as rich object systems. 75 SOAP works with today's deployed World Wide Web and provides 76 extensibility mechanisms for future enhancements. For example, SOAP 77 supports submitting invocations using both POST and M-POST. 79 3.1. Goals 80 * Provide a standard object invocation protocol built on 81 Internet standards, using HTTP as the transport and XML for data 82 encoding. 83 * Create an extensible protocol and payload format that can 84 evolve. 86 3.2. Non-Goals 87 Define all aspects of a distributed object system, including the 88 following: 89 * Distributed garbage collection 90 * Bi-directional HTTP communications 91 * Boxcarring or pipelining of messages 92 * Objects-by-reference (which requires distributed garbage 93 collection and bi-directional HTTP) 94 * Activation (which requires objects-by-reference) 96 3.3. Examples of SOAP Calls 98 The call is to a StockQuote server, and the method is 99 GetLastTradePrice. The method takes one string parameter, ticker, 100 and returns a float. 102 It uses the SOAP namespace to disambiguate SOAP keywords in the 103 payload and a method namespace to disambiguate method keywords in 104 the payload. 106 The root Envelope element tag name is used to disambiguate SOAP XML 107 encodings. 109 Box, Kakivaya, et al. HTTP -- June, 2000 2 111 SOAP: Simple Object Access Protocol November, 1999 113 3.3.1. Call 115 Example #1: 117 Following is an example of the SOAP encoding required to make this 118 method call. This example uses the familiar HTTP verb POST. SOAP 119 also supports the use of the HTTP verb M-POST for extensibility. See 120 section 6.1 for more information on M-POST. 122 POST /StockQuote HTTP/1.1 123 Host: www.stockquoteserver.com 124 Content-Type: text/xml 125 Content-Length: nnnn 126 SOAPMethodName: Some-Namespace-URI#GetLastTradePrice 128 129 130 132 DIS 133 134 135 137 3.3.2. Response 139 Example #2: 141 Following is the return message containing the HTTP headers and XML 142 body: 144 HTTP/1.1 200 OK 145 Content-Type: text/xml 146 Content-Length: nnnn 148 149 150 151 34.5 152 153 154 156 4. Relation to HTTP 158 In SOAP, the mechanism used for all communication is HTTP [1]. A 159 central design goal of SOAP is that SOAP be usable strictly on top 160 of today's deployed World Wide Web infrastructure. That means SOAP 161 has to live with and work in the face of various levels of HTTP 162 implementation, the active use of firewalls and proxies, and so on. 163 Some aspects of SOAP, such as the permitted use of HTTP methods 164 beyond those of classic HTTP, are designed to anticipate, and thus 166 Box, Kakivaya, et al. HTTP -- June, 2000 3 168 SOAP: Simple Object Access Protocol November, 1999 170 make use of, some evolution and improvement in this base, but 171 nothing in SOAP can require such fundamental changes in order for 172 SOAP to function. 174 SOAP uses the Content-Type of "text/xml". This is used to specify 175 the body of the HTTP request containing a XML encoded method call. 177 To disambiguate the headers it adds to HTTP, SOAP permits use of the 178 HTTP Extension Framework specification [2]. 180 Unless otherwise indicated in this document, existing practices with 181 respect to the handling of HTTP requests and responses are to be 182 adhered to. Specifically, this includes the following: 184 * Redirection 185 * Caching 186 * Connection management 187 * Support for access authentication and security 189 5. Relation to XML 191 XML is used to encode the call and response bodies. See [3] for more 192 information on XML. 194 All protocol tags SHOULD be scoped to the SOAP namespace. The sender 195 SHOULD include namespaces in SOAP elements and attributes. The 196 receiver MUST correctly process SOAP payloads that have namespaces; 197 the receiver MUST return an "Invalid Request" fault for requests 198 that have incorrect namespaces. The receiver MAY also process SOAP 199 payloads without namespaces as though they had the correct 200 namespaces. 202 The SOAP namespace has the proposed value "urn:schemas-xmlsoap- 203 org:soap.v1". See [6] for more information on XML namespaces. 205 No XML document forming the HTTP request of a SOAP invocation may 206 require the use of an XML DTD. 208 SOAP uses the ID attribute "id" to specify the unique identifier of 209 an encoded element. SOAP uses the attribute "href" to specify a 210 reference to that value, in a manner conforming to the XML Linking 211 Language specification working draft [9]. 213 It is worth noting that the rules governing XML payload format in 214 SOAP are entirely independent of the fact that the payload is 215 carried over an HTTP transport. 217 6. Method Invocation 219 A method invocation is performed by creating the HTTP request header 220 and body and processing the returned response header and body. The 221 request and response headers consist of standard and extended HTTP 222 headers. 224 Box, Kakivaya, et al. HTTP -- June, 2000 4 226 SOAP: Simple Object Access Protocol November, 1999 228 The following sections will cover the use of standard HTTP headers 229 and the definition of extended HTTP headers. 231 6.1. HTTP Verb Rules 233 SOAP allows two verb options within the Call HTTP header: POST or M- 234 POST. 236 The verb M-POST is an extension verb based on in the HTTP Extension 237 Framework specification [2]. A SOAP invocation MUST first try the 238 invocation by using POST. 240 If the POST invocation fails, it SHOULD retry using the HTTP method 241 M-POST. The details of this mechanism are provided below. The 242 purpose of supporting this extended invocation mechanism in SOAP is 243 to provide a mechanism to unambiguously add headers to the HTTP 244 protocol. 246 6.2. Using POST vs. M-POST 248 Since a design goal of the use of M-POST is to provide Internet 249 firewalls and proxies greater administrative flexibility, careful 250 attention must be paid as to when a SOAP client uses the POST method 251 vs. the M-POST method. The rules are as follows: 253 When carrying out an invocation, a SOAP client MUST first try the 254 invocation using the POST invocation style. 256 If that POST invocation fails with an HTTP status of "405 Method Not 257 Allowed" the client SHOULD retry the request using the M-POST 258 invocation style. If that M-POST invocation fails with an HTTP 259 status of "501 Not Implemented" or "510 Not Extended", the client 260 SHOULD fail the request. If any other HTTP error is returned, it 261 SHOULD be processed according to the HTTP specification. 263 Given this algorithm, firewalls can effectively force the use of M- 264 POST for SOAP invocations by prohibiting POST invocations of 265 Content-Type "text/xml" containing the HTTP header SOAPMethodName. 267 6.3. Method Invocation HTTP Headers 269 The payload and Content-Type of a method call are identical to a 270 method response except in the following circumstances: 272 * The method call SHOULD contain additional HTTP header fields 273 in the request: 275 a) If using the M-POST verb, a mandatory extension declaration 276 MUST be present that refers to the namespace "urn:schemas- 277 xmlsoap-org:soap.v1". For the purposes of this section, suppose 278 that said declaration chooses to map the namespace to the 279 header-prefix "01". If the POST verb is used, the namespace 281 Box, Kakivaya, et al. HTTP -- June, 2000 5 283 SOAP: Simple Object Access Protocol November, 1999 285 header-prefix is not used. For example, the SOAPMethodName 286 header introduced by SOAP would have an M-POST value of "01- 287 SOAPMethodName" and a POST value of "SOAPMethodName". 289 b) The request SHOULD include a header "SOAPMethodName" whose 290 value indicates the method to be invoked on the target. The 291 value consists of a URI followed by a "#", followed by a method 292 name (which MUST not include the "#" character). The URI used 293 for the interface MUST match the implied or specified namespace 294 qualification of the method name element in the SOAP:Body part 295 of the payload. For example: 297 SOAPMethodName: http://electrocommerce.org/abc#MyMethod 299 * The server MUST return an "Invalid Request" SOAP:Fault if the 300 required HTTP headers are missing or does not match the payload 301 exactly. Match means the URI and method name in the HTTP header 302 exactly match the namespace URI AND LocalPart of the first element 303 in the SOAP:Body. 305 6.4. Method Invocation Body 307 A SOAP method invocation consists of a method call and optionally a 308 method response. The method call and method response are HTTP 309 request and response respectively whose content is an XML document 310 that consists of the root, (optional) header, and (mandatory) body 311 elements. This XML document is referred to as SOAP payload in the 312 rest of this specification. 314 The SOAP payload is defined as follows: 316 * The SOAP root element is the top element in the XML tree. 317 * The SOAP payload headers contain additional information that 318 needs to travel with the call. 319 * The method request is represented as an XML element with 320 additional elements for parameters. It is the first child of the 321 SOAP:Body element. 322 * The response is the return value or error/exception that is 323 passed back to the client. 325 The encoding rules are as follows: 327 1) Root element 329 a) The element tag is "SOAP:Envelope". 331 b) SOAP defines a global attribute "SOAP:encodingStyle" indicating 332 any serialization rules used in lieu of those described by the 333 SOAP spec. This attribute MAY appear on any element, and is 334 scoped to that element and all child elements not themselves 335 containing such an attribute. Omission of this attribute 336 indicates that section 8 has been followed (unless overridden 337 by a parent element). The URI "urn:schemas-xmlsoap-org:soap.v1" 339 Box, Kakivaya, et al. HTTP -- June, 2000 6 341 SOAP: Simple Object Access Protocol November, 1999 343 is defined and all URIs beginning with this one indicate 344 conformance with section 8 (though with potentially tighter 345 rules). 347 c) The root element MAY contain namespace declarations. 349 d) The root element MAY contain additional attributes, provided 350 these are namespace-qualified. The root element may contain 351 additional sub elements provided these are namespace qualified 352 and follow the body. 354 2) SOAP payload headers 356 a) The element tag is "SOAP:Header". If present, this element MUST 357 be the first element under the root. 359 b) It contains a list of header entries. Each MUST be namespace- 360 qualified. 362 3) Call 364 a) The element tag is "SOAP:Body". 366 b) The Body element contains a first sub element whose name is the 367 method name. This method request element in turn contains elements 368 for each [in] and [in/out] parameter. The element names are the 369 parameter names. See section 8 for details. 371 or 373 4) Response 375 a) The element tag is "SOAP:Body". 377 b) The Body element contains a first sub element that in turn 378 contains child elements for each [in/out] and [out] parameter. The 379 element names are the parameter names. See section 8 for details. 381 or 383 5) Fault 385 a) The element tag is "SOAP:Body". 387 b) The Body element contains a first sub element that is the 388 SOAP:Fault element, indicating information about the fault. 390 The version of SOAP used is indicated by the SOAP namespace URI. A 391 server MUST use the version passed in the envelope of the call for 392 encoding the response, or it MUST fail the request. In the case 393 where the server accepts a version or level less than its maximum, 394 it MUST respond to the client by using the same version and level. 396 Box, Kakivaya, et al. HTTP -- June, 2000 7 398 SOAP: Simple Object Access Protocol November, 1999 400 If a server receives a version it cannot handle, it must return a 401 "Version Mismatch" SOAP:fault. 403 Processing requests in the face of missing parameters is application 404 defined. 406 See section 7 for information on how to encode parameter values. 408 6.5. SOAP Payload Headers 410 In addition to the elements that specify direct, explicit 411 information about the call or response, SOAP provides a way to pass 412 extended, implicit information with the call through the use of the 413 "header" element. It is encoded as a child of the SOAP:Envelope XML 414 element. It contains a collection of distinctly named entries. 416 An example of the use of the header element is the passing of an 417 implicit transaction ID along with a call. Since the transaction ID 418 is not part of the signature and is typically held in an 419 infrastructure component rather than application code, there is no 420 direct way to pass the necessary information with the call. By 421 adding an entry to the headers and giving it a fixed name, the 422 transaction manager on the receiving side can extract the 423 transaction ID and use it without affecting the coding of remote 424 procedure calls. 426 Each header entry is encoded as an embedded element. The encoding 427 rules for a header are as follows: 429 1. The element's name identifies the header. Header elements 430 always are namespace-qualified. 432 2. Unless indicated to the contrary by the value of 433 "SOAP:encodingStyle" attribute, header values are encoded according 434 to the rules of section 8. 436 3. The element MAY contain an attribute "SOAP:mustUnderstand" 437 specifying required understanding of the header by the destination. 439 An example is a header with an identifier of "TransactionID", a 440 "mustUnderstand" value of true, and a value of 5. This would be 441 encoded as follows: 443 444 446 5 447 448 450 6.5.1. The "SOAP:mustUnderstand" Attribute 452 Box, Kakivaya, et al. HTTP -- June, 2000 8 454 SOAP: Simple Object Access Protocol November, 1999 456 Header entries MAY have a global attribute "SOAP:mustUnderstand". 457 This may have one of two values, either "1" or "0". The absence of 458 such a "SOAP:mustUnderstand" attribute is semantically equivalent to 459 its presence with the value "0". 461 If a header element is tagged with a "SOAP:mustUnderstand" attribute 462 whose value is "1", the party processing the Request URI MUST 463 understand the semantics (as conveyed by its element tag, contextual 464 setting, and so on) and process correctly to those semantics. 466 If the SOAP implementation doesn't understand the element, it MUST 467 return an error as specified in section 7.1, "Results from a Method 468 Call." 470 The SOAP:mustUnderstand attribute allows for robust semantic 471 extensibility and change. Headers tagged with 472 SOAP:mustUnderstand="1" MUST be presumed to somehow modify the 473 semantics of their parent or peer elements. Tagging the headers in 474 this manner assures that this change in semantics will not be 475 silently (and, presumably, erroneously) ignored by those who may not 476 fully understand it. 478 If the "SOAP:mustUnderstand" attribute is missing or has a value of 479 "0", that element can safely be ignored. 481 For example: If the client passed along a transaction ID header, as 482 in the above example, with a "SOAP:mustUnderstand" of "1", then the 483 server SHOULD fail if it cannot process the transaction ID and 484 comply with the transactional semantics. 486 6.6. Making a Method Call 488 To make a method call, the following information is needed: 490 * The URI of the target object 491 * A method name 492 * An optional method signature 493 * The parameters to the method 494 * Optional header data 496 The target URI of the HTTP request indicates the resource that the 497 invocation is being made against; in this specification, that 498 resource is called the "server address," to distinguish it from 499 other uses of URIs. Other than it be a valid URI, SOAP places no 500 restriction on the form of an address. See [8] for more information 501 on URIs. 503 The body of a SOAP method call MUST be of Content-Type 'text/xml'. 505 The SOAP protocol places no absolute restriction on the syntax or 506 case-sensitivity of interface names, method names, or parameter 507 names. Of course, individual SOAP servers will respond to only the 508 names they support; the selection of these is at their own sole 510 Box, Kakivaya, et al. HTTP -- June, 2000 9 512 SOAP: Simple Object Access Protocol November, 1999 514 discretion. The one restriction is that the server MUST preserve the 515 case of names. 517 6.6.1. Representation of Method Parameters 519 Method parameters are encoded as child elements of the call or 520 response, encoded using the following rules: 522 1) The name of the parameter in the method signature is used as 523 the name of the corresponding element. 525 2) Parameter values are expressed using the rules in section 8 of 526 this document. 528 6.6.2. Sample Encoding of Call Requests 530 Example #3: 532 This sample is the same call as in section 3.3.1 but uses optional 533 headers. It uses SOAP namespace to disambiguate SOAP keywords in the 534 payload. 536 539 540 543 5 544 545 546 547 548 DEF 549 550 551 553 Example #4: 555 The following request sends a struct: 557 559 560 562 DEF 563 DEF Corp 564 34.1 565 566 568 Box, Kakivaya, et al. HTTP -- June, 2000 10 570 SOAP: Simple Object Access Protocol November, 1999 572 574 7. Results of Method Calls 576 At the receiving site, a call request can have one of the following 577 four outcomes: 579 a) The HTTP infrastructure on the receiving site was able to 580 receive and process the request. 582 b) The HTTP infrastructure on the receiving site could not receive 583 and process the request. 585 c) The SOAP infrastructure on the receiving site was able to 586 decode the input parameters, dispatch to an appropriate server 587 indicated by the server address, and invoke an application-level 588 function corresponding semantically to the method indicated in the 589 method call. 591 d) The SOAP infrastructure on the receiving site could not decode 592 the input parameters, dispatch to an appropriate server indicated by 593 the server address, and invoke an application-level function 594 corresponding semantically to the interface or method indicated in 595 the method call. 597 In the first case, the HTTP infrastructure passes the headers and 598 body to the SOAP infrastructure. 600 In the second case, the result is an HTTP response containing an 601 HTTP error in the status field and no XML body. 603 In the third case, the result of the method call consists of a 604 response or fault. 606 In the fourth case, the result of the method is a fault indicating a 607 fault that prevented the dispatching infrastructure on the receiving 608 side from successful completion. 610 In the third and fourth cases, additional payload headers MAY for 611 extensibility again be present in the results of the call. 613 7.1. Results from a Method Call 615 The results of the call are to be provided in the form of a call 616 response. The HTTP response MUST be of Content-Type "text/xml". 618 Because a result indicates success and a fault indicates failure, it 619 is an error for the method response to contain both a result and a 620 fault. 622 7.2. SOAP:Fault and HTTP Status Codes 624 Box, Kakivaya, et al. HTTP -- June, 2000 11 626 SOAP: Simple Object Access Protocol November, 1999 628 If the HTTP infrastructure successfully processes the method 629 request, passes it to the SOAP infrastructure, and an error occurs, 630 a fault indication is returned to the caller instead of a normal 631 response. In this section, a SOAP:Fault element is defined. This 632 element MUST be used to return fault indications. 634 The standard SOAP:Fault element consists of four sub elements: 636 * "faultcode", which MUST contain a qualified name value, as 637 defined in Namespaces in XML [6], section 3 "Qname". If unqualified, 638 the value is taken from the space of SOAP status codes, described 639 below. If qualified, the prefix MUST match a declared namespace 640 prefix. The faultcode is intended for use by software. 642 * "faultstring", which MUST contain a string value. The 643 faultstring is intended for use by human users and must not be acted 644 upon algorithmically by software. faultstring is similar to the 645 'Reason-Phrase' that may be present in HTTP responses. (See [1], 646 section 6.1.) 648 * "runcode", which MUST contain an enumerated value. The runcode 649 is intended to indicate whether or not the request was dispatched to 650 the application. There are three runcodes currently defined: 651 "Maybe", "No", "Yes". 653 * "detail", which if present MUST contain a value per section 8 654 with application-specific semantics. 656 Other sub elements members beyond the three described above MAY be 657 present, provided they are namespace-qualified. 659 If the fault specifies a server fault, as opposed to an HTTP fault, 660 the HTTP status code MUST be "200" and the HTTP status message MUST 661 be "OK". If it specifies an HTTP fault, the HTTP status code as 662 defined in the HTTP specification [1] SHOULD be used. 664 If a method call fails to be processed because of a non-understood 665 extension header element contained therein, the method invocation 666 MUST return a fault. The fault MUST contain a 'faultcode' of "Must 667 Understand". 669 If a method response fails to be processed for similar reasons, an 670 appropriate exceptional condition should be indicated to the 671 application layer in an implementation-defined manner. 673 7.3. SOAP Status Codes 675 SOAP defines its own space of status codes. This space is used only 676 by the SOAP infrastructure and is not expected to be used on HTTP 677 failure. The reason this space is defined is to aid the conversion 678 of existing protocols onto SOAP. 680 Box, Kakivaya, et al. HTTP -- June, 2000 12 682 SOAP: Simple Object Access Protocol November, 1999 684 This status code space MUST be used for faultcodes contained in 685 faults and in the method definitions defined in this specification 686 that return status code values. Further, use of this space is 687 recommended (but not required) in the specification of methods 688 defined outside of the present specification. 690 The SOAP status code space is identified by the URI, "urn:schemas- 691 xmlsoap-com:soap.v1/faultcode" and contains numeric values drawn 692 from the following ranges: 694 This specification at present defines the following status codes 695 beyond those specified in [1]: 697 Name Value Meaning 698 ==== ===== ======= 699 Version Mismatch 100 The call was using an 700 unsupported SOAP 701 version. 702 Must Understand 200 An XML element was 703 received that contained 704 an element tagged with 705 mustUnderstand="1" that 706 was not understood by 707 the receiver. 708 Invalid Request 300 The receiving 709 application did not 710 process the request 711 because it was ill 712 formed or not supported 713 by the application. 714 Application Faulted 400 The receiving 715 application faulted 716 processing the request. 717 The 'detail' element 718 contains the 719 application specific 720 fault. 722 7.4. Sample Encoding of Response 724 Example #5: 726 The response from the example in section 3.3.2 would be: 728 HTTP/1.1 200 OK 729 Content-Type: text/xml 730 Content-Length: nnnn 732 734 735 738 Box, Kakivaya, et al. HTTP -- June, 2000 13 740 SOAP: Simple Object Access Protocol November, 1999 742 34.5 743 744 745 747 Example #6: 749 The following response is similar to the one above, but uses 750 optional headers. 752 HTTP/1.1 200 OK 753 Content-Type: text/xml 754 Content-Length: nnnn 756 758 759 762 5 763 764 765 766 768 34.5 769 770 771 773 Example #7: 775 The following response returns a struct: 777 HTTP/1.1 200 OK 778 Content-Type: text/xml 779 Content-Length: nnnn 781 783 784 786 787 788 34.5 789 790 791 10000 792 793 794 796 Box, Kakivaya, et al. HTTP -- June, 2000 14 798 SOAP: Simple Object Access Protocol November, 1999 800 801 803 Example #8: 805 If there was an error in the HTTP infrastructure, the response could 806 be as follows: 808 HTTP/1.1 401 Unauthorized 810 Example #9: 812 If there was an error in the SOAP infrastructure processing the 813 request on the server, the response could be as follows: 815 HTTP/1.1 200 OK 816 Content-Type: text/xml 817 Content-Length: nnnn 819 820 821 822 200 823 824 SOAP Must Understand Error 825 826 1 827 828 829 831 Example #10: 833 If the application passed back its own fault element, the response 834 would be as follows: 836 HTTP/1.1 200 OK 837 Content-Type: text/xml 838 Content-Length: nnnn 840 842 843 844 400 845 846 SOAP Must Understand Error 847 848 1 849 854 Box, Kakivaya, et al. HTTP -- June, 2000 15 856 SOAP: Simple Object Access Protocol November, 1999 858 My application didn't work 859 860 1001 861 862 863 864 866 8. Types 868 SOAP uses a simple, traditional type system. A type either is a 869 simple (scalar) type or is a compound type constructed as a 870 composite of several parts, each with a type. 872 Because all types are contained or referenced within a call or 873 response element, the encoding samples in this section assume all 874 namespace declarations are at a higher element level. 876 8.1. Rules for Encoding Types in XML 878 XML allows very flexible encoding of data to represent a method 879 call. SOAP defines a narrower set of rules for encoding. This 880 section defines the encoding rules at a high level, and the next 881 section describes the encoding rules for specific types when they 882 require more detail. 884 To describe encoding, the following terminology is used: 886 1. A "type" includes integer, string, point, or street address. A 887 type in SOAP corresponds to a scalar or structured type in a 888 programming language or database. All values are of specific types. 890 2. A "compound type" is one that has distinct, named parts and 891 whose encoding should reflect those named parts. A "simple type" is 892 one without named parts. A structured type in a programming language 893 is a compound type, and so is an array. 895 3. The name of a parameter or of a named part of a compound type 896 is called an "accessor." 898 4. If only one accessor can reference it, a value is considered 899 "single-reference" for a given schema. If referenced by more than 900 one, actually or potentially in a given schema, it is "multi- 901 reference." Therefore, it is possible for a certain type to be 902 considered "single-reference" in one schema and "multi-reference" in 903 another schema. 905 5. Syntactically, an element MAY be "independent" or "embedded." 906 An independent element is contained immediately by its scoping 907 element. An embedded element is contained within a non-scoping 908 element. Examples of scoping element in this specification are 909 "SOAP:Header" and "SOAP:Body". 911 Box, Kakivaya, et al. HTTP -- June, 2000 16 913 SOAP: Simple Object Access Protocol November, 1999 915 The rules are as follows: 916 1. Elements MAY be used to reflect either accessors or instances 917 of types. Embedded elements always reflect accessors. Independent 918 elements always reflect instances of types. When reflecting an 919 accessor, the name of the element gives the name of the accessor. 920 When reflecting an instance of a type, the name of the element 921 typically gives the name of the type. 923 2. A call or response/fault is always encoded as an independent 924 element. 926 3. Accessors are always encoded as embedded elements. 928 4. A value (simple or compound) is encoded as element content, 929 either of an element reflecting an accessor to the value or of an 930 element reflecting an instance of that type. 932 5. A simple value is encoded as character data, that is, without 933 any sub elements. 935 6. Strings and byte arrays are multi-reference simple types, but 936 special rules allow them to be represented efficiently for common 937 cases. An accessor to a string or byte-array value MAY have an 938 attribute named "id" and of type "ID" per the XML Specification [3]. 939 If so, all other accessors to the same value are encoded as empty 940 elements having an attribute named "href" and of type "URI" per the 941 XML Linking Language Specifications [9], with the href containing a 942 URI fragment identifier referencing the single element containing 943 the value. 945 7. It is permissible to encode several references to a simple 946 value as though these were references to several single-reference 947 values, but only when from context it is known that the meaning of 948 the XML instance is unaltered. 950 8. A compound value is encoded as a sequence of elements, each 951 named according to the accessor it reflects. (See also section 952 8.4.1.) 954 9. A multi-reference simple or compound value is encoded as an 955 independent element containing an attribute named "id" and of type 956 "ID" per the XML Specification [3]. Each accessor to this value is 957 an empty element having an attribute named "href" and of type "URI" 958 per the XML Linking Language Specification [9], with the href 959 containing a URI fragment identifier referencing the corresponding 960 independent element. 962 10. Arrays are compound types. Arrays can be of one or more 963 dimensions (rank) whose elements are normally laid contiguously in 964 memory. Arrays can be single-reference or multi-reference values. 965 Single-reference embedded arrays are encoded using accessor 966 elements. A multi-reference array is always encoded as an 967 independent element whose tag name is the string "ArrayOf" prepended 969 Box, Kakivaya, et al. HTTP -- June, 2000 17 971 SOAP: Simple Object Access Protocol November, 1999 973 to the element type of the array. The independent element or the 974 accessor MUST contain a "xsd:type" attribute that specifies the type 975 and dimensions of the array and is encoded as the type of the array 976 element, followed by "[", followed by comma-separated lengths of 977 each dimension, followed by "]". The "xsd:type" attribute is 978 described in the "XML Schema Part 2: Datatypes" Specification (see 979 12]. Note that the array element itself can be an array. An array 980 type is encoded as its element type, followed by "[", followed by 981 rank encoded as a sequence of commas(one for each dimension), 982 followed by "]". It MAY also contain an "offset" attribute to 983 indicate the starting position of a partially represented array. 984 Each element of an array is encoded using the accessor named after 985 the type of array element. The elements are represented as a list 986 with the dimension on the right side varying rapidly. The accessor 987 MAY contain the "position" attribute that conveys the position of 988 the item in the enclosing array. Both "offset" and "position" 989 attributes are encoded as "[", followed by a comma-separated 990 position in each dimension, followed by "]", with offsets and 991 positions based at 0. 993 11. Any accessor element that contains its value directly MAY 994 optionally have an attribute named "xsd:type" whose value indicates 995 the type of the element's contained value as described in the "XML 996 Schema Part 2: Datatypes" Specification [12]. However, its presence 997 is mandatory on elements whose tag name combined with implicit or 998 explicit namespace does not unambiguously identify the type of the 999 element. 1001 12. A NULL value is indicated by an attribute named "xsd:null" with 1002 value of '1'. 1004 13. In many cases, it is necessary to package multiple related 1005 elements as a single element, for instance in cases where the 1006 elements are linked together via hrefs. SOAP defines another 1007 attribute "SOAP:Package" whose value can be "0" or "1". If "1" the 1008 element acts as a scoping element for contained sub elements. 1010 8.2. Simple Types 1012 For simple types, SOAP adopts the types found in the section "Built- 1013 in datatypes" of the "XML Schema Part 2: Datatypes" Specification 1014 [12], along with the corresponding recommended representation 1015 thereof. Examples include: 1017 integer: 58502 1018 real: 314159265358979E+1 1019 negative-integer: -32768 1021 Strings and arrays of bytes are encoded as multi-reference simple 1022 types. 1024 8.2.1. String 1026 Box, Kakivaya, et al. HTTP -- June, 2000 18 1028 SOAP: Simple Object Access Protocol November, 1999 1030 A string is a multi-reference simple type. According to the rules of 1031 multi-reference simple types, the containing element of the string 1032 value MAY have an ID attribute; additional accessor elements MAY 1033 then have matching href attributes. 1035 For example, two accessors to the same string could appear, as 1036 follows: 1038 Hello 1039 1041 However, if the fact that both accessors reference the same instance 1042 of the string is immaterial, they may be encoded as though single- 1043 reference, as follows: 1045 Hello 1046 Hello 1048 8.2.2. Enums 1050 An enum is a single reference type whose value is encoded as one of 1051 the possible enumeration strings. In the following example EyeColor 1052 is an enum with the possible values of "Green", "Blue", and "Brown": 1054 1055 Henry Ford 1056 32 1057 Brown 1058 1060 8.2.3. Array of Bytes 1062 An array of bytes is encoded as a multi-reference simple type. The 1063 recommended representation of an opaque array of bytes is the 1064 'bin.base64' encoding defined in XML DCD [5], which simply 1065 references the MIME standard. However, the line length restrictions 1066 that normally apply to Base64 data in MIME do not apply in SOAP. 1068 bin.base64: aG93IG5vdyBicm93biBjb3cNCg== 1070 8.3. Polymorphic Accessor 1072 Many languages allow accessors that can polymorphically access 1073 values of several types, each type being available at run-time. When 1074 the value is single-reference, the type of this kind of accessor is 1075 often called "Variant". A Polymorphic accessor MUST contain a 1076 "xsd:type" attribute that describes the type of the actual value. 1078 For example, a Polymorphic parameter named "cost" with a type of 1079 float would be encoded as follows: 1081 29.95 1083 Box, Kakivaya, et al. HTTP -- June, 2000 19 1085 SOAP: Simple Object Access Protocol November, 1999 1087 as contrasted with a cost parameter whose type is invariant, as 1088 follows: 1090 29.95 1092 8.4. Compound Types 1094 Beyond the simple types, SOAP defines support for the following 1095 constructed types: 1097 * Records/structs 1098 * arrays 1100 Where appropriate and possible, the representation in SOAP of a 1101 value of a given type mirrors that used by practitioners of XML-Data 1102 and the common practice of the XML community at large. 1104 8.4.1. Compound Values and References to Values 1106 A compound value contains an ordered sequence of structural members. 1107 When the members have distinct names, as in an instance of a C or 1108 C++ "struct", this is called a "struct," and when the members do not 1109 have distinct names but instead are known by their ordinal position, 1110 this is called an "array. 1112 The members of a compound value are encoded as accessor elements. 1113 For a struct, the accessor element name is the member name. For an 1114 array, the accessor element name is the element type name and the 1115 sequence of the accessor elements follows the ordinal sequence of 1116 the members. 1118 The following is an example of a struct of type Book: 1120 1121 Henry Ford 1122 Prefatory text 1123 This is a book. 1124 1126 Below is an example of a type with both simple and compound members. 1127 It shows two levels of referencing. 1129 Note that the "href" attribute of the Author accessor element is a 1130 reference to the value whose "id" attribute matches; a similar 1131 construction appears for the Address. 1133 1134 My Life and Work 1135 1136 1137 1138 Henry Ford 1139
1141 Box, Kakivaya, et al. HTTP -- June, 2000 20 1143 SOAP: Simple Object Access Protocol November, 1999 1145 1146
1147 henryford@hotmail.com 1148 www.henryford.com 1149
1151 The form above is appropriate when the Person value and the Address 1152 value are multi-reference. If these were instead both single- 1153 reference, they SHOULD be embedded, as follows: 1155 1156 My Life and Work 1157 1158 Henry Ford 1159
1160 henryford@hotmail.com 1161 www.henryford.com 1162
1163 1164 1166 If instead there existed a restriction that no two persons can have 1167 the same address in a given schema and that an address can be either 1168 a Street-address or an Electronic-address, a Book with two authors 1169 would be encoded in such a schema as follows: 1171 1172 My Life and Work 1173 1174 1175 1176 1177 Henry Ford 1178
1179 henryford@hotmail.com 1180 www.henryford.com 1181
1182 1183 1184 Thomas Cook 1185
1186 Martin Luther King Rd 1187 Raleigh 1188 North Carolina 1189
1190 1192 8.4.1.1. Generic Records 1194 There are cases where a struct is represented with its members named 1195 and values typed at run time. Even in these cases, the existing 1196 rules apply. Each member is encoded as an element with matching 1197 name, and each value is either contained or referenced. Contained 1199 Box, Kakivaya, et al. HTTP -- June, 2000 21 1201 SOAP: Simple Object Access Protocol November, 1999 1203 values MUST have a "xsd:type" attribute giving the type of the 1204 value. 1206 8.4.2. Arrays 1208 The representation of the value of an array is an ordered sequence 1209 of elements constituting items of the array. The default tag name 1210 for each element is the element type. 1212 As with compound types generally, if the type of an item in the 1213 array is a single-reference type, each item contains its value. 1214 Otherwise, the item references its value via an href attribute. 1216 The following example is an array containing integer array members. 1217 The length attribute is optional. 1219 1220 3 1221 4 1222 1224 The following example is an array of Variants containing an integer 1225 and a string. 1227 1228 23 1229 some string 1230 1232 The following is an example of a two-dimensional array of strings. 1234 1235 r1c1 1236 r1c2 1237 r1c3 1238 r2c1 1239 r2c2 1240 r2c3 1241 1243 The following is an example of an array of two arrays, each of which 1244 is an array of strings. 1246 1247 1248 1249 1250 1251 r1c1 1252 r1c2 1253 r1c3 1254 1255 1257 Box, Kakivaya, et al. HTTP -- June, 2000 22 1259 SOAP: Simple Object Access Protocol November, 1999 1261 r2c1 1262 r2c2 1263 1265 Finally, the following is an example of an array of phone numbers 1266 embedded in a struct of type Person and accessed through the 1267 accessor "phone-numbers": 1269 1270 John Hancock 1271 1272 111-2222 1273 999-0000 1274 1275 1277 A multi-reference array is always encoded as an independent element 1278 whose tag name is the string "ArrayOf" prepended to the element type 1279 of the array. For example an array of order structs encoded as an 1280 independent element: 1282 1283 1284 Apple 1285 1.56 1286 1287 1288 Peach 1289 1.48 1290 1291 1293 A single-reference array is encoded as an embedded element whose tag 1294 name is the accessor name. 1296 1297 Henry Ford 1298 1299 5th Ave 1300 New York 1301 NY 1302 10010 1303 1304 1305 1306 Apple 1307 1.56 1308 1309 1310 Peach 1311 1.48 1312 1313 1315 Box, Kakivaya, et al. HTTP -- June, 2000 23 1317 SOAP: Simple Object Access Protocol November, 1999 1319 1321 8.4.2.1. Partially transmitted arrays 1323 SOAP provides support for partially transmitted arrays, known as 1324 "varying" arrays, in some contexts [7]. A partially transmitted 1325 array indicates in an "offset" attribute the zero-origin index of 1326 the first element transmitted; if omitted, the offset is taken as 1327 zero. 1329 The following is an example of an array of size five that transmits 1330 only the third and fourth element: 1332 1333 The third element 1334 The fourth element 1335 1337 8.4.2.2. Sparse Arrays 1339 SOAP provides support for sparse arrays in some contexts. Each 1340 element contains a "position" attribute that indicates its position 1341 within the array. The following is an example of array of arrays of 1342 strings: 1344 1345 1346 1348 1349 The third element" 1350 The eighth element 1351 1353 Assuming that the only reference to array-1 occurs in the enclosing 1354 array, this example could also have been encoded as follows: 1356 1357 1358 1359 The third element" 1360 The eighth element 1361 1362 1363 1365 8.5. Default Values 1367 An omitted accessor element implies either a default value or that 1368 no value is known. The specifics depend on the accessor, method, and 1369 its context. Typically, an omitted accessor implies a Null value for 1370 Variant and for polymorphic accessors (with the exact meaning of 1371 Null accessor-dependent). Typically, an omitted Boolean accessor 1373 Box, Kakivaya, et al. HTTP -- June, 2000 24 1375 SOAP: Simple Object Access Protocol November, 1999 1377 implies either a False value or that no value is known, and an 1378 omitted numeric accessor implies either that the value is zero or 1379 that no value is known. 1381 9. Formal Syntax 1383 This specification uses the augmented Backus-Naur Form (BNF) as 1384 described in RFC-2234 [10]. 1386 10. Security Considerations 1388 Not described in this document are methods for integrity and privacy 1389 protection. Such issues will be addressed more fully in a future 1390 version(s) of this document. 1392 11. References 1394 [1] RFC2068: Hypertext Transfer Protocol, 1395 http://info.internet.isi.edu/in-notes/rfc/files/rfc2068.txt. Also: 1396 http://www.w3.org/Protocols/History.html. 1397 [2] HTTP Extension Framework, 1398 http://www.w3.org/Protocols/HTTP/ietf-http-ext. 1399 [3] The XML Specification, http://www.w3.org/TR/WD-xml-lang. 1400 [4] XML-Data Specification, http://www.w3.org/TR/1998/NOTE-XML- 1401 data. 1402 [5] Document Content Description for XML, 1403 http://www.w3.ort/TR/NOTE-dcd. 1404 [6] Namespaces in XML, http://www.w3.org/TR/REC-xml-names. 1405 [7] Transfer Syntax NDR, in "DCE 1.1: Remote Procedure Call," 1406 http://www.rdg.opengroup.org/onlinepubs/9629399/toc.htm. 1407 [8] RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax 1408 and Semantics, http://www.ietf.org/rfc/rfc2396.txt. 1409 [9] XML Linking Language, http://www.w3.org/1999/07/WD-xlink- 1410 19990726. 1411 [10] RFC-2234: Augmented BNF for Syntax Specifications: ABNF 1412 [11] Bradner, S., "Key words for use in RFCs to Indicate Requirement 1413 Levels", BCP 14, RFC 2119, March 1997 1414 [12] XML Schema Part 2: Datatypes, http://www.w3.org/TR/1999/WD- 1415 xmlschema-2-19991105/ 1416 [13] RFC2026: The Internet Standards Process -- Revision 3, 1417 http://info.internet.isi.edu/in-notes/rfc/files/rfc2026.txt. 1419 12. Author's Addresses 1421 Don Box 1422 DevelopMentor 1423 21535 Hawthorne Blvd., Fourth Floor 1424 Torrance, CA 90503 1425 Email: dbox@develop.com 1427 Gopal Kavivaya 1428 Microsoft 1429 One Microsoft Way 1431 Box, Kakivaya, et al. HTTP -- June, 2000 25 1433 SOAP: Simple Object Access Protocol November, 1999 1435 Redmond, WA 98052 1436 Email: gopalk@microsoft.com 1438 Andrew Layman 1439 Microsoft 1440 One Microsoft Way 1441 Redmond, WA 98052 1442 Email: andrewl@microsoft.com 1444 Satish Thatte 1445 Microsoft 1446 One Microsoft Way 1447 Redmond, WA 98052 1448 Email: satisht@microsoft.com 1450 Dave Winer 1451 UserLand Software, Inc. 1452 P.O. Box 1218 1453 Burlingame, CA 94011-1218 1454 Email: dave@userland.com 1456 Box, Kakivaya, et al. HTTP -- June, 2000 26 1458 SOAP: Simple Object Access Protocol November, 1999 1460 Full Copyright Statement 1462 "Copyright (C) The Internet Society (date). All Rights Reserved. 1463 This document and translations of it may be copied and furnished to 1464 others, and derivative works that comment on or otherwise explain it 1465 or assist in its implmentation may be prepared, copied, published 1466 and distributed, in whole or in part, without restriction of any 1467 kind, provided that the above copyright notice and this paragraph 1468 are included on all such copies and derivative works. However, this 1469 document itself may not be modified in any way, such as by removing 1470 the copyright notice or references to the Internet Society or other 1471 Internet organizations, except as needed for the purpose of 1472 developing Internet standards in which case the procedures for 1473 copyrights defined in the Internet Standards process must be 1474 followed, or as required to translate it into. 1476 Box, Kakivaya, et al. HTTP -- June, 2000 27