Internet DRAFT - draft-ietf-calsify-rfc2445bis
draft-ietf-calsify-rfc2445bis
Network Working Group B. Desruisseaux, Ed.
Internet-Draft Oracle
Obsoletes: 2445 (if approved) October 31, 2008
Intended status: Standards Track
Expires: May 4, 2009
Internet Calendaring and Scheduling Core Object Specification
(iCalendar)
draft-ietf-calsify-rfc2445bis-09
Status of This Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
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 May 4, 2009.
Desruisseaux Expires May 4, 2009 [Page 1]
Internet-Draft iCalendar October 2008
Abstract
This document defines the iCalendar data format for representing and
exchanging calendaring and scheduling information such as events, to-
dos, journal entries and free/busy information, independent of any
particular calendar service or protocol.
Desruisseaux Expires May 4, 2009 [Page 2]
Internet-Draft iCalendar October 2008
Editorial Note (To be removed by RFC Editor prior to publication)
This document is a product of the Calendaring and Scheduling
Standards Simplification (Calsify) working group of the Internet
Engineering Task Force. Comments on this draft are welcomed, and
should be addressed to the ietf-calsify@osafoundation.org [1] mailing
list.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
2. Basic Grammar and Conventions . . . . . . . . . . . . . . . . 8
2.1. Formatting Conventions . . . . . . . . . . . . . . . . . 8
2.2. Related Memos . . . . . . . . . . . . . . . . . . . . . . 9
3. iCalendar Object Specification . . . . . . . . . . . . . . . 10
3.1. Content Lines . . . . . . . . . . . . . . . . . . . . . . 10
3.1.1. List and Field Separators . . . . . . . . . . . . . . 12
3.1.2. Multiple Values . . . . . . . . . . . . . . . . . . . 13
3.1.3. Binary Content . . . . . . . . . . . . . . . . . . . 13
3.1.4. Character Set . . . . . . . . . . . . . . . . . . . . 14
3.2. Property Parameters . . . . . . . . . . . . . . . . . . . 14
3.2.1. Alternate Text Representation . . . . . . . . . . . . 15
3.2.2. Common Name . . . . . . . . . . . . . . . . . . . . . 16
3.2.3. Calendar User Type . . . . . . . . . . . . . . . . . 17
3.2.4. Delegators . . . . . . . . . . . . . . . . . . . . . 18
3.2.5. Delegatees . . . . . . . . . . . . . . . . . . . . . 18
3.2.6. Directory Entry Reference . . . . . . . . . . . . . . 19
3.2.7. Inline Encoding . . . . . . . . . . . . . . . . . . . 19
3.2.8. Format Type . . . . . . . . . . . . . . . . . . . . . 20
3.2.9. Free/Busy Time Type . . . . . . . . . . . . . . . . . 20
3.2.10. Language . . . . . . . . . . . . . . . . . . . . . . 21
3.2.11. Group or List Membership . . . . . . . . . . . . . . 22
3.2.12. Participation Status . . . . . . . . . . . . . . . . 23
3.2.13. Recurrence Identifier Range . . . . . . . . . . . . . 24
3.2.14. Alarm Trigger Relationship . . . . . . . . . . . . . 25
3.2.15. Relationship Type . . . . . . . . . . . . . . . . . . 25
3.2.16. Participation Role . . . . . . . . . . . . . . . . . 26
3.2.17. RSVP Expectation . . . . . . . . . . . . . . . . . . 27
3.2.18. Sent By . . . . . . . . . . . . . . . . . . . . . . . 28
3.2.19. Time Zone Identifier . . . . . . . . . . . . . . . . 28
3.2.20. Value Data Types . . . . . . . . . . . . . . . . . . 29
3.3. Property Value Data Types . . . . . . . . . . . . . . . . 30
3.3.1. Binary . . . . . . . . . . . . . . . . . . . . . . . 31
3.3.2. Boolean . . . . . . . . . . . . . . . . . . . . . . . 31
3.3.3. Calendar User Address . . . . . . . . . . . . . . . . 32
3.3.4. Date . . . . . . . . . . . . . . . . . . . . . . . . 32
3.3.5. Date-Time . . . . . . . . . . . . . . . . . . . . . . 33
3.3.6. Duration . . . . . . . . . . . . . . . . . . . . . . 36
Desruisseaux Expires May 4, 2009 [Page 3]
Internet-Draft iCalendar October 2008
3.3.7. Float . . . . . . . . . . . . . . . . . . . . . . . . 37
3.3.8. Integer . . . . . . . . . . . . . . . . . . . . . . . 37
3.3.9. Period of Time . . . . . . . . . . . . . . . . . . . 38
3.3.10. Recurrence Rule . . . . . . . . . . . . . . . . . . . 39
3.3.11. Text . . . . . . . . . . . . . . . . . . . . . . . . 46
3.3.12. Time . . . . . . . . . . . . . . . . . . . . . . . . 48
3.3.13. URI . . . . . . . . . . . . . . . . . . . . . . . . . 50
3.3.14. UTC Offset . . . . . . . . . . . . . . . . . . . . . 50
3.4. iCalendar Object . . . . . . . . . . . . . . . . . . . . 51
3.5. Property . . . . . . . . . . . . . . . . . . . . . . . . 52
3.6. Calendar Components . . . . . . . . . . . . . . . . . . . 52
3.6.1. Event Component . . . . . . . . . . . . . . . . . . . 54
3.6.2. To-do Component . . . . . . . . . . . . . . . . . . . 57
3.6.3. Journal Component . . . . . . . . . . . . . . . . . . 60
3.6.4. Free/Busy Component . . . . . . . . . . . . . . . . . 61
3.6.5. Time Zone Component . . . . . . . . . . . . . . . . . 64
3.6.6. Alarm Component . . . . . . . . . . . . . . . . . . . 73
3.7. Calendar Properties . . . . . . . . . . . . . . . . . . . 78
3.7.1. Calendar Scale . . . . . . . . . . . . . . . . . . . 78
3.7.2. Method . . . . . . . . . . . . . . . . . . . . . . . 79
3.7.3. Product Identifier . . . . . . . . . . . . . . . . . 80
3.7.4. Version . . . . . . . . . . . . . . . . . . . . . . . 81
3.8. Component Properties . . . . . . . . . . . . . . . . . . 82
3.8.1. Descriptive Component Properties . . . . . . . . . . 82
3.8.1.1. Attachment . . . . . . . . . . . . . . . . . . . 82
3.8.1.2. Categories . . . . . . . . . . . . . . . . . . . 83
3.8.1.3. Classification . . . . . . . . . . . . . . . . . 84
3.8.1.4. Comment . . . . . . . . . . . . . . . . . . . . . 85
3.8.1.5. Description . . . . . . . . . . . . . . . . . . . 86
3.8.1.6. Geographic Position . . . . . . . . . . . . . . . 87
3.8.1.7. Location . . . . . . . . . . . . . . . . . . . . 89
3.8.1.8. Percent Complete . . . . . . . . . . . . . . . . 90
3.8.1.9. Priority . . . . . . . . . . . . . . . . . . . . 91
3.8.1.10. Resources . . . . . . . . . . . . . . . . . . . . 93
3.8.1.11. Status . . . . . . . . . . . . . . . . . . . . . 94
3.8.1.12. Summary . . . . . . . . . . . . . . . . . . . . . 95
3.8.2. Date and Time Component Properties . . . . . . . . . 96
3.8.2.1. Date/Time Completed . . . . . . . . . . . . . . . 96
3.8.2.2. Date/Time End . . . . . . . . . . . . . . . . . . 97
3.8.2.3. Date/Time Due . . . . . . . . . . . . . . . . . . 98
3.8.2.4. Date/Time Start . . . . . . . . . . . . . . . . . 99
3.8.2.5. Duration . . . . . . . . . . . . . . . . . . . . 101
3.8.2.6. Free/Busy Time . . . . . . . . . . . . . . . . . 102
3.8.2.7. Time Transparency . . . . . . . . . . . . . . . . 103
3.8.3. Time Zone Component Properties . . . . . . . . . . . 104
3.8.3.1. Time Zone Identifier . . . . . . . . . . . . . . 104
3.8.3.2. Time Zone Name . . . . . . . . . . . . . . . . . 105
3.8.3.3. Time Zone Offset From . . . . . . . . . . . . . . 106
Desruisseaux Expires May 4, 2009 [Page 4]
Internet-Draft iCalendar October 2008
3.8.3.4. Time Zone Offset To . . . . . . . . . . . . . . . 107
3.8.3.5. Time Zone URL . . . . . . . . . . . . . . . . . . 108
3.8.4. Relationship Component Properties . . . . . . . . . . 108
3.8.4.1. Attendee . . . . . . . . . . . . . . . . . . . . 109
3.8.4.2. Contact . . . . . . . . . . . . . . . . . . . . . 111
3.8.4.3. Organizer . . . . . . . . . . . . . . . . . . . . 113
3.8.4.4. Recurrence ID . . . . . . . . . . . . . . . . . . 114
3.8.4.5. Related To . . . . . . . . . . . . . . . . . . . 116
3.8.4.6. Uniform Resource Locator . . . . . . . . . . . . 118
3.8.4.7. Unique Identifier . . . . . . . . . . . . . . . . 119
3.8.5. Recurrence Component Properties . . . . . . . . . . . 120
3.8.5.1. Exception Date/Times . . . . . . . . . . . . . . 120
3.8.5.2. Recurrence Date/Times . . . . . . . . . . . . . . 122
3.8.5.3. Recurrence Rule . . . . . . . . . . . . . . . . . 124
3.8.6. Alarm Component Properties . . . . . . . . . . . . . 134
3.8.6.1. Action . . . . . . . . . . . . . . . . . . . . . 134
3.8.6.2. Repeat Count . . . . . . . . . . . . . . . . . . 135
3.8.6.3. Trigger . . . . . . . . . . . . . . . . . . . . . 135
3.8.7. Change Management Component Properties . . . . . . . 138
3.8.7.1. Date/Time Created . . . . . . . . . . . . . . . . 138
3.8.7.2. Date/Time Stamp . . . . . . . . . . . . . . . . . 139
3.8.7.3. Last Modified . . . . . . . . . . . . . . . . . . 140
3.8.7.4. Sequence Number . . . . . . . . . . . . . . . . . 141
3.8.8. Miscellaneous Component Properties . . . . . . . . . 142
3.8.8.1. IANA Properties . . . . . . . . . . . . . . . . . 142
3.8.8.2. Non-standard Properties . . . . . . . . . . . . . 142
3.8.8.3. Request Status . . . . . . . . . . . . . . . . . 144
4. iCalendar Object Examples . . . . . . . . . . . . . . . . . . 147
5. Recommended Practices . . . . . . . . . . . . . . . . . . . . 152
6. Internationalization Considerations . . . . . . . . . . . . . 153
7. Security Considerations . . . . . . . . . . . . . . . . . . . 154
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 155
8.1. iCalendar Media Type Registration . . . . . . . . . . . . 155
8.2. New iCalendar Elements Registration . . . . . . . . . . . 158
8.2.1. iCalendar Elements Registration Procedure . . . . . . 158
8.2.2. Registration Template for Components . . . . . . . . 158
8.2.3. Registration Template for Properties . . . . . . . . 159
8.2.4. Registration Template for Parameters . . . . . . . . 160
8.2.5. Registration Template for Value Data Types . . . . . 160
8.2.6. Registration Template for Values . . . . . . . . . . 160
8.3. Initial iCalendar Elements Registries . . . . . . . . . . 161
8.3.1. Components Registry . . . . . . . . . . . . . . . . . 161
8.3.2. Properties Registry . . . . . . . . . . . . . . . . . 162
8.3.3. Parameters Registry . . . . . . . . . . . . . . . . . 164
8.3.4. Value Data Types Registry . . . . . . . . . . . . . . 166
8.3.5. Calendar User Types Registry . . . . . . . . . . . . 166
8.3.6. Free/Busy Time Types Registry . . . . . . . . . . . . 167
8.3.7. Participation Statuses Registry . . . . . . . . . . . 167
Desruisseaux Expires May 4, 2009 [Page 5]
Internet-Draft iCalendar October 2008
8.3.8. Relationship Types Registry . . . . . . . . . . . . . 168
8.3.9. Participation Roles Registry . . . . . . . . . . . . 168
8.3.10. Actions Registry . . . . . . . . . . . . . . . . . . 169
8.3.11. Classifications Registry . . . . . . . . . . . . . . 169
8.3.12. Methods Registry . . . . . . . . . . . . . . . . . . 169
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 170
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 171
10.1. Normative References . . . . . . . . . . . . . . . . . . 171
10.2. Informative References . . . . . . . . . . . . . . . . . 172
Appendix A. Differences from RFC 2445 . . . . . . . . . . . . . 175
A.1. New restrictions . . . . . . . . . . . . . . . . . . . . 175
A.2. Restrictions removed . . . . . . . . . . . . . . . . . . 175
A.3. Deprecated features . . . . . . . . . . . . . . . . . . . 175
Appendix B. Change Log (to be removed by RFC Editor prior to
publication) . . . . . . . . . . . . . . . . . . . . 176
B.1. Changes in -09 . . . . . . . . . . . . . . . . . . . . . 176
B.2. Changes in -08 . . . . . . . . . . . . . . . . . . . . . 176
B.3. Changes in -07 . . . . . . . . . . . . . . . . . . . . . 177
B.4. Changes in -06 . . . . . . . . . . . . . . . . . . . . . 179
B.5. Changes in -05 . . . . . . . . . . . . . . . . . . . . . 180
B.6. Changes in -04 . . . . . . . . . . . . . . . . . . . . . 181
B.7. Changes in -03 . . . . . . . . . . . . . . . . . . . . . 182
B.8. Changes in -02 . . . . . . . . . . . . . . . . . . . . . 183
B.9. Changes in -01 . . . . . . . . . . . . . . . . . . . . . 183
Desruisseaux Expires May 4, 2009 [Page 6]
Internet-Draft iCalendar October 2008
1. Introduction
The use of calendaring and scheduling has grown considerably in the
last decade. Enterprise and inter-enterprise business has become
dependent on rapid scheduling of events and actions using this
information technology. This memo is intended to progress the level
of interoperability possible between dissimilar calendaring and
scheduling applications. This memo defines a MIME content type for
exchanging electronic calendaring and scheduling information. The
Internet Calendaring and Scheduling Core Object Specification, or
iCalendar, allows for the capture and exchange of information
normally stored within a calendaring and scheduling application; such
as a Personal Information Manager (PIM) or a Group Scheduling
product.
The iCalendar format is suitable as an exchange format between
applications or systems. The format is defined in terms of a MIME
content type. This will enable the object to be exchanged using
several transports, including but not limited to SMTP, HTTP, a file
system, desktop interactive protocols such as the use of a memory-
based clipboard or drag/drop interactions, point-to-point
asynchronous communication, wired-network transport, or some form of
unwired transport such as infrared might also be used.
The memo also provides for the definition of iCalendar object methods
that will map this content type to a set of messages for supporting
calendaring and scheduling operations such as requesting, replying
to, modifying, and canceling meetings or appointments, to-dos and
journal entries. The iCalendar object methods can be used to define
other calendaring and scheduling operations such a requesting for and
replying with free/busy time data. Such a scheduling protocol is
defined in the iCalendar Transport-independent Interoperability
Protocol (iTIP) defined in [I-D.ietf-calsify-2446bis].
The memo also includes a formal grammar for the content type based on
the Internet ABNF defined in [RFC5234]. This ABNF is required for
the implementation of parsers and to serve as the definitive
reference when ambiguities or questions arise in interpreting the
descriptive prose definition of the memo. Additional restrictions
that could not easily be expressed with the ABNF syntax are specified
as comments in the ABNF. Comments with normative statements should
be treated as such.
Desruisseaux Expires May 4, 2009 [Page 7]
Internet-Draft iCalendar October 2008
2. Basic Grammar and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY" and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
This memo makes use of both a descriptive prose and a more formal
notation for defining the calendaring and scheduling format.
The notation used in this memo is the ABNF notation of [RFC5234].
Readers intending on implementing the format defined in this memo
should be familiar with this notation in order to properly interpret
the specifications of this memo.
All numeric values used in this memo are given in decimal notation.
All names of properties, property parameters, enumerated property
values and property parameter values are case-insensitive. However,
all other property values are case-sensitive, unless otherwise
stated.
Note: All indented editorial notes, such as this one, are intended
to provide the reader with additional information. The
information is not essential to the building of an implementation
conformant with this memo. The information is provided to
highlight a particular feature or characteristic of the memo.
The format for the iCalendar object is based on the syntax of the
text/directory media type [RFC2425]. While the iCalendar object is
not a profile of the text/directory media type [RFC2425], it does
reuse a number of the elements from the [RFC2425] specification.
2.1. Formatting Conventions
The elements defined in this memo are defined in prose. Many of the
terms used to describe these have common usage that is different than
the standards usage of this memo. In order to reference within this
memo elements of the calendaring and scheduling model, core object
(this memo) or interoperability protocol [I-D.ietf-calsify-2446bis]
some formatting conventions have been used. Calendaring and
scheduling roles are referred to in quoted-strings of text with the
first character of each word in upper case. For example, "Organizer"
refers to a role of a "Calendar User" within the scheduling protocol
defined by [I-D.ietf-calsify-2446bis]. Calendar components defined
by this memo are referred to with capitalized, quoted-strings of
text. All calendar components start with the letter "V". For
example, "VEVENT" refers to the event calendar component, "VTODO"
Desruisseaux Expires May 4, 2009 [Page 8]
Internet-Draft iCalendar October 2008
refers to the to-do calendar component and "VJOURNAL" refers to the
daily journal calendar component. Scheduling methods defined by iTIP
[I-D.ietf-calsify-2446bis] are referred to with capitalized, quoted-
strings of text. For example, "REQUEST" refers to the method for
requesting a scheduling calendar component be created or modified,
"REPLY" refers to the method a recipient of a request uses to update
their status with the "Organizer" of the calendar component.
The properties defined by this memo are referred to with capitalized,
quoted-strings of text, followed by the word "property". For
example, "ATTENDEE" property refers to the iCalendar property used to
convey the calendar address of a calendar user. Property parameters
defined by this memo are referred to with lowercase, quoted-strings
of text, followed by the word "parameter". For example, "value"
parameter refers to the iCalendar property parameter used to override
the default value type for a property value. Enumerated values
defined by this memo are referred to with capitalized text, either
alone or followed by the word "value". For example, the "MINUTELY"
value can be used with the "FREQ" component of the "RECUR" value type
to specify repeating components based on an interval of one minute or
more.
In this document, descriptions of characters are of the form
"character name (codepoint)", where "codepoint" is from the US-ASCII
character set. The "character name" is the authoritative
description; (codepoint) is a reference to that character in US-
ASCII.
2.2. Related Memos
Implementers will need to be familiar with several other memos that,
along with this memo, form a framework for Internet calendaring and
scheduling standards. This memo specifies a core specification of
objects, value types, properties and property parameters.
o iTIP [I-D.ietf-calsify-2446bis] specifies an interoperability
protocol for scheduling between different implementations;
o iMIP [I-D.ietf-calsify-rfc2447bis] specifies an Internet email
binding for [I-D.ietf-calsify-2446bis].
This memo does not attempt to repeat the specification of concepts or
definitions from these other memos. Where possible, references are
made to the memo that provides for the specification of these
concepts or definitions.
Desruisseaux Expires May 4, 2009 [Page 9]
Internet-Draft iCalendar October 2008
3. iCalendar Object Specification
The following sections define the details of a Calendaring and
Scheduling Core Object Specification. The Calendaring and Scheduling
Core Object is a collection of calendaring and scheduling
information. Typically, this information will consist of an
iCalendar stream with one or more iCalendar objects. The body of the
iCalendar object consists of a sequence of calendar properties and
one or more calendar components.
Section 3.1 defines the content line format; Section 3.2 defines the
property parameter format; Section 3.3 defines the data types for
property values; Section 3.4 defines the iCalendar object format;
Section 3.5 defines the iCalendar property format; Section 3.6
defines the calendar component format; Section 3.7 defines calendar
properties; and Section 3.8 defines calendar component properties.
This information is intended to be an integral part of the MIME
content type registration. In addition, this information can be used
independent of such content registration. In particular, this memo
has direct applicability for use as a calendaring and scheduling
exchange format in file-, memory- or network-based transport
mechanisms.
3.1. Content Lines
The iCalendar object is organized into individual lines of text,
called content lines. Content lines are delimited by a line break,
which is a CRLF sequence (US-ASCII decimal 13, followed by US-ASCII
decimal 10).
Lines of text SHOULD NOT be longer than 75 octets, excluding the line
break. Long content lines SHOULD be split into a multiple line
representations using a line "folding" technique. That is, a long
line can be split between any two characters by inserting a CRLF
immediately followed by a single linear white space character (i.e.,
SPACE, US-ASCII decimal 32 or HTAB, US-ASCII decimal 9). Any
sequence of CRLF followed immediately by a single linear white space
character is ignored (i.e., removed) when processing the content
type.
For example the line:
DESCRIPTION:This is a long description that exists on a long line.
Can be represented as:
Desruisseaux Expires May 4, 2009 [Page 10]
Internet-Draft iCalendar October 2008
DESCRIPTION:This is a lo
ng description
that exists on a long line.
The process of moving from this folded multiple line representation
to its single line representation is called "unfolding". Unfolding
is accomplished by removing the CRLF character and the linear white
space character that immediately follows.
When parsing a content line, folded lines MUST first be unfolded
according to the unfolding procedure described above.
Note: It is possible for very simple implementations to generate
improperly folded lines in the middle of a UTF-8 multi-octet
sequence. For this reason, implementations need to unfold lines
in such a way to properly restore the original sequence.
The content information associated with an iCalendar object is
formatted using a syntax similar to that defined by [RFC2425]. That
is, the content information consists of CRLF-separated content lines.
The following notation defines the lines of content in an iCalendar
object:
contentline = name *(";" param ) ":" value CRLF
; This ABNF is just a general definition for an initial parsing
; of the content line into its property name, parameter list,
; and value string
; When parsing a content line, folded lines MUST first
; be unfolded according to the unfolding procedure
; described above. When generating a content line, lines
; longer than 75 octets SHOULD be folded according to
; the folding procedure described above.
name = iana-token / x-name
iana-token = 1*(ALPHA / DIGIT / "-")
; iCalendar identifier registered with IANA
x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-")
; Reserved for experimental use.
vendorid = 3*(ALPHA / DIGIT)
; Vendor identification
param = param-name "=" param-value *("," param-value)
; Each property defines the specific ABNF for the parameters
Desruisseaux Expires May 4, 2009 [Page 11]
Internet-Draft iCalendar October 2008
; allowed on the property. Refer to specific properties for
; precise parameter ABNF.
param-name = iana-token / x-name
param-value = paramtext / quoted-string
paramtext = *SAFE-CHAR
value = *VALUE-CHAR
quoted-string = DQUOTE *QSAFE-CHAR DQUOTE
QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII
; Any character except CONTROL and DQUOTE
SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E
/ NON-US-ASCII
; Any character except CONTROL, DQUOTE, ";", ":", ","
VALUE-CHAR = WSP / %x21-7E / NON-US-ASCII
; Any textual character
NON-US-ASCII = UTF8-2 / UTF8-3 / UTF8-4
; UTF8-2, UTF8-3, and UTF8-4 are defined in [RFC3629]
CONTROL = %x00-08 / %x0A-1F / %x7F
; All the controls except HTAB
The property value component of a content line has a format that is
property specific. Refer to the section describing each property for
a definition of this format.
All names of properties, property parameters, enumerated property
values and property parameter values are case-insensitive. However,
all other property values are case-sensitive, unless otherwise
stated.
3.1.1. List and Field Separators
Some properties and parameters allow a list of values. Values in a
list of values MUST be separated by a COMMA character (US-ASCII
decimal 44). There is no significance to the order of values in a
list. For those parameter values (such as those that specify URI
values) that are specified in quoted-strings, the individual quoted-
strings are separated by a COMMA character (US-ASCII decimal 44).
Some property values are defined in terms of multiple parts. These
Desruisseaux Expires May 4, 2009 [Page 12]
Internet-Draft iCalendar October 2008
structured property values MUST have their value parts separated by a
SEMICOLON character (US-ASCII decimal 59).
Some properties allow a list of parameters. Each property parameter
in a list of property parameters MUST be separated by a SEMICOLON
character (US-ASCII decimal 59).
Property parameters with values containing a COLON character (US-
ASCII decimal 58), a SEMICOLON character (US-ASCII decimal 59) or a
COMMA character (US-ASCII decimal 44) MUST be placed in quoted text.
For example, in the following properties a SEMICOLON is used to
separate property parameters from each other, and a COMMA is used to
separate property values in a value list.
ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT:mailto:
jsmith@example.com
RDATE;VALUE=DATE:19970304,19970504,19970704,19970904
3.1.2. Multiple Values
Some properties defined in the iCalendar object can have multiple
values. The general rule for encoding multi-valued items is to
simply create a new content line for each value, including the
property name. However, it should be noted that some properties
support encoding multiple values in a single property by separating
the values with a COMMA character (US-ASCII decimal 44). Individual
property definitions should be consulted for determining whether a
specific property allows multiple values and in which of these two
forms. Multi-valued properties MUST NOT be used to specify multiple
language variants of the same value. Calendar applications SHOULD
display all values.
3.1.3. Binary Content
Binary content information in an iCalendar object SHOULD be
referenced using a URI within a property value. That is the binary
content information SHOULD be placed in an external MIME entity that
can be referenced by a URI from within the iCalendar object. In
applications where this is not feasible, binary content information
can be included within an iCalendar object, but only after first
encoding it into text using the "BASE64" encoding method defined in
[RFC4648]. Inline binary content SHOULD only be used in applications
whose special circumstances demand that an iCalendar object be
expressed as a single entity. A property containing inline binary
content information MUST specify the "ENCODING" property parameter.
Binary content information placed external to the iCalendar object
Desruisseaux Expires May 4, 2009 [Page 13]
Internet-Draft iCalendar October 2008
MUST be referenced by a uniform resource identifier (URI).
The following example specifies an "ATTACH" property that references
an attachment external to the iCalendar object with a URI reference:
ATTACH:http://example.com/public/quarterly-report.doc
The following example specifies an "ATTACH" property with inline
binary encoded content information:
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
<...remainder of "BASE64" encoded binary data...>
3.1.4. Character Set
There is not a property parameter to declare the charset used in a
property value. The default charset for an iCalendar stream is UTF-8
as defined in [RFC3629].
The "charset" Content-Type parameter MUST be used in MIME transports
to specify the charset being used.
3.2. Property Parameters
A property can have attributes associated with it. These "property
parameters" contain meta-information about the property or the
property value. Property parameters are provided to specify such
information as the location of an alternate text representation for a
property value, the language of a text property value, the value type
of the property value and other attributes.
Property parameter values that contain the COLON (US-ASCII decimal
58), SEMICOLON (US-ASCII decimal 59) or COMMA (US-ASCII decimal 44)
character separators MUST be specified as quoted-string text values.
Property parameter values MUST NOT contain the DQUOTE (US-ASCII
decimal 22) character. The DQUOTE (US-ASCII decimal 22) character is
used as a delimiter for parameter values that contain restricted
characters or URI text. For example:
DESCRIPTION;ALTREP="cid:part1.0001@example.org":The Fall'98 Wild
Wizards Conference - - Las Vegas\, NV\, USA
Property parameter values that are not in quoted strings are case
insensitive.
The general property parameters defined by this memo are defined by
Desruisseaux Expires May 4, 2009 [Page 14]
Internet-Draft iCalendar October 2008
the following notation:
icalparameter = altrepparam ; Alternate text representation
/ cnparam ; Common name
/ cutypeparam ; Calendar user type
/ delfromparam ; Delegator
/ deltoparam ; Delegatee
/ dirparam ; Directory entry
/ encodingparam ; Inline encoding
/ fmttypeparam ; Format type
/ fbtypeparam ; Free/busy time type
/ languageparam ; Language for text
/ memberparam ; Group or list membership
/ partstatparam ; Participation status
/ rangeparam ; Recurrence identifier range
/ trigrelparam ; Alarm trigger relationship
/ reltypeparam ; Relationship type
/ roleparam ; Participation role
/ rsvpparam ; RSVP expectation
/ sentbyparam ; Sent by
/ tzidparam ; Reference to time zone object
/ valuetypeparam ; Property value data type
/ other-param
other-param = (iana-param / x-param)
iana-param = iana-token "=" param-value *("," param-value)
; Some other IANA registered iCalendar parameter.
x-param = x-name "=" param-value *("," param-value)
; A non-standard, experimental parameter.
Applications MUST ignore x-param and iana-param value they don't
recognized.
3.2.1. Alternate Text Representation
Parameter Name: ALTREP
Purpose: To specify an alternate text representation for the
property value.
Format Definition: This property parameter is defined by the
following notation:
altrepparam = "ALTREP" "=" DQUOTE uri DQUOTE
Desruisseaux Expires May 4, 2009 [Page 15]
Internet-Draft iCalendar October 2008
Description: This parameter specifies a URI that points to an
alternate representation for a textual property value. A property
specifying this parameter MUST also include a value that reflects
the default representation of the text value. The URI parameter
value MUST be specified in a quoted-string.
Note: While there is no restriction imposed on the URI schemes
allowed for this parameter, CID [RFC2392], HTTP [RFC2616], and
HTTPS [RFC2818] are the URI schemes most commonly used by
current implementations.
Example:
DESCRIPTION;ALTREP="CID:part3.msg.970415T083000@example.com":
Project XYZ Review Meeting will include the following agenda
items: (a) Market Overview\, (b) Finances\, (c) Project Man
agement
The "ALTREP" property parameter value might point to a "text/html"
content portion.
Content-Type:text/html
Content-Id:<part3.msg.970415T083000@example.com>
<html>
<head>
<title></title>
</head>
<body>
<p>
<b>Project XYZ Review Meeting</b> will include
the following agenda items:
<ol>
<li>Market Overview</li>
<li>Finances</li>
<li>Project Management</li>
</ol>
</p>
</body>
</html>
3.2.2. Common Name
Parameter Name: CN
Desruisseaux Expires May 4, 2009 [Page 16]
Internet-Draft iCalendar October 2008
Purpose: To specify the common name to be associated with the
calendar user specified by the property.
Format Definition: This property parameter is defined by the
following notation:
cnparam = "CN" "=" param-value
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter specifies the common name
to be associated with the calendar user specified by the property.
The parameter value is text. The parameter value can be used for
display text to be associated with the calendar address specified
by the property.
Example:
ORGANIZER;CN="John Smith":mailto:jsmith@example.com
3.2.3. Calendar User Type
Parameter Name: CUTYPE
Purpose: To specify the type of calendar user specified by the
property.
Format Definition: This property parameter is defined by the
following notation:
cutypeparam = "CUTYPE" "="
("INDIVIDUAL" ; An individual
/ "GROUP" ; A group of individuals
/ "RESOURCE" ; A physical resource
/ "ROOM" ; A room resource
/ "UNKNOWN" ; Otherwise not known
/ x-name ; Experimental type
/ iana-token) ; Other IANA registered
; type
; Default is INDIVIDUAL
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter identifies the type of
calendar user specified by the property. If not specified on a
property that allows this parameter, the default is INDIVIDUAL.
Applications MUST treat x-name and iana-token value they don't
recognized the same way as they would the UNKNOWN value.
Desruisseaux Expires May 4, 2009 [Page 17]
Internet-Draft iCalendar October 2008
Example:
ATTENDEE;CUTYPE=GROUP:mailto:ietf-calsch@example.org
3.2.4. Delegators
Parameter Name: DELEGATED-FROM
Purpose: To specify the calendar users that have delegated their
participation to the calendar user specified by the property.
Format Definition: This property parameter is defined by the
following notation:
delfromparam = "DELEGATED-FROM" "=" DQUOTE cal-address
DQUOTE *("," DQUOTE cal-address DQUOTE)
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. This parameter specifies those calendar
users that have delegated their participation in a group scheduled
event or to-do to the calendar user specified by the property.
The individual calendar address parameter values MUST each be
specified in a quoted-string.
Example:
ATTENDEE;DELEGATED-FROM="mailto:jsmith@example.com":mailto:
jdoe@example.com
3.2.5. Delegatees
Parameter Name: DELEGATED-TO
Purpose: To specify the calendar users to whom the calendar user
specified by the property has delegated participation.
Format Definition: This property parameter is defined by the
following notation:
deltoparam = "DELEGATED-TO" "=" DQUOTE cal-address DQUOTE
*("," DQUOTE cal-address DQUOTE)
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. This parameter specifies those calendar
users whom have been delegated participation in a group scheduled
event or to-do by the calendar user specified by the property.
The individual calendar address parameter values MUST each be
specified in a quoted-string.
Desruisseaux Expires May 4, 2009 [Page 18]
Internet-Draft iCalendar October 2008
Example:
ATTENDEE;DELEGATED-TO="mailto:jdoe@example.com","mailto:jqpublic
@example.com":mailto:jsmith@example.com
3.2.6. Directory Entry Reference
Parameter Name: DIR
Purpose: To specify reference to a directory entry associated with
the calendar user specified by the property.
Format Definition: This property parameter is defined by the
following notation:
dirparam = "DIR" "=" DQUOTE uri DQUOTE
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter specifies a reference to
the directory entry associated with the calendar user specified by
the property. The parameter value SHOULD be a CID [RFC2392], DATA
[RFC2397], FILE [RFC1738], FTP [RFC1738], HTTP [RFC2616], HTTPS
[RFC2818], LDAP [RFC4516], or MID [RFC2392] URI. The URI
parameter value MUST be specified in a quoted-string.
Example:
ORGANIZER;DIR="ldap://example.com:6666/o=ABC%20Industries,
c=US???(cn=Jim%20Dolittle)":mailto:jimdo@example.com
3.2.7. Inline Encoding
Parameter Name: ENCODING
Purpose: To specify an alternate inline encoding for the property
value.
Format Definition: This property parameter is defined by the
following notation:
encodingparam = "ENCODING" "="
( "8BIT"
; "8bit" text encoding is defined in [RFC2045]
/ "BASE64"
; "BASE64" binary encoding format is defined in [RFC4648]
)
Desruisseaux Expires May 4, 2009 [Page 19]
Internet-Draft iCalendar October 2008
Description: This property parameter identifies the inline encoding
used in a property value. The default encoding is "8BIT",
corresponding to a property value consisting of text. The
"BASE64" encoding type corresponds to a property value encoded
using the "BASE64" encoding defined in [RFC2045].
If the value type parameter is ";VALUE=BINARY", then the inline
encoding parameter MUST be specified with the value
";ENCODING=BASE64".
Example:
ATTACH;FMTYPE=image/jpeg;ENCODING=BASE64;VALUE=BINARY:MIICajC
CAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDA
qBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRw
<...remainder of "BASE64" encoded binary data...>
3.2.8. Format Type
Parameter Name: FMTTYPE
Purpose: To specify the content type of a referenced object.
Format Definition: This property parameter is defined by the
following notation:
fmttypeparam = "FMTTYPE" "=" type "/" subtype *(";" parameter)
; Where "type", "subtype", and "parameter"
; are defined in section 5.1 of [RFC2045]
Description: This parameter can be specified on properties that are
used to reference an object. The parameter specifies the content
type of the referenced object. For example, on the "ATTACH"
property, a FTP type URI value does not, by itself, necessarily
convey the type of content associated with the resource. The
parameter value MUST be the text for either an IANA registered
media type or a non-standard media type.
Example:
ATTACH;FMTTYPE=application/msword:ftp://example.com/pub/docs/
agenda.doc
3.2.9. Free/Busy Time Type
Desruisseaux Expires May 4, 2009 [Page 20]
Internet-Draft iCalendar October 2008
Parameter Name: FBTYPE
Purpose: To specify the free or busy time type.
Format Definition: This property parameter is defined by the
following notation:
fbtypeparam = "FBTYPE" "=" ("FREE" / "BUSY"
/ "BUSY-UNAVAILABLE" / "BUSY-TENTATIVE"
/ x-name
; Some experimental iCalendar free busy type.
/ iana-token)
; Some other IANA registered iCalendar free busy type.
Description: This parameter specifies the free or busy time type.
The value FREE indicates that the time interval is free for
scheduling. The value BUSY indicates that the time interval is
busy because one or more events have been scheduled for that
interval. The value BUSY-UNAVAILABLE indicates that the time
interval is busy and that the interval can not be scheduled. The
value BUSY-TENTATIVE indicates that the time interval is busy
because one or more events have been tentatively scheduled for
that interval. If not specified on a property that allows this
parameter, the default is BUSY. Applications MUST treat x-name
and iana-token value they don't recognized the same way as they
would the BUSY value.
Example: The following is an example of this parameter on a
"FREEBUSY" property.
FREEBUSY;FBTYPE=BUSY:19980415T133000Z/19980415T170000Z
3.2.10. Language
Parameter Name: LANGUAGE
Purpose: To specify the language for text values in a property or
property parameter.
Format Definition: This property parameter is defined by the
following notation:
languageparam = "LANGUAGE" "=" language
language = Language-Tag
; As defined in [RFC4646]
Desruisseaux Expires May 4, 2009 [Page 21]
Internet-Draft iCalendar October 2008
Description: This parameter identifies the language of the text in
the property value and of all property parameter values of the
property. The value of the "LANGUAGE" property parameter is that
defined in [RFC4646].
For transport in a MIME entity, the Content-Language header field
can be used to set the default language for the entire body part.
Otherwise, no default language is assumed.
Example: The following are examples of this parameter on the
"SUMMARY" and "LOCATION" properties:
SUMMARY;LANGUAGE=en-US:Company Holiday Party
LOCATION;LANGUAGE=en:Germany
LOCATION;LANGUAGE=no:Tyskland
3.2.11. Group or List Membership
Parameter Name: MEMBER
Purpose: To specify the group or list membership of the calendar
user specified by the property.
Format Definition: This property parameter is defined by the
following notation:
memberparam = "MEMBER" "=" DQUOTE cal-address DQUOTE
*("," DQUOTE cal-address DQUOTE)
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter identifies the groups or
list membership for the calendar user specified by the property.
The parameter value is either a single calendar address in a
quoted-string or a COMMA character (US-ASCII decimal 44) separated
list of calendar addresses, each in a quoted-string. The
individual calendar address parameter values MUST each be
specified in a quoted-string.
Example:
ATTENDEE;MEMBER="mailto:ietf-calsch@example.org":mailto:
jsmith@example.com
ATTENDEE;MEMBER="mailto:projectA@example.com","mailto:pr
ojectB@example.com":mailto:janedoe@example.com
Desruisseaux Expires May 4, 2009 [Page 22]
Internet-Draft iCalendar October 2008
3.2.12. Participation Status
Parameter Name: PARTSTAT
Purpose: To specify the participation status for the calendar user
specified by the property.
Format Definition: This property parameter is defined by the
following notation:
partstatparam = "PARTSTAT" "="
(partstat-event
/ partstat-todo
/ partstat-jour)
partstat-event = ("NEEDS-ACTION" ; Event needs action
/ "ACCEPTED" ; Event accepted
/ "DECLINED" ; Event declined
/ "TENTATIVE" ; Event tentatively
; accepted
/ "DELEGATED" ; Event delegated
/ x-name ; Experimental status
/ iana-token) ; Other IANA registered
; status
; These are the participation statuses for a "VEVENT".
; Default is NEEDS-ACTION.
partstat-todo = ("NEEDS-ACTION" ; To-do needs action
/ "ACCEPTED" ; To-do accepted
/ "DECLINED" ; To-do declined
/ "TENTATIVE" ; To-do tentatively
; accepted
/ "DELEGATED" ; To-do delegated
/ "COMPLETED" ; To-do completed.
; COMPLETED property has
; date/time completed.
/ "IN-PROCESS" ; To-do in process of
; being completed
/ x-name ; Experimental status
/ iana-token) ; Other IANA registered
; status
; These are the participation statuses for a "VTODO".
; Default is NEEDS-ACTION.
Desruisseaux Expires May 4, 2009 [Page 23]
Internet-Draft iCalendar October 2008
partstat-jour = ("NEEDS-ACTION" ; Journal needs action
/ "ACCEPTED" ; Journal accepted
/ "DECLINED" ; Journal declined
/ x-name ; Experimental status
/ iana-token) ; Other IANA registered
; status
; These are the participation statuses for a "VJOURNAL".
; Default is NEEDS-ACTION.
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter identifies the
participation status for the calendar user specified by the
property value. The parameter values differ depending on whether
they are associated with a group scheduled "VEVENT", "VTODO" or
"VJOURNAL". The values MUST match one of the values allowed for
the given calendar component. If not specified on a property that
allows this parameter, the default value is NEEDS-ACTION.
Applications MUST treat x-name and iana-token value they don't
recognized the same way as they would the NEEDS-ACTION value.
Example:
ATTENDEE;PARTSTAT=DECLINED:mailto:jsmith@example.com
3.2.13. Recurrence Identifier Range
Parameter Name: RANGE
Purpose: To specify the effective range of recurrence instances from
the instance specified by the recurrence identifier specified by
the property.
Format Definition: This property parameter is defined by the
following notation:
rangeparam = "RANGE" "=" "THISANDFUTURE"
; To specify the instance specified by the recurrence identifier
; and all subsequent recurrence instances
Description: This parameter can be specified on a property that
specifies a recurrence identifier. The parameter specifies the
effective range of recurrence instances that is specified by the
property. The effective range is from the recurrence identifier
specified by the property. If this parameter is not specified on
an allowed property, then the default range is the single instance
specified by the recurrence identifier value of the property. The
parameter value can only be "THISANDFUTURE" to indicate a range
defined by the recurrence identifier and all subsequent instances.
Desruisseaux Expires May 4, 2009 [Page 24]
Internet-Draft iCalendar October 2008
Note: The value "THISANDPRIOR" is deprecated by this revision
of iCalendar and MUST NOT be generated by applications.
Example:
RECURRENCE-ID;RANGE=THISANDFUTURE:19980401T133000Z
3.2.14. Alarm Trigger Relationship
Parameter Name: RELATED
Purpose: To specify the relationship of the alarm trigger with
respect to the start or end of the calendar component.
Format Definition: This property parameter is defined by the
following notation:
trigrelparam = "RELATED" "="
("START" ; Trigger off of start
/ "END") ; Trigger off of end
Description: This parameter can be specified on properties that
specify an alarm trigger with a "DURATION" value type. The
parameter specifies whether the alarm will trigger relative to the
start or end of the calendar component. The parameter value START
will set the alarm to trigger off the start of the calendar
component; the parameter value END will set the alarm to trigger
off the end of the calendar component. If the parameter is not
specified on an allowable property, then the default is START.
Example:
TRIGGER;RELATED=END:PT5M
3.2.15. Relationship Type
Parameter Name: RELTYPE
Purpose: To specify the type of hierarchical relationship associated
with the calendar component specified by the property.
Format Definition: This property parameter is defined by the
following notation:
Desruisseaux Expires May 4, 2009 [Page 25]
Internet-Draft iCalendar October 2008
reltypeparam = "RELTYPE" "="
("PARENT" ; Parent relationship. Default.
/ "CHILD" ; Child relationship
/ "SIBLING" ; Sibling relationship
/ iana-token ; Some other IANA registered
; iCalendar relationship type
/ x-name) ; A non-standard, experimental
; relationship type
Description: This parameter can be specified on a property that
references another related calendar. The parameter specifies the
hierarchical relationship type of the calendar component
referenced by the property. The parameter value can be PARENT, to
indicate that the referenced calendar component is a superior of
calendar component; CHILD to indicate that the referenced calendar
component is a subordinate of the calendar component; SIBLING to
indicate that the referenced calendar component is a peer of the
calendar component. If this parameter is not specified on an
allowable property, the default relationship type is PARENT.
Applications MUST treat x-name and iana-token value they don't
recognized the same way as they would the PARENT value.
Example:
RELATED-TO;RELTYPE=SIBLING:19960401-080045-4000F192713@
example.com
3.2.16. Participation Role
Parameter Name: ROLE
Purpose: To specify the participation role for the calendar user
specified by the property.
Format Definition: This property parameter is defined by the
following notation:
Desruisseaux Expires May 4, 2009 [Page 26]
Internet-Draft iCalendar October 2008
roleparam = "ROLE" "="
("CHAIR" ; Indicates chair of the
; calendar entity
/ "REQ-PARTICIPANT" ; Indicates a participant whose
; participation is required
/ "OPT-PARTICIPANT" ; Indicates a participant whose
; participation is optional
/ "NON-PARTICIPANT" ; Indicates a participant who
; is copied for information
; purposes only
/ x-name ; Experimental role
/ iana-token) ; Other IANA role
; Default is REQ-PARTICIPANT
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter specifies the participation
role for the calendar user specified by the property in the group
schedule calendar component. If not specified on a property that
allows this parameter, the default value is REQ-PARTICIPANT.
Applications MUST treat x-name and iana-token value they don't
recognized the same way as they would the REQ-PARTICIPANT value.
Example:
ATTENDEE;ROLE=CHAIR:mailto:mrbig@example.com
3.2.17. RSVP Expectation
Parameter Name: RSVP
Purpose: To specify whether there is an expectation of a favor of a
reply from the calendar user specified by the property value.
Format Definition: This property parameter is defined by the
following notation:
rsvpparam = "RSVP" "=" ("TRUE" / "FALSE")
; Default is FALSE
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter identifies the expectation
of a reply from the calendar user specified by the property value.
This parameter is used by the "Organizer" to request a
participation status reply from an "Attendee" of a group scheduled
event or to-do. If not specified on a property that allows this
parameter, the default value is FALSE.
Desruisseaux Expires May 4, 2009 [Page 27]
Internet-Draft iCalendar October 2008
Example:
ATTENDEE;RSVP=TRUE:mailto:jsmith@example.com
3.2.18. Sent By
Parameter Name: SENT-BY
Purpose: To specify the calendar user that is acting on behalf of
the calendar user specified by the property.
Format Definition: This property parameter is defined by the
following notation:
sentbyparam = "SENT-BY" "=" DQUOTE cal-address DQUOTE
Description: This parameter can be specified on properties with a
CAL-ADDRESS value type. The parameter specifies the calendar user
that is acting on behalf of the calendar user specified by the
property. The parameter value MUST be a mailto URI as defined in
[RFC2368]. The individual calendar address parameter values MUST
each be specified in a quoted-string.
Example:
ORGANIZER;SENT-BY="mailto:sray@example.com":mailto:
jsmith@example.com
3.2.19. Time Zone Identifier
Parameter Name: TZID
Purpose: To specify the identifier for the time zone definition for
a time component in the property value.
Format Definition: This property parameter is defined by the
following notation:
tzidparam = "TZID" "=" [tzidprefix] paramtext
tzidprefix = "/"
Description: This parameter MUST be specified on the "DTSTART",
"DTEND", "DUE", "EXDATE" and "RDATE" properties when either a
DATE-TIME or TIME value type is specified and when the value is
not either a UTC or a "floating" time. Refer to the DATE-TIME or
TIME value type definition for a description of UTC and "floating
time" formats. This property parameter specifies a text value
Desruisseaux Expires May 4, 2009 [Page 28]
Internet-Draft iCalendar October 2008
which uniquely identifies the "VTIMEZONE" calendar component to be
used when evaluating the time portion of the property. The value
of the "TZID" property parameter will be equal to the value of the
"TZID" property for the matching time zone definition. An
individual "VTIMEZONE" calendar component MUST be specified for
each unique "TZID" parameter value specified in the iCalendar
object.
The parameter MUST be specified on properties with a DATE-TIME
value if the DATE-TIME is not either a UTC or a "floating" time.
The presence of the SOLIDUS character (US-ASCII decimal 47) as a
prefix, indicates that this "TZID" represents a unique ID in a
globally defined time zone registry (when such registry is
defined).
Note: This document does not define a naming convention for
time zone identifiers. Implementers may want to use the naming
conventions defined in existing time zone specifications such
as the public-domain TZ database [TZDB]. The specification of
globally unique time zone identifiers is not addressed by this
document and is left for future study.
The following are examples of this property parameter:
DTSTART;TZID=America/New_York:19980119T020000
DTEND;TZID=America/New_York:19980119T030000
The "TZID" property parameter MUST NOT be applied to DATE
properties, and DATE-TIME or TIME properties whose time values are
specified in UTC.
The use of local time in a DATE-TIME or TIME value without the
"TZID" property parameter is to be interpreted as a local time
value, regardless of the existence of "VTIMEZONE" calendar
components in the iCalendar object.
For more information see the sections on the value types DATE-TIME
and TIME.
3.2.20. Value Data Types
Parameter Name: VALUE
Desruisseaux Expires May 4, 2009 [Page 29]
Internet-Draft iCalendar October 2008
Purpose: To explicitly specify the value type format for a property
value.
Format Definition: This property parameter is defined by the
following notation:
valuetypeparam = "VALUE" "=" valuetype
valuetype = ("BINARY"
/ "BOOLEAN"
/ "CAL-ADDRESS"
/ "DATE"
/ "DATE-TIME"
/ "DURATION"
/ "FLOAT"
/ "INTEGER"
/ "PERIOD"
/ "RECUR"
/ "TEXT"
/ "TIME"
/ "URI"
/ "UTC-OFFSET"
/ x-name
; Some experimental iCalendar value type.
/ iana-token)
; Some other IANA registered iCalendar value type.
Description: This parameter specifies the value type and format of
the property value. The property values MUST be of a single value
type. For example, a "RDATE" property cannot have a combination
of DATE-TIME and TIME value types.
If the property's value is the default value type, then this
parameter need not be specified. However, if the property's
default value type is overridden by some other allowable value
type, then this parameter MUST be specified.
Applications MUST preserve the value data for x-name and iana-
token values that they don't recognize without attempting to
interpret or parse the value data.
3.3. Property Value Data Types
The properties in an iCalendar object are strongly typed. The
definition of each property restricts the value to be one of the
value data types, or simply value types, defined in this section.
The value type for a property will either be specified implicitly as
the default value type or will be explicitly specified with the
Desruisseaux Expires May 4, 2009 [Page 30]
Internet-Draft iCalendar October 2008
"VALUE" parameter. If the value type of a property is one of the
alternate valid types, then it MUST be explicitly specified with the
"VALUE" parameter.
3.3.1. Binary
Value Name: BINARY
Purpose: This value type is used to identify properties that contain
a character encoding of inline binary data. For example, an
inline attachment of a document might be included in an iCalendar
object.
Format Definition: This value type is defined by the following
notation:
binary = *(4b-char) [b-end]
; A "BASE64" encoded character string, as defined by [RFC4648].
b-end = (2b-char "==") / (3b-char "=")
b-char = ALPHA / DIGIT / "+" / "/"
Description: Property values with this value type MUST also include
the inline encoding parameter sequence of ";ENCODING=BASE64".
That is, all inline binary data MUST first be character encoded
using the "BASE64" encoding method defined in [RFC2045]. No
additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
Example: The following is an abridged example of a "BASE64" encoded
binary value data.
JKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlI
ENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZv
<...remainder of "BASE64" encoded binary data...>
3.3.2. Boolean
Value Name: BOOLEAN
Purpose: This value type is used to identify properties that contain
either a "TRUE" or "FALSE" Boolean value.
Format Definition: This value type is defined by the following
notation:
boolean = "TRUE" / "FALSE"
Desruisseaux Expires May 4, 2009 [Page 31]
Internet-Draft iCalendar October 2008
Description: These values are case insensitive text. No additional
content value encoding (i.e., BACKSLASH character encoding, see
Section 3.3.11) is defined for this value type.
Example: The following is an example of a hypothetical property that
has a BOOLEAN value type:
TRUE
3.3.3. Calendar User Address
Value Name: CAL-ADDRESS
Purpose: This value type is used to identify properties that contain
a calendar user address.
Format Definition: This value type is defined by the following
notation:
cal-address = uri
Description: The value is a URI as defined by [RFC3986] or any other
IANA registered form for a URI. When used to address an Internet
email transport address for a calendar user, the value MUST be a
mailto URI, as defined by [RFC2368]. No additional content value
encoding (i.e., BACKSLASH character encoding, see Section 3.3.11)
is defined for this value type.
Example:
mailto:jane_doe@example.com
3.3.4. Date
Value Name: DATE
Purpose: This value type is used to identify values that contain a
calendar date.
Format Definition: This value type is defined by the following
notation:
date = date-value
date-value = date-fullyear date-month date-mday
date-fullyear = 4DIGIT
date-month = 2DIGIT ;01-12
date-mday = 2DIGIT ;01-28, 01-29, 01-30, 01-31
Desruisseaux Expires May 4, 2009 [Page 32]
Internet-Draft iCalendar October 2008
;based on month/year
Description: If the property permits, multiple "date" values are
specified as a COMMA character (US-ASCII decimal 44) separated
list of values. The format for the value type is based on the
[ISO.8601.2004] complete representation, basic format for a
calendar date. The textual format specifies a four-digit year,
two-digit month, and two-digit day of the month. There are no
separator characters between the year, month and day component
text.
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
Example: The following represents July 14, 1997:
19970714
3.3.5. Date-Time
Value Name: DATE-TIME
Purpose: This value type is used to identify values that specify a
precise calendar date and time of day.
Format Definition: This value type is defined by the following
notation:
date-time = date "T" time ;As specified in the date and time
;value definitions
Description: If the property permits, multiple "date-time" values
are specified as a COMMA character (US-ASCII decimal 44) separated
list of values. No additional content value encoding (i.e.,
BACKSLASH character encoding, see Section 3.3.11) is defined for
this value type.
The "DATE-TIME" value type is used to identify values that contain
a precise calendar date and time of day. The format is based on
the [ISO.8601.2004] complete representation, basic format for a
calendar date and time of day. The text format is a concatenation
of the "date", followed by the LATIN CAPITAL LETTER T character
(US-ASCII decimal 84) time designator, followed by the "time"
format.
Desruisseaux Expires May 4, 2009 [Page 33]
Internet-Draft iCalendar October 2008
The "DATE-TIME" value type expresses time values in three forms:
The form of date and time with UTC offset MUST NOT be used. For
example, the following is not valid for a date-time value:
19980119T230000-0800 ;Invalid time format
FORM #1: DATE WITH LOCAL TIME
The date with local time form is simply a date-time value that
does not contain the UTC designator nor does it reference a time
zone. For example, the following represents January 18, 1998, at
11 PM:
19980118T230000
Date-time values of this type are said to be "floating" and are
not bound to any time zone in particular. They are used to
represent the same hour, minute, and second value regardless of
which time zone is currently being observed. For example, an
event can be defined that indicates that an individual will be
busy from 11:00 AM to 1:00 PM every day, no matter which time zone
the person is in. In these cases, a local time can be specified.
The recipient of an iCalendar object with a property value
consisting of a local time, without any relative time zone
information, SHOULD interpret the value as being fixed to whatever
time zone the "ATTENDEE" is in at any given moment. This means
that two "Attendees", in different time zones, receiving the same
event definition as a floating time, may be participating in the
event at different actual times. Floating time SHOULD only be
used where that is the reasonable behavior.
In most cases, a fixed time is desired. To properly communicate a
fixed time in a property value, either UTC time or local time with
time zone reference MUST be specified.
The use of local time in a DATE-TIME value without the "TZID"
property parameter is to be interpreted as floating time,
regardless of the existence of "VTIMEZONE" calendar components in
the iCalendar object.
FORM #2: DATE WITH UTC TIME
The date with UTC time, or absolute time, is identified by a LATIN
CAPITAL LETTER Z suffix character (US-ASCII decimal 90), the UTC
designator, appended to the time value. For example, the
following represents January 19, 1998, at 0700 UTC:
Desruisseaux Expires May 4, 2009 [Page 34]
Internet-Draft iCalendar October 2008
19980119T070000Z
The "TZID" property parameter MUST NOT be applied to DATE-TIME
properties whose time values are specified in UTC.
FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE
The date and local time with reference to time zone information is
identified by the use the "TZID" property parameter to reference
the appropriate time zone definition. "TZID" is discussed in
detail in Section 3.2.19. For example, the following represents
2:00 A.M. in New York on Janurary 19, 1998:
TZID=America/New_York:19980119T020000
If, based on the definition of the referenced time zone, the local
time described occurs more than once (when changing from daylight
to standard time), the DATE-TIME value refers to the first
occurence of the referenced time. Thus, TZID=America/
New_York:20071104T013000 indicates November 4, 2007 at 1:30 A.M.
EDT (UTC-04:00). If the local time described does not occur (when
changing from standard to daylight time), the DATE-TIME value is
interpreted using the UTC offset before the gap in local times.
Thus, TZID=America/New_York:20070311T023000 indicates March 11,
2007 at 3:30 A.M. EDT (UTC-04:00), one hour after 1:30 A.M. EST
(UTC-05:00).
A time value MUST only specify the second 60 when specifying a
positive leap second. For example:
19970630T235960Z
Implementations which do not support leap seconds SHOULD interpret
the second 60 as equivalent to the second 59.
Example: The following represents July 14, 1997, at 1:30 PM in New
York City in each of the three time formats, using the "DTSTART"
property.
DTSTART:19970714T133000 ; Local time
DTSTART:19970714T173000Z ; UTC time
DTSTART;TZID=America/New_York:19970714T133000
; Local time and time
; zone reference
Desruisseaux Expires May 4, 2009 [Page 35]
Internet-Draft iCalendar October 2008
3.3.6. Duration
Value Name: DURATION
Purpose: This value type is used to identify properties that contain
a duration of time.
Format Definition: This value type is defined by the following
notation:
dur-value = (["+"] / "-") "P" (dur-date / dur-time / dur-week)
dur-date = dur-day [dur-time]
dur-time = "T" (dur-hour / dur-minute / dur-second)
dur-week = 1*DIGIT "W"
dur-hour = 1*DIGIT "H" [dur-minute]
dur-minute = 1*DIGIT "M" [dur-second]
dur-second = 1*DIGIT "S"
dur-day = 1*DIGIT "D"
Description: If the property permits, multiple "duration" values are
specified by a COMMA character (US-ASCII decimal 44) separated
list of values. The format is based on the [ISO.8601.2004]
complete representation basic format with designators for the
duration of time. The format can represent nominal durations
(weeks and days) and accurate durations (hours, minutes, and
seconds). Note that unlike [ISO.8601.2004] this value type
doesn't support the "Y" and "M" designators to specify durations
in terms of years and months.
The duration of a week or a day depends on its position in the
calendar. In the case of discontinuities in the time scale, such
as the change from standard time to daylight time and back, the
computation of the exact duration requires the substraction or
addition of the change of duration of the discontinuity. Leap
seconds MUST NOT be considered when computing an exact duration.
When computing an exact duration, the greatest order time
components MUST be added first, that is, the number of days MUST
be added first, followed by the number of hours, number of
minutes, and number of seconds.
Negative durations are typically used to schedule an alarm to
trigger before an associated time (see Section 3.8.6.3).
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) are defined for this value type.
Desruisseaux Expires May 4, 2009 [Page 36]
Internet-Draft iCalendar October 2008
Example: A duration of 15 days, 5 hours and 20 seconds would be:
P15DT5H0M20S
A duration of 7 weeks would be:
P7W
3.3.7. Float
Value Name: FLOAT
Purpose: This value type is used to identify properties that contain
a real number value.
Format Definition: This value type is defined by the following
notation:
float = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]
Description: If the property permits, multiple "float" values are
specified by a COMMA character (US-ASCII decimal 44) separated
list of values.
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
Example:
1000000.0000001
1.333
-3.14
3.3.8. Integer
Value Name: INTEGER
Purpose: This value type is used to identify properties that contain
a signed integer value.
Format Definition: This value type is defined by the following
notation:
integer = (["+"] / "-") 1*DIGIT
Desruisseaux Expires May 4, 2009 [Page 37]
Internet-Draft iCalendar October 2008
Description: If the property permits, multiple "integer" values are
specified by a COMMA character (US-ASCII decimal 44) separated
list of values. The valid range for "integer" is -2147483648 to
2147483647. If the sign is not specified, then the value is
assumed to be positive.
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
Example:
1234567890
-1234567890
+1234567890
432109876
3.3.9. Period of Time
Value Name: PERIOD
Purpose: This value type is used to identify values that contain a
precise period of time.
Format Definition: This value type is defined by the following
notation:
period = period-explicit / period-start
period-explicit = date-time "/" date-time
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and end. The start MUST
; be before the end.
period-start = date-time "/" dur-value
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and positive duration
; of time.
Description: If the property permits, multiple "period" values are
specified by a COMMA character (US-ASCII decimal 44) separated
list of values. There are two forms of a period of time. First,
a period of time is identified by its start and its end. This
format is based on the [ISO.8601.2004] complete representation,
basic format for "DATE-TIME" start of the period, followed by a
SOLIDUS character (US-ASCII decimal 47), followed by the "DATE-
TIME" of the end of the period. The start of the period MUST be
before the end of the period. Second, a period of time can also
be defined by a start and a positive duration of time. The format
Desruisseaux Expires May 4, 2009 [Page 38]
Internet-Draft iCalendar October 2008
is based on the [ISO.8601.2004] complete representation, basic
format for the "DATE-TIME" start of the period, followed by a
SOLIDUS character (US-ASCII decimal 47), followed by the
[ISO.8601.2004] basic format for "DURATION" of the period.
Example: The period starting at 18:00:00 UTC, on January 1, 1997 and
ending at 07:00:00 UTC on January 2, 1997 would be:
19970101T180000Z/19970102T070000Z
The period start at 18:00:00 on January 1, 1997 and lasting 5
hours and 30 minutes would be:
19970101T180000Z/PT5H30M
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
3.3.10. Recurrence Rule
Value Name: RECUR
Purpose: This value type is used to identify properties that contain
a recurrence rule specification.
Format Definition: This value type is defined by the following
notation:
recur = recur-rule-part *( ";" recur-rule-part )
;
; The rule parts are not ordered in any
; particular sequence
;
; The FREQ rule part is REQUIRED,
; but MUST NOT occur more than once
;
; The UNTIL or COUNT rule parts are OPTIONAL,
; but they MUST NOT occur in the same 'recur'
;
; The other rule parts are OPTIONAL,
; but MUST NOT occur more than once
recur-rule-part = ( "FREQ" "=" freq )
/ ( "UNTIL" "=" enddate )
/ ( "COUNT" "=" 1*DIGIT )
/ ( "INTERVAL" "=" 1*DIGIT )
/ ( "BYSECOND" "=" byseclist )
/ ( "BYMINUTE" "=" byminlist )
Desruisseaux Expires May 4, 2009 [Page 39]
Internet-Draft iCalendar October 2008
/ ( "BYHOUR" "=" byhrlist )
/ ( "BYDAY" "=" bywdaylist )
/ ( "BYMONTHDAY" "=" bymodaylist )
/ ( "BYYEARDAY" "=" byyrdaylist )
/ ( "BYWEEKNO" "=" bywknolist )
/ ( "BYMONTH" "=" bymolist )
/ ( "BYSETPOS" "=" bysplist )
/ ( "WKST" "=" weekday )
freq = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"
/ "WEEKLY" / "MONTHLY" / "YEARLY"
enddate = date / date-time ;A UTC value
byseclist = ( seconds *("," seconds) )
seconds = 1*2DIGIT ;0 to 60
byminlist = ( minutes *("," minutes) )
minutes = 1*2DIGIT ;0 to 59
byhrlist = ( hour *("," hour) )
hour = 1*2DIGIT ;0 to 23
bywdaylist = ( weekdaynum *("," weekdaynum) )
weekdaynum = [[plus / minus] ordwk] weekday
plus = "+"
minus = "-"
ordwk = 1*2DIGIT ;1 to 53
weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
;FRIDAY, and SATURDAY days of the week.
bymodaylist = ( monthdaynum *("," monthdaynum) )
monthdaynum = [plus / minus] ordmoday
ordmoday = 1*2DIGIT ;1 to 31
byyrdaylist = ( yeardaynum *("," yeardaynum) )
Desruisseaux Expires May 4, 2009 [Page 40]
Internet-Draft iCalendar October 2008
yeardaynum = [plus / minus] ordyrday
ordyrday = 1*3DIGIT ;1 to 366
bywknolist = ( weeknum *("," weeknum) )
weeknum = [plus / minus] ordwk
bymolist = ( monthnum *("," monthnum) )
monthnum = 1*2DIGIT ;1 to 12
bysplist = ( setposday *("," setposday) )
setposday = yeardaynum
Description: This value type is a structured value consisting of a
list of one or more recurrence grammar parts. Each rule part is
defined by a NAME=VALUE pair. The rule parts are separated from
each other by the SEMICOLON character (US-ASCII decimal 59). The
rule parts are not ordered in any particular sequence. Individual
rule parts MUST only be specified once.
Note: Compliant applications MUST accept rule parts ordered in
any sequence, but to ensure backward compatibility with
applications that pre-date this revision of iCalendar the FREQ
rule part MUST be the first rule part specified in a RECUR
value.
The FREQ rule part identifies the type of recurrence rule. This
rule part MUST be specified in the recurrence rule. Valid values
include SECONDLY, to specify repeating events based on an interval
of a second or more; MINUTELY, to specify repeating events based
on an interval of a minute or more; HOURLY, to specify repeating
events based on an interval of an hour or more; DAILY, to specify
repeating events based on an interval of a day or more; WEEKLY, to
specify repeating events based on an interval of a week or more;
MONTHLY, to specify repeating events based on an interval of a
month or more; and YEARLY, to specify repeating events based on an
interval of a year or more.
The INTERVAL rule part contains a positive integer representing at
which intervals the recurrence rule repeats. The default value is
"1", meaning every second for a SECONDLY rule, every minute for a
MINUTELY rule, every hour for an HOURLY rule, every day for a
DAILY rule, every week for a WEEKLY rule, every month for a
MONTHLY rule, and every year for a YEARLY rule. For example,
within a DAILY rule, a value of "8" means every eight days.
Desruisseaux Expires May 4, 2009 [Page 41]
Internet-Draft iCalendar October 2008
The UNTIL rule part defines a DATE or DATE-TIME value which bounds
the recurrence rule in an inclusive manner. If the value
specified by UNTIL is synchronized with the specified recurrence,
this DATE or DATE-TIME becomes the last instance of the
recurrence. The value of the UNTIL rule part MUST have the same
value type as the "DTSTART" property. Furthermore, if the
"DTSTART" property is specified as a date with local time, then
the UNTIL rule part MUST also be specified as a date with local
time. If the "DTSTART" property is specified as a date with UTC
time or a date with local time and time zone reference, then the
UNTIL rule part MUST be specified as a date with UTC time. In the
case of the "STANDARD" and "DAYLIGHT" sub-components the UNTIL
rule part MUST always be specified as a date with UTC time. If
specified as a DATE-TIME value, then it MUST be specified in a UTC
time format. If not present, and the COUNT rule part is also not
present, the "RRULE" is considered to repeat forever.
The COUNT rule part defines the number of occurrences at which to
range-bound the recurrence. The "DTSTART" property value always
counts as the first occurrence.
The BYSECOND rule part specifies a COMMA character (US-ASCII
decimal 44) separated list of seconds within a minute. Valid
values are 0 to 60. The BYMINUTE rule part specifies a COMMA
character (US-ASCII decimal 44) separated list of minutes within
an hour. Valid values are 0 to 59. The BYHOUR rule part
specifies a COMMA character (US-ASCII decimal 44) separated list
of hours of the day. Valid values are 0 to 23. The BYSECOND,
BYMINUTE and BYHOUR rule parts MUST NOT be specified when the
associated "DTSTART" property has a DATE value type. These rule
parts MUST be ignored in RECUR value that violate the above
requirement (e.g., generated by applications that pre-date this
revision of iCalendar).
The BYDAY rule part specifies a COMMA character (US-ASCII decimal
44) separated list of days of the week; SU indicates Sunday; MO
indicates Monday; TU indicates Tuesday; WE indicates Wednesday; TH
indicates Thursday; FR indicates Friday; SA indicates Saturday.
Each BYDAY value can also be preceded by a positive (+n) or
negative (-n) integer. If present, this indicates the nth
occurrence of a specific day within the MONTHLY or YEARLY "RRULE".
For example, within a MONTHLY rule, +1MO (or simply 1MO)
represents the first Monday within the month, whereas -1MO
represents the last Monday of the month. The numeric value in a
BYDAY rule part with the FREQ rule part set to YEARLY corresponds
to an offset within the month when the BYMONTH rule part is
present, and corresponds to an offset within the year when the
Desruisseaux Expires May 4, 2009 [Page 42]
Internet-Draft iCalendar October 2008
BYWEEKNO or BYMONTH rule parts are present. If an integer
modifier is not present, it means all days of this type within the
specified frequency. For example, within a MONTHLY rule, MO
represents all Mondays within the month. The BYDAY rule part MUST
NOT be specified with a numeric value when the FREQ rule part is
not set to MONTHLY or YEARLY. Furthermore, the BYDAY rule part
MUST NOT be specified with a numeric value with the FREQ rule part
set to YEARLY when the BYWEEKNO rule part is specified.
The BYMONTHDAY rule part specifies a COMMA character (US-ASCII
decimal 44) separated list of days of the month. Valid values are
1 to 31 or -31 to -1. For example, -10 represents the tenth to
the last day of the month. The BYMONTHDAY rule part MUST NOT be
specified when the FREQ rule part is set to WEEKLY.
The BYYEARDAY rule part specifies a COMMA character (US-ASCII
decimal 44) separated list of days of the year. Valid values are
1 to 366 or -366 to -1. For example, -1 represents the last day
of the year (December 31st) and -306 represents the 306th to the
last day of the year (March 1st). The BYYEARDAY rule part MUST
NOT be specified when the FREQ rule part is set to DAILY, WEEKLY,
or MONTHLY.
The BYWEEKNO rule part specifies a COMMA character (US-ASCII
decimal 44) separated list of ordinals specifying weeks of the
year. Valid values are 1 to 53 or -53 to -1. This corresponds to
weeks according to week numbering as defined in [ISO.8601.2004].
A week is defined as a seven day period, starting on the day of
the week defined to be the week start (see WKST). Week number one
of the calendar year is the first week which contains at least
four (4) days in that calendar year. This rule part MUST NOT be
used when the FREQ rule part is set to anything other than YEARLY.
For example, 3 represents the third week of the year.
Note: Assuming a Monday week start, week 53 can only occur when
Thursday is January 1 or if it is a leap year and Wednesday is
January 1.
The BYMONTH rule part specifies a COMMA character (US-ASCII
decimal 44) separated list of months of the year. Valid values
are 1 to 12.
The WKST rule part specifies the day on which the workweek starts.
Valid values are MO, TU, WE, TH, FR, SA and SU. This is
significant when a WEEKLY "RRULE" has an interval greater than 1,
and a BYDAY rule part is specified. This is also significant when
in a YEARLY "RRULE" when a BYWEEKNO rule part is specified. The
default value is MO.
Desruisseaux Expires May 4, 2009 [Page 43]
Internet-Draft iCalendar October 2008
The BYSETPOS rule part specifies a COMMA character (US-ASCII
decimal 44) separated list of values which corresponds to the nth
occurrence within the set of recurrence instances specified by the
rule. BYSETPOS operates on a set of recurrence instances in one
interval of the recurrence rule. For example, in a WEEKLY rule,
the interval would be one week A set of recurrence instances
starts at the beginning of the interval defined by the FREQ rule
part. Valid values are 1 to 366 or -366 to -1. It MUST only be
used in conjunction with another BYxxx rule part. For example
"the last work day of the month" could be represented as:
FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1
Each BYSETPOS value can include a positive (+n) or negative (-n)
integer. If present, this indicates the nth occurrence of the
specific occurrence within the set of occurences specified by the
rule.
Recurrence rules may generate recurrence instances with invalid
date (e.g., February 30) or nonexistent local time (e.g., 1:30 AM
on a day where the local time is moved forward by an hour at 1:00
AM). Such recurrence instances MUST be ignored and MUST NOT be
counted as part of the recurrence set.
Information, not contained in the rule, necessary to determine the
various recurrence instance start time and dates are derived from
the Start Time ("DTSTART") component attribute. For example,
"FREQ=YEARLY;BYMONTH=1" doesn't specify a specific day within the
month or a time. This information would be the same as what is
specified for "DTSTART".
BYxxx rule parts modify the recurrence in some manner. BYxxx rule
parts for a period of time which is the same or greater than the
frequency generally reduce or limit the number of occurrences of
the recurrence generated. For example, "FREQ=DAILY;BYMONTH=1"
reduces the number of recurrence instances from all days (if
BYMONTH rule part is not present) to all days in January. BYxxx
rule parts for a period of time less than the frequency generally
increase or expand the number of occurrences of the recurrence.
For example, "FREQ=YEARLY;BYMONTH=1,2" increases the number of
days within the yearly recurrence set from 1 (if BYMONTH rule part
is not present) to 2.
If multiple BYxxx rule parts are specified, then after evaluating
the specified FREQ and INTERVAL rule parts, the BYxxx rule parts
are applied to the current set of evaluated occurrences in the
following order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY,
BYHOUR, BYMINUTE, BYSECOND and BYSETPOS; then COUNT and UNTIL are
Desruisseaux Expires May 4, 2009 [Page 44]
Internet-Draft iCalendar October 2008
evaluated.
The table below summarizes the dependency of BYxxx rule part
expand or limit behaviour on the FREQ rule part value.
The term "N/A" means that the corresponding BYxxx rule part MUST
NOT be used with the corresponding FREQ value.
BYDAY has some special behaviour depending on the FREQ value and
this is described in separate notes below the table.
+----------+--------+--------+-------+-------+------+-------+------+
| |SECONDLY|MINUTELY|HOURLY |DAILY |WEEKLY|MONTHLY|YEARLY|
+----------+--------+--------+-------+-------+------+-------+------+
|BYMONTH |Limit |Limit |Limit |Limit |Limit |Limit |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYWEEKNO |N/A |N/A |N/A |N/A |N/A |N/A |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYYEARDAY |Limit |Limit |Limit |N/A |N/A |N/A |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYMONTHDAY|Limit |Limit |Limit |Limit |N/A |Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYDAY |Limit |Limit |Limit |Limit |Expand|Note 1 |Note 2|
+----------+--------+--------+-------+-------+------+-------+------+
|BYHOUR |Limit |Limit |Limit |Expand |Expand|Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYMINUTE |Limit |Limit |Expand |Expand |Expand|Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYSECOND |Limit |Expand |Expand |Expand |Expand|Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYSETPOS |Limit |Limit |Limit |Limit |Limit |Limit |Limit |
+----------+--------+--------+-------+-------+------+-------+------+
Note 1: Limit if BYMONTHDAY is present, otherwise special expand
for MONTHLY.
Note 2: Limit if BYYEARDAY or BYMONTHDAY is present, otherwise
special expand for WEEKLY if BYWEEKNO present, otherwise
special expand for MONTHLY if BYMONTH present, otherwise
special expand for YEARLY.
Desruisseaux Expires May 4, 2009 [Page 45]
Internet-Draft iCalendar October 2008
Here is an example of evaluating multiple BYxxx rule parts.
DTSTART;TZID=America/New_York:19970105T083000
RRULE:FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9;
BYMINUTE=30
First, the "INTERVAL=2" would be applied to "FREQ=YEARLY" to
arrive at "every other year". Then, "BYMONTH=1" would be applied
to arrive at "every January, every other year". Then, "BYDAY=SU"
would be applied to arrive at "every Sunday in January, every
other year". Then, "BYHOUR=8,9" would be applied to arrive at
"every Sunday in January at 8 AM and 9 AM, every other year".
Then, "BYMINUTE=30" would be applied to arrive at "every Sunday in
January at 8:30 AM and 9:30 AM, every other year". Then, lacking
information from "RRULE", the second is derived from "DTSTART", to
end up in "every Sunday in January at 8:30:00 AM and 9:30:00 AM,
every other year". Similarly, if the BYMINUTE, BYHOUR, BYDAY,
BYMONTHDAY or BYMONTH rule part were missing, the appropriate
minute, hour, day or month would have been retrieved from the
"DTSTART" property.
If the computed local start time of a recurrence instance does not
exist, or occurs more than once, for the specified time zone, the
time of the recurrence instance is interpreted in the same manner
as an explicit DATE-TIME value describing that date and time, as
specified in Section 3.3.5.
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
Example: The following is a rule which specifies 10 occurences which
occur every other day:
FREQ=DAILY;COUNT=10;INTERVAL=2
There are other examples specified in Section 3.8.5.3.
3.3.11. Text
Value Name: TEXT
Purpose: This value type is used to identify values that contain
human readable text.
Format Definition: This value type is defined by the following
notation.
Desruisseaux Expires May 4, 2009 [Page 46]
Internet-Draft iCalendar October 2008
text = *(TSAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR)
; Folded according to description above
ESCAPED-CHAR = ("\\" / "\;" / "\," / "\N" / "\n")
; \\ encodes \, \N or \n encodes newline
; \; encodes ;, \, encodes ,
TSAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-5B /
%x5D-7E / NON-US-ASCII
; Any character except CONTROLs not needed by the current
; character set, DQUOTE, ";", ":", "\", ","
Description: If the property permits, multiple TEXT values are
specified by a COMMA character (US-ASCII decimal 44) separated
list of values.
The language in which the text is represented can be controlled by
the "LANGUAGE" property parameter.
An intentional formatted text line break MUST only be included in
a "TEXT" property value by representing the line break with the
character sequence of BACKSLASH (US-ASCII decimal 92), followed by
a LATIN SMALL LETTER N (US-ASCII decimal 110) or a LATIN CAPITAL
LETTER N (US-ASCII decimal 78), that is "\n" or "\N".
The "TEXT" property values may also contain special characters
that are used to signify delimiters, such as a COMMA character for
lists of values or a SEMICOLON character for structured values.
In order to support the inclusion of these special characters in
"TEXT" property values, they MUST be escaped with a BACKSLASH
character. A BACKSLASH character (US-ASCII decimal 92) in a
"TEXT" property value MUST be escaped with another BACKSLASH
character. A COMMA character in a "TEXT" property value MUST be
escaped with a BACKSLASH character (US-ASCII decimal 92). A
SEMICOLON character in a "TEXT" property value MUST be escaped
with a BACKSLASH character (US-ASCII decimal 92). However, a
COLON character in a "TEXT" property value SHALL NOT be escaped
with a BACKSLASH character.
Example: A multiple line value of:
Project XYZ Final Review
Conference Room - 3B
Come Prepared.
would be represented as:
Project XYZ Final Review\nConference Room - 3B\nCome Prepared.
Desruisseaux Expires May 4, 2009 [Page 47]
Internet-Draft iCalendar October 2008
3.3.12. Time
Value Name: TIME
Purpose: This value type is used to identify values that contain a
time of day.
Format Definition: This value type is defined by the following
notation:
time = time-hour time-minute time-second [time-utc]
time-hour = 2DIGIT ;00-23
time-minute = 2DIGIT ;00-59
time-second = 2DIGIT ;00-60
;The "60" value is used to account for positive "leap" seconds.
time-utc = "Z"
Description: If the property permits, multiple "time" values are
specified by a COMMA character (US-ASCII decimal 44) separated
list of values. No additional content value encoding (i.e.,
BACKSLASH character encoding, see Section 3.3.11) is defined for
this value type.
The "TIME" value type is used to identify values that contain a
time of day. The format is based on the [ISO.8601.2004] complete
representation, basic format for a time of day. The text format
consists of a two-digit 24-hour of the day (i.e., values 00-23),
two-digit minute in the hour (i.e., values 00-59), and two-digit
seconds in the minute (i.e., values 00-60). The seconds value of
60 MUST only be used to account for positive "leap" seconds.
Fractions of a second are not supported by this format.
In parallel to the "DATE-TIME" definition above, the "TIME" value
type expresses time values in three forms:
The form of time with UTC offset MUST NOT be used. For example,
the following is not valid for a time value:
230000-0800 ;Invalid time format
FORM #1 LOCAL TIME
The local time form is simply a time value that does not contain
the UTC designator nor does it reference a time zone. For
example, 11:00 PM:
Desruisseaux Expires May 4, 2009 [Page 48]
Internet-Draft iCalendar October 2008
230000
Time values of this type are said to be "floating" and are not
bound to any time zone in particular. They are used to represent
the same hour, minute, and second value regardless of which time
zone is currently being observed. For example, an event can be
defined that indicates that an individual will be busy from 11:00
AM to 1:00 PM every day, no matter which time zone the person is
in. In these cases, a local time can be specified. The recipient
of an iCalendar object with a property value consisting of a local
time, without any relative time zone information, SHOULD interpret
the value as being fixed to whatever time zone the "ATTENDEE" is
in at any given moment. This means that two "Attendees", may
participate in the same event at different UTC times; floating
time SHOULD only be used where that is reasonable behavior.
In most cases, a fixed time is desired. To properly communicate a
fixed time in a property value, either UTC time or local time with
time zone reference MUST be specified.
The use of local time in a TIME value without the "TZID" property
parameter is to be interpreted as a local time value, regardless
of the existence of "VTIMEZONE" calendar components in the
iCalendar object.
FORM #2: UTC TIME
UTC time, or absolute time, is identified by a LATIN CAPITAL
LETTER Z suffix character (US-ASCII decimal 90), the UTC
designator, appended to the time value. For example, the
following represents 07:00 AM UTC:
070000Z
The "TZID" property parameter MUST NOT be applied to TIME
properties whose time values are specified in UTC.
FORM #3: LOCAL TIME AND TIME ZONE REFERENCE
The local time with reference to time zone information form is
identified by the use the "TZID" property parameter to reference
the appropriate time zone definition. "TZID" is discussed in
detail in Section 3.2.19.
Example: The following represents 8:30 AM in New York in Winter,
five hours behind UTC, in each of the three formats:
Desruisseaux Expires May 4, 2009 [Page 49]
Internet-Draft iCalendar October 2008
083000
133000Z
TZID=America/New_York:083000
3.3.13. URI
Value Name: URI
Purpose: This value type is used to identify values that contain a
uniform resource identifier (URI) type of reference to the
property value.
Format Definition: This value type is defined by the following
notation:
uri = <As defined in section 3 of [RFC3986]>
Description: This value type might be used to reference binary
information, for values that are large, or otherwise undesirable
to include directly in the iCalendar object.
Property values with this value type MUST follow the generic URI
syntax defined in [RFC3986].
When a property parameter value is a URI value type, the URI MUST
be specified as a quoted-string value.
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
Example: The following is a URI for a network file:
http://example.com/my-report.txt
3.3.14. UTC Offset
Value Name: UTC-OFFSET
Purpose: This value type is used to identify properties that contain
an offset from UTC to local time.
Format Definition: This value type is defined by the following
notation:
Desruisseaux Expires May 4, 2009 [Page 50]
Internet-Draft iCalendar October 2008
utc-offset = time-numzone
time-numzone = ("+" / "-") time-hour time-minute [time-second]
Description: The PLUS SIGN (US-ASCII decimal 43) character MUST be
specified for positive UTC offsets (i.e., ahead of UTC). The
HYPHEN-MINUS character (US-ASCII decimal 45) MUST be specified for
negative UTC offsets (i.e., behind of UTC). The value of "-0000"
and "-000000" are not allowed. The time-second, if present, MUST
NOT be 60; if absent, it defaults to zero.
No additional content value encoding (i.e., BACKSLASH character
encoding, see Section 3.3.11) is defined for this value type.
Example: The following UTC offsets are given for standard time for
New York (five hours behind UTC) and Geneva (one hour ahead of
UTC):
-0500
+0100
3.4. iCalendar Object
The Calendaring and Scheduling Core Object is a collection of
calendaring and scheduling information. Typically, this information
will consist of an iCalendar stream with a single iCalendar object.
However, multiple iCalendar objects can be sequentially grouped
together in an iCalendar stream. The first line and last line of the
iCalendar object MUST contain a pair of iCalendar object delimiter
strings. The syntax for an iCalendar stream is as follows:
icalstream = 1*icalobject
icalobject = "BEGIN" ":" "VCALENDAR" CRLF
icalbody
"END" ":" "VCALENDAR" CRLF
The following is a simple example of an iCalendar object:
Desruisseaux Expires May 4, 2009 [Page 51]
Internet-Draft iCalendar October 2008
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
UID:19970610T172345Z-AF23B2@example.com
DTSTAMP:19970610T172345Z
DTSTART:19970714T170000Z
DTEND:19970715T040000Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR
3.5. Property
A property is the definition of an individual attribute describing a
calendar object or a calendar component. A property takes the form
defined by the "contentline" notation defined in Section 3.1.
The following is an example of a property:
DTSTART:19960415T133000Z
This memo imposes no ordering of properties within an iCalendar
object.
Property names, parameter names and enumerated parameter values are
case insensitive. For example, the property name "DUE" is the same
as "due" and "Due", DTSTART;TZID=America/New_York:19980714T120000 is
the same as DtStart;TzID=America/New_York:19980714T120000.
3.6. Calendar Components
The body of the iCalendar object consists of a sequence of calendar
properties and one or more calendar components. The calendar
properties are attributes that apply to the calendar object as a
whole. The calendar components are collections of properties that
express a particular calendar semantic. For example, the calendar
component can specify an event, a to-do, a journal entry, time zone
information, free/busy time information, or an alarm.
The body of the iCalendar object is defined by the following
notation:
Desruisseaux Expires May 4, 2009 [Page 52]
Internet-Draft iCalendar October 2008
icalbody = calprops component
calprops = *(
; the following are REQUIRED,
; but MUST NOT occur more than once
prodid / version /
; the following are OPTIONAL,
; but MUST NOT occur more than once
calscale / method /
; the following are OPTIONAL,
; and MAY occur more than once
x-prop / iana-prop
)
component = 1*(eventc / todoc / journalc / freebusyc /
timezonec / iana-comp / x-comp)
iana-comp = "BEGIN" ":" iana-token CRLF
1*contentline
"END" ":" iana-token CRLF
x-comp = "BEGIN" ":" x-name CRLF
1*contentline
"END" ":" x-name CRLF
An iCalendar object MUST include the "PRODID" and "VERSION" calendar
properties. In addition, it MUST include at least one calendar
component. Special forms of iCalendar objects are possible to
publish just busy time (i.e., only a "VFREEBUSY" calendar component)
or time zone (i.e., only a "VTIMEZONE" calendar component)
information. In addition, a complex iCalendar object that is used to
capture a
