CALSCH Working Group Surendra Reddy Internet Draft Oracle Corporation draft-reddy-scap-00.txt April 27, 1998 Expires October 27, 1998 Web based Simple Calendar Access Protocol - SCAP Status of this Memo This document is an Internet-Draft. Internet-Drafts are working docu- ments of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute work- ing documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or made obsolete 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". To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Please send comments to the CALSCH working group at ietf-calendar@imc.org, which may be joined by sending a message with subject "subscribe" to ietf- calendar-request@imc.org. Abstract Distributed calendaring is gradually becoming more demanding than standalone calendaring and scheduling. The use of calendaring and scheduling has grown exponentially and enterprise and inter- enterprise business has become so dependent on group scheudling applications. But there is no Internet standard to provide interoperability among various calendaring applications. Consequently, user need to install different conduit programs to access these calendaring stores. This memo proposes a HTTP based simple calendaring access protocol which allows web, email and any HTTP compliant clients to access and manipulate calendar store. The motivation for this proposal is the expanded scope and diversity of the World Wide Web. The World Wide Web provides a simple and effective means for users to search, browse, retrieve, and publish Surendra Reddy [Page 1] draft-ietf-calsch-scap-00.txt April 1998 information of their own available for others. Now that Web browsers and servers are ubiquitous on the Internet, it is worthwhile to use HTTP as transport protocol and XML to encode calendar objects. The power and extensibility of XML allows us to represent calendar data objects as well-formed XML documents. Simple Calendar Access Protocol(SCAP) allows exchanging calendaring information between scheduling systems using the Hypertext Transfer Protocol (HTTP). This allows users to schedule meetings with anyone else, no matter what scheduling software they use. This document specifies a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of calender properties, creation and management of calendar objects, and namespace manipulation. Table of Contents i. Status of this Memo .......................................... 1 ii. Abstract .................................................... 1 1. Introduction ................................................ 4 2. Notational Conventions ...................................... 4 3. Calendar Object Model ....................................... 5 3.1 The Calendar Property Model ............................. 5 3.2 Property Values ......................................... 5 3.3 Property Names .......................................... 5 3.4 Calendar Names and User Names ........................... 5 4. HTTP Methods of Calendar Access ............................. 5 4.1 CSOP Method ............................................. 6 4.1.1 Create Calendar Store ............................. 6 4.1.2 Example: Create Calendar Store .................... 6 4.1.3 Example - Select Calendar Store ................... 7 4.1.4 Delete Calendar Store ............................. 8 4.1.5 Example: Delete Calendar Store .................... 8 4.1.6 Copy and Move Calendar Stores ..................... 9 4.1.7 Example: Rename Calendar Store .................... 9 4.1.8 List Calendar Store ............................... 10 4.1.9 Examples: List Calendar Store ..................... 10 4.1.10 Set Calendar View by Range ....................... 11 4.1.11 Example: Calendar View by Range .................. 11 4.2 MKCSOBJ ................................................. 12 4.2.1 Examples: ........................................ 12 4.3 CSPROP Method ........................................... 13 4.3.1 Example:Get Freebusy time ......................... 14 5. Calendar XML Element Definitions ............................ 15 5.1 Calendar Message ........................................ 15 5.2 vevent XML element ...................................... 16 Surendra Reddy [Page 2] draft-ietf-calsch-scap-00.txt April 1998 5.2.1 Example: vevent ................................... 16 5.3 vtodo XML element ....................................... 17 5.3.1 Example: vtodo .................................... 18 5.4 vjournal XML element ................................... 18 5.4.1 Example: vjournal ................................ 19 5.5 vfreebusy XML element ................................... 19 5.5.1 Example: vfreebusy ................................ 20 5.5 vtimezone XML element ................................... 21 5.6.1 Example: vtimezone ................................ 22 5.6 valarm XML element ...................................... 23 5.6.1 Example: valarm ................................... 24 6. Calendar Properties ......................................... 25 6.1 attach Property ......................................... 25 6.2 categories Property ..................................... 26 6.3 class Property .......................................... 26 6.4 comment Property ........................................ 26 6.5 description Property .................................... 27 6.6 location Property ....................................... 27 6.7 percentcomplete Property ................................ 27 6.8 priority Property ....................................... 28 6.9 resources Property ...................................... 28 6.10 status Property ........................................ 28 6.11 summary Property ....................................... 29 6.12 completed property ..................................... 29 6.13 dtend Property ......................................... 29 6.14 due Property ........................................... 30 6.15 dtstart Property ....................................... 30 6.16 duration Property ...................................... 31 6.17 freebusy Property ...................................... 31 6.18 attendee Property ...................................... 32 6.19 contact Property ....................................... 33 6.20 organizer Property ..................................... 33 6.21 recurid Property ....................................... 34 6.22 relatedto Property ..................................... 35 6.23 url property ........................................... 35 6.24 uid Property ........................................... 35 6.25 exdate Property ........................................ 36 6.26 exrule Property ........................................ 36 6.27 rdate Property ......................................... 36 6.28 rrule Property ......................................... 37 6.29 trigger Property ....................................... 37 6.30 created Property ....................................... 38 6.31 dtstamp Property ....................................... 38 6.32 lastmodified Property .................................. 38 6.33 sequence Property ...................................... 39 6.34 requeststatus Property ................................. 39 7. Security Considerations ..................................... 40 8. Calendar Object Specification - XML DTD ..................... 40 Surendra Reddy [Page 3] draft-ietf-calsch-scap-00.txt April 1998 8. References .................................................. 44 9. Author's Address ............................................ 45 1. Introduction This document describes an extension to the HTTP/1.1 protocol that allows clients to perform remote calendaring operations. This extension provides a coherent set of methods, headers, request entity body formats, and response entity body formats that provide operations for: Properties: The ability to create, remove, and query information about Calendar resources, such as their freetime, todo etc. Namespace Operations: The ability to instruct the server to copy and move calendar objects. SCAP, encodes method parameter information either in an Extensible Markup Language (XML) [Bray, Paoli, Sperberg-McQueen, 1998] request entity body, or in an HTTP header. The use of XML to encode method parameters was motivated by the ability to add extra XML elements to existing structures, providing extensibility, and by XML's ability to encode information in ISO 10646 character sets, providing internationalization support. As a rule of thumb, parameters are encoded in XML entity bodies when they have unbounded length, or when they may be shown to a human user and hence require encoding in an ISO 10646 character set. Otherwise, parameters are encoded within HTTP headers. In addition to encoding method parameters, XML is used in SCAP to encode the responses from methods, providing the extensibility and internationalization advantages of XML for method output, as well as input. 2. Notational Conventions Since this document describes a set of extensions to the HTTP/1.1 protocol, the augmented BNF used herein to describe protocol elements is exactly the same as described in section 2.1 of [Fielding et al., 1997]. Since this augmented BNF uses the basic production rules provided in section 2.2 of [Fielding et al., 1997], these rules apply to this document as well. 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 [Bradner, 1997]. Surendra Reddy [Page 4] draft-ietf-calsch-scap-00.txt April 1998 3. Calendar Object Model 3.1. The Calendar Property Model Properties are pieces of data that describe the state of Calendar objects. Properties are data about data. [Refer iCalendar] The SCAP property model consists of name/value pairs. The name of a property identifies the property's syntax and semantics, and provides an address by which to refer to its syntax and semantics. 3.2. Property Values The value of a property is, at minimum, well formed XML. XML has been chosen because it is a flexible, self-describing, structured data format that supports rich schema definitions, and because of its support for multiple character sets. XML's self- describing nature allows any property's value to be extended by adding new elements. Older clients will not break when they encounter extensions because they will still have the data specified in the original schema and will ignore elements they do not understand. XML's support for multiple character sets allows any human-readable property to be encoded and read in a character set familiar to the user. 3.3. Property Names A property name is a universally unique identifier that is associated with a schema that provides information about the syntax and semantics of the property. Because a property's name is universally unique, clients can depend upon consistent behavior for a particular property across multiple resources, so long as that property is "live" on the resources in question. The XML namespace mechanism, which is based on URIs, is used to name properties because it prevents namespace collisions and provides for varying degrees of administrative control. 3.4. Calendar Names and User Names The name parameter can be the name of a Calendar and optionally a user name. 4. HTTP Methods of Calendar Access The following new HTTP methods use XML as a request and response format. All SCAP compliant clients and resources MUST use XML parsers that are complaint with [Bray, Paoli, Sperberg-McQueen, Surendra Reddy [Page 5] draft-ietf-calsch-scap-00.txt April 1998 1998]. All XML used in either requests or responses MUST be, at minimum, well formed. If a server receives ill-formed XML in a request it MUST reject the entire request with a 400 Bad Request. If a client receives ill-formed XML in response then it SHOULD treat the server as malfunctioning. 4.1. CSOP Method The Calendar Store Operation(CSOP) method processes instructions specified in the request body. All SCAP compliant servers MUST support CSOP and MUST process instructions that are specified using csoperation XML element of SCAP schema. The request message body of a CSOP MUST contain at least one csoperation XML element. A client MUST submit csoperation XML element in the body of the request method decribing what action is being requested on the Request-URI. All SCAP complaiance servers MUST support returing a response of content type text/xml that contains a multistatus XML element that describes the results of the attempts to perform the various actions. If any requested operation is resulted in an error then the error result MUST be included in the response XML element. 4.1.1. Create Calendar Store Creates a new Calendar store with the given name. Calendar store names must begin with an alphabetic character and consist of alphanumeric characters. Calendar names are not case sensitive. It is illegal to create more than one Calendar store with the same name. "create" does not automatically select the Calendar store created. SCAP servers are NOT required to support hierarchical names. If a client attempts to create a Calendar Store with a hierarchical name on a server which does not support hierarchical names, the server MUST return an error response of to the "create" action request. If the Calendar name is suffixed with the hierarchy separator "/", this is a declaration that the client intends to create Calendar names under this name in the hierarchy. Server implementations that do not require this declaration MUST ignore it. 4.1.2. Example: Create Calendar Store >>Request CSOP HTTP/1.1 Surendra Reddy [Page 6] draft-ietf-calsch-scap-00.txt April 1998 HOST: www.foo.com Content-Type: text/xml Content-Length: xxxx Projects/ Projects >>Response HTTP/1.1 207 MULTI-STATUS Content-Type: text/xml Content-Length: xxxx HTTP/1.1 415 Unsupported HTTP/1.1 201 OK The above example creates two Calendar stores for the default user. First operation failed as creating hierarchical Calendar store is not supported, hence server responded with a response code 415. 4.2. Example - Select Calendar Store >>Request CSOP HTTP/1.1 HOST: www.foo.com Content-Type: text/xml Content-Length: xxxx Bob