Internet DRAFT - draft-ietf-calsch-scap
draft-ietf-calsch-scap
HTTP/1.1 200 OK
Date: Tue, 09 Apr 2002 01:26:52 GMT
Server: Apache/1.3.20 (Unix)
Last-Modified: Wed, 29 Apr 1998 01:33:00 GMT
ETag: "2ed5b7-1628a-3546834c"
Accept-Ranges: bytes
Content-Length: 90762
Connection: close
Content-Type: text/plain
CALSCH Working Group Surendra Reddy
Internet Draft Oracle Corporation
draft-ietf-calsch-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
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as = "C"?>
<C:csoperation>
<create>Projects/</create>
<create>Projects</create>
</C:csoperation>
>>Response
HTTP/1.1 207 MULTI-STATUS
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:multistatus>
<respone status="415" action="create" >
HTTP/1.1 415 Unsupported
</response>
<response status="201"action="create" >
HTTP/1.1 201 OK
</response>
</C:multistatus>
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
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as = "C"?>
<C:csoperation>
<select/>
<select>Bob</select>
<select><Sally</select>
</C:csoperation>
Surendra Reddy [Page 7]
draft-ietf-calsch-scap-00.txt April 1998
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:multistatus>
<response status="201" store="Bob">
HTTP/1.1 424 Method Failure
</response>
<response status="201" store="Sally">
HTTP/1.1 424 Method Failure
</response>
</C:multistatus>
This sequence uses multiple SELECT commands to open the current
user's default Calendar store plus the default Calendar stores of Bob
and Sally.
4.3. Delete Calendar Store
Deletes the Calendar store with the given name. If this command is
given from the Selected state, a currently selected Calendar cannot
be deleted.
4.3.1. Example: Delete Calendar Store
>>Request
CSOP HTTP/1.1
HOST: www.foo.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as = "C"?>
<C:csoperation>
<delete>Projects</delete>
<delete>Purple/</delete>
</C:csoperation>
>>Response
HTTP/1.1 207 MULTI-STATUS
Content-Type: text/xml
Content-Length: xxxx
Surendra Reddy [Page 8]
draft-ietf-calsch-scap-00.txt April 1998
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:multistatus>
<respone status="201" action="delete" >
HTTP/1.1 2O1 OK
</response>
<response status="415"action="delete" >
HTTP/1.1 415 Unsupported
</response>
</C:multistatus>
4.4. Copy and Move Calendar Stores
"copy" action transfer a given set of Objects to a different
Calendar store.
The "rename" action changes the name of a Calendar store. It is an
error to attempt to rename from a Calendar name that does not exist
or to a Calendar name that already exists and it MUST be responded
to the client.
If the hierarchy separator character appears in the new Calendar
store name, the server SHOULD return an error response to the
client. No actions MUST be performed on the Calendar Store.
The Calendar store to "rename" or "copy" to MUST exist before the
operation is initiated.
4.4.1. Example: Rename Calendar Store
>>Request
CSOP HTTP/1.1
HOST: www.foo.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as = "C"?>
<C:csoperation>
<rename from ="Projects" to="ProjectScap"/>
<rename from ="Purple" to="ProjectScap/PurpleScap/" />
</C:csoperation>
>>Response
Surendra Reddy [Page 9]
draft-ietf-calsch-scap-00.txt April 1998
HTTP/1.1 207 MULTI-STATUS
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:multistatus>
<respone status="201" action="rename" >
HTTP/1.1 2O1 OK
</response>
<response status="415"action="rename" >
HTTP/1.1 415 Unsupported
</response>
</C:multistatus>
4.5. List Calendar Store
The "list" action returns listresp XML for each Calendar store that
matches the given reference and store name. The "*" character is a
wildcard and can be used to matche any length string of valid
Calendar Store name characters.
The SCAP complaince servers must hide all Calendar stores that the
current user does not have access to.
These reference names should be interpreted in the following manner:
allstores XML element - lists all top level Calendar stores
accessible
to the current user. allusers XML element - list all
users accessible by the server curuser XML element - lists the
currently authenticated user
4.5.1. Examples: List Calendar Store
>>Request
CSOP HTTP/1.1
HOST: www.foo.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as = "C"?>
<C:csoperation>
Surendra Reddy [Page 10]
draft-ietf-calsch-scap-00.txt April 1998
<list><allstores/></list>
</C:csoperation>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:multistatus>
<listresp type="STORES"> skreddy </listresp>
<listresp type="STORES"> oracle </listresp>
<listresp type="STORES"> nobody </listresp>
</C:multistatus>
4.6. Set Calendar View by Range
The "range" action sets a date/time range for the currently selected
Calendars and returns a response with the number of items in the
range.
Either the start time(dtstart) or end time(dtend) can be replaced
with the wildcard character "*" in which case lower or upper bound,
respectively, is placed on the current date range.
The start time given must be included in the range. The end time
given must be excluded from the range.
If any Object in the selected Calendar store contains a set of
recurrence rules that resolve to dates within the specified date
range, then that Object MUST appear once for each date resolved
within the specified range. In other words, an Object may count for
more than one Object in the response returned by the "range" action
if it is a recurring Object.
4.6.1. Example:
>>Request
CSOP HTTP/1.1
HOST: www.foo.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as = "C"?>
Surendra Reddy [Page 11]
draft-ietf-calsch-scap-00.txt April 1998
<C:csoperation>
<range>
<dtstart>19971230T0900-0500</dtstart>
<dtend>19971230T1700-0500</dtend>
</C:csoperation>
>>Response
HTTP/1.1 207 Multi-Status
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:multistatus>
<rangeresp>9</rangeresp>
</C:multistatus>
4.7. MKCSOBJ
The MKCSOBJ method creates a new Calendar Object in the Calendar
Store identified by the Request-URI. If the Calendar Store
identified by the Request-URI does not exist, the server must return
an error response with status codei 424.
New Calendar Objects added to a Calendar store with the MKCSOBJ
command MUST contain all required iCalendar properties specified in
well formed XML request body. If a required property is missing the
server MUST return a response and MUST not modify any of the
specified Calendar stores.
If a Calendar Object has been created on the Request-URI Calendar
Store, the response SHOULD be 201(Created) and contain a response
XML element which describes the status of the request.
4.7.1. Examples:
>>Request
MKCSOBJ Personal_Calendar HTTP/1.1
HOST: www.foo.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as = "C"?>
<C:vcalendar version="2.0"> <C:VEVENT>
Surendra Reddy [Page 12]
draft-ietf-calsch-scap-00.txt April 1998
<C:DTSTART>19970606T140000-0800</DTSTART>
<C:DTEND>19970606T150000-0800</DTEND>
<C:DESCRIPTION>Meeting with Pete.</DTEND>
<C:VEVENT>
</C:VCALENDAR> >>Response
HTTP/1.1 207 MULTI-STATUS
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:multistatus> <respone status="201"
action="mkcsobj" > HTTP/1.1 2O1 OK </response>
</C:multistatus>
4.8. CSPROP Method
The CSPROP method returns information requested by the csprop XML
element as a request body on the Calendar Store specified by the
Request-URI.
The CSPROP method currently supports the XML request bodies to
retrive the various Calendar Store properties.
getcsid The unique identifier of this Calendar store.
getcomponents An iCalendar object
gettimezone An iCalendar object containing a TIMEZONE Component
getfreebusy Get freebusy time for the specified "resource"
fetch Fecthes the specifies properites from the Calendar
Store
store Update the Calendar Objects specfied by the vcalendar
XML request body in the calendar store specified by
the Request-URI.
search Searches the Calendar store for given properties.
The "getcomponents" XML element can be used by a client to determine
which Calendar Components that can be stored within a Calendar
Store, along with the names and types of the properties of those
Calendar Components. The server MUST return an iCalendar object
which contains a "model" of all the Components the Calendar Store
supports. The "model" Components MUST contain all of the properties
that the Component can store. The Properties should specify a VALUE
property parameter that identifies the data-type of the property. The
property value MUST be an null string.
The server does not have to return a TIMEZONE Component to
Surendra Reddy [Page 13]
draft-ietf-calsch-scap-00.txt April 1998
indicate that this Component is supported. The server MUST return an
ALARM Component if this Component is supported.
The "getfreebusy" action searches the currently selected Calendars,
bounded by a start and end time, and returns a list of intervals during
which an event of the given length of time can be scheduled.
The "fetch" action fetches all the specified calendar Objects from the
Calendar store specified by the Request-URI.
Note that items returned by "fetch" action should always be returned in
ascending chronological order, even when multiple Calendar stores are
selected.
The "store" action updates the iCalendar data associated with this
Calendar Object. The request body must contain well formed vcalendar
XML elements and Calendar Store must be specified by Request-URI.
If there is more than one Calendar store selected in the given
selected object, then the "store" action will add the new Object to
all of the Calendar stores.
New Calendar Objects added to a Calendar store must contain all
required iCalendar properties. Updates to existing Calendar Objects
need only contain the actual data to be updated. Duplicate attributes
names are not allowed, whenever a value is given for a attribute name
that already exists, the new value replaces the old value.
The "search" action searches the Calendar store for Objects that
match the given searching criteria. Searching criteria consist of one or
more search keys. The untagged SEARCH response from the server
contains a listing of Object numbers corresponding to those Objects
that match the searching criteria.
When multiple keys are specified, the result is the intersection (AND
function) of all the messages that match those keys. A search key can
also be a parenthesized list of one or more search keys (e.g. for use
with the OR and NO keys).
4.8.0.1. Example:Get Freebusy time
>>Request
CSPROP / HTTP/1.1
HOST: www.foo.com
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
Surendra Reddy [Page 14]
draft-ietf-calsch-scap-00.txt April 1998
<?xml:namespace name="SCAP:" as = "C"?>
<getfreebusy>
<csname>Ann</csname>
<csname>Bob</csname>
<dtstart>19970930T0900-0700</dtstart>
<dtend>19970930T1700-0700</dtend>
</freebusyreq>
>>Response
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: xxxx
<?xml version="1.0"?>
<?xml:namespace name="SCAP:" as ="C"?>
<C:vcalendar version="2.0">
<vfreebusy>
<attendee>Ann</attendee>
<dtstart>19970930T0900-0700</dtstart>
<dtend>19970930T1700-0700<dtend>
<freebusy value="PERIOD-START">
19970930T1000-0700/PT1H
</freebusy>
<freebusy value="period-start">
19970930T1200-0700/PT1H
</freebusy>
</vfreebusy>
</vcalendar>
In the example above, only two busy periods were found for the given
time range: Ann is busy from 10 to 11 on 19970903 and also busy from
12 to 1 o'clock on the same day.
5. Calendar XML Element Definitions
5.1. Calendar Message
Calendar messages are [XML] documents which are sent between SCAP
client and server. the XML definition of a Calendar message is as
follows:
<!ELEMENT vcalendar ( vevent |
vtodo |
vjournal |
vfreebusy |
vtimezone )+)>
<!ATTLIST vcalendar
version PCDATA #REQUIRED
prodid PCDATA #REQUIRED >
Surendra Reddy [Page 15]
draft-ietf-calsch-scap-00.txt April 1998
5.2. vevent XML element
Name: vevent
Purpose: Provide a grouping of component properties that describe an
event.
Description: A vevent XML element is a grouping of component
properties and an OPTIONAL "valarm" XML element that represent
a scheduled amount of time on a calendar.
<!ELEMENT vevent (attach*, attendee*, categories*, class?,
comment*, contact*, created?, description?,
(dtend|duration)?, dtstart, exdate*, exrule*,
lastmodified?, location?, organizer?,
priority?, rstatus? related*, resources*,
rdate*, rrule*, dtstamp,
sequence?, status? summary, transp?, uid,
url?, recurid?)>
The "vevent" calendar component MUST include the "dtstamp", "dtstart", "summary"
And "uid" properties.`In addition, it MUST include the "sequence" property, if
It's value is greater than zero.
5.2.1. Example
The following is an example of the "vevent" calendar component used
to represent a meeting that will also be opaque to searches for busy
time:
<vevent>
<uid>19970901T130000Z-123401@host.com</uid>
<dtstamp>19970901T1300Z</dtstamp>
<dtstart>19970903T163000Z</dtstart>
<dtend>19970903T190000Z</dtend>
<summary>Annual Employee Review</summary.
<class>PRIVATE</class>
<categories><BUSINESS></categories>
<categories>HUMAN RESOURCES</categories>
</vevent>
The following is an example of the "vevent" calendar component used
to represent a reminder that will not be opaque, but rather
transparent, to searches for busy time:
<vevent>
<uid>19970901T130000Z-123402@host.com</uid>
<dtstamp>19970901T1300Z</dtstamp>
<dtstart>19970401T163000Z</dtstart>
<dtend>19970402T010000Z</dtend>
<summary>Laurel is in sensitivity awareness class.</summary>
<class>PUBLIC</class>
Surendra Reddy [Page 16]
draft-ietf-calsch-scap-00.txt April 1998
<categories>BUSINESS</categories>
<categories>HUMAN RESOURCES</categories>
<transp>transpARENT</TANSP>
</vevent>
The following is an example of the "vevent" calendar component used
to represent an anniversary that will occur annually. Since it takes
up no time, it will not appear as opaque in a search for busy time;
no matter what the value of the "transp" property indicates:
<vevent>
<uid>19970901T130000Z-123403@host.com</uid>
<dtstamp>19970901T1300Z</dtstand>
<dtstart>19971102</dtstart>
<summary>Our Blissful Anniversary</summary>
<class>CONFIDENTIAL</class>
<categories>ANNIVERSARY</categories>
<categories>PERSONAL</categories>
<categories>SPECIAL OCCASION</categories>
<rrule FREQ=YEARLY/>
</vevent>
5.3. vtodo XML element
Name: vtodo
Purpose: Provide a grouping of calendar properties that describe a
to-do.
Description: A "vtodo" calendar component is a grouping of component
properties and an OPTIONAL "valarm" calendar component that
represent an action-item or assignment.
<!ELEMENT vtodo (attach*, attendee*, categories*, class?, comment*,
contact*, completed?, created?, description?,
(dtend|duration)?, dtstart?, exdate*, exrule*,
lastmodified?, location?, organizer?, percent?,
priority, rstatus? related*, resources*, rdate*,
rrule*, dtstamp, sequence?, status?
summary, transp?, uid, url?, recurid?)>
The "vtodo" calendar component MUST include the "dtstamp", "priority",
"summary" and "uid" properties. In addition, it MUST include the "sequence"
property, if it's value is greater than zero.
A "vtodo" calendar component without the "dtstart" and "due" (or
"duration") properties specifies a to-do that is associated with each
successive calendar dates, until it is completed.
Surendra Reddy [Page 17]
draft-ietf-calsch-scap-00.txt April 1998
5.3.1. Example: vtodo
The following is an example of a "vtodo" calendar component:
<vtodo>
<uid>19970901T130000Z-123404@host.com</uid>
<dtstamp>19970901T1300Z</dtstamp>
<dtstart>19970415T133000Z</dtstart>
<due>19970416T045959Z</due>
<summary>1996 Income Tax Preparation</summary>
<class>CONFIDENTIAL</class>
<categories>FAMILY</categories>
<categories>FINANCE</categories>
<priority>1</priority>
<status>NEEDS-ACTION</status.
</vtodo>
5.4. vjournal XML element
Name: vjournal
Purpose: Provide a grouping of component properties that describe a
journal entry.
Description: A "vjournal" calendar component is a grouping of
component properties that represent one or more descriptive text
notes on a particular calendar date. The "dtstart" property is used
to specify the calendar date that the journal entry is associated
with. Generally, it will have a DATE value data type, but it MAY
also be used to specify a DATE-TIME value data type. Examples of a
journal entry include a daily record of a legislative body or a
journal entry of individual telephone contacts for the day or an
ordered list of accomplishments for the day. The "vjournal" calendar
component can also be used to associate a document with a calendar
date.
The "vjournal" calendar component does not take up time on a
calendar. Hence, it does not play a role in free or busy time
searches - - it is as though it has a time transparency value of
transpARENT. It is transparent to any such searches.
<!ELEMENT vjournal (attach*, attendee*, categories*, class?,
comment*, contact*, created?, description,
dtstart, dtstamp, exdate*, exrule*,
lastmodified?, organizer?, rstatus?
related*, rdate*, rrule*, sequence?,
summary, uid, url?, recurid?)>
The "vjournal" calendar component MUST include the "dtstamp",
"dtstart", "description", "summary" an "uid" properties. In addition,
it MUST include the "sequence" property, if it's value is greater
Surendra Reddy [Page 18]
draft-ietf-calsch-scap-00.txt April 1998
than zero.
The "vjournal" calendar component cannot be nested within another
calendar component. If "vjournal" calendar components need to be
related to each other or to a "vevent" or "vtodo" calendar component,
they can specify a relationship with the "RELATED-TO" property.
5.4.1. Example:
The following is an example of the "vjournal" calendar component:
<vjournal>
<uid>19970901T130000Z-123405@host.com</uid>
<dtstamp>19970901T1300Z</dtstamp>
<dtstart VALUE=DATE>19970317</dtstart>
<summary>Staff meeting minutes</summary>
<description>1. Staff meeting: Participants include Joe, Lisa
and Bob. Aurora project plans were reviewed. There is currently
no budget reserves for this project. Lisa will escalate to
management. Next meeting on Tuesday.
2. Telephone Conference: ABC Corp. sales representative called
to discuss new printer. Promised to get us a demo by Friday.
3. Henry Miller (Handsoff Insurance): Car was totaled by tree.
Is looking into a loaner car. 654-2323 (tel).
</description>
<vjournal>
5.5. vfreebusy XML element
Name: vfreebusy
Purpose: Provide a grouping of component properties that describe
either a request for free/busy time, describe a response to a
request for free/busy time or describe a published set of busy time.
Description: A "vfreebusy" calendar component is a grouping of
component properties that represents either a request for, a reply
to a request for free or busy time information or a published set of
busy time information.
The "vfreebusy" calendar component is intended for use in iCalendar
object methods involving requests for free time, requests for busy
time, requests for both free and busy, and the associated replies.
The recurrence properties ("rrule", "exrule", "rdate", "exdate") are
not permitted within a "vfreebusy" calendar component. Any recurring
events are resolved into their individual busy time periods using
the "freebusy" property.
Surendra Reddy [Page 19]
draft-ietf-calsch-scap-00.txt April 1998
<!ELEMENT vfreebusy( freebusyreq|freebusyresp|busytime )>
<!ELEMENT freebusyreq ( attendee, dtstamp, dtstart, dtend,
uid, sequence?)>
<!ELEMENT freebusyresp( attendee, dtstamp, freebusy, uid )>
<!ELEMENT busytime (attendee, dtstamp, dtstart, dtend, freebusy)>
The "vfreebusy" calendar component MUST include one of the "freebusyreq",
"freebusyresp" or "busytime" calendar components.
The "freebusyreq" component MUST include the "attendee", "dtstamp",
"dtstart", "dtend", and "uid" properties. In addition, it MUST
include the "sequence" property, if it's value is greater than zero.
The "freebusyresp" component MUST include the "attendee", "dtstamp",
"freebusy", and "uid" properties. In addition, it MUST include the
"sequence" property, it's value is greater than zero.
The "busytime" component MUST include the "attendee", "dtstamp",
"dtstart", dtend", and "freebusy" properties.
5.5.1. Example:
The following is an example of a "vfreebusy" calendar component used
to request free or busy time information:
<vfreebusy>
<freebusyreq>
<organizer MAILTO>jane_doe@host1.com</ORAGANIZER>
<attendee MAILTO:john_public@host2.com</attendee>
<dtstart>19971015T050000Z</dtstart>
<dtend>19971016T050000Z<dtend>
<dtstamp>19970901T083000Z<dtstamp>
<sequence>0</sequence>
<uid>19970901T0830000-uid1@host1.com</uid>
</freebusyreq>
<vfreebusy>
The following is an example of a "vfreebusy" calendar component used
to reply to the request with busy time information:
<vfreebusy>
<freebusyresp>
<attendee MAILTO>john_public@host2.com</attendee>
<dtstamp>19970901T100000Z</dtstamp>
<sequence>0</sequence>
<uid>19970901T0830000-uid1@host1.com</uid>
<freebusy VALUE=PERIOD>19971015T050000Z/PT8H30M,
19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M</freebusy>
<URL>http://host2.com/pub/busy/jpublic-01.vcs</URL>
</freebusyresp>
<comment>
Surendra Reddy [Page 20]
draft-ietf-calsch-scap-00.txt April 1998
This iCalendar file contains busy time information for
the next three months.</comment>
<vfreebusy>
The following is an example of a "vfreebusy" calendar component used
to published busy time information.
<vfreebusy>
<busytime>
<attendee:jsmith@host.com
<dtstart:19980313T141711Z
<dtend:19980410T141711Z
<freebusy>19980314T233000Z/19980315T003000Z</freebusy>
<freebusy>19980316T153000Z/19980316T163000Z</freebusy>
<freebusy>19980318T030000Z/19980318T040000Z</freebusy>
<URL>http://www.host.com/calendar/busytime/jsmith.ifb</URL>
</busytime>
<vfreebusy>
5.6. vtimezone XML element
Name: vtimezone
Purpose: Provide a grouping of component properties that defines a
time zone.
Description: A time zone is unambiguously defined by the set of time
measurement rules determined by the governing body for a given
geographic area. These rules describe at a minimum the base offset
from UTC for the time zone, often referred to as the Standard Time
offset.
If present, the "vtimezone" calendar component defines the set of
Standard Time and Daylight Saving Time observances (or rules) for a
particular time zone for a given interval of time. The "vtimezone"
calendar component cannot be nested within other calendar
components. Multiple "vtimezone" calendar components MAY exist in
an iCalendar object. In this situation, each "vtimezone" MUST
represent a unique time zone definition. This is necessary for some
classes of events, such as airline flights, that start in one time
zone and end in another.
<!ELEMENT vtimezone ( tzid, lastmodified?, tzurl?,
(standard | daylight)) >
<!ELEMENT standard ( comment*, dtstart, (rdate |rrule)?. tzname*,
tzoffsetto, tzoffsetfrom)>
<!ELEMENT daylight ( comment*, dtstart, (rdate | rrule )?, tzname*,
tzoffsetto, tzoffsetfrom)>
Surendra Reddy [Page 21]
draft-ietf-calsch-scap-00.txt April 1998
The properties in a "vtimezone" calendar componets are:
The mandatory "tzid" property is a text value that uniquely idenifies
the "vtimezone" calendar component within the scope of an iCalendar
object.
The optional "lastmodified" property is a UTC value that specifies the
date and time that this timezone definition was updated.
The optional "tzurl" property is a url value that points to a published
"vtimezone" definiton.
5.6.1. Example:
The following are examples of the "vtimezone" calendar component:
This is a simple example showing time zone information for the
Eastern United States using "rdate" property. Note that this is only
suitable for a recurring event that starts on or later than April 6,
1997 at 02:00:00 EST (i.e., the earliest effective transition date
and time) and ends no later than April 7, 1998 02:00:00 EST (i.e.,
latest valid date and time for EST in this scenario). For example,
this can be used for a recurring event that occurs every Friday,
8am-9am, starting June 1, 1997, ending December 31, 1997.
<vtimezone>
<tzid>America-New_York</tzid>
<lastmodified>19870101T000000Z<lastmodified>
<standard>
<dtstart>19971026T020000</dtstart>
<rdate>19971026T020000</rdate>
<tzoffsetfrom>-0400</tzoffsetfrom>
<TZOFFSETTO>-0500</TZOFFSETTO>
<TZNAME>EST</TZNAME>
</standard
<daylight
<dtstart>19971026T020000</dtstart>
<rdate>19970406T020000</rdate>
<tzoffsetfrom>-0500<tzoffsetfrom>
<tzoffsetto>-0400</tzoffsetto>
<tzname>EDT</tzname>
</daylight>
END:vtimezone
This is a simple example showing the current time zone rules for the
Eastern United States using a rrule recurrence pattern. Note that
there is no effective end date to either of the Standard Time or
Daylight Time rules. This information would be valid for a recurring
event starting today and continuing on into the known future.
<vtimezone>
<tzid>America-New_York<tzid>
Surendra Reddy [Page 22]
draft-ietf-calsch-scap-00.txt April 1998
<lastmodified>19870101T000000Z</lastmodified>
<tzurl>http://zones.stds_r_us.net/tz/America-New_York</tzurl>
<standard>
<dtstart>19671029T020000</dtstart>
<rrule:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10/>
<tzoffsetfrom>-0400</tzoffsetfrom>
<tzoffsetto>-0500</tzoffsetto>
<tzname>EST</tzname>
</standard>
<daylight>
<dtstart>19870405T020000 </dtstart>
<rrule FREQ=YEARLY;BYDAY=1SU;BYMONTH=4/>
<tzoffsetfrom>-0500</tzoffsetfrom>
<tzoffsetto>-0400</tzoffsetto>
<tzname>EDT</tzname>
</daylight>
</vtimezone>
This is an example showing a fictitious set of rules for the Eastern
United States, where the Daylight Time rule has an effective end date
(i.e., after that date, Daylight Time is no longer observed).
<vtimezone>
<tzid>America-New_York</tzid>
<lastmodified>19870101T000000Z</last-modified>
<standard>
<dtstart>19671029T020000
<rrule FREQ=YEARLY BYDAY=-1SU BYMONTH=10/>
<tzoffsetfrom>-0400<tzoffsetfrom>
<TZOFFSETTO>-0500</tzoffsetto>
<tzname>EST</tzname>
<standard>
<daylight>
<dtstart>19870405T020000</dtstart>
<rrule FREQ=YEARLY BYDAY=1SU BYMONTH=1 UNTIL=19980404T070000/>
<tzoffsetfrom>-0500</tzoffsetfrom>
<tzoffsetto>-0400</tzoffsetto>
<tzname>EDT</tzname>
</daylight>
</vtimezone>
5.7. valarm XML element
Name: valarm
Purpose: Provide a grouping of component properties that define an
alarm.
Surendra Reddy [Page 23]
draft-ietf-calsch-scap-00.txt April 1998
Description: A "valarm" calendar component is a grouping of
component properties that is a reminder or alarm for an event or a
to-do. For example, it may be used to define a reminder for a
pending event or an overdue to-do.
The "valarm" calendar component MUST include the "alarmtype" and
"trigger" properties. In addition, an AUDIO type of alarm MUST
include the "attach" property to point to a digital sound resource
to be played. The DISPLAY type of alarm MUST include the
"description" property. The EMAIL type of alarm MUST include the
"attendee", "description" and "summary" properties. The PROCEDURE
type of alarm MUST include the "attach" property to point to a
procedure resource to be invoked.
The "valarm" calendar component MUST only appear within either a
"vevent" or "vtodo" calendar component. The "valarm" calendar
components cannot be nested. Multiple "valarm" calendar components
MAY be specified.
<!ELEMENT valarm ( alarmtype, (trigger, (duration, repeat)?, attach) |
(description, trigger, (duration, repeat)?) |
(attendee*, attach*, description, trigger,
(duration, repeat)?, summary) |
(attach, description?, trigger, (duration, repeat)?))>
5.7.1. Example:
The following example is for a "valarm" calendar component that
specifies an audio alarm that will sound at a precise time and
repeat 4 more times at 15 minute intervals:
<valarm>
<alarmtype>AUDIO</alarmtype>
<trigger value=DATE-TIME>19970317T133000Z</trigger>
<repeat>4</repeat>
<duration>PT15M</duration>
<attach>ftp://host.com/pub/sounds/bell-01.wav</attach>
<valarm>
The following example is for a "valarm" calendar component that
specifies a display alarm that will trigger 15 minutes before the
scheduled start of the event or the due date/time of the to-do it is
associated with and will repeat 2 more times at 15 minute intervals:
<valarm>
<alarmtype>DISPLAY</alarmtype>
<description>Breakfast meeting with executive
team at 8:30 AM EST.</description>
<trigger>PT30M</trigger>
<repeat>2</repeat>
Surendra Reddy [Page 24]
draft-ietf-calsch-scap-00.txt April 1998
<duration>PT15M</duration>
<valarm>
The following example is for a "valarm" calendar component that
specifies an email alarm that will trigger 2 days before the
scheduled due date/time of a to-do it is associated with. It does not
repeat. The email has a subject, body and attachment link.
<valarm>
<alarmtype>EMAIL</alarmtype>
<attendee>mailto:john_doe@host.com</attendee>
<trigger>P2D</trigger>
<summary>
*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING ***
</summary>
<description>
A draft agenda needs to be sent out to the attendees
to the weekly managers meeting (MGR-LIST). Attached is a
pointer the document template for the agenda file.
</description>
<attach>http://host.com/templates/agenda.doc</attach>
</valarm>
The following example is for a "valarm" calendar component that
specifies a procedural alarm that will trigger at a precise date/time
and will repeat 23 more times at one hour intervals. The alarm will
invoke a procedure file.
<valarm>
<alarmtype>PROCEDURE</alarmtype>
<trigger VALUE=DATE-TIME>
19980101T050000Z
</trigger>
<repeat>23</repeat>
<duration>PT1H</duration>
<attach>ftp://host.com/novo-procs/felizano.exe</attach>
</valarm>
6. Calendar Properties
Property: A property is the definition of an individual attribute
describing a calendar property or a calendar component.
Property names, attribute names and attribute values are case
insensitive.
6.1. attach Property
Name: attach
Purpose: The property provides the capability to associate a document
object with a calendar component.
Value: URI ; The default value type for this property is URI. The
value type MAY also be reset to BINARY in order to include inline
Surendra Reddy [Page 25]
draft-ietf-calsch-scap-00.txt April 1998
binary encoded content information.
Description: The property MAY only be specified within "vevent",
"vtodo", "vjournal", or "VALARM" calendar components. This property
MAY be specified multiple times within an iCalendar object.
<!ELEMENT attach (#PCDATA) >
<!ATTLIST attach
encoding NMTOKEN #REQUIRED
value CDATA #REQUIRED >
6.2. categories Property
Name: categories
Purpose: This property defines the categories for a calendar
component.
Description: This property is used to specify categories or subtypes
of the calendar component. The categories are useful in searching for
a calendar component of a particular type and category. Within the
"vevent", "vtodo" or "vjournal" calendar components, more than one
category MAY be specified as a list of categories separated by the
COMMA character (ASCII decimal 44).
<!ELEMENT categories (#PCDATA) >
<!ATTLIST categories
language NMTOKEN #REQUIRED >
6.3. class Property
Name: class
Purpose: This property defines the access classification for a
calendar component.
Description: An access classification is only one component of the
general security system within a calendar application. It provides a
method of capturing the scope of the access the calendar owner
intends for information within an individual calendar entry.
<!ELEMENT class (#PCDATA)>
6.4. comment Property
Name: comment
Purpose: This property specifies non-processing information intended
to provide a comment to the calendar user.
Surendra Reddy [Page 26]
draft-ietf-calsch-scap-00.txt April 1998
Description: The property MAY be specified multiple times.
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
6.5. description Property
Name: description
Purpose: This property provides a more complete description of the
calendar component, than that provided by the "summary" property.
Description: This property is used to capture lengthy textual decriptions
associated with the activity.
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
6.6. location Property
Name: location
Purpose: The property defines the intended venue for the activity
defined by a calendar component.
Description: Specific venues such as conference or meeting rooms may
be explicitly specified using this property. An alternate
representation may be specified that is a URI that points to
directory information with more structured specification of the
location.
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
6.7. percentcomplete Property
Name: percentcomplete
Purpose: This property is used by an assignee or delegatee of a to-do
to convey the percent completion of a to-do to the Organizer.
Surendra Reddy [Page 27]
draft-ietf-calsch-scap-00.txt April 1998
Description: The property value is a postive integer between zero and
one hundred. A valu e of "0" indicates the to-do has not yet been
started. A value of "100" indicates that the to-do has been
completed. Integer values in between indicate the percent partially
complete.
6.8. priority Property
Name: priority
Purpose: The property defines the relative priority for a calendar
component.
Description: The priority is specified as an integer in the range
zero to nine. A value of zero (ASCII decimal 48) specifies an
undefined priority. A value of one (ASCII decimal 49) is the highest
priority. A value of two (ASCII decimal 50) is the second highest
priority. Subsequent numbers specify a decreasing ordinal priority. A
value of nine (ASCII decimal 58) is the lowest priority.
Within a "vevent" calendar component, this property specifies a
priority for the event. This property may be useful when more than
one event is scheduled for a given time period.
Within a "vtodo" calendar component, this property specified a
priority for the to-do. This property is useful in prioritizing
multiple action items for a given time period.
6.9. resources Property
Name: resources
Purpose: This property defines the equipment or resources anticipated
for an activity specified by a calendar entity..
Description: The property value is an arbitrary text. More than one
resource MAY be specified as a list of resources separated by the
COMMA character (ASCII decimal 44).
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED >
6.10. status Property
Name: status
Surendra Reddy [Page 28]
draft-ietf-calsch-scap-00.txt April 1998
Purpose: This property defines the overall status or confirmation for
the calendar component.
Description: In a group scheduled calendar component, the property is
used by the "Organizer" to provide a confirmation of the event to the
"Attendees". For example in a "vevent" calendar component, the
"Organizer" can indicate that a meeting is tentative, confirmed or
cancelled. In a "vtodo" calendar component, the "Organizer" can
indicate that an action item needs action, is completed, is in
process or being worked on, or has been cancelled. In a "vjournal"
calendar component, the "Organizer" can indicate that a journal entry
is draft, final or has been cancelled or removed.
6.11. summary Property
Name: summary
Purpose: This property defines a short summary or subject for the
calendar component.
Description: This property is used to capture a short, one line summary
about the activity or journal entry.
<!ELEMENT summary(#PCDATA)>
<!ATTLIST summary
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
6.12. completed property
Property Name: completed
Purpose: This property defines the date and time that a to-do was
actually completed.
Value : DATE-TIME
Description: The date and time must be in a UTC format.
6.13. dtend Property
Name: dtend
Purpose: This property specifies the date and time that a calendar
component ends.
Surendra Reddy [Page 29]
draft-ietf-calsch-scap-00.txt April 1998
Value: DATE-TIME; The default value type is DATE-TIME. The value type MAY
BE reset to a DATE value type.
Description: Within the "vevent" calendar component, this property
defines the date and time by which the event ends. The value MUST be
later in time than the value of the "dtstart" property.
Within the "VFREEBUSY" calendar component, this property defines the
end date and time for the free or busy time information. The time
MUST be specified as in the UTC time format. The value MUST be later
in time than the value of the "dtstart" property.
<!ELEMENT dtend(#PCDATA)>
<!ATTLIST dtend
value NMTOKEN #REQUIRED
tzid NMTOKEN #REQUIRED>
6.14. due Property
Name: due
Purpose: This property defines the date and time that a to-do is
expected to be completed.
Value: DATE-TIME ; The default value type is DATE-TIME. The value type MAY
BE reset to a DATE value type.
Description: The value MUST be a date/time equal to or after the
dtstart value, if specified.
<!ELEMENT due(#PCDATA)>
<!ATTLIST due
value NMTOKEN #REQUIRED
tzid NMTOKEN #REQUIRED>
6.15. dtstart Property
Name: dtstart
Purpose: This property specifies when the calendar component begins.
Value: DATE-TIME; The default value type is DATE-TIME. The DATE-TYPE value
will be one of the forms defined for the DATE-TIME value type. The
value type MAY BE reset to a DATE value type.
Description: Within the "vevent" calendar component, this property
Surendra Reddy [Page 30]
draft-ietf-calsch-scap-00.txt April 1998
defines the start date and time for the event. The property is
REQUIRED in "vevent" calendar components. Events MAY have a start
date/time but no end date/time. In that case, the event does not take
up any time.
Within the "VFREEBUSY" calendar component, this property defines the
start date and time for the free or busy time information. The time
MUST be specified in UTC time.
Within the "VTIMEZONE" calendar component, this property defines the
effective start date and time for a time zone specification. This
property is REQUIRED within "VTIMEZONE" calendar components. The time
MUST be specified in the UTC time format.
<!ELEMENT dtstart(#PCDATA)>
<!ATTLIST dtstart
value NMTOKEN #REQUIRED
tzid NMTOKEN #REQUIRED>
6.16. duration Property
Name: duration
Purpose: The property specifies a duration of time .
Value : duration
Description: In a "vevent" calendar component the property may be
used to specify a duration of the event, instead of an explicit end
date/time. In a "vtodo" calendar component the property may be used
to specify a duration for the to-do, instead of an explicit due
date/time. In a "VFREEBUSY" calendar component the property may be
used to specify the interval of free time being requested. In a
"VALARM" calendar component the property may be used to specify the
delay period prior to repeating an alarm.
6.17. freebusy Property
Name: freebusy
Purpose: The property defines one or more free or busy time
intervals.
Value : PERIOD; The data and time value MUST be in a UTC time
format.
Surendra Reddy [Page 31]
draft-ietf-calsch-scap-00.txt April 1998
Description: These time periods MAY be specified as either a start
and end date-time or a start date-time and duration. The date and
time MUST be a UTC time format.
The "FREEBUSY" property MAY include the "TYPE" property parameter to
specify whether the information defines a FREE or BUSY time interval.
The default "TYPE" property parameter value is BUSY.
If the "TYPE" property parameter is set to "BUSY", then the property
MAY also include the "BSTAT" property parameter to provide added
information about the busy time. For example, if the busy time is
associated with a time interval that would be unavailable for
scheduling in any case the parameter MAY BE set to UNAVAILABLE or if
the busy time that has been tentatively scheduled the parameter MAY
BE set to TENTATIVE. The default "BSTAT" property parameter value is
BUSY, providing no additional busy status information.
"FREEBUSY" properties within the "VFREEBUSY" calendar component
should be sorted in ascending order, based on start time and then end
time, with the earliest periods first.
The "FREEBUSY" property MAY specify more than one value, separated by
the COMMA character (ASCII decimal 44). In such cases, the "FREEBUSY"
property values should all be of the same "TYPE" and "BSTAT" property
parameter type (e.g., all values of a particular "TYPE" and "BSTAT"
listed together in a single property).
<!ELEMENT freebusy(#PCDATA)>
<!ATTLIST freebusy
type (busy|free)
bstat (busy|unavialable|trntative)
6.18. attendee Property
Name: attendee
Purpose: The property defines an attendee within a calendar
component.
Value: CAL-ADDRESS ; See Calendar Object Specification for more info.
Conformance: This property MUST be specified in an iCalendar object
that specifies a group scheduled calendar entity. This property MUST
be specified in an iCalendar object that specifies the publication of
a calendar user's busy time. This property is not specified in an
iCalendar object that specifies only a time zone definition or that
defines calendar entities that are not group scheduled entities, but
Surendra Reddy [Page 32]
draft-ietf-calsch-scap-00.txt April 1998
are entities only on a single user's calendar.
Description: The property is specified within the "vevent", "vtodo",
"vjournal calendar components to specify participants, non-
participants and the chair of a group scheduled calendar entity. The
property is specified within the "VFREEBUSY" calendar component to
specify the calendar user associated with the free or busy time. The
property is specified within an "EMAIL" category of the "VALARM"
calendar component to specify an email address that is to receive the
email type of iCalendar alarm.
6.19. contact Property
Name: contact
Purpose: The property is used to represent contact information or
alternately a reference to contact information associated with the
calendar component.
Description: The property value consists of textual contact
information. An alternative representation for the property value MAY
also be specified that refers to a URI pointing to an alternate form,
such as a vCard, for the contact information.
<!ELEMENT contact(#PCDATA)>
<!ATTLIST contact
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
6.20. organizer Property
Name: organizer
Purpose: The property defines the organizer for a calendar component.
Value: CAL-ADDRESS
Description: The property is specified within the "vevent", "vtodo",
"vjournal calendar components to specify the organizer of a group
scheduled calendar entity. The property is specified within the
"VFREEBUSY" calendar component to specify the calendar user
requesting the free or busy time.
<!ELEMENT organizer(#PCDATA)>
<!ATTLIST organizer
cn NMTOKEN #REQUIRED
Surendra Reddy [Page 33]
draft-ietf-calsch-scap-00.txt April 1998
sentby NMTOKEN #REQUIRED
dir NMTOKEN #REQUIRED>
The property has the property parameters CN, for specifying the
common or display name associated with the "Organizer", DIR, for
specifying a pointer to the directory information associated with the
"Organizer", SENT-BY, for specifying another calendar user that is
acting on behalf of the "Organizer". No other parameters MAY be
specified on this property.
6.21. recurid Property
Name: recurid
Purpose: This property is used in conjunction with the "uid" and
"sequence" property to identify a specific instance of a recurring
"vevent", "vtodo" or "vjournal" calendar component. The property
value is the effective value of the "dtstart" property of the
recurrence instance.
Value Type: DATE-TIME; The default value type for this property is DATE-TIME.
The time format MAY BE any of the valid forms defined for a DATE-TIME
value type. See DATE-TIME value type definition for specific
interpretations of the various forms. The value type MAY be reset to
DATE.
Description: The full range of calendar components specified by a
recurrence set is referenced by referring to just the "uid" property
value corresponding to the calendar component. The "recurrence-id"
property allows the reference to an individual instance within the
recurrence set.
If the value of the "dtstart" property is a DATE type value, then the
value MUST be the calendar date for the recurrence instance.
The date/time value is set to the time when the original recurrence
instance would occur - - meaning that if the intent is to change a
Friday meeting to Thursday, the date/time is still set to the
original Friday meeting.
The "recurrence-id" property is used in conjunction with the "uid"
and "SEQUENCE" property to identify a particular instance of a
recurring event, to-do or journal. For a given pair of "uid" and
"SEQUENCE" property values, the "recurrence-id" value for a
recurrence instance is fixed.
<!ELEMENT recurid(#PCDATA)>
Surendra Reddy [Page 34]
draft-ietf-calsch-scap-00.txt April 1998
<!ATTLIST recurid
value (date-time | date | period )
range ( thisandprior | thisandfuture )>
6.22. relatedto Property
Name: relatedto
Purpose: The property is used to represent a relationship or
reference between one calendar component and another.
Description: The property value consists of the persistent, globally
unique identifier of another calendar component. This value would be
represented in a calendar component by the "uid" property.
By default, the property value points to another calendar component
that has a PARENT relationship to the referencing object. The
"RELTYPE" property parameter is used to either explicitly state the
default PARENT relationship type to the referenced calendar component
or to override the default PARENT relationship type and specify
either a CHILD or SIBLING relationship.
<!ELEMENT related-to(#PCDATA)>
<!ATTLIST related-to
reltype (parent | child |sibling)>
6.23. url property
Name: url
Purpose: This property defines a Uniform Resource Locator (URL)
associated with the iCalendar object.
Value: URI
Description: This property may be used in a calendar component to
convey a location where a more dynamic rendition of the calendar
information associated with the calendar component can be found. This
memo does not attempt to standardize the form of the URI, nor the
format of the resource pointed to by the property value. If the
6.24. uid Property
Name: uid
Purpose: This property defines the persistent, globally unique
Surendra Reddy [Page 35]
draft-ietf-calsch-scap-00.txt April 1998
identifier for the calendar component.
Description: The uid itself MUST be a globally unique identifier. The
generator of the identifier MUST guarantee that the identifier is
unique. There are several algorithms that can be used to accomplish
this. The identifier is RECOMMENDED to be the identical syntax to the
[RFC 822] addr-spec.
6.25. exdate Property
Name: exdate
Purpose: This property defines the list of date/time exceptions for a
recurring calendar component.
Value: DATE-TIME ; The default value type for this property is DATE-TIME.
The value type MAY be reset to DATE.
Description: The exception dates, if specified, is used in computing
the recurrence set. The recurrence set is the complete set of
recurrence instances for a calendar component.
6.26. exrule Property
Name: exrule
Purpose: This property defines a rule or repeating pattern for an
exception to a recurrence set.
Value: RECUR
Description: The exception rule, if specified, is used in computing
the recurrence set. The recurrence set is the complete set of
recurrence instances for a calendar component.
6.27. rdate Property
Name: rdate
Purpose: This property defines the list of date/times for a
recurrence set.
Value : DATE-TIME ; The default value type for this property is DATE-TIME.
The value type MAY be reset to DATE or PERIOD.
Description: This property MAY appear along with the "rrule" property
Surendra Reddy [Page 36]
draft-ietf-calsch-scap-00.txt April 1998
to define an aggregate set of repeating occurrences. When they both
appear in an iCalendar object, the recurring events are defined by
the union of occurrences defined by both the "rdate" and "rrule".
The recurrence dates, if specified, is used in computing the
recurrence set. The recurrence set is the complete set of recurrence
instances for a calendar component.
<!ELEMENT rdate(#PCDATA)>
<!ATTLIST rdate
value (date|date-time|period)
tzid NMTOKEN #REQUIRED>
6.28. rrule Property
Name: rrule
Purpose: This property defines a rule or repeating pattern for a
recurring events, to-dos, or time zone definitions.
Value: RECUR
Description: The recurring rule, if specified, is used in computing
the recurrence set. The recurrence set is the complete set of
recurrence instances for a calendar component.
6.29. trigger Property
Name: trigger
Purpose: This property specifies when an alarm will trigger.
Value: duration ; The default value type is duration. The value type MAY BE
reset to a DATE-TIME value type.
Description: Within the "VALARM" calendar component, this property
defines when the alarm will trigger. The default value type is
duration, specifying a relative time for the trigger of the alarm.
The default duration is relative to the start of an event or to-do
that the alarm is associated with. The duration can be explicitly set
to trigger from either the end or the start of the associated event
or to-do with the "RELATED" parameter. A value of START will set the
alarm to trigger off the start of the associated event or to-do. A
value of END will set the alarm to trigger off the end of the
associated event or to-do.
Surendra Reddy [Page 37]
draft-ietf-calsch-scap-00.txt April 1998
<!ELEMENT trigger(#PCDATA)>
<!ATTLIST trigger
value (duration | date-time)
related (start|end)
tzid NMTOKEN #REQUIRED>
6.30. created Property
Name: created
Purpose: This property specifies the date and time that the calendar
information was created in the calendar user agent.
Value : DATE-TIME
Description: The date and time is a UTC value.
6.31. dtstamp Property
Name: dtstamp
Purpose: The property indicates the date/time that the instance of
the iCalendar object was created.
Value: DATE-TIME
Description: The value must be specified in the UTC time format.
This property will assist in the proper sequencing of messages
containing iCalendar objects.
This property is different than the "created" and "lastmodified"
properties. These two properties are used to specify when the
calendar service information was created and last modified. This is
different than when the iCalendar object representation of the
calendar service information was created or last modified.
6.32. lastmodified Property
Name: lastmodified
Purpose: The property specifies the date and time that the
information associated with the calendar component was last revised.
Surendra Reddy [Page 38]
draft-ietf-calsch-scap-00.txt April 1998
Value: DATE-TIME
Description: The property value MUST be specified in the UTC time
format.
6.33. sequence Property
Name: sequence
Purpose: This property defines the revision sequence of the calendar
component used in a request.
Value: INTEGER
Description: This property is needed to properly handle the receipt
and processing of a sequence of calendar components that have been
delivered out of order. Such is the case for store-and-forward based
transports. The first request is created with a sequence number of
"0" (ASCII decimal 48). It is incremented each time the organizer or
OWNER issues a revision to the request.
6.34. requeststatus Property
Name: requeststatus
Purpose: This property defines the status code returned for a
scheduling request.
Description: This property is used to return status code information
related to the processing of an associated iCalendar object. The data
type for this property is TEXT.
The value consists of a short return status, a longer return status
description, and optionally the offending data. The components of the
value are separated by the SEMICOLON character (ASCII decimal 59).
The short return status is a PERIOD character (ASCII decimal 46)
separated 3-tuple of integers. For example, "3.1.1". The successive
levels of integers provide for a successive level of status code
granularity.
<!ELEMENT requeststatus(#PCDATA)>
<!ATTLIST requeststatus
statcode NMTOKEN #REQUIRED
statdesc NMTOKEN #REQUIRED>
Surendra Reddy [Page 39]
draft-ietf-calsch-scap-00.txt April 1998
7. Security Considerations
Since calendaring interoperability may involve the exchange of
sensitive information, any calendaring interoperability mechanism
must provide for encryption and authentication. Several techniques
such as SSL and HTTP Access Authorization are available for use with
HTTP as described in [3] and [4]. Without such techniques, SCAP
clients and servers are wide open to forged or snooped meeting
proposals or responses.
8. Calendar Object Specification - XML DTD
<!DOCTYPE scap-1.0 [
<!-- Calendar Object Model - XML element definitions -->
<!-- Author : Surendra Reddy -->
<!-- Version 1.0 -->
<!ELEMENT vcalendar ( vevent | vtodo | vjournal |
vfreebusy | vtimezone )+)>
<!ATTLIST vcalendar
version PCDATA #REQUIRED
prodid PCDATA #REQUIRED >
<!ELEMENT vevent (attach*, attendee*, categories*, class?, comment*,
contact*, created?, description?, (dtend|duration)?,
dtstart, exdate*,exrule*, lastmodified?, location?,
organizer?, priority?, rstatus?,
related*, resources*, rdate*, rrule*, dtstamp,
sequence?, status?, summary, transp?, uid, url?,
recurid?)>
<!ELEMENT vtodo (attach*, attendee*, categories*, class?, comment*,
contact*, completed?, created?, description?,
(dtend|duration)?, dtstart?,
exdate*, exrule*, lastmodified?, location?,
organizer?, percent?,
priority, rstatus?, related*, resources*,
rdate*, rrule*, dtstamp, sequence?, status?,
summary, transp?, uid, url?, recurid?)>
<!ELEMENT vjournal (attach*, attendee*, categories*, class?,
comment*, contact*, created?, description,
dtstart, dtstamp, exdate*,
exrule*, lastmodified?, organizer?, rstatus?,
related*, rdate*, rrule*, sequence?,
summary, uid, url?, recurid?)>
<!ELEMENT vfreebusy( freebusyreq|freebusyresp|busytime )>
<!ELEMENT freebusyreq ( attendee, dtstamp, dtstart, dtend, uid,
sequence?)>
Surendra Reddy [Page 40]
draft-ietf-calsch-scap-00.txt April 1998
<!ELEMENT freebusyresp( attendee, dtstamp, freebusy, uid )>
<!ELEMENT busytime (attendee, dtstamp, dtstart, dtend, freebusy)>
<!ELEMENT vtimezone ( tzid, lastmodified?, tzurl?,
(standard | daylight)) >
<!ELEMENT standard ( comment*, dtstart, (rdate |rrule)?. tzname*,
tzoffsetto, tzoffsetfrom)>
<!ELEMENT daylight ( comment*, dtstart, (rdate | rrule )?, tzname*,
tzoffsetto, tzoffsetfrom)>
<!ELEMENT valarm ( alarmtype, (trigger, (duration, repeat)?, attach) |
(description, trigger, (duration, repeat)?) |
(attendee*, attach*, description, trigger,
(duration, repeat)?, summary) |
(attach, description?, trigger,
(duration, repeat)?))>
<!ELEMENT attach (#PCDATA) >
<!ATTLIST attach
encoding NMTOKEN #REQUIRED
value CDATA #REQUIRED >
<!ELEMENT categories (#PCDATA) >
<!ATTLIST categories
language NMTOKEN #REQUIRED >
<!ELEMENT class (#PCDATA)>
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
<!ELEMENT percentcomplete(#PCDATA)>
Surendra Reddy [Page 41]
draft-ietf-calsch-scap-00.txt April 1998
<!ELEMENT priority (#PCDATA)>
<!ELEMENT comment(#PCDATA)>
<!ATTLIST comment
language NMTOKEN #REQUIRED >
<!ELEMENT status (#PCDATA)>
<!ELEMENT summary (#PCDATA)
<!ATTLIST summary
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
<!ELEMENT completed (#PCDATA)>
<!ELEMENT dtend(#PCDATA)>
<!ATTLIST dtend
value NMTOKEN #REQUIRED
tzid NMTOKEN #REQUIRED>
<!ELEMENT due(#PCDATA)>
<!ATTLIST due
value NMTOKEN #REQUIRED
tzid NMTOKEN #REQUIRED>
<!ELEMENT dtstart(#PCDATA)>
<!ATTLIST dtstart
value NMTOKEN #REQUIRED
tzid NMTOKEN #REQUIRED>
<!ELEMENT duration (#PCDATA)>
<!ELEMENT freebusy(#PCDATA)>
<!ATTLIST freebusy
type (busy|free)
bstat (busy|unavialable|trntative)
<!ELEMENT attendee
<!ELEMENT contact(#PCDATA)>
<!ATTLIST contact
language NMTOKEN #REQUIRED
altrep NMTOKEN #REQUIRED>
<!ELEMENT organizer(#PCDATA)>
<!ATTLIST organizer
cn NMTOKEN #REQUIRED
sent-by NMTOKEN #REQUIRED
Surendra Reddy [Page 42]
draft-ietf-calsch-scap-00.txt April 1998
dir NMTOKEN #REQUIRED>
<!ELEMENT recurid(#PCDATA)>
<!ATTLIST recurid
value (date-time | date | period )
range ( thisandprior | thisandfuture )>
<!ELEMENT relatedto(#PCDATA)>
<!ATTLIST relatedto
reltype (parent | child |sibling)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT uid (#PCDATA)>
<!ELEMENT exdate (#PCDATA)>
<!ELEMENT exrule(#PCDATA)>
<!ELEMENT rdate (#PCDATA)>
<!ELEMENT rdate(#PCDATA)>
<!ATTLIST rdate
value (date|date-time|period)
tzid NMTOKEN #REQUIRED>
<!ELEMENT trigger(#PCDATA)>
<!ATTLIST trigger
value (duration | date-time)
related (start|end)
tzid NMTOKEN #REQUIRED>
<!ELEMENT created (#PCDATA)
<!ELEMENT dtstamp (#PCDATA)>
<!ELEMENT lastmodified(#PCDATA)>
<!ELEMENT sequence (#PCDATA)>
<!ELEMENT csoperation(create|delete|select|rename)+ >
<!ELEMENT create (#PCDATA) >
<!ELEMENT delete (#PCDATA) >
<!ELEMENT select (#PCDATA) >
Surendra Reddy [Page 43]
draft-ietf-calsch-scap-00.txt April 1998
<!ELEMENT rename (from,to) >
<!ELEMENT copy (from,to) >
<!ELEMENT from (#PCDATA) >
<!ELEMENT to (#PCDATA) >
<!ELEMENT list ( allstores | allusers | curusr)+ >
<!ELEMENT allstores (#PCDATA) >
<!ELEMENT allusers (#PCDATA) >
<!ELEMENT curusr (#PCDATA) >
<!ELEMENT getcomponent(#PCDATA) >
<!ELEMENT freebusyreq(csname+, dtstart,dtend)>
<!ELEMENT csname (#PCDATA)>
<!ELEMENT requeststatus(#PCDATA)>
<!ATTLIST requeststatus
statcode NMTOKEN #REQUIRED
statdesc NMTOKEN #REQUIRED>
]>
9. References
[CSCOS] F. Dawson, D. Stenerson, Internet Calendaring and Scheduling
Core Object Specification, Internet Draft, draft-ietf-calsch-ical-00.txt,
February 1997.
[Alvestrand, 1995] H. T. Alvestrand, "Tags for the Identification of
Languages." RFC 1766. Uninett. March, 1995.
[Alvestrand, 1998] H. T. Alvestrand, "IETF Policy on Character Sets
and Languages." RFC 2277, BCP 18. Uninett. January, 1998.
[Bradner, 1997] S. Bradner, "Key words for use in RFCs to Indicate
Requirement Levels." RFC 2119, BCP 14. Harvard University. March,
1997.
[Bray, Paoli, Sperberg-McQueen, 1998] T. Bray, J. Paoli, C. M.
Sperberg-McQueen, "Extensible Markup Language (XML)." World Wide Web
Consortium Recommendation REC-xml-19980210.
Surendra Reddy [Page 44]
draft-ietf-calsch-scap-00.txt April 1998
http://www.w3.org/TR/1998/REC-xml-19980210.
[Franks et al., 1997] J. Franks, P. Hallam-Baker, J. Hostetler, P.
Leach, A. Luotonen, E. Sink, and L. Stewart. "An Extension to HTTP :
Digest Access Authentication" RFC 2069. Northwestern University,
CERN, Spyglass Inc., Microsoft Corp., Netscape Communications Corp.,
Spyglass Inc., Open Market Inc. January 1997.
[Fielding et al., 1997] R. Fielding, J. Gettys, J. Mogul, H.
Frystyk, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1."
RFC 2068. U.C. Irvine, DEC, MIT/LCS. January, 1997.
[ISO-639] ISO (International Organization for Standardization). ISO
639:1988. "Code for the representation of names of languages."
[ISO-8601] ISO (International Organization for Standardization). ISO
8601:1988. "Data elements and interchange formats - Information
interchange - Representation of dates and times."
[Leach, Salz, 1998] P. J. Leach, R. Salz, "UUIDs and GUIDs."
Internet-draft, work-in-progress, February, 1998.
ftp://ietf.org/internet-drafts/draft-leach-uuids-guids-01.txt
[Yergeau, 1998] F. Yergeau, "UTF-8, a transformation format of
Unicode and ISO 10646." RFC 2279. Alis Technologies. January, 1998.
[Bradner, 1996] S. Bradner, "The Internet Standards Process -
Revision 3." RFC 2026, BCP 9. Harvard University. October, 1996.
[Bray, Hollander, Layman, 1998] T. Bray, D. Hollander, A. Layman,
"Name Spaces in XML" World Wide Web Consortium Working Draft,
http://www.w3.org/TR/WD-xml-names.
10. Author's Address
Surendra Reddy
Oracle Corporation
500 Oracle Parkway
M/S 6op3
Redwoodshores, CA 94065
Phone: +1(650) 506 5441
Fax: +1(650) 654 6205
Email: skreddy@us.oracle.com
Surendra Reddy [Page 45]