INTERNET-DRAFT A. Megacz draft-megacz-xmc-01.txt The XWT Foundation Category: Informational 01 Sep 2002 Expires: February 2003 XML Method Call (XMC) ** DRAFT ** Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. This Internet-Draft will expire on October 22, 2002. Copyright Notice Copyright (C) The Internet Society 2002. All Rights Reserved. Abstract This memo describes the XML Method Call (XMC) protocol. XMC a simple presentation layer protocol for network transactions with method call semantics and payloads consisting of small object trees. XMC specifies the request and response protocol, an XML representation for the object trees, and a tree-encoding for graphs. XMC is forward and backward compatible with XML-RPC [1]. XMC clients can make calls to XML-RPC servers, and XML-RPC clients can make calls to XMC servers. 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. Table of Contents 1. Introduction 2. Implementation Requirements 3. Relationship to XML-RPC 4. XMC values 4.1 Simple Types 4.1.1 boolean 4.1.2 int 4.1.3 string 4.1.4 unicode 4.1.5 double 4.1.6 dateTime.iso8601 4.1.7 base64 4.2 Aggregate Types 4.2.1 array 4.2.2 struct 5. XMC Requests 6. XMC Responses 6.1 Successful Response 6.2 Fault Response 7. Graph Encoding 8. Session Layer Bindings 8.1 HTTP 8.2 HTTPS 8.3 SMTP 8.4 Jabber 1. Introduction XMC is a presentation layer protocol for network transactions with method call semantics. Each transaction consists of a single request sent in its entirity by the client, followed by a single response sent in its entirity by the server. Both the request and the response consist of object trees built from a small set of primitive types. The object trees are encoded in XML, providing an easily human-readable wire format which aids debugging. A standardized mapping from graphs to trees is provided for applications which need to encode multi-reference data. XMC assumes that the request and response are each small enough to be held entirely in main memory before being passed up to the application layer. 2. Relationship to XML-RPC XMC is forward and backward compatible with Dave Winer's XML-RPC [1] protocol. Because UserLand Software, Inc. holds trademark rights on the name "XML-RPC", XMC is not XML-RPC, although it is fully compatible with it. XMC is stricter than XML-RPC in two areas: - The order of a 's child elements is mandated. - XMC's behavior is undefined when recieving characters other than 0x09, 0x0A, 0x0D, and 0x20-0x7F in a or element, in order to ensure that all XMC requests and replies are valid XML. Unlike XML-RPC, XMC is defined independently of any particular session layer protocol. Bindings for HTTP, SMTP, and Jabber are included in this document; other bindings may be defined in future RFCs. The SMTP Binding described in section 8.2 is derived from and compatible with the "XML-RPC via SMTP" specification [2] published by Eric Soroos. The Jabber Binding described in section 8.3 is derived from and compatible with JEP-0009 [3] published by DJ Adams. 3. Implementation Requirements XMC implementations SHOULD use an XML parser compliant with the XML 1.0 specification [5]. XMC implementations MUST NOT assume that their peers are using a compliant parser. The behavior of an XMC implementation is undefined when recieving the following: - Characters in a CDATA section other than 0x09 (tab), 0x0A (LF), 0x0D (CR), and 0x20-0xFF (inclusive). Octets in the range 0x80-0xFF may only occur in the CDATA section of elements. - Character and entity references other than "<" and "&". - sections. - XML attributes, comments, and namespaces. - XML processing directives other than those explicitly required by this document. Any transmission of these constructs is outside this specification and may be used only by private agreement between endpoints. 4. XMC Values An XMC value is a single node in an object tree. Each value belongs to a type, which can be either simple or aggregate. An XMC value is encoded in XML as a element with a single child element, except in the case of string values. The tag name and content of that child element is determined by the value's type. 4.1 Simple Types XMC values are of one of six simple types: boolean, int, string, double, dateTime.iso8601, and base64. 4.1.1 boolean A boolean is either true or false. The true value is encoded as "1" and the false value is encoded as "0". Whitespace is not permitted. Example: 1 4.1.2 int An int is a signed integer between 1 - 2^31 and 2^31. It is encoded as an optional '+' or '-' character followed by one or more digits in the range 0-9. Leading zeroes are not permitted. Whitespace is not permitted. The type name "i4" can be used interchangeably with "int". Example: +3313 4.1.3 string A string is encoded as a sequence of CDATA characters subject to the restrictions in section 3. Example: fooBaz As a special exception for compatability with XML-RPC, XMC implementations which recieve a element with character content should assume that the character content represents a value of type string. XMC implementations MUST NOT send values encoded this way. Example: fooBaz 4.1.4 unicode A unicode value is a sequence of unicode characters least one of which is 0x0080 or greater. The characters must be encoded into octets using UTF-8. Character sequences which do not contain any non-ASCII characters should be sent as a string value. Not all implementations support unicode strings. An XMC server which does not support unicode strings MUST return a fault if it recieves a unicode value. An XMC client which does not support unicode strings MUST NOT propagate any part of the request to the application layer if it recieves a unicode value. 4.1.5 double A double is a real number. It is encoded as an optional '+' or '-' character followed by zero or more digits in the range 0-9, followed by a mandatory period '.', followed by zero or more digits in the range 0-9. Leading zeroes are not permitted. Whitespace is not permitted. There is no mechanism for representing NaN, positive infinity, or negative infinity as a double. There is no bound on the precision of double values; implementations recieving a double may truncate or round the double if they cannot represent it at the level of precision provided. Example: +.123 4.1.6 dateTime.iso8601 A dateTime.iso8601 is an instant in time. It is encoded with the following format YYYYMMDDTHH:mm:SS where YYYY is the four digit year, MM is the two digit month, DD is the two digit day of the month, T is the literal character 'T', HH is the two digit time (0-23), : is the literal character ':', mm is the two digit minute (00-59), SS is the two digit second (00-59). Implementations MUST assume that the timezone is UTC unless server-specific documentation explicitly states otherwise. Whitespace is not permitted. The identifier "dateTime.iso8601" is used for compatability with XML-RPC; the format used is not actually found in ISO 8601 [4]. Example: 19711103T16:20:00 4.1.7 base64 A base64 is a sequence of octets. It is encoded using Base64, as defined in Section 6.8 of RFC 2045 [6]. Although RFC 2045 limits lines to no more than 76 characters, XMC implementations MUST correctly decode lines of any length for compatability with XML-RPC. XMC implementations SHOULD NOT send lines longer than 76 characters. Example: d293LCB5b3UgbXVzdCByZWFsbHkgYmUgYm9yZWQK 4.2 Aggregate Types 4.2.1 array An array is a sequence of values whose order is significant. An array is encoded as an element with exactly one child element, . The element contains zero or more encoded XMC values. Example: 0 43 Festering Concrete 4.2.2 struct A struct is a set of key-value pairs. The order of the pairs is not significant, and implementations may reorder the pairs. A struct is encoded as a element with zero or more child elements. Each element has exactly two child elements. The first child element is , whose CDATA content is the key, subject to the restrictions in section 3. The second child element is an encoded XMC value, which constitutes the value of the pair. Example: Atomic mass of various elements Hydrogen 1.008 Helium 4.003 5. XMC Requests An XMC Request is a well-formed XML document. Example: airline.priceAirlineTicket SFO PIT 1729 1 An XMC Request begins with an XML processing directive indicating only the XML version being used. This directive is followed by a single element. The element has exactly two child elements: a single element and a single element. To ensure compatability, the element is mandatory in XMC, even if the method takes no parameters. The element's content is the name of the method to be invoked on the server. The string may only contain the following ASCII characters: A-Z, a-z, 0-9, underscore, period, colon, and forward slash. All method names beginning with the seven-character sequence "system." are reserved for use as well-known methods with the same semantics on every server; all other method names are server-specific. The element contains zero or more elements, each of which represents a single argument to the method being invoked. Each element has exactly one child element, which must be an encoded XMC value. 6. XMC Responses Just like an XMC request, an XMC response begins with an XML processing directive indicating the XML version in use. The processing directive is followed by a element. The element must have exactly one child element, which is a element if the call was successful, or a element if the call faulted. 6.1 Successful Response An XMC Successful Response is sent if the requested method executed successfully. Example: 22.01 The element must have exactly one child element, . The element must contain a single XMC value, which represents the result of the method call. 6.2 Fault Response An XMC Fault Response is sent if the server was unable to decode the XMC Request, the method requested could not be invoked, or the method invoked wishes to signal an error condition. Example: faultCode 102 faultString No such airport. The element contains an encoded XMC value, which must be a struct. The struct must have two members, named "faultCode" and "faultString". The "faultCode" member's value must be an int. The value should represent a machine-readable description of the error encountered. The meaning of this int is server-specific. The "faultString" member's value must be a string. The value should be a description of the error, suitable for presentation to a human. 7. Graph Encoding Some applications, particluarly XMC-to-SOAP and SOAP-to-XMC gateways, will need to encode data structures containing null references or more than one reference to a given value. XMC Graph Encoding provides a simple mapping from graphs to trees so that these data structures can be sent via XMC. Graph Encoding is implemented as a layer above XMC so that clients using older toolkits and clients which cannot natively represent multi-reference data can manipulate and transfer the data in its tree-encoded form. Example: a struct with one member (my_array) which is a two-element array. The first element in the array is the string "/startswithaslash". The second element of the array is a reference to the first element in the array. my_array //startswithaslash /my_array/0 To encode a graph as an XMC value tree: - Prepend an additional slash (0x2F) to the beginning of all string values that begin with a slash. - Encode null references as an XMC string representing the six-character sequence "/null/". - Encode one of the references to each value as the value itself, and all others as an XMC string containing the path to the value. The path to the root value is encoded as a single slash. The path to any other value is the concatenation of steps along the path to that value from the root of the tree. - A step from an array to one of its elements is encoded as a slash followed by a decimal integer indicating the index in the array to follow. The index of the first element is zero. - A step from a struct to one of its members is encoded as a slash followed by the contents of the element of the member, with each ocurrence of the slash character replaced with the four-character sequence "_//_". 8. Session Layer Bindings 8.1 HTTP The XMC HTTP binding is compatible with XML-RPC. To make an XMC call over HTTP, the client should send an HTTP POST request to the server. The URI used is server-specific, although it is typical for XML-RPC servers to use "/RPC2" and XMC servers to use "/XMC". Servers MAY assign semantic meaning to the URI. The request MUST have the following headers, although it may have others: User-Agent: Host: Content-Length: Content-Type: text/xml The payload of the HTTP POST request is the XMC request. The HTTP reply should return code 200 for successes and faults unless an error occurred at or below the session layer. An HTTP authentication [8] failure is considered a session layer error, and MUST result in a return code of 401. The response must include the following headers, although it may include others as well: Content-Length: Content-Type: text/xml The payload of the HTTP response is the XMC response. 8.2 HTTPS The HTTPS binding is identical to the HTTP binding, except that HTTPS [9] is used as the session layer. 8.3 SMTP Both the request and response are sent as RFC 2822 messages, each of which MUST have, at a minimum, the following headers: To: Subject: From: Date: Message-Id: Mime-Version: 1.0 Content-Type: text/xml The request and response SHOULD also include the X-Mailer header. The values of the To: and Subject: headers in the request message are specified by the server and may be used to route or filter calls. The body of the message sent by the client is the XMC request. The value of the To: header in the response message must match the value of the From: header in the request message. If the client included an X-XMC-Response-Subject header, its value is used as the value of the Subject header of the response message; otherwise the response Subject is the same as the request subject, prepended with the four characters "Re: ". The body of the message sent by the server is the XMC response. All other headers in the request and response may have any value consistent with RFC 2822. 8.4 Jabber An XMC request is sent over Jabber [7] as an element of type "set". The "iq" element must have exactly one child element, , whose namespace is "jabber:iq:rpc". The element must have exactly one child element, which is the element of the XMC request. Example: ... An XMC response is sent as an element of type "result". The "iq" element must have exactly one child element, , whose namespace is "jabber:iq:rpc". The element must have exactly one child element, which is the element of the XMC response. Example: ... Session layer errors are indicated in the normal way for elements -- by an element of type "error". Informative References [1] Winer, Dave, "XML-RPC Specification", http://www.xmlrpc.org/spec , June 1999. [2] Soroos, Eric, "XML-RPC via SMTP", http://www.wiredfool.com/discuss/msgReader$117 , April 2000. [3] Adams, DJ. "JEP-0009: Transporting XML-RPC over Jabber", JEP-0009, September 2001. [4] International Standard ISO 8601 Normative References [5] Bray, Paoli, Sperberg-McQueen, and Maler, "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C Recommendation, 6 October 2000. [6] Freed, Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996. [7] Miller, "Jabber", http://hades.jabber.org/ietf/draft-miller-jabber-00.html, Work in Progress [8] Franks, Hallam-Baker, Hostetler, Lawrence, Leach, Stewart, and Luotonen, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2167, June 1999. [9] E. Rescorla, "HTTP Over TLS", RFC 2818, May 2000. Author's Address Adam Megacz The XWT Foundation EMail: adam@xwt.org Full Copyright Statement Copyright (C) The Internet Society (2002). 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 implementation 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 languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgements Dave Winer designed XML-RPC, which XMC is based upon. P. Oscar Boykin contributed the wording for the first three paragraphs of section 4.1.6. Wording for section 3 was taken from Jay Carlson's lcdXML-RPC recommendation. Funding for the RFC Editor function is currently provided by the Internet Society.