RFC 2445
Internet Calendaring and Scheduling Core Object Specification (iCalendar)
Internet Calendaring and Scheduling Core Object Specification (iCalendar) ✨
RFC 2445 🎀 Network Working Group, November 1998. Written by F. Dawson (Lotus) and D. Stenerson (Microsoft). It's a Standards Track doc. The header doesn't list anything it obsoletes or updates, so no drama there 💅
Status of this Memo 🌸
Okay so this doc is an Internet standards track protocol for the whole Internet community, and it's literally asking for discussion and suggestions for improvements 🫶 If you want to know where this protocol stands in the official standardization state, check the current edition of the "Internet Official Protocol Standards" (STD 1). And distribution of this memo is unlimited, so share it with everyone 💜
Copyright Notice 🔥
Copyright (C) The Internet Society (1998). All Rights Reserved. Obviously 💅
Abstract 🦋
Okay bestie, the world really needs calendaring and scheduling that works across the Internet, and it needs it now ✨ Group scheduling and Personal Information Management (PIM) products are already being stretched across the Internet today, but they're doing it in proprietary ways, which is giving chaos 💀 So this memo is here to define one common format for openly exchanging calendaring and scheduling info 🧚
This memo is written up as a registration for a MIME media type per [RFC 2048]. BUT the format is just as usable outside of a MIME message content type, so it's not locked in 🌈
The proposed media type value is 'text/calendar'. That string labels a media type holding calendaring and scheduling info, encoded as text characters in the way outlined below 🎀
This MIME media type is a standard content type for capturing calendar event, to-do, and journal entry information 💖 It can also carry free/busy time info 🍓 The content type can ride along as a MIME message entity over MIME-based email systems, over HTTP, or over some other Internet transport 🚀 It's also useful as an object for interactions between desktop apps using the operating system clipboard, drag/drop, or file systems capabilities. Main character energy 👑
This memo is built on the earlier work of the vCalendar specification for exchanging personal calendaring and scheduling info. To avoid mixing it up with that referenced work, this memo goes by the name iCalendar specification ✨
Now the memo defines the format for specifying iCalendar object methods ⭐ An iCalendar object method is a set of usage constraints for the iCalendar object. For example, these methods can define scheduling messages that:
- request an event be scheduled
- reply to an event request
- send a cancellation notice for an event
- modify or replace the definition of an event
- provide a counter proposal for an original event request
- delegate an event request to another individual
- request free or busy time
- reply to a free or busy time request
- provide similar scheduling messages for a to-do or journal entry calendar component
The iCalendar Transport-indendent Interoperability Protocol (iTIP) defined in [ITIP] is one such scheduling protocol. Iconic 🫶
Table of Contents 💖
okay bestie, here's the whole map so you always know where everything lives 🗺️✨ no getting lost in this one, promise 🎀
1 Introduction.....................................................5
2 Basic Grammar and Conventions....................................6
2.1 Formatting Conventions .......................................7
2.2 Related Memos ................................................8
2.3 International Considerations .................................8
3 Registration Information.........................................8
3.1 Content Type .................................................8
3.2 Parameters ...................................................9
3.3 Content Header Fields .......................................10
3.4 Encoding Considerations .....................................10
3.5 Security Considerations .....................................10
3.6 Interoperability Considerations .............................11
3.7 Applications Which Use This Media Type ......................11
3.8 Additional Information ......................................11
3.9 Magic Numbers ...............................................11
3.10 File Extensions ............................................11
3.11 Contact for Further Information: ...........................12
3.12 Intended Usage .............................................12
3.13 Authors/Change Controllers .................................12
4 iCalendar Object Specification..................................13
4.1 Content Lines ...............................................13
4.1.1 List and Field Separators ................................16
4.1.2 Multiple Values ..........................................16
4.1.3 Binary Content ...........................................16
4.1.4 Character Set ............................................17
4.2 Property Parameters .........................................17
4.2.1 Alternate Text Representation ............................18
4.2.2 Common Name ..............................................19
4.2.3 Calendar User Type .......................................20
4.2.4 Delegators ...............................................20
4.2.5 Delegatees ...............................................21
4.2.6 Directory Entry Reference ................................21
4.2.7 Inline Encoding ..........................................22
4.2.8 Format Type ..............................................23
4.2.9 Free/Busy Time Type ......................................23
4.2.10 Language ................................................24
4.2.11 Group or List Membership ................................25
4.2.12 Participation Status ....................................25
4.2.13 Recurrence Identifier Range .............................27
4.2.14 Alarm Trigger Relationship ..............................27
4.2.15 Relationship Type .......................................28
4.2.16 Participation Role ......................................29
4.2.17 RSVP Expectation ........................................29
4.2.18 Sent By .................................................30
4.2.19 Time Zone Identifier ....................................30
4.2.20 Value Data Types ........................................32
4.3 Property Value Data Types ...................................32
4.3.1 Binary ...................................................33
4.3.2 Boolean ..................................................33
4.3.3 Calendar User Address ....................................34
4.3.4 Date .....................................................34
4.3.5 Date-Time ................................................35
4.3.6 Duration .................................................37
4.3.7 Float ....................................................38
4.3.8 Integer ..................................................38
4.3.9 Period of Time ...........................................39
4.3.10 Recurrence Rule .........................................40
4.3.11 Text ....................................................45
4.3.12 Time ....................................................47
4.3.13 URI .....................................................49
4.3.14 UTC Offset ..............................................49
4.4 iCalendar Object ............................................50
4.5 Property ....................................................51
4.6 Calendar Components .........................................51
4.6.1 Event Component ..........................................52
4.6.2 To-do Component ..........................................55
4.6.3 Journal Component ........................................56
4.6.4 Free/Busy Component ......................................58
4.6.5 Time Zone Component ......................................60
4.6.6 Alarm Component ..........................................67
4.7 Calendar Properties .........................................73
4.7.1 Calendar Scale ...........................................73
4.7.2 Method ...................................................74
4.7.3 Product Identifier .......................................75
4.7.4 Version ..................................................76
4.8 Component Properties ........................................77
4.8.1 Descriptive Component Properties .........................77
4.8.1.1 Attachment ...........................................77
4.8.1.2 Categories ...........................................78
4.8.1.3 Classification .......................................79
4.8.1.4 Comment ..............................................80
4.8.1.5 Description ..........................................81
4.8.1.6 Geographic Position ..................................82
4.8.1.7 Location .............................................84
4.8.1.8 Percent Complete .....................................85
4.8.1.9 Priority .............................................85
4.8.1.10 Resources ...........................................87
4.8.1.11 Status ..............................................88
4.8.1.12 Summary .............................................89
4.8.2 Date and Time Component Properties .......................90
4.8.2.1 Date/Time Completed ..................................90
4.8.2.2 Date/Time End ........................................91
4.8.2.3 Date/Time Due ........................................92
4.8.2.4 Date/Time Start ......................................93
4.8.2.5 Duration .............................................94
4.8.2.6 Free/Busy Time .......................................95
4.8.2.7 Time Transparency ....................................96
4.8.3 Time Zone Component Properties ...........................97
4.8.3.1 Time Zone Identifier .................................97
4.8.3.2 Time Zone Name .......................................98
4.8.3.3 Time Zone Offset From ................................99
4.8.3.4 Time Zone Offset To .................................100
4.8.3.5 Time Zone URL .......................................101
4.8.4 Relationship Component Properties .......................102
4.8.4.1 Attendee ............................................102
4.8.4.2 Contact .............................................104
4.8.4.3 Organizer ...........................................106
4.8.4.4 Recurrence ID .......................................107
4.8.4.5 Related To ..........................................109
4.8.4.6 Uniform Resource Locator ............................110
4.8.4.7 Unique Identifier ...................................111
4.8.5 Recurrence Component Properties .........................112
4.8.5.1 Exception Date/Times ................................112
4.8.5.2 Exception Rule ......................................114
4.8.5.3 Recurrence Date/Times ...............................115
4.8.5.4 Recurrence Rule .....................................117
4.8.6 Alarm Component Properties ..............................126
4.8.6.1 Action ..............................................126
4.8.6.2 Repeat Count ........................................126
4.8.6.3 Trigger .............................................127
4.8.7 Change Management Component Properties ..................129
4.8.7.1 Date/Time Created ...................................129
4.8.7.2 Date/Time Stamp .....................................130
4.8.7.3 Last Modified .......................................131
4.8.7.4 Sequence Number .....................................131
4.8.8 Miscellaneous Component Properties ......................133
4.8.8.1 Non-standard Properties .............................133
4.8.8.2 Request Status ......................................134
5 iCalendar Object Examples......................................136
6 Recommended Practices..........................................140
7 Registration of Content Type Elements..........................141
7.1 Registration of New and Modified iCalendar Object Methods ..141
7.2 Registration of New Properties .............................141
7.2.1 Define the property .....................................142
7.2.2 Post the Property definition ............................143
7.2.3 Allow a comment period ..................................143
7.2.4 Submit the property for approval ........................143
7.3 Property Change Control ....................................143
8 References.....................................................144
9 Acknowledgments................................................145
10 Authors' and Chairs' Addresses................................146
11 Full Copyright Statement......................................1481. Introduction ✨
Okay so calendaring and scheduling has been blowing up for the last decade, and honestly it makes sense. Enterprise and inter-enterprise business now depends on scheduling events and actions super fast with this tech 💼. The problem is that the long-term growth is kind of stuck, because there aren't Internet standards for the message content types that sit at the heart of these knowledgeware apps 😭. This memo is here to level up how well different calendaring and scheduling apps can actually talk to each other 🫶. It defines a MIME content type for swapping calendaring and scheduling info 💜.
The Internet Calendaring and Scheduling Core Object Specification, aka iCalendar, lets you capture and exchange the stuff a calendaring and scheduling app normally holds, like in a Personal Information Manager (PIM) or a Group Scheduling product 📅.
iCalendar is giving "exchange format between apps or systems" 💖. Because it's defined as a MIME content type, the object can travel over a bunch of transports, and the list is not limited to these: SMTP, HTTP, a file system, desktop interactive stuff like a memory-based clipboard or drag/drop, point-to-point asynchronous communication, wired-network transport, and even some form of unwired transport like infrared 🌈. Main character transport energy, no cap ✨.
The memo also defines iCalendar object methods, which map this content type onto messages for calendaring and scheduling operations. Think requesting, replying to, modifying, and canceling meetings or appointments, to-dos, and journal entries 🗓️. Those methods can also be used to define other operations, like requesting free/busy time data and replying with it 🦋. That whole scheduling protocol lives in the iCalendar Transport-independent Interoperability Protocol (iTIP), which is defined in [ITIP] 🎀.
Last but not least, the memo includes a formal grammar for the content type, based on the Internet ABNF defined in [RFC 2234] 🧚. This ABNF is required for building parsers, and it's the definitive reference whenever the descriptive prose is ambiguous or someone has questions 🙈.
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 interoperated as described in [RFC 2119] 🔑.
This memo uses both descriptive prose and a more formal notation to define the calendaring and scheduling format 💅.
That formal notation is the ABNF notation of [RFC 2234]. If you're planning on implementing the format in this memo, you should be familiar with this notation so you can properly interpret the specifications here 🤓.
All numeric and hexadecimal values in this memo are given in decimal notation 🔢.
Here's a tea: 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 [RFC 2425] content type. The iCalendar object is not a profile of [RFC 2425], but it does reuse a number of the elements from the [RFC 2425] specification 🍓.
2.1. Formatting Conventions 🎀
The mechanisms in this memo are defined in prose, and a lot of the terms have everyday meanings that are different from how this memo uses them 🙃. So to reference the calendaring and scheduling model, core objects (this memo) or the interoperability protocol [ITIP], some formatting conventions are used 💅.
Calendaring and scheduling roles get written as quoted strings where each word starts with an uppercase letter. For example, "Organizer" refers to a role of a "Calendar User" within the scheduling protocol defined by [ITIP] 👑.
Calendar components defined by this memo get written as capitalized, quoted strings too, and every one of them starts with the letter "V" 🌟. For example, "VEVENT" is the event calendar component, "VTODO" is the to-do calendar component, and "VJOURNAL" is the daily journal calendar component 📓.
Scheduling methods defined by [ITIP] are also capitalized, quoted strings. For example, "REQUEST" is the method for requesting that a scheduling calendar component be created or modified, and "REPLY" is the method a recipient uses to update their status with the "Organizer" of the calendar component 💌.
Properties defined by this memo are written as capitalized, quoted strings followed by the word "property". For example, the "ATTENDEE" property is the iCalendar property used to convey the calendar address of a calendar user 🧾.
Property parameters defined by this memo are written as lowercase, quoted strings followed by the word "parameter". For example, the "value" parameter is the iCalendar property parameter used to override the default data type for a property value 🔧.
Enumerated values defined by this memo are written as 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" data type to specify repeating components based on an interval of one minute or more 🔁.
2.2. Related Memos 🧩
Implementers will need to be familiar with several other memos that, together with this one, form a framework for Internet calendaring and scheduling standards 🕸️. This memo, [ICAL], specifies a core specification of objects, data types, properties and property parameters 🌷.
- [ITIP] - specifies an interoperability protocol for scheduling between different implementations;
- [IMIP] specifies an Internet email binding for [ITIP].
This memo doesn't try to repeat the concepts or definitions from these other memos. Wherever possible, it points you to the memo that specifies them 🫶.
2.3. International Considerations 🌍
Throughout the rest of this document, characters are described in the form "character name (codepoint)", where "codepoint" comes from the US-ASCII character set 🔤. The "character name" is the authoritative description, and (codepoint) is a reference to that character in US-ASCII or a US-ASCII compatible set, like the ISO-8859-x family, UTF-8, ISO-2022-xx or KOI8-R 🌏. If a non-US-ASCII compatible character set is used, the appropriate code point from that character set MUST be chosen instead. Use of non-US-ASCII-compatible character sets is NOT recommended 🙅♀️.
3. Registration Information 🎀
The Calendaring and Scheduling Core Object Specification is meant to be used as a MIME content type. That said, implementing this memo is in no way limited to just being a MIME content type 🌈.
3.1. Content Type 💖
The following text is intended to register this memo as the MIME content type "text/calendar" 💌.
To: ietf-types@uninett.no
Subject: Registration of MIME content type text/calendar.
MIME media type name: text
MIME subtype name: calendar3.2. Parameters 🧁
Required parameters: none
Optional parameters: charset, method, component and optinfo
The "charset" parameter is defined in [RFC 2046] for other body parts. It's used to identify the default character set used within the body part 🔡.
The "method" parameter conveys the iCalendar object method or transaction semantics for the calendaring and scheduling information 📨. It's also an identifier for the restricted set of properties and values that the iCalendar object consists of 🧠. This parameter is a guide for applications interpreting the information in the body part, so it SHOULD NOT be used to exclude or require particular pieces of information, unless the identified method definition specifically calls for that behavior 🙅♀️. Unless a particular method definition specifically forbids it, a text/calendar content type can contain any set of properties permitted by the Calendaring and Scheduling Core Object Specification ✨. The "method" parameter MUST be the same value as the one specified in the "METHOD" component property in the iCalendar object. If one is present, the other MUST also be present 👯♀️.
The value for the "method" parameter is defined as follows:
method = 1*(ALPHA / DIGIT / "-")
; IANA registered iCalendar object methodThe "component" parameter conveys the type of iCalendar calendar component within the body part 🗂️. If the iCalendar object contains more than one calendar component type, then multiple component parameters MUST be specified 🫧.
The value for the "component" parameter is defined as follows:
component = ("VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY"
/ "VTIMEZONE" / x-name / iana-token)The "optinfo" parameter conveys optional information about the iCalendar object within the body part 🎁. This parameter can only specify semantics that are already specified by the iCalendar object and that can otherwise be determined by parsing the body part. On top of that, the optional information this parameter specifies MUST be consistent with the information specified by the iCalendar object 🔒. For example, it can be used to convey the "Attendee" response status to a meeting request 📬. The parameter value is a string value 🧵.
The parameter can be specified multiple times 🔁.
This parameter MAY only specify semantics already specified by the iCalendar object and that can otherwise be determined by parsing the body part 🌙.
The value for the "optinfo" parameter is defined as follows:
optinfo = infovalue / qinfovalue
infovalue = iana-token / x-name
qinfovalue = DQUOTE (infovalue) DQUOTE3.3. Content Header Fields 📋
Optional content header fields: Any header fields defined by [RFC 2045] 🍭.
3.4. Encoding Considerations 🫧
This MIME content type can contain 8bit characters, so quoted-printable or BASE64 MIME content-transfer-encodings might be necessary when iCalendar objects get transferred across protocols that are restricted to the 7bit repertoire 🔐. Also, a text valued property in the content entity can have its special characters encoded with the BACKSLASH character (US-ASCII decimal 92) escapement technique 🪞. Which means content values can end up encoded twice, so keep that in mind 😵💫💅.
3.5 Security Considerations 🔐
SPOOFING - - Okay bestie, this one is SERIOUS 😭. In this memo, the "Organizer" is the only person allowed to make changes to an existing "VEVENT", "VTODO", "VJOURNAL" calendar component and send the updates out to the "Attendees". An iCalendar object that maliciously changes or cancels an existing "VEVENT", "VTODO" or "VJOURNAL" or "VFREEBUSY" calendar component might be built by someone other than the "Organizer" and sent to the "Attendees" 💀. Also in this memo, besides the "Organizer", an "Attendee" of a "VEVENT", "VTODO", "VJOURNAL" calendar component is the only other person allowed to update any parameter tied to their "ATTENDEE" property and send it to the "Organizer". An iCalendar object that maliciously changes the "ATTENDEE" parameters can be constructed by someone other than the real "Attendee" and sent to the "Organizer" 🙈.
PROCEDURAL ALARMS - - Here's a sneaky one 👀. An iCalendar object can be created that contains a "VEVENT" and "VTODO" calendar component with "VALARM" calendar components. The "VALARM" calendar component can be of type PROCEDURE and can have an attachment containing some sort of executable program. Implementations that incorporate these types of alarms are subject to any virus or malicious attack that might occur as a result of executing the attachment.
ATTACHMENTS - - An iCalendar object can include references to Uniform Resource Locators that can be programmed resources 🦋.
Implementers and users of this memo should be aware of the network security implications of accepting and parsing such information. In addition, the security considerations observed by implementations of electronic mail systems should be followed for this memo. Be careful out there, babes 🫶.
3.6 Interoperability Considerations 🧚
This MIME content type is intended to define a common format for conveying calendaring and scheduling information between different systems. It is heavily based on the earlier [VCAL] industry specification ✨.
3.7 Applications Which Use This Media Type 🍓
This content-type is designed for widespread use by Internet calendaring and scheduling applications. In addition, applications in the workflow and document management area might find this content-type applicable. The [ITIP] and [IMIP] Internet protocols directly use this content-type also. Future work on an Internet calendar access protocol will utilize this content-type too 💅.
3.8 Additional Information 🌸
This memo defines this content-type.
3.9 Magic Numbers 🪄
None.
3.10 File Extensions 🗂️
The file extension of "ics" is to be used to designate a file containing (an arbitrary set of) calendaring and scheduling information consistent with this MIME content type 📅.
The file extension of "ifb" is to be used to designate a file containing free or busy time information consistent with this MIME content type.
Macintosh file type codes: The file type code of "iCal" is to be used in Apple MacIntosh operating system environments to designate a file containing calendaring and scheduling information consistent with this MIME media type 🍎.
The file type code of "iFBf" is to be used in Apple MacIntosh operating system environments to designate a file containing free or busy time information consistent with this MIME media type.
3.11 Contact for Further Information: 📞
Frank Dawson
6544 Battleford Drive
Raleigh, NC 27613-3502
919-676-9515 (Telephone)
919-676-9564 (Data/Facsimile)
Frank_Dawson@Lotus.com (Internet Mail)
Derik Stenerson
One Microsoft Way
Redmond, WA 98052-6399
425-936-5522 (Telephone)
425-936-7329 (Facsimile)
deriks@microsoft.com (Internet Mail)3.12 Intended Usage 💜
COMMON
3.13 Authors/Change Controllers 👑
Frank Dawson
6544 Battleford Drive
Raleigh, NC 27613-3502
919-676-9515 (Telephone)
919-676-9564 (Data/Facsimile)
Frank_Dawson@Lotus.com (Internet Mail)
Derik Stenerson
One Microsoft Way
Redmond, WA 98052-6399
425-936-5522 (Telephone)
425-936-7329 (Facsimile)
deriks@microsoft.com (Internet Mail)4 iCalendar Object Specification 🎀
The following sections define the details of a Calendaring and Scheduling Core Object Specification. 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 🚀.
4.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:
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. When generating a content line, lines longer than 75 octets SHOULD be folded according to the folding procedure described above.
The content information associated with an iCalendar object is formatted using a syntax similar to that defined by [RFC 2425]. 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 = x-name / iana-token
iana-token = 1*(ALPHA / DIGIT / "-")
; iCalendar identifier registered with IANA
x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-")
; Reservered for experimental use. Not intended for use in
; released products.
vendorid = 3*(ALPHA / DIGIT) ;Vendor identification
param = param-name "=" param-value
*("," param-value)
; Each property defines the specific ABNF for the parameters
; allowed on the property. Refer to specific properties for
; precise parameter ABNF.
param-name = iana-token / x-token
param-value = paramtext / quoted-string
paramtext = *SAFE-CHAR
value = *VALUE-CHAR
quoted-string = DQUOTE *QSAFE-CHAR DQUOTE
NON-US-ASCII = %x80-F8
; Use restricted by charset parameter
; on outer MIME object (UTF-8 preferred)
QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII
; Any character except CTLs and DQUOTE
SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E
/ NON-US-ASCII
; Any character except CTLs, DQUOTE, ";", ":", ","
VALUE-CHAR = WSP / %x21-7E / NON-US-ASCII
; Any textual character
CR = %x0D
; carriage return
LF = %x0A
; line feed
CRLF = CR LF
; Internet standard newline
CTL = %x00-08 / %x0A-1F / %x7F
; Controls
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DIGIT = %x30-39
; 0-9
DQUOTE = %x22
; Quotation Mark
WSP = SPACE / HTAB
SPACE = %x20
HTAB = %x09The 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 💖.
4.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 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, a SEMICOLON or a COMMA character 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@host.com
RDATE;VALUE=DATE:19970304,19970504,19970704,199709044.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 🤓.
4.1.3 Binary Content ✨
okay so bestie, binary stuff in an iCalendar object has a strong preference for being linked, not stuffed inside. the binary content SHOULD be referenced with a URI inside a property value 🦋 so the actual file lives in an external MIME entity that the calendar can point at. only when that's not doable can you include binary content directly, and even then it has to be turned into text with the "BASE64" encoding from [RFC 2045] first 🍓 inline binary should only show up when the situation really needs the whole iCalendar object to be one single entity. and whenever a property has inline binary content, it MUST specify the "ENCODING" property parameter 💅 anything that sits outside the iCalendar object MUST be referenced by a uniform resource identifier (URI), no exceptions 🔥
here's an ATTACH property pointing at an outside file with a URI:
ATTACH:http://xyz.com/public/quarterly-report.docand here's one with inline binary content that's been encoded:
ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
<...remainder of "BASE64" encoded binary data...>4.1.4 Character Set 🌸
so here's the tea 🫖 there's no property parameter for declaring the character set of a property value. the default is UTF-8, as defined in [RFC 2279] ✨ if you're using MIME transports, the "charset" Content-Type parameter is how you can name any other character set that's registered with IANA 💜
4.2 Property Parameters 🎀
okay this part is my favourite 😭 a property can have attributes attached to it, and these "property parameters" are basically meta-information about the property or its value 🧚 they tell you things like where an alternate text version lives, what language a text value is in, what data type the value is, and a bunch of other stuff 💅
these rules are so important, babe. property parameter values with a COLON (US-ASCII decimal 58), SEMICOLON (US-ASCII decimal 59) or COMMA (US-ASCII decimal 44) character separator MUST be written as quoted-string text values 🔥 and property parameter values MUST NOT contain the DOUBLE-QUOTE (US-ASCII decimal 22) character. the DOUBLE-QUOTE (US-ASCII decimal 22) is only used as a delimiter around parameter values that have restricted characters or URI text, like this:
DESCRIPTION;ALTREP="http://www.wiz.org":The Fall'98 Wild Wizards
Conference - - Las Vegas, NV, USAalso, property parameter values that aren't in quoted strings are case insensitive 🦋
the general property parameters this memo defines are written in the following notation, so here's the full menu 👑
parameter = 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
/ ianaparam
; Some other IANA registered iCalendar parameter.
/ xparam
; A non-standard, experimental parameter.
ianaparam = iana-token "=" param-value *("," param-value)
xparam =x-name "=" param-value *("," param-value)4.2.1 Alternate Text Representation 🌈
Parameter Name: ALTREP
Purpose: to point at an alternate text representation for the property value 🧚
Format Definition: the property parameter is written like this:
altrepparam = "ALTREP" "=" DQUOTE uri DQUOTEDescription: this parameter gives a URI that points to an alternate representation of a textual property value 💖 a property using this parameter MUST also include a value that reflects the default representation of the text. each individual URI parameter value MUST be in its own quoted-string, so no skipping the quotes, bestie 🙈
Example:
DESCRIPTION;ALTREP="CID:<part3.msg.970415T083000@host.com>":Project
XYZ Review Meeting will include the following agenda items: (a)
Market Overview, (b) Finances, (c) Project Managementthe "ALTREP" parameter value might point at a "text/html" content portion, which looks like this 🌸
Content-Type:text/html
Content-Id:<part3.msg.970415T083000@host.com>
<html><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>4.2.2 Common Name 💜
Parameter Name: CN
Purpose: to name the common name linked to the calendar user the property is about 🎀
Format Definition: the property parameter is written like this:
cnparam = "CN" "=" param-valueDescription: you can put this parameter on properties with a CAL-ADDRESS value type ✨ it gives the common name for the calendar user the property specifies, and the value is text. that text can be used as display text for the calendar address in the property 💅
Example:
ORGANIZER;CN="John Smith":MAILTO:jsmith@host.com4.2.3 Calendar User Type 👑
Parameter Name: CUTYPE
Purpose: to say what type of calendar user the property is describing 🦋
Format Definition: the property parameter is written like this:
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 INDIVIDUALDescription: you can use this parameter on properties with a CAL-ADDRESS value type 🌈 it identifies the kind of calendar user the property specifies. if it isn't specified on a property that allows this parameter, the default is INDIVIDUAL 🫶
Example:
ATTENDEE;CUTYPE=GROUP:MAILTO:ietf-calsch@imc.org4.2.4 Delegators 🧚
Parameter Name: DELEGATED-FROM
Purpose: to name the calendar users who have handed their participation over to the calendar user the property is about 💌
Format Definition: the property parameter is written like this:
delfromparam = "DELEGATED-FROM" "=" DQUOTE cal-address DQUOTE
*("," DQUOTE cal-address DQUOTE)Description: this can go on properties with a CAL-ADDRESS value type, and also on a property whose value type is a calendar address 🍓 it lists the calendar users who delegated their participation in a group scheduled event or to-do to the calendar user in the property. the value MUST be a MAILTO URI as defined in [RFC 1738] 🔥 and each individual calendar address parameter value MUST be wrapped in its own quoted-string 🙈
Example:
ATTENDEE;DELEGATED-FROM="MAILTO:jsmith@host.com":MAILTO:
jdoe@host.com4.2.5 Delegatees 🦋
Parameter Name: DELEGATED-TO
Purpose: to name the calendar users that the calendar user in the property has delegated participation to 🌸
Format Definition: the property parameter is written like this:
deltoparam = "DELEGATED-TO" "=" DQUOTE cal-address DQUOTE
*("," DQUOTE cal-address DQUOTE)Description: you can put this on properties with a CAL-ADDRESS value type ✨ it specifies the calendar users who have been delegated participation in a group scheduled event or to-do by the calendar user in the property. the value MUST be a MAILTO URI as defined in [RFC 1738] 💅 and each individual calendar address parameter value MUST be in a quoted-string 🫶
Example:
ATTENDEE;DELEGATED-TO="MAILTO:jdoe@host.com","MAILTO:jqpublic@
host.com":MAILTO:jsmith@host.com4.2.6 Directory Entry Reference 🎀
Parameter Name: DIR
Purpose: to reference a directory entry linked to the calendar user in the property 🧚
Format Definition: the property parameter is written like this:
dirparam = "DIR" "=" DQUOTE uri DQUOTEDescription: you can use this on properties with a CAL-ADDRESS value type 💖 it points at the directory entry for the calendar user in the property, and the parameter value is a URI. each individual URI parameter value MUST be wrapped in a quoted-string 🙈
Example:
ORGANIZER;DIR="ldap://host.com:6666/o=eDABC%20Industries,c=3DUS??
(cn=3DBJim%20Dolittle)":MAILTO:jimdo@host1.com4.2.7 Inline Encoding 🌈
Parameter Name: ENCODING
Purpose: to specify an alternate inline encoding for the property value 💜
Format Definition: the property parameter is written like this:
encodingparam = "ENCODING" "="
("8BIT"
; "8bit" text encoding is defined in [RFC 2045]
/ "BASE64"
; "BASE64" binary encoding format is defined in [RFC 2045]
/ iana-token
; Some other IANA registered iCalendar encoding type
/ x-name)
; A non-standard, experimental encoding typeDescription: this parameter names the inline encoding used in a property value 🦋 the default encoding is "8BIT", which matches a property value made of text. the "BASE64" encoding type matches a property value encoded with the "BASE64" encoding defined in [RFC 2045] 🍓
if the value type parameter is ";VALUE=BINARY", then the inline encoding parameter MUST be specified with the value ";ENCODING=BASE64" 🔥 no way around it, bestie 💀
Example:
ATTACH;FMTYPE=IMAGE/JPEG;ENCODING=BASE64;VALUE=BINARY:MIICajC
CAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDA
qBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRw
<...remainder of "BASE64" encoded binary data...>4.2.8 Format Type 📎
Parameter Name: FMTTYPE
Purpose: To specify the content type of a referenced object. 🎀
Format Definition: The property parameter is defined by the following notation:
fmttypeparam = "FMTTYPE" "=" iana-token
; A IANA registered content type
/ x-name
; A non-standard content typeDescription: Okay so this one hangs out on properties that point at an object 🔗. It lets you say what kind of content the referenced thing is. Like, an FTP URI on the "ATTACH" property doesn't tell you by itself what's inside, so this parameter fills in the gap 💅. The parameter value MUST be the TEXT for either an IANA registered content type or a non-standard content type. ✨
Example:
ATTACH;FMTTYPE=application/binary:ftp://domain.com/pub/docs/
agenda.doc4.2.9 Free/Busy Time Type 🦋
Parameter Name: FBTYPE
Purpose: To specify the free or busy time type. 🌸
Format Definition: The property parameter is defined by the following notation:
fbtypeparam = "FBTYPE" "=" ("FREE" / "BUSY"
/ "BUSY-UNAVAILABLE" / "BUSY-TENTATIVE"
/ x-name
; Some experimental iCalendar data type.
/ iana-token)
; Some other IANA registered iCalendar data type.Description: This one is about how a time block is marked 🕰️. FREE means the interval is open for scheduling 🍓. BUSY means one or more events are booked in that slot 📅. BUSY-UNAVAILABLE is the "absolutely do not book me" option 🙈, and BUSY-TENTATIVE means something's been penciled in but isn't locked yet ✏️. If you leave it off on a property that allows it, the default is BUSY, so you're busy unless you say otherwise 💀.
Example: Here's what it looks like on a FREEBUSY property 👑:
FREEBUSY;FBTYPE=BUSY:19980415T133000Z/19980415T170000Z4.2.10 Language 🌍
Parameter Name: LANGUAGE
Purpose: To specify the language for text values in a property or property parameter. 🗣️
Format Definition: The property parameter is defined by the following notation:
languageparam = "LANGUAGE" "=" language
language = <Text identifying a language, as defined in [RFC 1766]>Description: This parameter can go on properties with a text value type 📝. It tells you what language the text in the property or property parameter value is written in. The value of the language property parameter is whatever [RFC 1766] defines 🌐.
Now, if this is being sent in a MIME entity, the Content-Language header field can set the default language for the entire body part 🎀. If you don't do that, no default language is assumed, so nobody's guessing for you 🤷♀️.
Example:
SUMMARY;LANGUAGE=us-EN:Company Holiday Party
LOCATION;LANGUAGE=en:Germany
LOCATION;LANGUAGE=no:TysklandNext up, this one shows Quoted-Printable encoding doing its thing for non-ASCII characters 🇩🇰 ✨:
LOCATION;LANGUAGE=da:K=F8benhavn
LOCATION;LANGUAGE=en:Copenhagen4.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: The property parameter is defined by the following notation:
memberparam = "MEMBER" "=" DQUOTE cal-address DQUOTE
*("," DQUOTE cal-address DQUOTE)Description: This parameter can go on properties with a CAL-ADDRESS value type 📮. It says which groups or lists the calendar user from the property belongs to. The parameter value is either one calendar address in a quoted-string, or a list of calendar addresses separated by COMMA characters (US-ASCII decimal 44), each one in its own quoted-string 🧁. Each individual calendar address parameter value MUST be specified in a quoted-string, so keep those quotes on, bestie 🫶.
Example:
ATTENDEE;MEMBER="MAILTO:ietf-calsch@imc.org":MAILTO:jsmith@host.com
ATTENDEE;MEMBER="MAILTO:projectA@host.com","MAILTO:projectB@host.
com":MAILTO:janedoe@host.com4.2.12 Participation Status 🙋♀️
Parameter Name: PARTSTAT
Purpose: To specify the participation status for the calendar user specified by the property. ✨
Format Definition: The property parameter is defined by the following notation. This one has three flavours, one for each kind of calendar component 🍰:
partstatparam = "PARTSTAT" "="
("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
partstatparam /= "PARTSTAT" "="
("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
partstatparam /= "PARTSTAT" "="
("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-ACTIONDescription: This one goes on properties with a CAL-ADDRESS value type 🎟️. It tells you where the calendar user stands on the invite. The values change depending on whether the thing is a group scheduled "VEVENT", "VTODO" or "VJOURNAL", so the statuses are a bit of a mood ring 🔮. The values MUST match one of the values allowed for the given calendar component, no exceptions 🚫. If you leave it off on a property that allows it, the default is NEEDS-ACTION, which is basically "still waiting on you" 💅.
Example:
ATTENDEE;PARTSTAT=DECLINED:MAILTO:jsmith@host.com4.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: The property parameter is defined by the following notation:
rangeparam = "RANGE" "=" ("THISANDPRIOR"
; To specify all instances prior to the recurrence identifier
/ "THISANDFUTURE")
; To specify the instance specified by the recurrence identifier
; and all subsequent recurrence instancesDescription: This can go on a property that specifies a recurrence identifier 🧠. It says how far the effect reaches, starting from the recurrence identifier on the property. If you don't include this parameter on an allowed property, the default range is just the single instance that the recurrence identifier value points to, so it's a one-and-done 🎯. THISANDPRIOR covers that instance plus all the ones before it ⏪, and THISANDFUTURE covers that instance plus all the ones after it ⏩. Iconic range energy 👑.
Example:
RECURRENCE-ID;RANGE=THISANDPRIOR:19980401T133000Z4.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: The property parameter is defined by the following notation:
trigrelparam = "RELATED" "="
("START" ; Trigger off of start
/ "END") ; Trigger off of endDescription: This can go on properties that set an alarm trigger with a DURATION value type ⏳. It decides whether the alarm goes off relative to the start or the end of the calendar component. START triggers off the start, and END triggers off the end. If you don't specify it on an allowed property, the default is START, so it's giving "start of the party" energy 🎉.
Example:
TRIGGER;RELATED=END:PT5M4.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: The property parameter is defined by the following notation:
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 typeDescription: This one goes on a property that references another related calendar 🗂️. It says what kind of hierarchy links the referenced component to the one the property belongs to. PARENT means the referenced component is a superior 👑, CHILD means it's a subordinate 🧸, and SIBLING means it's a peer 👯. If you don't specify it on an allowed property, the default is PARENT, because every family needs a boss 💅.
Example:
RELATED-TO;RELTYPE=SIBLING:<19960401-080045-4000F192713@host.com>4.2.16 Participation Role ✨
Parameter Name: ROLE 🎀
Purpose: okay so this one tells you what job the calendar user has in a group event 🧚 It's giving "who is this person and what are they doing here" 💅
Format Definition: here's the notation, bestie 🌸
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-PARTICIPANTDescription: this parameter can go on properties with a CAL-ADDRESS value type 💖 It specifies the participation role for the calendar user named by the property, inside the group schedule calendar component ✨ If it's not specified on a property that allows it, the default is REQ-PARTICIPANT, so no drama 🫶
Example:
ATTENDEE;ROLE=CHAIR:MAILTO:mrbig@host.com4.2.17 RSVP Expectation 🦋
Parameter Name: RSVP 💜
Purpose: this one checks whether the calendar user is expected to send back a reply 🍓 Like, "pls respond bestie" energy 😭
Format Definition:
rsvpparam = "RSVP" "=" ("TRUE" / "FALSE")
; Default is FALSEDescription: also goes on CAL-ADDRESS properties 🌈 It identifies whether a reply is expected from the calendar user named by the property value. The Organizer uses this to ask an Attendee of a group scheduled event or to-do for a participation status reply 👑 If it's not specified on a property that allows it, the default is FALSE 💅
Example:
ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host.com4.2.18 Sent By 🧚
Parameter Name: SENT-BY 🌸
Purpose: this is for when someone is acting on behalf of the calendar user, like an assistant doing the work 💖 Main character energy for the delegate 💅
Format Definition:
sentbyparam = "SENT-BY" "=" DQUOTE cal-address DQUOTEDescription: also on CAL-ADDRESS properties ✨ It names the calendar user who is acting on behalf of the calendar user named by the property 🫶 The parameter value MUST be a MAILTO URI as defined in [RFC 1738]. Each individual calendar address parameter value MUST be written as a quoted-string 🎀
Example:
ORGANIZER;SENT-BY:"MAILTO:sray@host.com":MAILTO:jsmith@host.com4.2.19 Time Zone Identifier 🌍
Parameter Name: TZID 🦋
Purpose: this names the time zone definition used for the time part of the property value ⭐ Like, which clock are we even talking about 🙈
Format Definition:
tzidparam = "TZID" "=" [tzidprefix] paramtext CRLF
tzidprefix = "/"Description: okay so this MUST be specified on DTSTART, DTEND, DUE, EXDATE and RDATE when a DATE-TIME or TIME value type is used, and the value is neither UTC nor "floating" time 😭 Check out the DATE-TIME and TIME value type definitions for what UTC and "floating time" look like 💜 This parameter gives a text value that uniquely identifies the VTIMEZONE calendar component to use when evaluating the time portion of the property 🌸 The TZID value MUST equal the TZID property value of the matching time zone definition 💖 Every unique TZID parameter value in the iCalendar object MUST have its own VTIMEZONE calendar component 🫶
The parameter MUST be specified on properties with a DATE-TIME value if the DATE-TIME is neither UTC nor "floating" time 🎀
The SOLIDUS character (US-ASCII decimal 47) as a prefix means this TZID is a unique ID in a globally defined time zone registry, assuming one 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 Olson database [TZ]. 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=US-Eastern:19980119T020000
DTEND;TZID=US-Eastern:19980119T030000The TZID property parameter MUST NOT be applied to DATE-TIME or TIME properties whose time values are specified in UTC 🙅♀️
Local time in a DATE-TIME or TIME value without the TZID property parameter is to be read as a local time value, no matter whether there are VTIMEZONE calendar components in the iCalendar object 🌙
For more info, check the sections on the data types DATE-TIME and TIME 🦋
4.2.20 Value Data Types 💫
Parameter Name: VALUE 🌷
Purpose: this explicitly sets the data type format for a property value 🍓
Format Definition:
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 data type.
/ iana-token)
; Some other IANA registered iCalendar data type.Description: the parameter sets the data type and format of the property value 💅 Property values MUST be of a single value type 🫶 For example, a RDATE property cannot mix DATE-TIME and TIME value types 🙈
If the property's value is the default value type, you don't need to specify this parameter 🌸 But if the default value type gets overridden by some other allowable value type, then this parameter MUST be specified ✨
4.3 Property Value Data Types 🎀
The properties in an iCalendar object are strongly typed 💖 The definition of each property restricts the value to one of the value data types, or simply value types, defined in this section 🦋 The value type for a property is either implicitly the default value type or explicitly specified with the 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 👑
4.3.1 Binary 💜
Value Name: BINARY 🧚
Purpose: this value type identifies properties that contain a character encoding of inline binary data 🌸 For example, an inline attachment of object code might be included in an iCalendar object 💻
Formal Definition:
binary = *(4b-char) [b-end]
; A "BASE64" encoded character string, as defined by [RFC 2045].
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 💖 So all inline binary data MUST first be character encoded using the BASE64 method defined in [RFC 2045] 🫶 No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type 🙅♀️
Example: here's an abridged BASE64 binary value 🌈
ATTACH;VALUE=BINARY;ENCODING=BASE64:MIICajCCAdOgAwIBAgICBEUwDQY
JKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlI
ENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZv
<...remainder of "BASE64" encoded binary data...>4.3.2 Boolean ✨
Value Name: BOOLEAN 💅
Purpose: this value type identifies properties that contain either a "TRUE" or "FALSE" Boolean value 🦋
Formal Definition:
boolean = "TRUE" / "FALSE"Description: these values are case insensitive text 🌸 No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type 🫶
Example: here's a hypothetical property with a BOOLEAN value type 👀
GIBBERISH:TRUE4.3.3 Calendar User Address 🌷
Value Name: CAL-ADDRESS 🧚
Purpose: this value type identifies properties that contain a calendar user address 💖
Formal Definition:
cal-address = uriDescription: the value is a URI as defined by [RFC 1738] or any other IANA registered form for a URI 🌈 When it's used to address an Internet email transport address for a calendar user, the value MUST be a MAILTO URI, as defined by [RFC 1738] 💜 No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type 🙅♀️
Example:
ATTENDEE:MAILTO:jane_doe@host.com4.3.4 Date ✨
Value Name: DATE
Purpose: okay so DATE is the value type for when you only care about which day it is, no clock time needed 📅💖
Formal Definition: here's the notation, bestie 🎀
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
;based on month/yearDescription: if the property allows it, you can list several "date" values separated by a COMMA character (US-ASCII decimal 44) 🍓 The format is the [ISO 8601] complete representation, basic format for a calendar date. So you get a four-digit year, a two-digit month, and a two-digit day, with no separator characters between them. Clean, iconic ✨
No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type.
Example: July 14, 1997 looks like this 🌸
199707144.3.5 Date-Time 🦋
Value Name: DATE-TIME
Purpose: this one is for a precise calendar date and time of day, so you get the full picture 🕰️
Formal Definition: the notation is:
date-time = date "T" time ;As specified in the date and time
;value definitionsDescription: if the property permits it, you can list multiple "date-time" values separated by a COMMA character (US-ASCII decimal 44). No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type.
The "DATE-TIME" data type is based on the [ISO 8601] complete representation, basic format for a calendar date and time of day. You write the "date", then the LATIN CAPITAL LETTER T character (US-ASCII decimal 84) as the time designator, then the "time" format. Super simple, super cute 💅
The "DATE-TIME" data type expresses time values in three forms, and each one is a little different:
- Form #1: date with local time
- Form #2: date with UTC time
- Form #3: date with local time and a time zone reference
First though, the form with a UTC offset is a no-go 🙅♀️ It MUST NOT be used. For example, this is not valid for a date-time value:
DTSTART:19980119T230000-0800 ;Invalid time formatFORM #1: DATE WITH LOCAL TIME 🌙
This is just a date-time value with no UTC designator and no time zone reference. For example, this represents January 18, 1998, at 11 PM:
DTSTART:19980118T230000These values are called "floating" because they aren't tied to any particular time zone. They stay the same hour, minute, and second no matter which time zone is being observed. Say an event shows that a person is busy from 11:00 AM to 1:00 PM every day, no matter where they are. A local time is perfect for that 🧚 The recipient of an iCalendar object with a local time value, and no time zone info, SHOULD interpret the value as fixed to whatever time zone the ATTENDEE is in at any given moment. That means two ATTENDEEs in different time zones could get the same floating event and be in it at totally different real-world times 😭 So floating time SHOULD only be used where that's the reasonable behavior.
Most of the time you want a fixed time, though. To communicate a fixed time properly, you MUST specify either UTC time or local time with a time zone reference 🔒
The use of local time in a DATE-TIME value without the TZID property parameter is to be interpreted as floating time, even if there are "VTIMEZONE" calendar components in the iCalendar object. Floating means floating, periodt 💜
FORM #2: DATE WITH UTC TIME 🌍
This is the absolute time form. You add a LATIN CAPITAL LETTER Z suffix (US-ASCII decimal 90), the UTC designator, to the end of the time value. For example, this represents January 19, 1998, at 0700 UTC:
DTSTART:19980119T070000ZThe TZID property parameter MUST NOT be applied to DATE-TIME properties whose time values are specified in UTC. Don't mix them, bestie ✨
FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE 🗽
Here you use the TZID property parameter to point at the right time zone definition. TZID gets its own deep dive in the section on Time Zone. For example, this represents 2 AM in New York on January 19, 1998:
DTSTART;TZID=US-Eastern:19980119T020000Example: this is July 14, 1997, at 1:30 PM in New York City, shown in all three time formats using the "DTSTART" property 🗽🎀
DTSTART:19970714T133000 ;Local time
DTSTART:19970714T173000Z ;UTC time
DTSTART;TZID=US-Eastern:19970714T133000 ;Local time and time
; zone referenceA time value MUST ONLY specify 60 seconds when it's showing the periodic "leap second" in the time value. For example:
COMPLETED:19970630T235960Z4.3.6 Duration ⏳
Value Name: DURATION
Purpose: this value type is for properties that hold an amount of time, like "how long is this thing" 💖
Formal Definition: here's the 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 it, you can list several "duration" values separated by a COMMA character (US-ASCII decimal 44). The format is the [ISO 8601] basic format for a duration of time, and it can express weeks, days, hours, minutes, and seconds. Very flexible, very slay 💅
No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type.
Example: 15 days, 5 hours, and 20 seconds looks like this 🧁
P15DT5H0M20SAnd 7 weeks looks like this 🌈
P7W4.3.7 Float 🌊
Value Name: FLOAT
Purpose: this one is for properties holding a real number value 🔢✨
Formal Definition: here's the notation:
float = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]Description: if the property permits it, you can list multiple "float" values separated by a COMMA character (US-ASCII decimal 44).
No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type.
Example: 🦋
1000000.0000001
1.333
-3.144.3.8 Integer 🔟
Value Name: INTEGER
Purpose: this value type is for properties holding a signed integer value 💜
Formal Definition: the notation is:
integer = (["+"] / "-") 1*DIGITDescription: if the property permits it, you can list multiple "integer" values separated by a COMMA character (US-ASCII decimal 44). The valid range for "integer" is -2147483648 to 2147483647 🫶 If the sign isn't specified, the value is assumed to be positive.
No additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type.
Example: 🍓
1234567890
-1234567890
+1234567890
4321098764.3.9 Period of Time 🎀
Value Name: PERIOD
Purpose: this value type is for values holding a precise period of time, like a start and an end, or a start and a length ⏰
Formal Definition: the data type is defined by this notation:
period = period-explicit / period-start
period-explicit = date-time "/" date-time
; [ISO 8601] 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] complete representation basic format for a period of
; time consisting of a start and positive duration of time.Description: if the property permits it, you can list multiple "period" values separated by a COMMA character (US-ASCII decimal 44). There are two ways to write a period. The first is by its start and its end. That's the [ISO 8601] complete representation, basic format for the "DATE-TIME" start, then a SOLIDUS character (US-ASCII decimal 47), then the "DATE-TIME" end. The start MUST be before the end of the period, no exceptions 🙅♀️ The second way is by a start and a positive duration. That's the [ISO 8601] complete representation, basic format for the "DATE-TIME" start, then a SOLIDUS character (US-ASCII decimal 47), then the [ISO 8601] basic format for the "DURATION" of the period.
Example: a period from 18:00:00 UTC on January 1, 1997, to 07:00:00 UTC on January 2, 1997, looks like this 🌙
19970101T180000Z/19970102T070000ZA period starting at 18:00:00 on January 1, 1997, and lasting 5 hours and 30 minutes looks like this ✨
19970101T180000Z/PT5H30MNo additional content value encoding (i.e., BACKSLASH character encoding) is defined for this value type. 💖
4.3.10 Recurrence Rule 🔁
Value Name: RECUR 💖
Purpose: Okay so this value type is for properties that hold a recurrence rule specification 🦋. It's the part that says "and then it happens AGAIN" ✨
Formal Definition: The value type is defined by the following notation 📝:
recur = "FREQ"=freq *(
; either UNTIL or COUNT may appear in a 'recur',
; but UNTIL and COUNT MUST NOT occur in the same 'recur'
( ";" "UNTIL" "=" enddate ) /
( ";" "COUNT" "=" 1*DIGIT ) /
; the rest of these keywords are optional,
; but MUST NOT occur more than once
( ";" "INTERVAL" "=" 1*DIGIT ) /
( ";" "BYSECOND" "=" byseclist ) /
( ";" "BYMINUTE" "=" byminlist ) /
( ";" "BYHOUR" "=" byhrlist ) /
( ";" "BYDAY" "=" bywdaylist ) /
( ";" "BYMONTHDAY" "=" bymodaylist ) /
( ";" "BYYEARDAY" "=" byyrdaylist ) /
( ";" "BYWEEKNO" "=" bywknolist ) /
( ";" "BYMONTH" "=" bymolist ) /
( ";" "BYSETPOS" "=" bysplist ) /
( ";" "WKST" "=" weekday ) /
( ";" x-name "=" text )
)
freq = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"
/ "WEEKLY" / "MONTHLY" / "YEARLY"
enddate = date
enddate =/ date-time ;An UTC value
byseclist = seconds / ( seconds *("," seconds) )
seconds = 1DIGIT / 2DIGIT ;0 to 59
byminlist = minutes / ( minutes *("," minutes) )
minutes = 1DIGIT / 2DIGIT ;0 to 59
byhrlist = hour / ( hour *("," hour) )
hour = 1DIGIT / 2DIGIT ;0 to 23
bywdaylist = weekdaynum / ( weekdaynum *("," weekdaynum) )
weekdaynum = [([plus] ordwk / minus ordwk)] weekday
plus = "+"
minus = "-"
ordwk = 1DIGIT / 2DIGIT ;1 to 53
weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
;FRIDAY, SATURDAY and SUNDAY days of the week.
bymodaylist = monthdaynum / ( monthdaynum *("," monthdaynum) )
monthdaynum = ([plus] ordmoday) / (minus ordmoday)
ordmoday = 1DIGIT / 2DIGIT ;1 to 31
byyrdaylist = yeardaynum / ( yeardaynum *("," yeardaynum) )
yeardaynum = ([plus] ordyrday) / (minus ordyrday)
ordyrday = 1DIGIT / 2DIGIT / 3DIGIT ;1 to 366
bywknolist = weeknum / ( weeknum *("," weeknum) )
weeknum = ([plus] ordwk) / (minus ordwk)
bymolist = monthnum / ( monthnum *("," monthnum) )
monthnum = 1DIGIT / 2DIGIT ;1 to 12
bysplist = setposday / ( setposday *("," setposday) )
setposday = yeardaynumDescription: Okay so if the property allows it, you can list several recur values separated by a COMMA (US-ASCII decimal 44) 💌. The whole thing is a structured value made up of one or more recurrence grammar parts, and each part is a NAME=VALUE pair 🧩. The parts are split apart by a SEMICOLON (US-ASCII decimal 59). Order doesn't matter at all, so no vibe check needed 🫶. Just know that each individual rule part MUST only be specified once 💀.
The FREQ part is the main character 👑 because it tells you what kind of recurrence rule you've got. It MUST be specified in the recurrence rule, no exceptions bestie 🙅. The valid values are:
SECONDLY: repeating events based on an interval of a second or more ⏱️MINUTELY: repeating events based on an interval of a minute or moreHOURLY: repeating events based on an interval of an hour or moreDAILY: repeating events based on an interval of a day or more ☀️WEEKLY: repeating events based on an interval of a week or moreMONTHLY: repeating events based on an interval of a month or more 🌙YEARLY: repeating events based on an interval of a year or more 🎂
The INTERVAL part is a positive integer that says how often the rule repeats 🔁. If you don't include it, the default is 1, which means 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 🌸.
The UNTIL part sets a date-time value that bounds the rule in an inclusive manner 🚪. If the value in UNTIL lines up with the recurrence, that date or date-time becomes the very last instance 🏁. If you use a date-time value, then it MUST be specified in an UTC time format 🕰️. And if neither UNTIL nor COUNT is there, the RRULE is considered to repeat forever ♾️.
The COUNT part sets how many occurrences you get before the recurrence is range-bound 🎟️. If DTSTART is specified, it counts as the first occurrence 🥇.
The BYSECOND part is a COMMA-separated list of seconds within a minute, with valid values of 0 to 59 ⏲️. The BYMINUTE part is a COMMA-separated list of minutes within an hour, also 0 to 59 🕧. The BYHOUR part is a COMMA-separated list of hours of the day, with valid values of 0 to 23 🌅.
The BYDAY part is a COMMA-separated list of days of the week 📅:
MOis MondayTUis TuesdayWEis WednesdayTHis ThursdayFRis FridaySAis SaturdaySUis Sunday
Each BYDAY value can also get a positive (+n) or negative (-n) integer in front of it 🎯. If that's there, it means the nth occurrence of that day within a MONTHLY or YEARLY RRULE. So within a MONTHLY rule, +1MO (or just 1MO) is the first Monday of the month, while -1MO is the last Monday of the month 🏆. If there's no integer modifier, it means all days of that type within the specified frequency. So within a MONTHLY rule, MO means every Monday in the month 🗓️.
The BYMONTHDAY part is a COMMA-separated list of days of the month (ASCII decimal 44) 📆. Valid values are 1 to 31 or -31 to -1. For example, -10 is the tenth to the last day of the month 🙃.
The BYYEARDAY part is a COMMA-separated list of days of the year 📖. Valid values are 1 to 366 or -366 to -1. For example, -1 is the last day of the year (December 31st) 🎆, and -306 is the 306th to the last day of the year (March 1st) 🌷.
The BYWEEKNO part is a COMMA-separated list of ordinals for weeks of the year 🗂️. Valid values are 1 to 53 or -53 to -1. This matches the week numbering defined in [ISO 8601]. A week is a seven-day period that starts on whatever day is set as the week start (see WKST) 📍. Week number one of the calendar year is the first week that has at least four (4) days in that calendar year 🥳. This part is only valid for YEARLY rules. For example, 3 is 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 part is a COMMA-separated list of months of the year, with valid values of 1 to 12 🎈.
The WKST part says which day the workweek starts on 💼. Valid values are MO, TU, WE, TH, FR, SA and SU. This matters when a WEEKLY RRULE has an interval greater than 1 and a BYDAY part is specified. It also matters in a YEARLY RRULE when a BYWEEKNO part is specified. The default value is MO ☕.
The BYSETPOS part is a COMMA-separated list of values that picks the nth occurrence within the set of events the rule makes 🎯. 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 written like this:
RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1Each BYSETPOS value can include a positive (+n) or negative (-n) integer. If it's there, it means the nth occurrence of that specific occurrence within the set of events the rule specifies 💅.
If you get BYxxx rule part values that are beyond the available scope (ie, BYMONTHDAY=30 in February), they're simply ignored 🙈.
Info that isn't in the rule but is needed to figure out the start times and dates of each recurrence instance comes from the Start Time (DTSTART) entry attribute 🧠. For example, "FREQ=YEARLY;BYMONTH=1" doesn't pick out a specific day of the month or a time. That info would be the same as whatever is set for DTSTART ⏰.
BYxxx rule parts change the recurrence in some way 🎀. The ones for a period of time that's the same as or bigger than the frequency generally reduce or limit how many occurrences get generated. For example, "FREQ=DAILY;BYMONTH=1" shrinks the instances from every day (if there's no BYMONTH tag) to every day in January ❄️. The ones for a period of time smaller than the frequency generally expand how many occurrences you get. For example, "FREQ=YEARLY;BYMONTH=1,2" bumps the days in the yearly set from 1 (if there's no BYMONTH tag) up to 2 🌈.
If you've got multiple BYxxx rule parts, then after evaluating the FREQ and INTERVAL parts, the BYxxx parts get applied to the current set of evaluated occurrences in this order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND and BYSETPOS. After that, COUNT and UNTIL get evaluated 🧁.
Here's an example of evaluating multiple BYxxx rule parts 🔍:
DTSTART;TZID=US-Eastern:19970105T083000
RRULE:FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9;
BYMINUTE=30First, INTERVAL=2 gets applied to FREQ=YEARLY to get "every other year" 🦋. Then BYMONTH=1 gets applied to get "every January, every other year" ❄️. Then BYDAY=SU gets applied to get "every Sunday in January, every other year" ☀️. Then BYHOUR=8,9 gets applied to get "every Sunday in January at 8 AM and 9 AM, every other year" ⏰. Then BYMINUTE=30 gets applied to get "every Sunday in January at 8:30 AM and 9:30 AM, every other year" 🕣. Then, since the RRULE doesn't give us the second, it gets pulled from DTSTART, so you end up with "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 part were missing, the matching minute, hour, day or month would be pulled from the DTSTART property 🫠.
No extra content value encoding (i.e., BACKSLASH character encoding) is defined for this value type 🙅♀️.
Example: Here's a rule that sets up 10 meetings that happen every other day 📅:
FREQ=DAILY;COUNT=10;INTERVAL=2There are other examples in the "RRULE" specification too 💖.
4.3.11 Text 💬
Value Name: TEXT
Purpose: okay so this value type is for anything that holds human readable text 📝
Formal Definition: the character sets supported by this revision of iCalendar are UTF-8 and US ASCII thereof 🌸 Support for other character sets is future work, so it's not in scope yet. Here's how the value type is defined:
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 = %x20-21 / %x23-2B / %x2D-39 / %x3C-5B
%x5D-7E / NON-US-ASCII
; Any character except CTLs not needed by the current
; character set, DQUOTE, ";", ":", "\", ","Note: other character sets might need changes to the definitions above, but that's beyond this document's scope 🙈
Description: if the property allows it, you can have multiple "text" values separated by a COMMA character (US-ASCII decimal 44) in a list 💅
The language the text is written in can be set with the "LANGUAGE" property parameter 🌈
An intentional formatted text line break MUST only be included in a "TEXT" property value by writing the line break as a BACKSLASH (US-ASCII decimal 92) followed by either a LATIN SMALL LETTER N (US-ASCII decimal 110) or a LATIN CAPITAL LETTER N (US-ASCII decimal 78). So it's "\n" or "\N" 🫶
"TEXT" property values can also contain special characters that act as delimiters, like a COMMA for lists or a SEMICOLON for structured values. To include those characters in a "TEXT" value, 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 in a "TEXT" property value MUST be escaped with a BACKSLASH character (US-ASCII decimal 92), and a SEMICOLON in a "TEXT" property value MUST be escaped with a BACKSLASH character (US-ASCII decimal 92). BUT a COLON in a "TEXT" property value SHALL NOT be escaped with a BACKSLASH character 💀 colons are the one exception, so no backslash for them, periodt ✨
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.4.3.12 Time ⏰
Value Name: TIME
Purpose: this value type is for values that hold a time of day 🕐
Formal Definition: the data 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 "leap" seconds.
time-utc = "Z"Description: if the property allows it, you can have multiple "time" values separated by a COMMA character (US-ASCII decimal 44) in a list. No extra content value encoding (like BACKSLASH character encoding) is defined for this value type 🍓
The "TIME" data type is for values that hold a time of day. The format is based on the [ISO 8601] complete representation, basic format for a time of day. The text format is a two-digit 24-hour clock (so values 0-23), a two-digit minute in the hour (values 0-59), and a two-digit second in the minute (values 0-60). A seconds value of 60 MUST only be used to account for "leap" seconds. Fractions of a second are not supported by this format 🧚
Just like the "DATE-TIME" definition above, the "TIME" data 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 formatFORM #1 LOCAL TIME 🌙
The local time form is simply a time value that doesn't have the UTC designator and doesn't reference a time zone. For example, 11:00 PM:
230000Time values of this type are called "floating" and aren't tied to any particular time zone. They represent the same hour, minute, and second no matter which time zone is being observed 🦋 For example, you could define an event where a person is busy from 11:00 AM to 1:00 PM every day, no matter what time zone they're in. In these cases, a local time can be specified. The recipient of an iCalendar object with a property value that's a local time, with no relative time zone information, SHOULD interpret the value as being fixed to whatever time zone the ATTENDEE is in at any given moment. That means two ATTENDEEs might join the same event at different UTC times, so floating time SHOULD only be used where that's reasonable behavior 🤔
In most cases you want a fixed time. To communicate a fixed time properly in a property value, either UTC time or local time with a time zone reference MUST be specified 💖
Using local time in a TIME value without the TZID property parameter means it's a local time value, regardless of whether "VTIMEZONE" calendar components exist in the iCalendar object 🌸
FORM #2: UTC TIME 🌍
UTC time, also called absolute time, is marked by a LATIN CAPITAL LETTER Z suffix character (US-ASCII decimal 90), the UTC designator, added to the end of the time value. For example, the following is 07:00 AM UTC:
070000ZThe 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 a time zone reference form uses the TZID property parameter to point at the right time zone definition. TZID gets the full story in the section on Time Zone 🎀
Example: the following is 8:30 AM in New York in Winter, five hours behind UTC, written in each of the three forms using the "X-TIMEOFDAY" non-standard property:
X-TIMEOFDAY:083000
X-TIMEOFDAY:133000Z
X-TIMEOFDAY;TZID=US-Eastern:0830004.3.13 URI 🔗
Value Name: URI
Purpose: this value type is for values that hold a uniform resource identifier (URI) type of reference to the property value ✨
Formal Definition: the data type is defined by the following notation:
uri = <As defined by any IETF RFC>Description: this data type might be used to reference binary information, for values that are large, or otherwise not something you'd want to put directly in the iCalendar object 📦
The URI value formats in RFC 1738, RFC 2111 and any other IETF registered value format can be specified 🌈
Any IANA registered URI format can be used. These include, but aren't limited to, the ones defined in RFC 1738 and RFC 2111 🦋
When a property parameter value is a URI value type, the URI MUST be specified as a quoted-string value 💅
No extra content value encoding (like BACKSLASH character encoding) is defined for this value type 🙈
Example: the following is a URI for a network file:
http://host1.com/my-report.txt4.3.14 UTC Offset 🌏
Value Name: UTC-OFFSET
Purpose: this value type is for properties that hold an offset from UTC to local time 🕰️
Formal Definition: the data type is defined by the following notation:
utc-offset = time-numzone ;As defined above in time data type
time-numzone = ("+" / "-") time-hour time-minute [time-
second]Description: the PLUS SIGN character MUST be specified for positive UTC offsets (so, ahead of UTC) ➕ The values "-0000" and "-000000" are not allowed. The time-second, if it's there, may not be 60. If it's absent, it defaults to zero 🍬
No extra content value encoding (like BACKSLASH character encoding) 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
+01004.4 iCalendar Object 🎁
The Calendaring and Scheduling Core Object is a collection of calendaring and scheduling information. Usually this info is a single iCalendar object, but multiple iCalendar objects can be grouped together one after another 📚 The first line and last line of the iCalendar object MUST contain a pair of iCalendar object delimiter strings. The syntax for an iCalendar object looks like this:
icalobject = 1*("BEGIN" ":" "VCALENDAR" CRLF
icalbody
"END" ":" "VCALENDAR" CRLF)Here's a simple example of an iCalendar object 🥳
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR4.5 Property 🎀
A property is the definition of one individual attribute that describes a calendar or a calendar component 💖 A property takes the form defined by the "contentline" notation in section 4.1.1.
Here's an example of a property:
DTSTART:19960415T133000ZThis memo puts no ordering on properties within an iCalendar object. Property order is totally free, bestie 🦋
Property names, parameter names and enumerated parameter values are case insensitive. So the property name "DUE" is the same as "due" and "Due", and DTSTART;TZID=US-Eastern:19980714T120000 is the same as DtStart;TzID=US-Eastern:19980714T120000 ✨
4.6. Calendar Components 🎀
okay so the body of an iCalendar object is basically a bunch of calendar properties 💅 plus one or more calendar components 🦋. The properties are the attributes that describe the calendar as a whole ✨. The components are little bundles of properties that each express one particular kind of calendar thing: an event 🎉, a to-do ✅, a journal entry 📓, time zone info 🌍, free/busy time 🕒, or an alarm ⏰.
The body of the iCalendar object is defined by this notation:
icalbody = calprops component
calprops = 2*(
; 'prodid' and 'version' are both REQUIRED,
; but MUST NOT occur more than once
prodid /version /
; 'calscale' and 'method' are optional,
; but MUST NOT occur more than once
calscale /
method /
x-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 CRLFAn iCalendar object MUST include the "PRODID" and "VERSION" calendar properties, no exceptions bestie 🫶. In addition, it MUST include at least one calendar component. Special forms are possible too 🌸: you can publish just busy time (so only a "VFREEBUSY" calendar component) or just time zone info (so only a "VTIMEZONE" calendar component). You can also go big and make a complex iCalendar object that captures a complete snapshot of a calendar, a composite of lots of different calendar components 📸. Most of the time though, an iCalendar object is just one "VEVENT", "VTODO" or "VJOURNAL" calendar component, and honestly that's the iconic classic look 💖.
4.6.1. Event Component 📅
Component Name: "VEVENT"
Purpose: Provide a grouping of component properties that describe an event.
Format Definition: A "VEVENT" calendar component is defined by the following notation:
eventc = "BEGIN" ":" "VEVENT" CRLF
eventprop *alarmc
"END" ":" "VEVENT" CRLF
eventprop = *(
; the following are optional,
; but MUST NOT occur more than once
class / created / description / dtstart / geo /
last-mod / location / organizer / priority /
dtstamp / seq / status / summary / transp /
uid / url / recurid /
; either 'dtend' or 'duration' may appear in
; a 'eventprop', but 'dtend' and 'duration'
; MUST NOT occur in the same 'eventprop'
dtend / duration /
; the following are optional,
; and MAY occur more than once
attach / attendee / categories / comment /
contact / exdate / exrule / rstatus / related /
resources / rdate / rrule / x-prop
)Description: A "VEVENT" is a grouping of component properties, and possibly "VALARM" calendar components too 🔔, that represents a scheduled chunk of time on a calendar. Like, it can be an activity, say a one-hour department meeting from 8:00 AM to 9:00 AM tomorrow 💼. Usually an event takes up time on an individual's calendar, so it shows up as an opaque interval when someone searches for busy time 🙈. BUT if you want, the event can have its Time Transparency set to "TRANSPARENT", which stops it from blocking anything in busy-time searches 🦋.
The "VEVENT" is also the component you use for an anniversary or a daily reminder 🎂. These events have a DATE value type for the "DTSTART" property instead of the default DATE-TIME data type. If one of these "VEVENT"s has a "DTEND" property, it MUST be specified as a DATE value also. The anniversary flavor of "VEVENT" can span more than one date, so the "DTEND" property value can be a calendar date after the "DTSTART" property value 🌈.
The "DTSTART" property for a "VEVENT" marks the inclusive start of the event 🏁. For recurring events, it also marks the very first instance in the recurrence set 🔁. The "DTEND" property for a "VEVENT" marks the non-inclusive end of the event 🛑. If a "VEVENT" has a "DTSTART" with a DATE data type but no "DTEND", the event's non-inclusive end is the end of the calendar date given by "DTSTART". If a "VEVENT" has a "DTSTART" with a DATE-TIME data type but no "DTEND", the event ends on that same calendar date and time of day as "DTSTART" 🕰️.
The "VEVENT" calendar component cannot be nested inside another calendar component 🙅♀️. However, "VEVENT" calendar components can be related to each other, or to a "VTODO" or a "VJOURNAL" calendar component, using the "RELATED-TO" property 🔗.
Example: Here's a "VEVENT" representing a meeting that will also be opaque to busy-time searches 💼:
BEGIN:VEVENT
UID:19970901T130000Z-123401@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970903T163000Z
DTEND:19970903T190000Z
SUMMARY:Annual Employee Review
CLASS:PRIVATE
CATEGORIES:BUSINESS,HUMAN RESOURCES
END:VEVENTAnd here's a "VEVENT" representing a reminder that is not opaque, but transparent, to busy-time searches 👀:
BEGIN:VEVENT
UID:19970901T130000Z-123402@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970401T163000Z
DTEND:19970402T010000Z
SUMMARY:Laurel is in sensitivity awareness class.
CLASS:PUBLIC
CATEGORIES:BUSINESS,HUMAN RESOURCES
TRANSP:TRANSPARENT
END:VEVENTAnd an anniversary that happens every year 💍. Since it takes up no time, it won't show up as opaque in a busy-time search, no matter what the "TRANSP" property says 🥹:
BEGIN:VEVENT
UID:19970901T130000Z-123403@host.com
DTSTAMP:19970901T1300Z
DTSTART:19971102
SUMMARY:Our Blissful Anniversary
CLASS:CONFIDENTIAL
CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
RRULE:FREQ=YEARLY
END:VEVENT4.6.2. To-do Component ✅
Component Name: VTODO
Purpose: Provide a grouping of calendar properties that describe a to-do.
Formal Definition: A "VTODO" calendar component is defined by the following notation:
todoc = "BEGIN" ":" "VTODO" CRLF
todoprop *alarmc
"END" ":" "VTODO" CRLF
todoprop = *(
; the following are optional,
; but MUST NOT occur more than once
class / completed / created / description / dtstamp /
dtstart / geo / last-mod / location / organizer /
percent / priority / recurid / seq / status /
summary / uid / url /
; either 'due' or 'duration' may appear in
; a 'todoprop', but 'due' and 'duration'
; MUST NOT occur in the same 'todoprop'
due / duration /
; the following are optional,
; and MAY occur more than once
attach / attendee / categories / comment / contact /
exdate / exrule / rstatus / related / resources /
rdate / rrule / x-prop
)Description: A "VTODO" is a grouping of component properties, and possibly "VALARM" calendar components, that stand in for an action item or assignment 📝. Think of it as a task with your name on it, like "turn in travel expense today" 💸. The "VTODO" calendar component cannot be nested inside another calendar component 🙅♀️. However, "VTODO" calendar components can be related to each other, or to a "VTODO" or a "VJOURNAL" calendar component, using the "RELATED-TO" property 🔗.
A "VTODO" without the "DTSTART" and "DUE" (or "DURATION") properties is a to-do that gets associated with each successive calendar date, until it's completed 🔁. Main character energy for a to-do that never lets you go 😭.
Example: Here's a "VTODO" calendar component 💅:
BEGIN:VTODO
UID:19970901T130000Z-123404@host.com
DTSTAMP:19970901T1300Z
DTSTART:19970415T133000Z
DUE:19970416T045959Z
SUMMARY:1996 Income Tax Preparation
CLASS:CONFIDENTIAL
CATEGORIES:FAMILY,FINANCE
PRIORITY:1
STATUS:NEEDS-ACTION
END:VTODO4.6.3 Journal Component 📓✨
Component Name: VJOURNAL
Purpose: Groups together the properties that describe a journal entry 💜
Formal Definition: A "VJOURNAL" calendar component is defined like this 👇
journalc = "BEGIN" ":" "VJOURNAL" CRLF
jourprop
"END" ":" "VJOURNAL" CRLF
jourprop = *(
; the following are optional,
; but MUST NOT occur more than once
class / created / description / dtstart / dtstamp /
last-mod / organizer / recurid / seq / status /
summary / uid / url /
; the following are optional,
; and MAY occur more than once
attach / attendee / categories / comment /
contact / exdate / exrule / related / rdate /
rrule / rstatus / x-prop
)Description: Okay so a "VJOURNAL" is basically a bundle of properties holding one or more text notes that are tied to a specific calendar date 📝 The "DTSTART" property is how you say which date the journal entry belongs to. It's usually a DATE value, but it can also be a DATE-TIME value, so you have options 🎀 Some examples are a daily record kept by a legislative body, a log of phone calls you made that day, or an ordered list of accomplishments. Oh, and a "VJOURNAL" can also link a document to a calendar date, which is so useful, iykyk 🙈
A "VJOURNAL" does not take up any time on a calendar 🦋 That means it doesn't count in free or busy time searches at all. It's like it has a time transparency value of TRANSPARENT, so every search just ignores it. Literally invisible to the searches 🫥
A "VJOURNAL" can't be nested inside another calendar component 🚫 But journals can be related to each other, or to a "VEVENT" or a "VTODO", using the "RELATED-TO" property. Main character linking energy 🔗💅
Example: Here's what a "VJOURNAL" looks like in action 🌸
BEGIN:VJOURNAL
UID:19970901T130000Z-123405@host.com
DTSTAMP:19970901T1300Z
DTSTART;VALUE=DATE:19970317
SUMMARY:Staff meeting minutes
DESCRIPTION:1. Staff meeting: Participants include Joe\, Lisa
and Bob. Aurora project plans were reviewed. There is currently
no budget reserves for this project. Lisa will escalate to
management. Next meeting on Tuesday.\n
2. Telephone Conference: ABC Corp. sales representative called
to discuss new printer. Promised to get us a demo by Friday.\n
3. Henry Miller (Handsoff Insurance): Car was totaled by tree.
Is looking into a loaner car. 654-2323 (tel).
END:VJOURNAL4.6.4 Free/Busy Component 🫧💙
Component Name: VFREEBUSY
Purpose: Groups together the properties that describe one of three things: a request for free/busy time, a response to a request for free/busy time, or a published set of busy time 🕰️
Formal Definition: A "VFREEBUSY" calendar component is defined like this 👇
freebusyc = "BEGIN" ":" "VFREEBUSY" CRLF
fbprop
"END" ":" "VFREEBUSY" CRLF
fbprop = *(
; the following are optional,
; but MUST NOT occur more than once
contact / dtstart / dtend / duration / dtstamp /
organizer / uid / url /
; the following are optional,
; and MAY occur more than once
attendee / comment / freebusy / rstatus / x-prop
)Description: A "VFREEBUSY" is a bundle of properties that does one of three jobs 🎯 It can ask for free/busy time, reply to that kind of request, or publish a set of busy time 📣
When it's asking for free/busy time 🙋♀️, the "ATTENDEE" property says whose free/busy time you want. The "ORGANIZER" property says who's doing the asking. The "DTSTART" and "DTEND" properties set the window of time you're asking about, and "UID" and "DTSTAMP" are there so multiple requests can be put in the right order 🔢
When it's replying 💌, the "ATTENDEE" property says who is answering. The "ORGANIZER" property says who originally asked. The "FREEBUSY" property holds the free/busy info (if there is any 🫣), and "UID" and "DTSTAMP" help keep multiple replies in order 📚
When it's publishing busy time 📢, the "ORGANIZER" property says whose busy time this is. "DTSTART" and "DTEND" set an inclusive time window around the busy info, the "FREEBUSY" property has the actual busy time, and "DTSTAMP" says when the iCalendar object was created ⏰
A "VFREEBUSY" can't be nested inside another calendar component 🙅♀️ But you can put several of them in one iCalendar object, which is great for grouping busy info into neat collections, like one group per month 🗓️✨
The "VFREEBUSY" component is meant for iCalendar object methods that involve asking for free time, asking for busy time, asking for both, and the replies to all of that 💫
Free/busy info is shown with the "FREEBUSY" property 🍓. It's a super compact way of writing down time periods. You can have one or more "FREEBUSY" properties in a "VFREEBUSY" component 🧁
When a "VFREEBUSY" component has "DTSTART" and "DTEND", those SHOULD come before any "FREEBUSY" properties 💅 When you're asking for free time, you can pair them with the "DURATION" property to ask for a chunk of free time inside a certain window of time ⏳
The recurrence properties ("RRULE", "EXRULE", "RDATE", "EXDATE") are not allowed in a "VFREEBUSY" component 🚫 Instead, any recurring events get broken down into their individual busy time periods using the "FREEBUSY" property 🧩
Example: Here's a "VFREEBUSY" used to ask for free or busy time 💬
BEGIN:VFREEBUSY
ORGANIZER:MAILTO:jane_doe@host1.com
ATTENDEE:MAILTO:john_public@host2.com
DTSTART:19971015T050000Z
DTEND:19971016T050000Z
DTSTAMP:19970901T083000Z
END:VFREEBUSYHere's a "VFREEBUSY" used to reply to that request with busy time info 💌
BEGIN:VFREEBUSY
ORGANIZER:MAILTO:jane_doe@host1.com
ATTENDEE:MAILTO:john_public@host2.com
DTSTAMP:19970901T100000Z
FREEBUSY;VALUE=PERIOD:19971015T050000Z/PT8H30M,
19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M
URL:http://host2.com/pub/busy/jpublic-01.ifb
COMMENT:This iCalendar file contains busy time information for
the next three months.
END:VFREEBUSYAnd here's a "VFREEBUSY" used to publish busy time info 📣
BEGIN:VFREEBUSY
ORGANIZER:jsmith@host.com
DTSTART:19980313T141711Z
DTEND:19980410T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
URL:http://www.host.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY4.6.5 Time Zone Component 🌍🕒
Component Name: VTIMEZONE
Purpose: Groups together the properties that define a time zone 🗺️
Formal Definition: A "VTIMEZONE" calendar component is defined like this 👇
timezonec = "BEGIN" ":" "VTIMEZONE" CRLF
2*(
; 'tzid' is required, but MUST NOT occur more
; than once
tzid /
; 'last-mod' and 'tzurl' are optional,
but MUST NOT occur more than once
last-mod / tzurl /
; one of 'standardc' or 'daylightc' MUST occur
..; and each MAY occur more than once.
standardc / daylightc /
; the following is optional,
; and MAY occur more than once
x-prop
)
"END" ":" "VTIMEZONE" CRLF
standardc = "BEGIN" ":" "STANDARD" CRLF
tzprop
"END" ":" "STANDARD" CRLF
daylightc = "BEGIN" ":" "DAYLIGHT" CRLF
tzprop
"END" ":" "DAYLIGHT" CRLF
tzprop = 3*(
; the following are each REQUIRED,
; but MUST NOT occur more than once
dtstart / tzoffsetto / tzoffsetfrom /
; the following are optional,
; and MAY occur more than once
comment / rdate / rrule / tzname / x-prop
)Description: Okay, so a time zone is locked in by the set of time rules that a governing body has set for a certain geographic area 🏛️ Those rules describe, at the very least, the base offset from UTC, which is often called the Standard Time offset 🕐 Lots of places shift their Standard Time forward or back by an hour to deal with the seasonal changes in daylight hours. That's called Daylight Saving Time ☀️ Some places shift by a fraction of an hour instead 🫠 Standard Time is also called Winter Time, and Daylight Saving Time goes by Advanced Time, Summer Time, or Legal Time in certain countries 🌞
Here's a table showing how the time zone rules for New York City changed starting in 1967. Each line is one observance or rule 📊
Effective Observance Rule
Date (Date/Time) Offset Abbreviation
1967-* last Sun in Oct, 02:00 -0500 EST
1967-1973 last Sun in Apr, 02:00 -0400 EDT
1974-1974 Jan 6, 02:00 -0400 EDT
1975-1975 Feb 23, 02:00 -0400 EDT
1976-1986 last Sun in Apr, 02:00 -0400 EDT
1987-* first Sun in Apr, 02:00 -0400 EDTNote: A global time zone registry isn't covered by this document. It's left for future study 🔮 But implementers might find the Olson time zone database [TZ] really helpful. It's an informal, public-domain collection of time zone info that volunteer Internet folks currently maintain, and it's used in several operating systems 💻 It has current and historical time zone info for tons of locations around the globe. It gives a time zone identifier for every unique time zone rule set that's been in actual use since 1970, with historical data going back to when standard time was introduced 🧠✨
Interoperability between two calendaring and scheduling apps is a big deal, especially for recurring events, to-dos, or journal entries 🫶 It all depends on being able to capture and share date and time info in an unambiguous format. Having current time zone info is a huge part of making that work 🎀
Okay so the VTIMEZONE calendar component is where the time zone gets its whole personality 🌍💅. It lays out the Standard Time and Daylight Saving Time observances (or rules) for one particular time zone over a given stretch of time, if it's there at all ✨. It literally cannot be nested inside other calendar components 🙅♀️. You can have several VTIMEZONE components in one iCalendar object, and when you do, each "VTIMEZONE" MUST represent a unique time zone definition 💖. This is super important for stuff like airline flights that take off in one time zone and land in another ✈️.
The "VTIMEZONE" calendar component MUST be present if the iCalendar object contains an RRULE that generates dates on both sides of a time zone shift (e.g. both in Standard Time and Daylight Saving Time) unless the iCalendar object intends to convey a floating time 🫠 (see the section "4.1.10.11 Time" for the proper interpretation of floating time). It can be present if the iCalendar object does not contain such a RRULE. Also, if a RRULE is present, there MUST be valid time zone information for all recurrence instances 📅.
The "VTIMEZONE" calendar component MUST include the "TZID" property and at least one definition of a standard or daylight component 🎀. The standard or daylight component MUST include the "DTSTART", "TZOFFSETFROM" and "TZOFFSETTO" properties, no exceptions 😤.
An individual "VTIMEZONE" calendar component MUST be specified for each unique "TZID" parameter value specified in the iCalendar object 🦋.
Each "VTIMEZONE" calendar component is a collection of one or more sub-components, and each one describes the rule for a particular observance (either a Standard Time or a Daylight Saving Time observance) 🌸. The "STANDARD" sub-component holds the properties that describe Standard Time, and the "DAYLIGHT" sub-component holds the ones that describe Daylight Saving Time 🌞. Generally speaking, that collection of properties covers:
- the first onset date-time for the observance
- the last onset date-time for the observance, if a last onset is known
- the offset to be applied for the observance
- a rule that describes the day and time when the observance takes effect
- an optional name for the observance
A given time zone can have multiple unique definitions of its observances over time 🕰️. Each observance is described using either a "STANDARD" or "DAYLIGHT" sub-component, and the whole collection of these sub-components is what describes the time zone for a given period. To figure out the offset at any moment, you find the observance with the last onset date and time before the time in question, then use the offset value from that observance 🔍. Main character energy, honestly 👑.
The top-level properties in a "VTIMEZONE" calendar component are:
The mandatory "TZID" property is a text value that uniquely identifies the VTIMZONE calendar component within the scope of an iCalendar object 🪪.
The optional "LAST-MODIFIED" property is a UTC value that specifies the date and time that this time zone definition was last updated 🕐.
The optional "TZURL" property is a url value that points to a published VTIMEZONE definition. TZURL SHOULD refer to a resource that is accessible by anyone who might need to interpret the object. This SHOULD NOT normally be a file: URL or other URL that is not widely-accessible 🌐. Like, the link should be something everyone can actually open, bestie 🙈.
The collection of properties used to define the STANDARD and DAYLIGHT sub-components includes:
The mandatory "DTSTART" property gives the effective onset date and local time for the time zone sub-component definition. "DTSTART" in this usage MUST be specified as a local DATE-TIME value 🧚.
The mandatory "TZOFFSETFROM" property gives the UTC offset that is in use when the onset of this time zone observance begins. "TZOFFSETFROM" is combined with "DTSTART" to define the effective onset for the time zone sub-component definition. For example, this represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City 🗽:
DTSTART:19671029T020000
TZOFFSETFROM:-0400The mandatory "TZOFFSETTO " property gives the UTC offset for the time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use 🍓.
The optional "TZNAME" property is the customary name for the time zone. It can be specified multiple times, so you can have multiple language variants of the time zone names 🌈. This is useful for displaying dates 📆.
If specified, the onset for the observance defined by the time zone sub-component is defined by either the "RRULE" or "RDATE" property. If neither is specified, only one sub-component can be specified in the "VTIMEZONE" calendar component, and it's assumed that the single observance specified is always in effect 💜.
The "RRULE" property defines the recurrence rule for the onset of the observance defined by this time zone sub-component. A few specific requirements for using RRULE this way:
- If the observance is known to have an effective end date, the "UNTIL" recurrence rule parameter MUST be used to specify the last valid onset of this observance (i.e., the UNTIL date-time will be equal to the last instance generated by the recurrence pattern). It MUST be specified in UTC time ⏳.
- The "DTSTART" and the "TZOFFSETTO" properties MUST be used when generating the onset date-time values (instances) from the RRULE 🔁.
Alternatively, the "RDATE" property can define the onset of the observance by giving the individual onset dates and times 🗓️. "RDATE" in this usage MUST be specified as a local DATE-TIME value in UTC time 🫶.
The optional "COMMENT" property is also allowed for descriptive, explanatory text 💬.
Example: here are some examples of the "VTIMEZONE" calendar component 🎀.
This is an example showing time zone information for the Eastern United States using the "RDATE" property. Note that this is only suitable for a recurring event that starts on or later than April 6, 1997 at 03:00:00 EDT (i.e., the earliest effective transition date and time) and ends no later than April 7, 1998 02:00:00 EST (i.e., the latest valid date and time for EST in this scenario). For example, this can be used for a recurring event that occurs every Friday, 8am-9:00 AM, starting June 1, 1997 and ending December 31, 1997 📆.
BEGIN:VTIMEZONE
TZID:US-Eastern
LAST-MODIFIED:19870101T000000Z
BEGIN:STANDARD
DTSTART:19971026T020000
RDATE:19971026T020000
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19971026T020000
RDATE:19970406T020000
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONEThis is a simple example showing the current time zone rules for the Eastern United States using a RRULE recurrence pattern. There's no effective end date on either the Standard Time or Daylight Time rule 🌟. This information would be valid for a recurring event starting today and continuing indefinitely ♾️.
BEGIN:VTIMEZONE
TZID:US-Eastern
LAST-MODIFIED:19870101T000000Z
TZURL:http://zones.stds_r_us.net/tz/US-Eastern
BEGIN:STANDARD
DTSTART:19671029T020000
RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19870405T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONEThis is an example showing a fictitious set of rules for the Eastern United States, where the Daylight Time rule has an effective end date (i.e., after that date, Daylight Time is no longer observed) 🫣.
BEGIN:VTIMEZONE
TZID:US--Fictitious-Eastern
LAST-MODIFIED:19870101T000000Z
BEGIN:STANDARD
DTSTART:19671029T020000
RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19870405T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONEThis is an example showing a fictitious set of rules for the Eastern United States, where the first Daylight Time rule has an effective end date. A second Daylight Time rule picks up where the other left off 🦋.
BEGIN:VTIMEZONE
TZID:US--Fictitious-Eastern
LAST-MODIFIED:19870101T000000Z
BEGIN:STANDARD
DTSTART:19671029T020000
RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19870405T020000
RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
BEGIN:DAYLIGHT
DTSTART:19990424T020000
RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=4
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONE4.6.6. Alarm Component ⏰
Component Name: VALARM
Purpose: Groups together the component properties that define an alarm. This is the reminder bestie, basically 🫶
Formal Definition: A VALARM calendar component is defined by the following notation:
alarmc = "BEGIN" ":" "VALARM" CRLF
(audioprop / dispprop / emailprop / procprop)
"END" ":" "VALARM" CRLF
audioprop = 2*(
; 'action' and 'trigger' are both REQUIRED,
; but MUST NOT occur more than once
action / trigger /
; 'duration' and 'repeat' are both optional,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat /
; the following is optional,
; but MUST NOT occur more than once
attach /
; the following is optional,
; and MAY occur more than once
x-prop
)
dispprop = 3*(
; the following are all REQUIRED,
; but MUST NOT occur more than once
action / description / trigger /
; 'duration' and 'repeat' are both optional,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat /
; the following is optional,
; and MAY occur more than once
*x-prop
)
emailprop = 5*(
; the following are all REQUIRED,
; but MUST NOT occur more than once
action / description / trigger / summary
; the following is REQUIRED,
; and MAY occur more than once
attendee /
; 'duration' and 'repeat' are both optional,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat /
; the following are optional,
; and MAY occur more than once
attach / x-prop
)
procprop = 3*(
; the following are all REQUIRED,
; but MUST NOT occur more than once
action / attach / trigger /
; 'duration' and 'repeat' are both optional,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat /
; 'description' is optional,
; and MUST NOT occur more than once
description /
; the following is optional,
; and MAY occur more than once
x-prop
)Description: A VALARM calendar component is a bundle of properties that acts as a reminder or alarm for an event or a to-do. For example, it can remind you about a pending event or nudge you about an overdue to-do 💅
The VALARM calendar component MUST include the ACTION and TRIGGER properties. The ACTION property adds more rules to the VALARM calendar component, like this:
When the action is AUDIO, the alarm can also include one and only one ATTACH property. That property MUST point to a sound resource, which gets rendered when the alarm goes off 🔊
When the action is DISPLAY, the alarm MUST also include a DESCRIPTION property, which holds the text that gets shown when the alarm is triggered 🎀
When the action is EMAIL, the alarm MUST include a DESCRIPTION property (the message body), a SUMMARY property (the message subject), and one or more ATTENDEE properties holding the email addresses of the people who should receive the message. It can also include one or more ATTACH properties, which are meant to be sent as attachments. When the alarm is triggered, the email message gets sent 📧
When the action is PROCEDURE, the alarm MUST include one and only one ATTACH property. That property MUST point to a procedure resource, which gets invoked when the alarm is triggered ⚙️
The VALARM calendar component MUST only appear inside a VEVENT or VTODO calendar component. VALARM calendar components cannot be nested. You can specify multiple mutually independent VALARM calendar components for a single VEVENT or VTODO calendar component, so go wild 🦋
The TRIGGER property decides when the alarm goes off. It sets a duration before the start of an event or a to-do. The TRIGGER edge can be explicitly set to be relative to the START or END of the event or to-do, using the RELATED parameter of the TRIGGER property. The TRIGGER property value type can also be set to an absolute calendar date and time of day instead 🕰️
For an alarm that's set to trigger on the START of an event or to-do, the DTSTART property MUST be present in the associated event or to-do. For an alarm in a VEVENT calendar component that's set to trigger on the END of the event, either the DTEND property MUST be present, or both the DTSTART and DURATION properties MUST be present. For an alarm in a VTODO calendar component that's set to trigger on the END of the to-do, either the DUE property MUST be present, or both the DTSTART and DURATION properties MUST be present.
An alarm can be set up to trigger repeatedly. An alarm with a repeating trigger MUST include both the DURATION and REPEAT properties. The DURATION property is the delay period after which the alarm repeats. The REPEAT property is the number of additional repetitions the alarm will trigger. That count is on top of the initial trigger. Both properties MUST be present to specify a repeating alarm. If either one is missing, the alarm won't repeat beyond its initial trigger 🔁
The ACTION property is used inside the VALARM calendar component to say what kind of action gets invoked when the alarm is triggered. The VALARM properties give enough info for a specific action to be invoked. It's usually the job of a "Calendar User Agent" (CUA) to deliver the alarm the way it's specified. An ACTION value of AUDIO means the alarm plays a sound to get the user's attention. DISPLAY means the alarm shows a text message to the user. EMAIL means the alarm sends an email message to one or more email addresses. PROCEDURE means the alarm runs a procedure. The ACTION property MUST specify one and only one of these values 💖
For an AUDIO alarm, if the optional ATTACH property is included, it MUST specify an audio sound resource. The point is that the sound plays as the alarm effect. If an ATTACH property doesn't refer to a sound resource, or if the sound resource can't be rendered (because its format isn't supported, or because it can't be retrieved), then the CUA or whatever else is responsible for playing the sound may choose a fallback. That could be playing a built-in default sound, or playing nothing at all 🤷♀️
For a DISPLAY alarm, the intended effect is for the text value of the DESCRIPTION property to be shown to the user 📝
For an EMAIL alarm, the intended effect is for an email message to be composed and delivered to all the addresses listed in the ATTENDEE properties of the VALARM calendar component. The DESCRIPTION property of the VALARM calendar component MUST be used as the body text of the message, and the SUMMARY property MUST be used as the subject text. Any ATTACH properties in the VALARM calendar component SHOULD be sent as attachments to the message 📎
For a PROCEDURE alarm, the ATTACH property in the VALARM calendar component MUST specify a procedure or program that is meant to be invoked as the alarm effect. If that procedure or program is in a format that can't be rendered, then no procedure alarm will be invoked. If the DESCRIPTION property is present, its value specifies the argument string to pass to the procedure or program. "Calendar User Agents" that receive an iCalendar object with this kind of alarm can disable it, allow the "Calendar User" to disable it, or otherwise ignore it. It's a super useful alarm capability, but the PROCEDURE type of alarm SHOULD be treated by the "Calendar User Agent" as a potential security risk 🚨
Examples: The following example is a VALARM calendar component that sets up an audio alarm which sounds at a precise time and then repeats 4 more times at 15 minute intervals:
BEGIN:VALARM
TRIGGER;VALUE=DATE-TIME:19970317T133000Z
REPEAT:4
DURATION:PT15M
ACTION:AUDIO
ATTACH;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell-01.aud
END:VALARMThe following example is a VALARM calendar component that sets up a display alarm which triggers 30 minutes before the scheduled start of the event (or the due date/time of the to-do it's attached to), and repeats 2 more times at 15 minute intervals:
BEGIN:VALARM
TRIGGER:-PT30M
REPEAT:2
DURATION:PT15M
ACTION:DISPLAY
DESCRIPTION:Breakfast meeting with executive\n
team at 8:30 AM EST.
END:VALARMThe following example is a VALARM calendar component that sets up an email alarm which triggers 2 days before the scheduled due date/time of a to-do it's attached to. It doesn't repeat. The email has a subject, a body, and an attachment link 💌
BEGIN:VALARM
TRIGGER:-P2D
ACTION:EMAIL
ATTENDEE:MAILTO:john_doe@host.com
SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING ***
DESCRIPTION:A draft agenda needs to be sent out to the attendees
to the weekly managers meeting (MGR-LIST). Attached is a
pointer the document template for the agenda file.
ATTACH;FMTTYPE=application/binary:http://host.com/templates/agen
da.doc
END:VALARMThe following example is a VALARM calendar component that sets up a procedural alarm which triggers at a precise date/time and repeats 23 more times at one hour intervals. The alarm invokes a procedure file 🧚
BEGIN:VALARM
TRIGGER;VALUE=DATE-TIME:19980101T050000Z
REPEAT:23
DURATION:PT1H
ACTION:PROCEDURE
ATTACH;FMTTYPE=application/binary:ftp://host.com/novo-
procs/felizano.exe
END:VALARM4.7. Calendar Properties 🌈
The Calendar Properties are attributes that apply to the iCalendar object as a whole. They don't show up inside a calendar component. They SHOULD be specified after the BEGIN:VCALENDAR property and before any calendar component. ✨
4.7.1. Calendar Scale 📅
Property Name: CALSCALE
Purpose: Okay so this property tells you which calendar scale the calendar info in the iCalendar object is using. 💅
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property. ✨
Conformance: The property can be specified in an iCalendar object. The default value is "GREGORIAN". 🌸
Description: This memo is based on the Gregorian calendar scale, bestie. 🗓️ If this property isn't in the iCalendar object, the Gregorian scale is assumed, so you get it by default. Other calendar scales are expected to be defined in other specs or in future versions of this memo, so keep an eye out. 👀
Format Definition: The property is defined by the following notation:
calscale = "CALSCALE" calparam ":" calvalue CRLF
calparam = *(";" xparam)
calvalue = "GREGORIAN" / iana-tokenExample: The following is an example of this property:
CALSCALE:GREGORIAN4.7.2. Method 📮
Property Name: METHOD
Purpose: This property defines the iCalendar object method that goes with the calendar object. It's giving method energy. 🎯
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: The property can be specified in an iCalendar object.
Description: When this is used in a MIME message entity, the value of this property MUST be the same as the Content-Type "method" parameter value. This property can only appear once within the iCalendar object. If either the "METHOD" property or the Content-Type "method" parameter is specified, then the other MUST also be specified. 🔁
No methods are defined by this specification. That's handled by other specs, like the iCalendar Transport-independent Interoperability Protocol (iTIP) defined by [ITIP]. 🧚
If this property isn't present in the iCalendar object, a scheduling transaction MUST NOT be assumed. In that case the iCalendar object is just carrying a snapshot of some calendar info, with no intention of sending a scheduling meaning. 📸
Format Definition: The property is defined by the following notation:
method = "METHOD" metparam ":" metvalue CRLF
metparam = *(";" xparam)
metvalue = iana-tokenExample: The following is a hypothetical example of this property, used to convey that the iCalendar object is a request for a meeting:
METHOD:REQUEST4.7.3. Product Identifier 🏷️
Property Name: PRODID
Purpose: This property specifies the identifier for the product that created the iCalendar object. Main character product, literally. 👑
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: The property MUST be specified once in an iCalendar object. 🙌
Description: The vendor of the implementation SHOULD assure that this is a globally unique identifier. One technique for that is using an FPI value, as defined in [ISO 9070]. 🌍
This property SHOULD not be used to change how an iCalendar object is interpreted beyond the semantics specified in this memo. For example, it isn't meant to help anyone understand non-standard properties. 🙅♀️
Format Definition: The property is defined by the following notation:
prodid = "PRODID" pidparam ":" pidvalue CRLF
pidparam = *(";" xparam)
pidvalue = text
;Any text that describes the product and version
;and that is generally assured of being unique.Example: The following is an example of this property. It does not imply that English is the default language. 🇬🇧
PRODID:-//ABC Corporation//NONSGML My Product//EN4.7.4. Version 🔢
Property Name: VERSION
Purpose: This property specifies the identifier for the highest version number, or the minimum and maximum range, of the iCalendar specification that you need in order to interpret the iCalendar object. 🧠
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: This property MUST be specified by an iCalendar object, but MUST only be specified once. 💖
Description: A value of "2.0" corresponds to this memo. ✨
Format Definition: The property is defined by the following notation:
version = "VERSION" verparam ":" vervalue CRLF
verparam = *(";" xparam)
vervalue = "2.0" ;This memo
/ maxver
/ (minver ";" maxver)
minver = <A IANA registered iCalendar version identifier>
;Minimum iCalendar version needed to parse the iCalendar object
maxver = <A IANA registered iCalendar version identifier>
;Maximum iCalendar version needed to parse the iCalendar objectExample: The following is an example of this property:
VERSION:2.04.8. Component Properties 🧩
The following properties can appear within calendar components, as each component property definition specifies. Think of it as a guest list for each component. 🎀
4.8.1. Descriptive Component Properties 📝
The following properties give you descriptive info about calendar components. It's the tea. ☕
4.8.1.1. Attachment 📎
Property Name: ATTACH
Purpose: This property lets you attach a document object to a calendar component. 🦋
Value Type: The default value type for this property is URI. You can also set the value type to BINARY, which means inline binary encoded content info. 🔐
Property Parameters: Non-standard, inline encoding, format type, and value data type property parameters can be specified on this property.
Conformance: The property can be specified in a "VEVENT", "VTODO", "VJOURNAL" or "VALARM" calendar component. 🌈
Description: The property can be specified within "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar components. It can be specified multiple times within an iCalendar object, so attach away. 🙌
Format Definition: The property is defined by the following notation:
attach = "ATTACH" attparam ":" uri CRLF
attach =/ "ATTACH" attparam ";" "ENCODING" "=" "BASE64"
";" "VALUE" "=" "BINARY" ":" binary
attparam = *(
; the following is optional,
; but MUST NOT occur more than once
(";" fmttypeparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: The following are examples of this property:
ATTACH:CID:jsmith.part3.960817T083000.xyzMail@host1.com
ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/
reports/r-960812.ps4.8.1.2. Categories 🏷️
Property Name: CATEGORIES
Purpose: This property defines the categories for a calendar component. Sorting your vibes, basically. 🗂️
Value Type: TEXT
Property Parameters: Non-standard and language property parameters can be specified on this property.
Conformance: The property can be specified within "VEVENT", "VTODO" or "VJOURNAL" calendar components.
Description: This property specifies categories or subtypes of the calendar component. Categories are super useful for searching for a calendar component of a particular type and category. Within the "VEVENT", "VTODO" or "VJOURNAL" calendar components, you can specify more than one category as a list, separated by the COMMA character (US-ASCII decimal 44). 🍓
Format Definition: The property is defined by the following notation:
categories = "CATEGORIES" catparam ":" text *("," text)
CRLF
catparam = *(
; the following is optional,
; but MUST NOT occur more than once
(";" languageparam ) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: The following are examples of this property:
CATEGORIES:APPOINTMENT,EDUCATION
CATEGORIES:MEETING4.8.1.3. Classification 🔒
Property Name: CLASS
Purpose: This property defines the access classification for a calendar component. It's the privacy setting, bestie. 🫣
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: The property can be specified once in a "VEVENT", "VTODO" or "VJOURNAL" calendar component. 🎯
Description: An access classification is only one piece of the general security system in a calendar app. It gives a way to capture how widely the calendar owner means for the info in one calendar entry to be seen. Its usefulness depends on the other security pieces of the calendar system, like calendar user authentication, authorization, access rights, access role, and so on. 🛡️ That means this memo alone can't fully define what each access classification means. And since most exchange processes using this memo are "blind," these classifications can't actually enforce anything on a system receiving an iCalendar object. Instead, they capture what the calendar owner intends for access to the component. 💭
Format Definition: The property is defined by the following notation:
class = "CLASS" classparam ":" classvalue CRLF
classparam = *(";" xparam)
classvalue = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / iana-token
/ x-name
;Default is PUBLICExample: The following is an example of this property:
CLASS:PUBLIC4.8.1.4. Comment 💬
Property Name: COMMENT
Purpose: This property carries non-processing info, meant to give a comment to the calendar user. Pure gossip-level stuff, no logic attached. 🤭
Value Type: TEXT
Property Parameters: Non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance: This property can be specified in "VEVENT", "VTODO", "VJOURNAL", "VTIMEZONE" or "VFREEBUSY" calendar components. 🌟
Description: The property can be specified multiple times. 🔁
Format Definition: The property is defined by the following notation:
comment = "COMMENT" commparam ":" text CRLF
commparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" altrepparam) / (";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: The following is an example of this property:
COMMENT:The meeting really needs to include both ourselves
and the customer. We can't hold this meeting without them.
As a matter of fact\, the venue for the meeting ought to be at
their site. - - JohnThe data type for this property is TEXT. 🦄
4.8.1.5. Description ✨
Property Name: DESCRIPTION 💖
Okay so this is the property that gives you the full tea on a calendar component, way more than the SUMMARY property does 🫶 Think of SUMMARY as the caption and DESCRIPTION as the whole essay 📝
Value Type: TEXT 🎀
Property Parameters: Non-standard, alternate text representation and language property parameters can be specified on this property ✨
Conformance: The property can be specified in the VEVENT, VTODO, VJOURNAL or VALARM calendar components. It can be specified multiple times only within a VJOURNAL calendar component 🦋
Description: In VEVENT and VTODO, this is where you dump all the lengthy textual details about the activity 💅
In VJOURNAL, it's used to hold one or more textual journal entries 📓🌸
In VALARM, it does triple duty 🔥. For a DISPLAY alarm, it's the display text. For an EMAIL alarm, it's the body text. For a PROCEDURE alarm, it's the argument string 🧚
Format Definition: The property is defined by the following notation:
description = "DESCRIPTION" descparam ":" text CRLF
descparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" altrepparam) / (";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: Here's an example with formatted line breaks in the value 🍓 (the \n is how you get a new line, bestie):
DESCRIPTION:Meeting to provide technical review for "Phoenix"
design.\n Happy Face Conference Room. Phoenix design team
MUST attend this meeting.\n RSVP to team leader.And here's one with folding for long lines, because nobody wants a giant wall of text 🙈:
DESCRIPTION:Last draft of the new novel is to be completed
for the editor's proof today.4.8.1.6. Geographic Position 🌍
Property Name: GEO 🗺️
Purpose: This property holds the global position for the activity that a calendar component describes 🧭
Value Type: FLOAT. The value MUST be two SEMICOLON separated FLOAT values. Two floats, separated by a semicolon, no excuses 💀
Property Parameters: Non-standard property parameters can be specified on this property ✨
Conformance: This property can be specified in VEVENT or VTODO calendar components 🌸
Description: The value gives latitude and longitude, in that order (so it's "LAT LON", not the other way around) 🦋 Longitude is east or west of the prime meridian. East is a positive real number and west is a negative one 🌈
The longitude and latitude values MAY be specified up to six decimal places. That gets you accuracy to within one meter of the geographical position 😭✨ Receiving applications MUST accept values at this precision, and they MAY truncate anything more precise than that 🫶
Latitude and longitude are written as decimal fractions of degrees. Whole degrees of latitude are a two-digit decimal number from 0 through 90. Whole degrees of longitude are a decimal number from 0 through 180. When there's a decimal fraction of a degree, it gets separated from the whole degrees by a decimal point 🎀
Latitudes north of the equator get a plus sign (+), or just no minus sign (-), in front of the degree digits. Latitudes south of the equator get a minus sign (-) in front of the degree digits. A point on the equator counts as Northern Hemisphere, no debate 🔥
Longitudes east of the prime meridian get a plus sign (+), or no minus sign (-), in front of the degree digits. Longitudes west of the meridian get a minus sign (-) in front of the degree digits. A point on the prime meridian counts as Eastern Hemisphere, and a point on the 180th meridian counts as Western Hemisphere 🌏 There's one exception to that last rule. When you're describing a band of latitude around the whole earth, the East Bounding Coordinate gets the value +180 (180) degrees 👑
Any spatial address with a latitude of +90 (90) or -90 degrees is the North or South Pole, respectively 🧊 The longitude component can be any legal value there, because it's giving no pressure 💅
Apart from that special band situation, this format comes from Department of Commerce, 1986, Representation of geographic point locations for information interchange (Federal Information Processing Standard 70-1): Washington, Department of Commerce, National Institute of Standards and Technology. Very official, very nerdy, I love it 📚💜
If you're converting degrees-minutes-seconds into decimal degrees, the simple formula is:
decimal = degrees + minutes/60 + seconds/3600.Format Definition: The property is defined by the following notation:
geo = "GEO" geoparam ":" geovalue CRLF
geoparam = *(";" xparam)
geovalue = float ";" float
;Latitude and Longitude componentsExample: Here's an example of this property 🍓
GEO:37.386013;-122.0829324.8.1.7. Location 📍
Property Name: LOCATION 🏠
Purpose: This property defines the intended venue for the activity in a calendar component ✨
Value Type: TEXT 🎀
Property Parameters: Non-standard, alternate text representation and language property parameters can be specified on this property 🌈
Conformance: This property can be specified in a VEVENT or VTODO calendar component 🌸
Description: You can name a specific venue like a conference room or meeting room right here 🏢 You can also add an alternate representation, which is a URI pointing to directory information with a more structured description of the location. For example, that alternate representation could be an LDAP URI pointing to an LDAP server entry, or a CID URI pointing to a MIME body part that contains a vCard [RFC 2426] for the location 🦋 Very organized, very iconic 💅
Format Definition: The property is defined by the following notation:
location = "LOCATION locparam ":" text CRLF
locparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" altrepparam) / (";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: Here are a couple of examples of this property 🧚
LOCATION:Conference Room - F123, Bldg. 002
LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":
Conference Room - F123, Bldg. 0024.8.1.8. Percent Complete 📊
Property Name: PERCENT-COMPLETE 💯
Purpose: An assignee or delegatee of a to-do uses this property to tell the Organizer how much of the to-do is done 🫶
Value Type: INTEGER 🔢
Property Parameters: Non-standard property parameters can be specified on this property ✨
Conformance: This property can be specified in a VTODO calendar component 🌸
Description: The value is a positive integer from zero to one hundred. A 0 means the to-do hasn't been started yet 🌱 A 100 means it's completely finished 🏆 Anything in between means it's partially done 🌈
When a to-do gets assigned to more than one person, the value shows the percent complete for that person's share of it 🤝 For example, say a to-do is assigned to both "A" and "B". If "A" replies with a percent complete of "70", that means "A" has finished 70% of the to-do assigned to them. If "B" replies with "50", that means "B" has finished 50% of the to-do assigned to them 💅
Format Definition: The property is defined by the following notation:
percent = "PERCENT-COMPLETE" pctparam ":" integer CRLF
pctparam = *(";" xparam)Example: Here's an example of this property showing 39% completion 🦋
PERCENT-COMPLETE:394.8.1.9. Priority 🚨
Property Name: PRIORITY 👑
Purpose: This property defines the relative priority of a calendar component 🔥
Value Type: INTEGER
Property Parameters: Non-standard property parameters can be specified on this property ✨
Conformance: This property can be specified in a VEVENT or VTODO calendar component 🌸
Description: Priority is an integer from zero to nine 🔢 A value of zero (US-ASCII decimal 48) means the priority is undefined 🫥 A value of one (US-ASCII decimal 49) is the highest priority 👑 A value of two (US-ASCII decimal 50) is the second highest, and so on. The numbers keep going down in ordinal priority, and nine (US-ASCII decimal 58) is the lowest priority 📉
Some CUAs use a three-level scheme of "HIGH", "MEDIUM" and "LOW". Those get mapped onto this property like so: a value from one (US-ASCII decimal 49) through four (US-ASCII decimal 52) means "HIGH" priority 🔴. A value of five (US-ASCII decimal 53) is the normal or "MEDIUM" priority 🟡. A value from six (US-ASCII decimal 54) through nine (US-ASCII decimal 58) means "LOW" priority 🟢
Other CUAs use a priority schema of "A1", "A2", "A3", "B1", "B2", ... "C3". That gets mapped as: a value of one (US-ASCII decimal 49) is "A1", a value of two (US-ASCII decimal 50) is "A2", a value of three (US-ASCII decimal 51) is "A3", and so on, up to a value of 9 (US-ASCII decimal 58) for "C3" 🧩
Other integer values are reserved for future use 🔮
Inside a VEVENT, this property sets a priority for the event. It may be handy when more than one event is scheduled for the same time period 📅
Inside a VTODO, this property sets a priority for the to-do. It's useful for ranking multiple action items in the same time period 🗂️
Format Definition: The property is specified by the following notation:
priority = "PRIORITY" prioparam ":" privalue CRLF
;Default is zero
prioparam = *(";" xparam)
privalue = integer ;Must be in the range [0..9]
; All other values are reserved for future useHere's an example of a property with the highest priority 👑
PRIORITY:1And here's one with the next highest priority ⭐
PRIORITY:2Example: Here's a property with no priority. This is the same as not specifying the PRIORITY property at all 🙈
PRIORITY:04.8.1.10 Resources 🎀
Property Name: RESOURCES
Purpose: okay so this one lets you list the equipment or resources you expect an activity on a calendar entry to need 🧰
Value Type: TEXT
Property Parameters: non-standard, alternate text representation and language property parameters can be specified on this property ✨
Conformance: this property can be specified in a "VEVENT" or "VTODO" calendar component 📅
Description: the property value is just arbitrary text 📝 You can list more than one resource by separating them with the COMMA character (US-ASCII decimal 44), so it's basically a little comma-separated list 🍓
Format Definition: the property is defined by the following notation:
resources = "RESOURCES" resrcparam ":" text *("," text) CRLF
resrcparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" altrepparam) / (";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: here's what it looks like 👀
RESOURCES:EASEL,PROJECTOR,VCR
RESOURCES;LANGUAGE=fr:1 raton-laveur4.8.1.11 Status 💅
Property Name: STATUS
Purpose: this property shows the overall status or confirmation for the calendar component 💖
Value Type: TEXT
Property Parameters: non-standard property parameters can be specified on this property 🎀
Conformance: this property can be specified in "VEVENT", "VTODO" or "VJOURNAL" calendar components 🦋
Description: in a group scheduled calendar component, the "Organizer" uses this property to confirm the event for the "Attendees" 🫶 In a "VEVENT", the "Organizer" can say that a meeting is tentative, confirmed or cancelled. In a "VTODO", the "Organizer" can say that an action item needs action, is completed, is in process or being worked on, or has been cancelled 🔥 In a "VJOURNAL", the "Organizer" can say that a journal entry is draft, final or has been cancelled or removed 📓
Format Definition: the property is defined by the following notation:
status = "STATUS" statparam] ":" statvalue CRLF
statparam = *(";" xparam)
statvalue = "TENTATIVE" ;Indicates event is
;tentative.
/ "CONFIRMED" ;Indicates event is
;definite.
/ "CANCELLED" ;Indicates event was
;cancelled.
;Status values for a "VEVENT"
statvalue =/ "NEEDS-ACTION" ;Indicates to-do needs action.
/ "COMPLETED" ;Indicates to-do completed.
/ "IN-PROCESS" ;Indicates to-do in process of
/ "CANCELLED" ;Indicates to-do was cancelled.
;Status values for "VTODO".
statvalue =/ "DRAFT" ;Indicates journal is draft.
/ "FINAL" ;Indicates journal is final.
/ "CANCELLED" ;Indicates journal is removed.
;Status values for "VJOURNAL".Example: for a "VEVENT" component, it looks like this ✨
STATUS:TENTATIVEFor a "VTODO" component, it's this 🧚
STATUS:NEEDS-ACTIONAnd for a "VJOURNAL" component, it's this 🌸
STATUS:DRAFT4.8.1.12 Summary 🌈
Property Name: SUMMARY
Purpose: this property gives a short summary or subject for the calendar component 💜
Value Type: TEXT
Property Parameters: non-standard, alternate text representation and language property parameters can be specified on this property 🎀
Conformance: the property can be specified in "VEVENT", "VTODO", "VJOURNAL" or "VALARM" calendar components 🦋
Description: in the "VEVENT", "VTODO" and "VJOURNAL" components, this property captures a short, one line summary about the activity or journal entry ✨
In the "VALARM" component, this property captures the subject of an EMAIL category of alarm 📧
Format Definition: the property is defined by the following notation:
summary = "SUMMARY" summparam ":" text CRLF
summparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" altrepparam) / (";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: here's an example 💖
SUMMARY:Department Party4.8.2 Date and Time Component Properties ⏰
The following properties specify date and time related information in calendar components 🕰️
4.8.2.1 Date/Time Completed ✅
Property Name: COMPLETED
Purpose: this property defines the date and time that a to-do was actually completed 🎉
Value Type: DATE-TIME
Property Parameters: non-standard property parameters can be specified on this property ✨
Conformance: the property can be specified in a "VTODO" calendar component 📝
Description: the date and time MUST be in a UTC format 🌍
Format Definition: the property is defined by the following notation:
completed = "COMPLETED" compparam ":" date-time CRLF
compparam = *(";" xparam)Example: here's an example 💅
COMPLETED:19960401T235959Z4.8.2.2 Date/Time End 🏁
Property Name: DTEND
Purpose: this property specifies the date and time that a calendar component ends 🌅
Value Type: the default value type is DATE-TIME, and it can be set to a DATE value type 💫
Property Parameters: non-standard, value data type, time zone identifier property parameters can be specified on this property 🌏
Conformance: this property can be specified in "VEVENT" or "VFREEBUSY" calendar components 🗓️
Description: within the "VEVENT" component, this property defines the date and time the event ends by. The value MUST be later in time than the value of the "DTSTART" property 🙈
Within the "VFREEBUSY" component, this property defines the end date and time for the free or busy time information. The time MUST be specified in the UTC time format. The value MUST be later in time than the value of the "DTSTART" property 🫧
Format Definition: the property is defined by the following notation:
dtend = "DTEND" dtendparam":" dtendval CRLF
dtendparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
(";" tzidparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
dtendval = date-time / date
;Value MUST match value typeExample: here are two examples 💖
DTEND:19960401T235959Z
DTEND;VALUE=DATE:199807044.8.2.3 Date/Time Due 🍓
Property Name: DUE
Purpose: this property defines the date and time that a to-do is expected to be completed 🗓️
Value Type: the default value type is DATE-TIME, and it can be set to a DATE value type 💫
Property Parameters: non-standard, value data type, time zone identifier property parameters can be specified on this property 🌏
Conformance: the property can be specified once in a "VTODO" calendar component ☝️
Description: the value MUST be a date/time equal to or after the DTSTART value, if specified 🙌
Format Definition: the property is defined by the following notation:
due = "DUE" dueparam":" dueval CRLF
dueparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
(";" tzidparam) /
; the following is optional,
; and MAY occur more than once
*(";" xparam)
)
dueval = date-time / date
;Value MUST match value typeExample: here's an example 🌸
DUE:19980430T235959Z4.8.2.4 Date/Time Start 🚀
Property Name: DTSTART
Purpose: this property specifies when the calendar component begins 🌅
Value Type: the default value type is DATE-TIME. The time value MUST be one of the forms defined for the DATE-TIME value type. The value type can be set to a DATE value type 🧩
Property Parameters: non-standard, value data type, time zone identifier property parameters can be specified on this property 🌏
Conformance: this property can be specified in the "VEVENT", "VTODO", "VFREEBUSY", or "VTIMEZONE" calendar components 🗂️
Description: within the "VEVENT" component, this property defines the start date and time for the event. The property is REQUIRED in "VEVENT" calendar components. Events can have a start date/time but no end date/time. In that case, the event does not take up any time ⏳
Within the "VFREEBUSY" component, this property defines the start date and time for the free or busy time information. The time MUST be specified in UTC time 🌍
Within the "VTIMEZONE" component, this property defines the effective start date and time for a time zone specification. This property is REQUIRED within each STANDARD and DAYLIGHT part included in "VTIMEZONE" calendar components and MUST be specified as a local DATE-TIME without the "TZID" property parameter 🌙
Format Definition: the property is defined by the following notation:
dtstart = "DTSTART" dtstparam ":" dtstval CRLF
dtstparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
(";" tzidparam) /
; the following is optional,
; and MAY occur more than once
*(";" xparam)
)
dtstval = date-time / date
;Value MUST match value typeExample: here's an example 🦋
DTSTART:19980118T073000Z4.8.2.5 Duration ⌛
Property Name: DURATION
Purpose: the property specifies a positive duration of time 💜
Value Type: DURATION
Property Parameters: non-standard property parameters can be specified on this property 🎀
Conformance: the property can be specified in "VEVENT", "VTODO", "VFREEBUSY" or "VALARM" calendar components 🦋
Description: in a "VEVENT" component the property may be used to specify a duration of the event, instead of an explicit end date/time. In a "VTODO" component the property may be used to specify a duration for the to-do, instead of an explicit due date/time. In a "VFREEBUSY" component the property may be used to specify the interval of free time being requested. In a "VALARM" component the property may be used to specify the delay period prior to repeating an alarm 🔔
Format Definition: the property is defined by the following notation:
duration = "DURATION" durparam ":" dur-value CRLF
;consisting of a positive duration of time.
durparam = *(";" xparam)Example: this example specifies an interval of time of 1 hour and zero minutes and zero seconds 🕐
DURATION:PT1H0M0SAnd this one specifies an interval of time of 15 minutes ⏱️
DURATION:PT15M4.8.2.6 Free/Busy Time
Property Name: FREEBUSY 🎀
Purpose: Okay bestie, this one lays out one or more free or busy time intervals so everyone can see exactly when someone is open or booked 💅
Value Type: PERIOD. The date and time values MUST be in an UTC time format 🌸
Property Parameters: Non-standard or free/busy time type property parameters can be specified on this property ✨
Conformance: The property can be specified in a VFREEBUSY calendar component 🦋
Property Parameter: FBTYPE and non-standard parameters can be specified on this property 💜
Description: These time periods can be specified as either a start and end date-time, or a start date-time and a duration. The date and time MUST be a UTC time format. No exceptions, periodt 🫶
FREEBUSY properties within the VFREEBUSY calendar component SHOULD be sorted in ascending order, based on start time and then end time, with the earliest periods first. Main character energy is the earliest one going first 👑
The FREEBUSY property can specify more than one value, separated by the COMMA character (US-ASCII decimal 44). In those cases, the FREEBUSY property values SHOULD all be of the same FBTYPE property parameter type. For example, all the values of a particular FBTYPE get listed together in a single property 🍓
Format Definition: The property is defined by the following notation:
freebusy = "FREEBUSY" fbparam ":" fbvalue
CRLF
fbparam = *(
; the following is optional,
; but MUST NOT occur more than once
(";" fbtypeparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
fbvalue = period *["," period]
;Time value MUST be in the UTC time format.Example: Here are some examples of this property 🧚
FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:19970308T160000Z/PT8H30M
FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H
FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H,
19970308T230000Z/19970309T000000Z4.8.2.7 Time Transparency
Property Name: TRANSP 🦋
Purpose: This property defines whether an event is transparent or not to busy time searches. It's giving "see-through or solid" energy ✨
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: This property can be specified once in a VEVENT calendar component.
Description: Time Transparency is the characteristic of an event that determines whether it appears to consume time on a calendar. Events that consume actual time for the individual or resource associated with the calendar SHOULD be recorded as OPAQUE, so they can be detected by free-busy time searches. Other events, which don't take up the individual's (or resource's) time, SHOULD be recorded as TRANSPARENT, which makes them invisible to free-busy time searches 🫧
Format Definition: The property is specified by the following notation:
transp = "TRANSP" tranparam ":" transvalue CRLF
tranparam = *(";" xparam)
transvalue = "OPAQUE" ;Blocks or opaque on busy time searches.
/ "TRANSPARENT" ;Transparent on busy time searches.
;Default value is OPAQUEExample: Here's the one for an event that's transparent, meaning it doesn't block free/busy time searches 🌈
TRANSP:TRANSPARENTAnd here's the one for an event that's opaque, meaning it does block free/busy time searches 🔥
TRANSP:OPAQUE4.8.3 Time Zone Component Properties
The following properties specify time zone information in calendar components 🌍
4.8.3.1 Time Zone Identifier
Property Name: TZID 🎀
Purpose: This property specifies the text value that uniquely identifies the VTIMEZONE calendar component. It's the name tag for the time zone 🏷️
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: This property MUST be specified in a VTIMEZONE calendar component 💖
Description: This is the label that any iCalendar properties use to reference a time zone calendar component, as long as their data type is either DATE-TIME or TIME and they aren't meant to be a UTC or a "floating" time. A SOLIDUS character (US-ASCII decimal 47) at the front signals that this TZID is an unique ID in a globally defined time zone registry (when such a 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 Olson database [TZ]. Globally unique time zone identifiers aren't addressed by this document and are left for future study. Lowkey a plot twist for later 🙈
Format Definition: This property is defined by the following notation:
tzid = "TZID" tzidpropparam ":" [tzidprefix] text CRLF
tzidpropparam = *(";" xparam)
;tzidprefix = "/"
; Defined previously. Just listed here for reader convenience.Example: These are examples of non-globally unique time zone identifiers 🍭
TZID:US-Eastern
TZID:California-Los_AngelesAnd this is a fictitious globally unique time zone identifier 🧁
TZID:/US-New_York-New_York4.8.3.2 Time Zone Name
Property Name: TZNAME 🎀
Purpose: This property specifies the customary designation for a time zone description. Basically the time zone's official nickname 💅
Value Type: TEXT
Property Parameters: Non-standard and language property parameters can be specified on this property.
Conformance: This property can be specified in a VTIMEZONE calendar component.
Description: This property may be specified in multiple languages, so it can meet different language needs 🌸
Format Definition: This property is defined by the following notation:
tzname = "TZNAME" tznparam ":" text CRLF
tznparam = *(
; the following is optional,
; but MUST NOT occur more than once
(";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: Here's an example of this property 🧚
TZNAME:ESTAnd here's one where two different languages are specified for the time zone name 🌈
TZNAME;LANGUAGE=en:EST
TZNAME;LANGUAGE=fr-CA:HNE4.8.3.3 Time Zone Offset From
Property Name: TZOFFSETFROM 🦋
Purpose: This property specifies the offset that's in use before this time zone observance kicks in ⏰
Value Type: UTC-OFFSET
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: This property MUST be specified in a VTIMEZONE calendar component. Non-negotiable, bestie 👑
Description: This property specifies the offset that's in use before this time observance. It's used to calculate the absolute time at which the transition to a given observance happens. This property MUST only be specified in a VTIMEZONE calendar component, and a VTIMEZONE calendar component MUST include this property. The value is a signed numeric that shows the number of hours, and possibly minutes, from UTC. Positive numbers mean time zones east of the prime meridian (ahead of UTC). Negative numbers mean time zones west of the prime meridian (behind UTC) 🌍✨
Format Definition: The property is defined by the following notation:
tzoffsetfrom = "TZOFFSETFROM" frmparam ":" utc-offset
CRLF
frmparam = *(";" xparam)Example: Here are examples of this property 💖
TZOFFSETFROM:-0500
TZOFFSETFROM:+13454.8.3.4 Time Zone Offset To
Property Name: TZOFFSETTO 🎀
Purpose: This property specifies the offset that's in use in this time zone observance. The new vibe after the switch 🌙
Value Type: UTC-OFFSET
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: This property MUST be specified in a VTIMEZONE calendar component 💅
Description: This property specifies the offset that's in use in this time zone observance. It's used to calculate the absolute time for the new observance. The value is a signed numeric that shows the number of hours, and possibly minutes, from UTC. Positive numbers mean time zones east of the prime meridian (ahead of UTC). Negative numbers mean time zones west of the prime meridian (behind UTC) 🫶
Format Definition: The property is defined by the following notation:
tzoffsetto = "TZOFFSETTO" toparam ":" utc-offset CRLF
toparam = *(";" xparam)Example: Here are examples of this property 🧁
TZOFFSETTO:-0400
TZOFFSETTO:+12454.8.3.5 Time Zone URL
Property Name: TZURL 🦋
Purpose: The TZURL gives a VTIMEZONE component a way to point to a network location where it can grab an up-to-date version of itself. It's like a little link to the freshest info 🔗
Value Type: URI
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: This property can be specified in a VTIMEZONE calendar component.
Description: The TZURL gives a VTIMEZONE component a way to point to a network location that can be used to retrieve an up-to-date version of itself. This is a hook for handling changes that government bodies make to time zone definitions, which is so iconic of them 🏛️✨. Retrieving this resource gives you an iCalendar object containing a single VTIMEZONE component and a METHOD property set to PUBLISH 🌸
Format Definition: The property is defined by the following notation:
tzurl = "TZURL" tzurlparam ":" uri CRLF
tzurlparam = *(";" xparam)Example: Here's an example of this property 🌈
TZURL:http://timezones.r.us.net/tz/US-California-Los_Angeles4.8.4 Relationship Component Properties
The following properties specify relationship information in calendar components 💜
4.8.4.1 Attendee
Property Name: ATTENDEE 💖
Purpose: okay so this property is how you define an "Attendee" inside a calendar component 🎀
Value Type: CAL-ADDRESS
Property Parameters: non-standard, language, calendar user type, group or list membership, participation role, participation status, RSVP expectation, delegatee, delegator, sent by, common name, or directory entry reference property parameters can all go on this property ✨
Conformance: bestie, this part is serious 🫶 This property MUST be specified in an iCalendar object that specifies a group scheduled calendar entity. This property MUST NOT be specified in an iCalendar object when you're publishing calendar info (so NOT in one that publishes a calendar user's busy time, event, to-do or journal). It's also not in an iCalendar object that only has a time zone definition, or one that defines calendar entities that aren't group scheduled and only live on a single user's calendar. 💅
Description: the property MUST only be specified within calendar components, to list the participants, non-participants and the chair of a group scheduled calendar entity 👑 It also shows up inside an "EMAIL" category of the "VALARM" calendar component, where it gives the email address that gets the email type of iCalendar alarm 📧
The parameters are the glow-up squad 🌸 CN is the common or displayable name tied to the calendar address. ROLE is the role the attendee is meant to have in the calendar component. PARTSTAT is the status of their participation. RSVP says whether a reply is requested (the favor of a reply, basically). CUTYPE tells you what kind of calendar user it is. MEMBER shows which groups the attendee belongs to. DELEGATED-TO lists the calendar users the original request got delegated to, and DELEGATED-FROM shows who it was delegated from. SENT-BY is for whoever is acting on behalf of the ATTENDEE, and DIR is a URI that points to the directory info for the attendee 🗂️
These parameters can go on an "ATTENDEE" property in a "VEVENT", "VTODO" or "VJOURNAL" calendar component. They MUST not be specified in an "ATTENDEE" property in a "VFREEBUSY" or "VALARM" calendar component 🙈 And if the LANGUAGE parameter is there, that language applies to the CN parameter 🌈
A recipient who got a delegated request MUST inherit the RSVP and ROLE values from the attendee who delegated it to them 🦋
You can have multiple attendees by including multiple "ATTENDEE" properties in the calendar component. The more the merrier ✨
Format Definition: here's the notation, no cap 🧚
attendee = "ATTENDEE" attparam ":" cal-address CRLF
attparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" cutypeparam) / (";"memberparam) /
(";" roleparam) / (";" partstatparam) /
(";" rsvpparam) / (";" deltoparam) /
(";" delfromparam) / (";" sentbyparam) /
(";"cnparam) / (";" dirparam) /
(";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: here's how it looks for a to-do 🍓
ORGANIZER:MAILTO:jsmith@host1.com
ATTENDEE;MEMBER="MAILTO:DEV-GROUP@host2.com":
MAILTO:joecool@host2.com
ATTENDEE;DELEGATED-FROM="MAILTO:immud@host3.com":
MAILTO:ildoit@host1.comAnd for multiple attendees on an event 👑
ORGANIZER:MAILTO:jsmith@host1.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;CN=Henry Cabot
:MAILTO:hcabot@host2.com
ATTENDEE;ROLE=REQ-PARTICIPANT;DELEGATED-FROM="MAILTO:bob@host.com"
;PARTSTAT=ACCEPTED;CN=Jane Doe:MAILTO:jdoe@host1.comHere's one with a URI to the attendee's directory info 🔍
ATTENDEE;CN=John Smith;DIR="ldap://host.com:6666/o=eDABC%
20Industries,c=3DUS??(cn=3DBJim%20Dolittle)":MAILTO:jimdo@
host1.comNow one with "delegatee" and "delegator" info for an event 🎀
ORGANIZER;CN=John Smith:MAILTO:jsmith@host.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;DELEGATED-FROM=
"MAILTO:iamboss@host2.com";CN=Henry Cabot:MAILTO:hcabot@
host2.com
ATTENDEE;ROLE=NON-PARTICIPANT;PARTSTAT=DELEGATED;DELEGATED-TO=
"MAILTO:hcabot@host2.com";CN=The Big Cheese:MAILTO:iamboss
@host2.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Jane Doe
:MAILTO:jdoe@host1.comAnd this one is for when another calendar user is acting on behalf of the "Attendee" 🙌
ATTENDEE;SENT-BY=MAILTO:jan_doe@host1.com;CN=John Smith:MAILTO:
jsmith@host1.com4.8.4.2 Contact
Property Name: CONTACT 📇
Purpose: this one holds contact info, or a reference to contact info, linked to the calendar component 💌
Value Type: TEXT
Property Parameters: non-standard, alternate text representation and language property parameters can be specified on this property 🌸
Conformance: this property can be specified in a "VEVENT", "VTODO", "VJOURNAL" or "VFREEBUSY" calendar component ✨
Description: the property value is textual contact info. You can also give an alternative representation that points to a URI for another form of the contact info, like a vCard [RFC 2426] 🧚
Format Definition: the notation, slay 💅
contact = "CONTACT" contparam ":" text CRLF
contparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" altrepparam) / (";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: plain textual contact info 🍓
CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234Now with an alternate representation as an LDAP URI to a directory entry with the contact info 🔍
CONTACT;ALTREP="ldap://host.com:6666/o=3DABC%20Industries\,
c=3DUS??(cn=3DBJim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234Here's an alternate representation as a MIME body part with the contact info, like a vCard [RFC 2426] embedded in a [MIME-DIR] content-type 🦋
CONTACT;ALTREP="CID=<part3.msg970930T083000SILVER@host.com>":Jim
Dolittle\, ABC Industries\, +1-919-555-1234And one referencing a network resource, like a vCard [RFC 2426] object with the contact info 🌈
CONTACT;ALTREP="http://host.com/pdi/jdoe.vcf":Jim
Dolittle\, ABC Industries\, +1-919-555-12344.8.4.3 Organizer
Property Name: ORGANIZER 👑
Purpose: this property defines the organizer for a calendar component 🎀
Value Type: CAL-ADDRESS
Property Parameters: non-standard, language, common name, directory entry reference, sent by property parameters can be specified on this property ✨
Conformance: this property MUST be specified in an iCalendar object that specifies a group scheduled calendar entity. It MUST also be specified in an iCalendar object that specifies the publication of a calendar user's busy time 🫶 This property MUST NOT be specified in an iCalendar object that specifies only a time zone definition, or that defines calendar entities that aren't group scheduled and are only on a single user's calendar 💅
Description: the property shows up within the "VEVENT", "VTODO", "VJOURNAL" calendar components to say who the organizer of a group scheduled calendar entity is 👑 In a "VFREEBUSY" component it says which calendar user is requesting the free or busy time. When a "VFREEBUSY" component is published, the property tells you which calendar the published busy time came from 🗓️
It has the parameters CN, for the common or display name of the "Organizer"; DIR, for a pointer to the directory info for the "Organizer"; and SENT-BY, for another calendar user who's acting on the "Organizer"'s behalf. The non-standard parameters can be specified on it too. If the LANGUAGE parameter is there, that language applies to the CN parameter value 🌸
Format Definition: the notation, periodt 💖
organizer = "ORGANIZER" orgparam ":"
cal-address CRLF
orgparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" cnparam) / (";" dirparam) / (";" sentbyparam) /
(";" languageparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)Example: the simplest version 🧚
ORGANIZER;CN=John Smith:MAILTO:jsmith@host1.comWith a pointer to the directory info for the organizer 🔍
ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ
ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith@host1.comAnd this one is used by another calendar user acting on behalf of the organizer. Responses are meant to go back to the organizer, not to that other calendar user 🙈
ORGANIZER;SENT-BY="MAILTO:jane_doe@host.com":
MAILTO:jsmith@host1.com4.8.4.4 Recurrence ID ✨
Property Name: RECURRENCE-ID
Purpose: okay so this one works together with the UID and SEQUENCE properties 🎀 to point at one specific instance of a recurring VEVENT, VTODO or VJOURNAL component. Its value is the effective value of the DTSTART property of that recurrence instance. 🦋
Value Type: the default is DATE-TIME 💖 and the time can be any of the valid DATE-TIME forms (see the DATE-TIME value type definition for what each form means). You can also set the value type to DATE. 📅
Property Parameters: non-standard, value data type, time zone identifier and recurrence identifier range parameters can all go on this one 💅
Conformance: this property shows up in an iCalendar object that has a recurring calendar component. 🌸
Description: the whole recurrence set is referenced by just the UID value of the component, and then RECURRENCE-ID lets you zoom in on one instance inside that set. ✨
If the DTSTART value is a DATE type value, then the value MUST be the calendar date for the recurrence instance. 📆
The date/time value is set to the time when the original recurrence instance would occur. So if you want to move a Friday meeting to Thursday, the date/time is still the original Friday meeting 🙈 (the vibe is "remember where it started, bestie").
Okay, here's the lore: for a given pair of UID and SEQUENCE values, the RECURRENCE-ID value for a recurrence instance is fixed. 🔒 But when the definition of the recurrence set changes (so the SEQUENCE value changes too), the RECURRENCE-ID for a given instance might also change. 🌈
The RANGE parameter tells you the effective range of recurrence instances starting from the instance named by the RECURRENCE-ID value. By default it's just that one single instance 🧚 The value can also be THISANDPRIOR, which covers the given instance and all the earlier ones, or THISANDFUTURE, which covers the given instance and all the later ones. 💜
Format Definition: the property is defined by the following notation:
recurid = "RECURRENCE-ID" ridparam ":" ridval CRLF
ridparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" "VALUE" "=" ("DATE-TIME" / "DATE)) /
(";" tzidparam) / (";" rangeparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
ridval = date-time / date
;Value MUST match value typeExample: here are some examples of this property 🍓
RECURRENCE-ID;VALUE=DATE:19960401
RECURRENCE-ID;RANGE=THISANDFUTURE:19960120T120000Z4.8.4.5 Related To 🔗
Property Name: RELATED-TO
Purpose: this property is how one calendar component refers to, or has a relationship with, another one. 🫶
Value Type: TEXT 📝
Property Parameters: non-standard and relationship type property parameters can go on this property 🌷
Conformance: this property can show up one or more times in the VEVENT, VTODO or VJOURNAL calendar components. 💫
Description: the value is the persistent, globally unique identifier of another calendar component. In a calendar component, that identifier shows up as the UID property. 🆔
By default, the value points to a calendar component that has a PARENT relationship to the component doing the referencing. The RELTYPE property parameter can either spell out that default PARENT relationship, or override it so you get a CHILD or SIBLING relationship instead. 👑 A PARENT relationship means the component is a subordinate of the referenced component. A CHILD relationship means the component is a superior of the referenced component. A SIBLING relationship means the component is a peer of the referenced component. 👯♀️
Changes to a component referenced by this property can have an implicit impact on the related component. For example, if a group event changes its start or end date or time, then the related, dependent events will need to have their start and end dates changed in a corresponding way. 🗓️ Similarly, if a PARENT component is canceled or deleted, there's an implied impact on the related CHILD components. 💀 This property is only meant to give information about how calendar components relate to each other. It's up to the target calendar system to keep up with any property implications of that relationship. 🧠
Format Definition: the property is defined by the following notation:
related = "RELATED-TO" [relparam] ":" text CRLF
relparam = *(
; the following is optional,
; but MUST NOT occur more than once
(";" reltypeparam) /
; the following is optional,
; and MAY occur more than once
(";" xparm)
)Example: the following are examples of this property 🧚♀️
RELATED-TO:<jsmith.part7.19960817T083000.xyzMail@host3.com>
RELATED-TO:<19960401-080045-4000F192713-0052@host1.com>4.8.4.6 Uniform Resource Locator 🌐
Property Name: URL
Purpose: this property defines a Uniform Resource Locator (URL) that goes with the iCalendar object. 🦋
Value Type: URI 🔗
Property Parameters: non-standard property parameters can go on this property 🎀
Conformance: this property can be specified once in the VEVENT, VTODO, VJOURNAL or VFREEBUSY calendar components. 💅
Description: a component can use this property to point to a place where a more dynamic version of the calendar info for that component can be found. ✨ This memo doesn't try to standardize the form of the URI, or the format of the resource it points to. 🤷♀️ And if both the URL property and the Content-Location MIME header are specified, they MUST point to the same resource. 🔥
Format Definition: the property is defined by the following notation:
url = "URL" urlparam ":" uri CRLF
urlparam = *(";" xparam)Example: the following is an example of this property 🌈
URL:http://abc.com/pub/calendars/jsmith/mytime.ics4.8.4.7 Unique Identifier 🆔
Property Name: UID
Purpose: this property defines the persistent, globally unique identifier for the calendar component. 💖
Value Type: TEXT 📝
Property Parameters: non-standard property parameters can go on this property 🌸
Conformance: the property MUST be specified in the VEVENT, VTODO, VJOURNAL or VFREEBUSY calendar components. This one is non-negotiable, bestie 😭
Description: the UID itself MUST be a globally unique identifier, and whoever generates it MUST guarantee that it's unique. 🔐 There are several algorithms that can do this 🧚 The identifier is RECOMMENDED to use the same syntax as the [RFC 822] addr-spec. A good way to make it unique is to put the domain name, or a domain literal IP address, of the host where the identifier was created on the right-hand side of the "@". On the left-hand side, put a combination of the current calendar date and time of day (formatted as a DATE-TIME value) along with some other currently unique (maybe sequential) identifier available on the system, like a process id number. 🍓 Using a date/time value on the left and a domain name or domain literal on the right makes uniqueness guaranteeable, since no two hosts should be using the same domain name or IP address at the same time. 🫶 Other algorithms will work too, but it is RECOMMENDED that the right-hand side contain some domain identifier (either the host's own or some other one), so that the generator can guarantee uniqueness of the left-hand side within the scope of that domain. 👑
This is how scheduling messages get matched up with the VEVENT, VTODO, or VJOURNAL calendar component they refer to. 📬
Same as before, the full range of components in a recurrence set is referenced by just the UID value of the component. The RECURRENCE-ID property lets you point at one individual instance inside that set. 🎯
This property is a big deal for group scheduling apps 🔥 It's how they match requests with later replies, modifications or deletion requests. Calendaring and scheduling applications MUST generate this property in VEVENT, VTODO and VJOURNAL calendar components so they interoperate with other group scheduling apps. 🤝 The calendar system that generates the iCalendar object is the one that creates this identifier. 🧚♀️
Implementations MUST be able to receive and persist values of at least 255 characters for this property. 💾
Format Definition: the property is defined by the following notation:
uid = "UID" uidparam ":" text CRLF
uidparam = *(";" xparam)Example: the following is an example of this property 🌟
UID:19960401T080045Z-4000F192713-0052@host1.com4.8.5 Recurrence Component Properties ✨
The following properties specify recurrence information in calendar components. 🔁
4.8.5.1 Exception Date/Times 🚫📅
Property Name: EXDATE 💅
Purpose: This property is the VIP list of date/time exceptions for a recurring calendar component. 🙅♀️
Value Type: The default value type is DATE-TIME, but you can switch it to DATE. 🎀
Property Parameters: Non-standard, value data type and time zone identifier params are allowed here. ✨
Conformance: You can put this on an iCalendar object that has a recurring calendar component in it. 🌸
Description: Okay so, exception dates are used when figuring out the recurrence set, which is basically the full guest list of every instance a calendar component shows up on. 🦋 The recurrence set gets built by looking at the starting DTSTART along with every RRULE, RDATE, EXDATE and EXRULE in the iCalendar object. DTSTART is the first instance in the set, period. You can stack multiple RRULE and EXRULE properties to make really fancy patterns. 💖 The final set is made by gathering every start date-time from the RRULE and RDATE properties, then kicking out anything that lands in the union of start date-times from the EXRULE and EXDATE properties. So the exclusion ones (EXDATE and EXRULE) always win over the inclusion ones (RDATE and RRULE). 👑 If RRULE and RDATE make the same instance twice, it only counts once. Duplicates get ignored, bye bye. 🙈
Here's the tea though: you can use EXDATE to exclude the DTSTART value, but the original DTSTART date MUST still be maintained by the calendaring and scheduling system. Why? Because other properties, like RECURRENCE-ID, depend on that original value. Don't delete it just because it's been excluded, bestie. 🫶
Format Definition: The property is defined by the following notation:
exdate = "EXDATE" exdtparam ":" exdtval *("," exdtval) CRLF
exdtparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
(";" tzidparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
exdtval = date-time / date
;Value MUST match value typeExample: The following is an example of this property:
EXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z4.8.5.2 Exception Rule 🙅♀️✨
Property Name: EXRULE 🧚
Purpose: This property defines a rule or repeating pattern for an exception to a recurrence set. 🌈
Value Type: RECUR 💜
Property Parameters: Non-standard property parameters can be specified on this property. 🍓
Conformance: You can specify this property in VEVENT, VTODO or VJOURNAL calendar components. 🎀
Description: Same energy as EXDATE, just with a rule instead of a list. 💅 The exception rule is used when computing the recurrence set, which is the complete set of recurrence instances for a calendar component. That set is built by looking at the starting DTSTART along with every RRULE, RDATE, EXDATE and EXRULE in the iCalendar object. DTSTART defines the first instance, and you can use multiple RRULE and EXRULE properties for more sophisticated sets. ✨ The final set gathers every start date-time from the RRULE and RDATE properties, and then removes any start date-time that falls within the union of start date-times from the EXRULE and EXDATE properties. The exclusion properties (EXDATE and EXRULE) take precedence over the inclusion properties (RDATE and RRULE). Duplicates from RRULE and RDATE only count once, and extra copies get ignored. 🦋
Same as before: you can use EXRULE to exclude the DTSTART value, but the original DTSTART date MUST still be maintained by the calendaring and scheduling system, because other properties like RECURRENCE-ID depend on it. 😭 Do not delete your starting point, periodt. 💀
Format Definition: The property is defined by the following notation:
exrule = "EXRULE" exrparam ":" recur CRLF
exrparam = *(";" xparam)Example: The following are examples of this property. Okay so this one means except every other week, on Tuesday and Thursday, for 4 occurrences:
EXRULE:FREQ=WEEKLY;COUNT=4;INTERVAL=2;BYDAY=TU,THExcept daily for 10 occurrences:
EXRULE:FREQ=DAILY;COUNT=10Except yearly in June and July for 8 occurrences:
EXRULE:FREQ=YEARLY;COUNT=8;BYMONTH=6,74.8.5.3 Recurrence Date/Times 📆🌸
Property Name: RDATE 🦋
Purpose: This property defines the list of date/times for a recurrence set. 💖
Value Type: The default value type is DATE-TIME, but you can set it to DATE or PERIOD. 🌈
Property Parameters: Non-standard, value data type and time zone identifier params are allowed here. ✨
Conformance: You can put this property in VEVENT, VTODO, VJOURNAL or VTIMEZONE calendar components. 🎀
Description: This one can hang out alongside RRULE to build an aggregate set of repeating occurrences. 👑 When both show up in an iCalendar object, the recurring events are the union of the occurrences from RDATE and RRULE combined. Iconic. 🫶
The recurrence dates, if you specify them, get used when computing the recurrence set. That set is built by looking at the starting DTSTART along with every RRULE, RDATE, EXDATE and EXRULE in the iCalendar object. DTSTART is the first instance, and you can use multiple RRULE and EXRULE properties for fancier sets. 💅 The final set collects every start date/time from the RRULE and RDATE properties, then drops anything inside the union of start date/times from EXRULE and EXDATE. Exclusion (EXDATE and EXRULE) beats inclusion (RDATE and RRULE) every single time. 🔥 Duplicate instances from RRULE and RDATE only count once, and the copies get ignored. 🙈
Format Definition: The property is defined by the following notation:
rdate = "RDATE" rdtparam ":" rdtval *("," rdtval) CRLF
rdtparam = *(
; the following are optional,
; but MUST NOT occur more than once
(";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) /
(";" tzidparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
rdtval = date-time / date / period
;Value MUST match value typeExample: The following are examples of this property:
RDATE:19970714T123000Z
RDATE;TZID=US-EASTERN:19970714T083000
RDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z,
19960404T010000Z/PT3H
RDATE;VALUE=DATE:19970101,19970120,19970217,19970421
19970526,19970704,19970901,19971014,19971128,19971129,199712254.8.5.4 Recurrence Rule 🔁💕
Property Name: RRULE 🌷
Purpose: This property defines a rule or repeating pattern for recurring events, to-dos, or time zone definitions. 🧁
Value Type: RECUR 💜
Property Parameters: Non-standard property parameters can be specified on this property. 🍓
Conformance: You can specify this property one or more times in recurring VEVENT, VTODO and VJOURNAL calendar components. You can also specify it once in each STANDARD or DAYLIGHT sub-component of the VTIMEZONE calendar component. 🌈
Description: Ngl, this is the main event. 🎀 The recurrence rule is used when computing the recurrence set, which is the complete set of recurrence instances for a calendar component. That set is built by looking at the starting DTSTART along with every RRULE, RDATE, EXDATE and EXRULE in the iCalendar object. DTSTART defines the first instance, and you can stack multiple RRULE and EXRULE properties for more sophisticated sets. ✨ The final set gathers all the start date/times from the RRULE and RDATE properties, then excludes anything inside the union of start date/times from EXRULE and EXDATE. Exclusion always takes precedence over inclusion. 👑 Duplicates from RRULE and RDATE only count once. 🦋
The DTSTART and DTEND pair, or the DTSTART and DURATION pair, in the iCalendar object defines the first instance of the recurrence. When you use a recurrence rule, the DTSTART and DTEND properties MUST be specified in local time, and the right set of VTIMEZONE calendar components MUST be included. For more on how VTIMEZONE works, check out its own calendar component definition. 🌍💖
Any duration tied to the iCalendar object applies to every member of the generated recurrence set. If a specific recurrence needs a modified duration, that MUST be explicitly specified using the RDATE property. 🙌
Format Definition: This property is defined by the following notation:
rrule = "RRULE" rrulparam ":" recur CRLF
rrulparam = *(";" xparam)Example: All of these examples assume the Eastern United States time zone. 🗽 Daily for 10 occurrences:
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
==> (1997 9:00 AM EDT)September 2-11Daily until December 24, 1997:
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
==> (1997 9:00 AM EDT)September 2-30;October 1-25
(1997 9:00 AM EST)October 26-31;November 1-30;December 1-23Every other day, forever:
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=DAILY;INTERVAL=2
==> (1997 9:00 AM EDT)September2,4,6,8...24,26,28,30;
October 2,4,6...20,22,24
(1997 9:00 AM EST)October 26,28,30;November 1,3,5,7...25,27,29;
Dec 1,3,...Every 10 days, 5 occurrences:
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
==> (1997 9:00 AM EDT)September 2,12,22;October 2,12Everyday in January, for 3 years:
DTSTART;TZID=US-Eastern:19980101T090000
RRULE:FREQ=YEARLY;UNTIL=20000131T090000Z;
BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA
or
RRULE:FREQ=DAILY;UNTIL=20000131T090000Z;BYMONTH=1
==> (1998 9:00 AM EDT)January 1-31
(1999 9:00 AM EDT)January 1-31
(2000 9:00 AM EDT)January 1-31Weekly for 10 occurrences 🎀
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=WEEKLY;COUNT=10
==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21
(1997 9:00 AM EST)October 28;November 4Weekly until December 24, 1997 🗓️
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=WEEKLY;UNTIL=19971224T000000Z
==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21
(1997 9:00 AM EST)October 28;November 4,11,18,25;
December 2,9,16,23Every other week, forever 🦋
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;WKST=SU
==> (1997 9:00 AM EDT)September 2,16,30;October 14
(1997 9:00 AM EST)October 28;November 11,25;December 9,23
(1998 9:00 AM EST)January 6,20;February
...Weekly on Tuesday and Thursday for 5 weeks 💅
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=WEEKLY;UNTIL=19971007T000000Z;WKST=SU;BYDAY=TU,TH
or
RRULE:FREQ=WEEKLY;COUNT=10;WKST=SU;BYDAY=TU,TH
==> (1997 9:00 AM EDT)September 2,4,9,11,16,18,23,25,30;October 2Every other week on Monday, Wednesday and Friday until December 24, 1997, but starting on Tuesday, September 2, 1997 🌸
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU;
BYDAY=MO,WE,FR
==> (1997 9:00 AM EDT)September 2,3,5,15,17,19,29;October
1,3,13,15,17
(1997 9:00 AM EST)October 27,29,31;November 10,12,14,24,26,28;
December 8,10,12,22Every other week on Tuesday and Thursday, for 8 occurrences ✨
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=8;WKST=SU;BYDAY=TU,TH
==> (1997 9:00 AM EDT)September 2,4,16,18,30;October 2,14,16Monthly on the 1st Friday for ten occurrences 👑
DTSTART;TZID=US-Eastern:19970905T090000
RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR
==> (1997 9:00 AM EDT)September 5;October 3
(1997 9:00 AM EST)November 7;Dec 5
(1998 9:00 AM EST)January 2;February 6;March 6;April 3
(1998 9:00 AM EDT)May 1;June 5Monthly on the 1st Friday until December 24, 1997 🌈
DTSTART;TZID=US-Eastern:19970905T090000
RRULE:FREQ=MONTHLY;UNTIL=19971224T000000Z;BYDAY=1FR
==> (1997 9:00 AM EDT)September 5;October 3
(1997 9:00 AM EST)November 7;December 5Every other month on the 1st and last Sunday of the month for 10 occurrences 🍓
DTSTART;TZID=US-Eastern:19970907T090000
RRULE:FREQ=MONTHLY;INTERVAL=2;COUNT=10;BYDAY=1SU,-1SU
==> (1997 9:00 AM EDT)September 7,28
(1997 9:00 AM EST)November 2,30
(1998 9:00 AM EST)January 4,25;March 1,29
(1998 9:00 AM EDT)May 3,31Monthly on the second to last Monday of the month for 6 months 🧚
DTSTART;TZID=US-Eastern:19970922T090000
RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO
==> (1997 9:00 AM EDT)September 22;October 20
(1997 9:00 AM EST)November 17;December 22
(1998 9:00 AM EST)January 19;February 16Monthly on the third to the last day of the month, forever 🌙
DTSTART;TZID=US-Eastern:19970928T090000
RRULE:FREQ=MONTHLY;BYMONTHDAY=-3
==> (1997 9:00 AM EDT)September 28
(1997 9:00 AM EST)October 29;November 28;December 29
(1998 9:00 AM EST)January 29;February 26
...Monthly on the 2nd and 15th of the month for 10 occurrences 💜
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=2,15
==> (1997 9:00 AM EDT)September 2,15;October 2,15
(1997 9:00 AM EST)November 2,15;December 2,15
(1998 9:00 AM EST)January 2,15Monthly on the first and last day of the month for 10 occurrences 🫶
DTSTART;TZID=US-Eastern:19970930T090000
RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=1,-1
==> (1997 9:00 AM EDT)September 30;October 1
(1997 9:00 AM EST)October 31;November 1,30;December 1,31
(1998 9:00 AM EST)January 1,31;February 1Every 18 months on the 10th thru 15th of the month for 10 occurrences 🔥
DTSTART;TZID=US-Eastern:19970910T090000
RRULE:FREQ=MONTHLY;INTERVAL=18;COUNT=10;BYMONTHDAY=10,11,12,13,14,
15
==> (1997 9:00 AM EDT)September 10,11,12,13,14,15
(1999 9:00 AM EST)March 10,11,12,13Every Tuesday, every other month 🎀
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=MONTHLY;INTERVAL=2;BYDAY=TU
==> (1997 9:00 AM EDT)September 2,9,16,23,30
(1997 9:00 AM EST)November 4,11,18,25
(1998 9:00 AM EST)January 6,13,20,27;March 3,10,17,24,31
...Yearly in June and July for 10 occurrences ☀️
DTSTART;TZID=US-Eastern:19970610T090000
RRULE:FREQ=YEARLY;COUNT=10;BYMONTH=6,7
==> (1997 9:00 AM EDT)June 10;July 10
(1998 9:00 AM EDT)June 10;July 10
(1999 9:00 AM EDT)June 10;July 10
(2000 9:00 AM EDT)June 10;July 10
(2001 9:00 AM EDT)June 10;July 10Note: Since none of the BYDAY, BYMONTHDAY or BYYEARDAY components are specified, the day is gotten from DTSTART 👀
Every other year on January, February, and March for 10 occurrences ❄️
DTSTART;TZID=US-Eastern:19970310T090000
RRULE:FREQ=YEARLY;INTERVAL=2;COUNT=10;BYMONTH=1,2,3
==> (1997 9:00 AM EST)March 10
(1999 9:00 AM EST)January 10;February 10;March 10
(2001 9:00 AM EST)January 10;February 10;March 10
(2003 9:00 AM EST)January 10;February 10;March 10Every 3rd year on the 1st, 100th and 200th day for 10 occurrences 🌷
DTSTART;TZID=US-Eastern:19970101T090000
RRULE:FREQ=YEARLY;INTERVAL=3;COUNT=10;BYYEARDAY=1,100,200
==> (1997 9:00 AM EST)January 1
(1997 9:00 AM EDT)April 10;July 19
(2000 9:00 AM EST)January 1
(2000 9:00 AM EDT)April 9;July 18
(2003 9:00 AM EST)January 1
(2003 9:00 AM EDT)April 10;July 19
(2006 9:00 AM EST)January 1Every 20th Monday of the year, forever 🌟
DTSTART;TZID=US-Eastern:19970519T090000
RRULE:FREQ=YEARLY;BYDAY=20MO
==> (1997 9:00 AM EDT)May 19
(1998 9:00 AM EDT)May 18
(1999 9:00 AM EDT)May 17
...Monday of week number 20 (where the default start of the week is Monday), forever 🧁
DTSTART;TZID=US-Eastern:19970512T090000
RRULE:FREQ=YEARLY;BYWEEKNO=20;BYDAY=MO
==> (1997 9:00 AM EDT)May 12
(1998 9:00 AM EDT)May 11
(1999 9:00 AM EDT)May 17
...Every Thursday in March, forever 🌼
DTSTART;TZID=US-Eastern:19970313T090000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=TH
==> (1997 9:00 AM EST)March 13,20,27
(1998 9:00 AM EST)March 5,12,19,26
(1999 9:00 AM EST)March 4,11,18,25
...Every Thursday, but only during June, July, and August, forever 🏖️
DTSTART;TZID=US-Eastern:19970605T090000
RRULE:FREQ=YEARLY;BYDAY=TH;BYMONTH=6,7,8
==> (1997 9:00 AM EDT)June 5,12,19,26;July 3,10,17,24,31;
August 7,14,21,28
(1998 9:00 AM EDT)June 4,11,18,25;July 2,9,16,23,30;
August 6,13,20,27
(1999 9:00 AM EDT)June 3,10,17,24;July 1,8,15,22,29;
August 5,12,19,26
...Every Friday the 13th, forever 🖤
DTSTART;TZID=US-Eastern:19970902T090000
EXDATE;TZID=US-Eastern:19970902T090000
RRULE:FREQ=MONTHLY;BYDAY=FR;BYMONTHDAY=13
==> (1998 9:00 AM EST)February 13;March 13;November 13
(1999 9:00 AM EDT)August 13
(2000 9:00 AM EDT)October 13
...The first Saturday that follows the first Sunday of the month, forever 🥳
DTSTART;TZID=US-Eastern:19970913T090000
RRULE:FREQ=MONTHLY;BYDAY=SA;BYMONTHDAY=7,8,9,10,11,12,13
==> (1997 9:00 AM EDT)September 13;October 11
(1997 9:00 AM EST)November 8;December 13
(1998 9:00 AM EST)January 10;February 7;March 7
(1998 9:00 AM EDT)April 11;May 9;June 13...
...Every four years, the first Tuesday after a Monday in November, forever (U.S. Presidential Election day) 🇺🇸
DTSTART;TZID=US-Eastern:19961105T090000
RRULE:FREQ=YEARLY;INTERVAL=4;BYMONTH=11;BYDAY=TU;BYMONTHDAY=2,3,4,
5,6,7,8
==> (1996 9:00 AM EST)November 5
(2000 9:00 AM EST)November 7
(2004 9:00 AM EST)November 2
...The 3rd instance into the month of one of Tuesday, Wednesday or Thursday, for the next 3 months 🥇
DTSTART;TZID=US-Eastern:19970904T090000
RRULE:FREQ=MONTHLY;COUNT=3;BYDAY=TU,WE,TH;BYSETPOS=3
==> (1997 9:00 AM EDT)September 4;October 7
(1997 9:00 AM EST)November 6The 2nd to last weekday of the month 🫠
DTSTART;TZID=US-Eastern:19970929T090000
RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-2
==> (1997 9:00 AM EDT)September 29
(1997 9:00 AM EST)October 30;November 27;December 30
(1998 9:00 AM EST)January 29;February 26;March 30
...Every 3 hours from 9:00 AM to 5:00 PM on a specific day ⏰
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=HOURLY;INTERVAL=3;UNTIL=19970902T170000Z
==> (September 2, 1997 EDT)09:00,12:00,15:00Every 15 minutes for 6 occurrences ⏱️
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=MINUTELY;INTERVAL=15;COUNT=6
==> (September 2, 1997 EDT)09:00,09:15,09:30,09:45,10:00,10:15Every hour and a half for 4 occurrences 🍪
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=MINUTELY;INTERVAL=90;COUNT=4
==> (September 2, 1997 EDT)09:00,10:30;12:00;13:30Every 20 minutes from 9:00 AM to 4:40 PM every day 🥰
DTSTART;TZID=US-Eastern:19970902T090000
RRULE:FREQ=DAILY;BYHOUR=9,10,11,12,13,14,15,16;BYMINUTE=0,20,40
or
RRULE:FREQ=MINUTELY;INTERVAL=20;BYHOUR=9,10,11,12,13,14,15,16
==> (September 2, 1997 EDT)9:00,9:20,9:40,10:00,10:20,
... 16:00,16:20,16:40
(September 3, 1997 EDT)9:00,9:20,9:40,10:00,10:20,
...16:00,16:20,16:40
...An example where the days generated makes a difference because of WKST 🧠
DTSTART;TZID=US-Eastern:19970805T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=MO
==> (1997 EDT)Aug 5,10,19,24Changing only WKST from MO to SU yields different results, so watch that one 👀
DTSTART;TZID=US-Eastern:19970805T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=SU
==> (1997 EDT)August 5,17,19,314.8.6 Alarm Component Properties ⏰
The following properties specify alarm information in calendar components 🔔
4.8.6.1 Action 💥
Property Name: ACTION
Purpose: This property defines the action to be invoked when an alarm is triggered 🚨
Value Type: TEXT
Property Parameters: Non-standard property parameters can be specified on this property.
Conformance: This property MUST be specified once in a "VALARM" calendar component.
Description: Each "VALARM" calendar component has a particular type of action associated with it. This property specifies the type of action
Format Definition: The property is defined by the following notation:
action = "ACTION" actionparam ":" actionvalue CRLF
actionparam = *(";" xparam)
actionvalue = "AUDIO" / "DISPLAY" / "EMAIL" / "PROCEDURE"
/ iana-token / x-nameExample: The following are examples of this property in a "VALARM" calendar component 📝
ACTION:AUDIO
ACTION:DISPLAY
ACTION:PROCEDURE4.8.6.2 Repeat Count 🔁
Property Name: REPEAT
Purpose: okay so this one defines how many times the alarm gets repeated after the initial trigger. bestie, it's giving snooze button 💅
Value Type: INTEGER
Property Parameters: non-standard property parameters can be specified on this property ✨
Conformance: this property can be specified in a "VALARM" calendar component 🎀
Description: if the alarm triggers more than once, then this property MUST be specified along with the "DURATION" property. no skipping this one, it's literally the rule 🙈
Format Definition: the property is defined by the following notation:
repeatcnt = "REPEAT" repparam ":" integer CRLF
;Default is "0", zero.
repparam = *(";" xparam)Example: here's an alarm that repeats 4 additional times, with a 5 minute delay after the initial trigger. so cute 🦋
REPEAT:4
DURATION:PT5M4.8.6.3 Trigger ⏰
Property Name: TRIGGER
Purpose: this one specifies when an alarm will trigger. main character timing, obviously 👑
Value Type: the default value type is DURATION. you can switch it to a DATE-TIME value type, but then the value MUST be a UTC formatted DATE-TIME value 🌍
Property Parameters: non-standard, value data type, time zone identifier or trigger relationship property parameters can be specified on this property. the trigger relationship property parameter MUST only be specified when the value type is DURATION. be careful with that one, bestie 💀
Conformance: this property MUST be specified in the "VALARM" calendar component. no excuses 🫶
Description: inside a "VALARM" component, this property decides when the alarm goes off. the default value type is DURATION, which means a relative time for the trigger. by default that duration is measured from the start of the event or to-do the alarm belongs to. you can explicitly anchor it to the end or the start of the associated event or to-do with the "RELATED" parameter. a value of START triggers off the start, and a value of END triggers off the end ✨
Either a positive or negative duration can be used for "TRIGGER". a positive duration fires after the associated start or end of the event or to-do. a negative duration fires before it. so it's giving time travel, but make it chronological 🧚
The "RELATED" property parameter is NOT valid when the value type is DATE-TIME (aka an absolute date and time alarm trigger), because there's nothing to be relative to there 🙅♀️. If the value type is DATE-TIME, the property value MUST be in UTC time format. And if an absolute trigger is set on an alarm for a recurring event or to-do, the alarm only goes off at that specified absolute date/time, plus any repeating instances you've set up 🔁
Now the anchoring rules, which are kind of a lot but so important 💅. If the trigger is set relative to START, then the "DTSTART" property MUST be present in the associated "VEVENT" or "VTODO" calendar component. If an event's alarm has its trigger set relative to the END, then the "DTEND" property, or the "DSTART" and "DURATION" properties, MUST be present in the associated "VEVENT" calendar component. For a to-do with a trigger set relative to the END, either the "DUE" property or the "DSTART" and "DURATION" properties MUST be present in the associated "VTODO" calendar component 🌸
Alarms on an event or to-do that's defined with a DATE value type trigger relative to 00:00:00 UTC on that specified date. For example, if DTSTART:19980205 is set, then the duration trigger is relative to 19980205T000000Z 🍓
Format Definition: the property is defined by the following notation:
trigger = "TRIGGER" (trigrel / trigabs)
trigrel = *(
; the following are optional,
; but MUST NOT occur more than once
(";" "VALUE" "=" "DURATION") /
(";" trigrelparam) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
) ":" dur-value
trigabs = 1*(
; the following is REQUIRED,
; but MUST NOT occur more than once
(";" "VALUE" "=" "DATE-TIME") /
; the following is optional,
; and MAY occur more than once
(";" xparam)
) ":" date-timeExample: a trigger set 15 minutes before the start of the event or to-do 🌈
TRIGGER:-P15MA trigger set 5 minutes after the end of the event or to-do 💜
TRIGGER;RELATED=END:P5MA trigger set to an absolute date/time ⭐
TRIGGER;VALUE=DATE-TIME:19980101T050000Z4.8.7. Change Management Component Properties 📝
The following properties specify change management information in calendar components. this is the paper trail section, and honestly it's so organized 🎀
4.8.7.1 Date/Time Created 🌷
Property Name: CREATED
Purpose: this one records the date and time the calendar information was created by the calendar user agent in the calendar store ✨
Note: this is basically the creation date and time for a file in the file system. same energy, different app 💅
Value Type: DATE-TIME
Property Parameters: non-standard property parameters can be specified on this property ✨
Conformance: the property can be specified once in "VEVENT", "VTODO" or "VJOURNAL" calendar components 🦋
Description: the date and time is a UTC value 🌍
Format Definition: the property is defined by the following notation:
created = "CREATED" creaparam ":" date-time CRLF
creaparam = *(";" xparam)Example: here's an example of this property:
CREATED:19960329T133000Z4.8.7.2 Date/Time Stamp 💌
Property Name: DTSTAMP
Purpose: this one shows the date/time the instance of the iCalendar object was created. it's giving receipt timestamp 🧾
Value Type: DATE-TIME
Property Parameters: non-standard property parameters can be specified on this property 🌸
Conformance: this property MUST be included in the "VEVENT", "VTODO", "VJOURNAL" or "VFREEBUSY" calendar components. literally non-negotiable 🔥
Description: the value MUST be specified in the UTC time format 🌍
This property is also useful to protocols such as [IMIP] that have inherent latency issues when delivering content. it helps keep messages containing iCalendar objects in the right order, so nothing arrives out of sequence and gets confusing 🫶
This property is different from "CREATED" and "LAST-MODIFIED". those two track when the particular calendar data in the calendar store was created and last modified. "DTSTAMP" is different, because it's about when the iCalendar object representation of the calendar service information was created or last modified. two timestamps, two jobs, no drama 💜
Format Definition: the property is defined by the following notation:
dtstamp = "DTSTAMP" stmparam ":" date-time CRLF
stmparam = *(";" xparam)Example:
DTSTAMP:19971210T080000Z4.8.7.3 Last Modified ✏️
Property Name: LAST-MODIFIED
Purpose: this one specifies the date and time the information associated with the calendar component was last revised in the calendar store 🍓
Note: this is basically the modification date and time for a file in the file system. the glow-up timeline, iykyk 💖
Value Type: DATE-TIME
Property Parameters: non-standard property parameters can be specified on this property ✨
Conformance: this property can be specified in the "EVENT", "VTODO", "VJOURNAL" or "VTIMEZONE" calendar components 🦋
Description: the property value MUST be specified in the UTC time format 🌍
Format Definition: the property is defined by the following notation:
last-mod = "LAST-MODIFIED" lstparam ":" date-time CRLF
lstparam = *(";" xparam)Example: here are examples of this property:
LAST-MODIFIED:19960817T133000Z4.8.7.4 Sequence Number 🔢
Property Name: SEQUENCE
Purpose: this one defines the revision sequence number of the calendar component within a sequence of revisions. it's like a version number, but make it cute 🎀
Value Type: integer
Property Parameters: non-standard property parameters can be specified on this property ✨
Conformance: the property can be specified in "VEVENT", "VTODO" or "VJOURNAL" calendar components 🦋
Description: when a calendar component is created, its sequence number is zero (US-ASCII decimal 48). after that, the "Organizer's" CUA increments it monotonically, one step at a time, each time the "Organizer" makes a significant revision to the component. so it only goes up, never back 📈
When the "Organizer" changes any of these properties, the sequence number MUST be incremented:
- "DTSTART" 🛫
- "DTEND" 🛬
- "DUE" 📅
- "RDATE" 🔁
- "RRULE" 🌀
- "EXDATE" 🙅♀️
- "EXRULE" 🚫
- "STATUS" 🚦
Changes the "Organizer" makes to other properties can also force the sequence number to go up. The "Organizer" CUA MUST increment the sequence number whenever it changes properties in the calendar component that the "Organizer" thinks could jeopardize the validity of the "Attendees'" participation status. for example, moving a meeting from one locale to a distant locale could really mess with the "Attendees'" participation status, so the sequence number has to reflect that 🗺️
The "Organizer" includes this property in an iCalendar object it sends to an "Attendee", to specify the current version of the calendar component 📬
The "Attendee" includes this property in an iCalendar object it sends to the "Organizer", to specify which version of the calendar component the "Attendee" is referring to 💌
Bumping the sequence number is NOT how an "Organizer" asks for a response from the "Attendees". that job belongs to the "RSVP" parameter on the "ATTENDEE" property, which the "Organizer" uses to say a response is requested 🙋♀️
Format Definition: this property is defined by the following notation:
seq = "SEQUENCE" seqparam ":" integer CRLF
; Default is "0"
seqparam = *(";" xparam)Example: here's an example for a calendar component that the "Organizer" just created 🌱
SEQUENCE:0And here's one for a calendar component the "Organizer" has revised two different times 🌟
SEQUENCE:24.8.8 Miscellaneous Component Properties 🧚
The following properties specify information about a number of miscellaneous features of calendar components. this is the grab bag, and I'm obsessed 💖
4.8.8.1 Non-standard Properties ✨
Property Name: Any property name with a "X-" prefix
Purpose: okay bestie, this one is a whole framework for making your own properties 🧚 It's basically the extension zone, and it's giving creative freedom 💅
Value Type: TEXT
Property Parameters: Non-standard and language property parameters can be specified on this property.
Conformance: This property can be specified in any calendar component.
Description: So the MIME Calendaring and Scheduling Content Type gives us a "standard mechanism for doing non-standard things" 🦋 This extension support is there so implementers can "push the envelope" on the existing version of the memo. Extension properties are named by property and/or property parameter names that start with the prefix text "X-" (that's the two character sequence: LATIN CAPITAL LETTER X character followed by the HYPEN-MINUS character). Vendors are recommended to tack on another short prefix text right after that sentinel to identify themselves 🏷️ This keeps things readable and cuts down on name collisions between different vendors ✨
User agents that support this content type are expected to be able to parse the extension properties and property parameters, but they can ignore them 🫶
At present, there is no registration authority for names of extension properties and property parameters. The data type for this property is TEXT. Optionally, the data type can be any of the other valid data types 🌸
Format Definition: The property is defined by the following notation:
x-prop = x-name *(";" xparam) [";" languageparam] ":" text CRLF
; Lines longer than 75 octets should be foldedExample: The following might be the ABC vendor's extension for an audio-clip form of subject property 🎧
X-ABC-MMSUBJ;X-ABC-MMSUBJTYPE=wave:http://load.noise.org/mysubj.wav4.8.8.2 Request Status 📬
Property Name: REQUEST-STATUS
Purpose: This property tells you the status code that came back for a scheduling request 💌
Value Type: TEXT
Property Parameters: Non-standard and language property parameters can be specified on this property.
Conformance: The property can be specified in "VEVENT", "VTODO", "VJOURNAL" or "VFREEBUSY" calendar component.
Description: This property is used to return status code information related to the processing of an associated iCalendar object. The data type for this property is TEXT.
The value is made up of a short return status component, a longer return status description component, and optionally a status-specific data component. The components of the value are separated by the SEMICOLON character (US-ASCII decimal 59) ✨
The short return status is a PERIOD character (US-ASCII decimal 46) separated 3-tuple of integers. For example, "3.1.1". The successive levels of integers give you a finer and finer level of status code granularity 🔍
The following are the initial classes for the return status code. Individual iCalendar object methods will define specific return status codes for these classes. Other classes for the return status code may also be defined using the registration process defined later in this memo 🗂️
|==============+===============================================|
| Short Return | Longer Return Status Description |
| Status Code | |
|==============+===============================================|
| 1.xx | Preliminary success. This class of status |
| | of status code indicates that the request has |
| | request has been initially processed but that |
| | completion is pending. |
|==============+===============================================|
| 2.xx | Successful. This class of status code |
| | indicates that the request was completed |
| | successfuly. However, the exact status code |
| | can indicate that a fallback has been taken. |
|==============+===============================================|
| 3.xx | Client Error. This class of status code |
| | indicates that the request was not successful.|
| | The error is the result of either a syntax or |
| | a semantic error in the client formatted |
| | request. Request should not be retried until |
| | the condition in the request is corrected. |
|==============+===============================================|
| 4.xx | Scheduling Error. This class of status code |
| | indicates that the request was not successful.|
| | Some sort of error occurred within the |
| | calendaring and scheduling service, not |
| | directly related to the request itself. |
|==============+===============================================|Heads up, this one has some sharp edges 💀 Read the format rules closely!
Format Definition: The property is defined by the following notation:
rstatus = "REQUEST-STATUS" rstatparam ":"
statcode ";" statdesc [";" extdata]
rstatparam = *(
; the following is optional,
; but MUST NOT occur more than once
(";" languageparm) /
; the following is optional,
; and MAY occur more than once
(";" xparam)
)
statcode = 1*DIGIT *("." 1*DIGIT)
;Hierarchical, numeric return status code
statdesc = text
;Textual status description
extdata = text
;Textual exception data. For example, the offending property
;name and value or complete property line.Example: Here are some possible examples of this property 🎀 The COMMA and SEMICOLON separator characters in the property value are BACKSLASH character escaped because they appear in a text value 💅
REQUEST-STATUS:2.0;Success
REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01
REQUEST-STATUS:2.8; Success\, repeating event ignored. Scheduled
as a single event.;RRULE:FREQ=WEEKLY\;INTERVAL=2
REQUEST-STATUS:4.1;Event conflict. Date/time is busy.
REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
MAILTO:jsmith@host.com5 iCalendar Object Examples ✨
okay bestie, this part is all about examples 🦋 these are informational only, just illustrative iCalendar objects that fit this content type 💖
The first one is a three-day conference that starts at 8:00 AM EDT on September 18, 1996 and ends at 6:00 PM EDT on September 20, 1996 🎀
BEGIN:VCALENDAR PRODID:-//xyz Corp//NONSGML PDA Calendar Verson
1.0//EN VERSION:2.0 BEGIN:VEVENT DTSTAMP:19960704T120000Z
UID:uid1@host.com ORGANIZER:MAILTO:jsmith@host.com
DTSTART:19960918T143000Z DTEND:19960920T220000Z STATUS:CONFIRMED
CATEGORIES:CONFERENCE SUMMARY:Networld+Interop Conference
DESCRIPTION:Networld+Interop Conference
and Exhibit\nAtlanta World Congress Center\n
Atlanta, Georgia END:VEVENT END:VCALENDARNext up is a group scheduled meeting that starts at 8:30 AM EST on March 12, 1998 and ends at 9:30 AM EST on March 12, 1998 🧚 The "Organizer" has scheduled it with one or more calendar users in a group, and there's a time zone specification for Eastern United States in there too 🌸
BEGIN:VCALENDAR
PRODID:-//RDU Software//NONSGML HandCal//EN
VERSION:2.0
BEGIN:VTIMEZONE
TZID:US-Eastern
BEGIN:STANDARD
DTSTART:19981025T020000
RDATE:19981025T020000
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19990404T020000
RDATE:19990404T020000
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
DTSTAMP:19980309T231000Z
UID:guid-1.host1.com
ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com
ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
MAILTO:employee-A@host.com
DESCRIPTION:Project XYZ Review Meeting
CATEGORIES:MEETING
CLASS:PUBLIC
CREATED:19980309T130000Z
SUMMARY:XYZ Project Review
DTSTART;TZID=US-Eastern:19980312T083000
DTEND;TZID=US-Eastern:19980312T093000
LOCATION:1CP Conference Room 4350
END:VEVENT
END:VCALENDARHere's an iCalendar object passed in a MIME message, with a single body part that's a "text/calendar" Content Type 💌
TO:jsmith@host1.com
FROM:jdoe@host1.com
MIME-VERSION:1.0
MESSAGE-ID:<id3@host1.com>
CONTENT-TYPE:text/calendar
BEGIN:VCALENDAR
METHOD:xyz
VERSION:2.0
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VEVENT
DTSTAMP:19970324T1200Z
SEQUENCE:0
UID:uid3@host1.com
ORGANIZER:MAILTO:jdoe@host1.com
ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host1.com
DTSTART:19970324T123000Z
DTEND:19970324T210000Z
CATEGORIES:MEETING,PROJECT
CLASS:PUBLIC
SUMMARY:Calendaring Interoperability Planning Meeting
DESCRIPTION:Discuss how we can test c&s interoperability\n
using iCalendar and other IETF standards.
LOCATION:LDB Lobby
ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/
conf/bkgrnd.ps
END:VEVENT
END:VCALENDARNow a to-do that's due on April 15, 1998 🍓 It has an audio alarm that reminds the calendar user at noon on the day before the to-do is expected to be completed, and it repeats hourly four additional times. The to-do definition has been modified twice since it was first created, which you can see from the SEQUENCE value 🫶
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VTODO
DTSTAMP:19980130T134500Z
SEQUENCE:2
UID:uid4@host1.com
ORGANIZER:MAILTO:unclesam@us.gov
ATTENDEE;PARTSTAT=ACCEPTED:MAILTO:jqpublic@host.com
DUE:19980415T235959
STATUS:NEEDS-ACTION
SUMMARY:Submit Income Taxes
BEGIN:VALARM
ACTION:AUDIO
TRIGGER:19980403T120000
ATTACH;FMTTYPE=audio/basic:http://host.com/pub/audio-
files/ssbanner.aud
REPEAT:4
DURATION:PT1H
END:VALARM
END:VTODO
END:VCALENDARHere's a journal entry 📓✨
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VJOURNAL
DTSTAMP:19970324T120000Z
UID:uid5@host1.com
ORGANIZER:MAILTO:jsmith@host.com
STATUS:DRAFT
CLASS:PUBLIC
CATEGORY:Project Report, XYZ, Weekly Meeting
DESCRIPTION:Project xyz Review Meeting Minutes\n
Agenda\n1. Review of project version 1.0 requirements.\n2.
Definition
of project processes.\n3. Review of project schedule.\n
Participants: John Smith, Jane Doe, Jim Dandy\n-It was
decided that the requirements need to be signed off by
product marketing.\n-Project processes were accepted.\n
-Project schedule needs to account for scheduled holidays
and employee vacation time. Check with HR for specific
dates.\n-New schedule will be distributed by Friday.\n-
Next weeks meeting is cancelled. No meeting until 3/23.
END:VJOURNAL
END:VCALENDARAnd finally, an example of published busy time information 🌈 The iCalendar object might be placed at the network resource www.host.com/calendar/busytime/jsmith.ifb 💜
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//RDU Software//NONSGML HandCal//EN
BEGIN:VFREEBUSY
ORGANIZER:MAILTO:jsmith@host.com
DTSTART:19980313T141711Z
DTEND:19980410T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
URL:http://www.host.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY
END:VCALENDAR6 Recommended Practices 🎀
these are the recommended practices you should follow so everyone handles these cases the same way, no drama 💅
- Content lines longer than 75 octets SHOULD be folded.
- A calendar entry with a
DTSTARTproperty but noDTENDproperty doesn't take up any time 🕰️ It's meant to represent an event tied to a specific calendar date and time of day, like an anniversary. Since it doesn't take up any time, it MUST NOT be used to record busy time, no matter what the value for theTRANSPproperty is. - When the
DTSTARTandDTEND, forVEVENT,VJOURNALandVFREEBUSYcalendar components, andDTSTARTandDUE, forVTODOcalendar components, have the same value data type (e.g., DATE-TIME), they SHOULD specify values in the same time format (e.g., UTC time format). ⏰ - When the combination of the
RRULEandRDATEproperties on an iCalendar object produces multiple instances having the same start date/time, they should be collapsed to, and considered as, a single instance. 🧩 - When a calendar user receives multiple requests for the same calendar component (e.g., REQUEST for a
VEVENTcalendar component) because they're on multiple mailing lists specified byATTENDEEproperties in the request, they SHOULD respond to only one of the requests. The calendar user SHOULD also specify (using theMEMBERparameter of theATTENDEEproperty) which mailing list they're a member of. 📬 - An implementation can truncate a
SUMMARYproperty value to 255 characters. ✂️ - If seconds of the minute aren't supported by an implementation, then a value of
"00"SHOULD be specified for the seconds component in a time value. ⏱️ - If the value type parameter (
VALUE=) contains an unknown value type, it SHOULD be treated as TEXT. 🤷♀️ TZURLvalues SHOULD NOT be specified as a FILE URI type. This URI form can be useful within an organization, but it's problematic on the Internet 🙈- Some possible English values for the
CATEGORIESproperty are"ANNIVERSARY","APPOINTMENT","BUSINESS","EDUCATION","HOLIDAY","MEETING","MISCELLANEOUS","NON-WORKING HOURS","NOT IN OFFICE","PERSONAL","PHONE CALL","SICK DAY","SPECIAL OCCASION","TRAVEL", and"VACATION". Categories can be specified in any registered language 🌍 - Some possible English values for the
RESOURCESproperty are"CATERING","CHAIRS","COMPUTER PROJECTOR","EASEL","OVERHEAD PROJECTOR","SPEAKER PHONE","TABLE","TV","VCR","VIDEO PHONE", and"VEHICLE". Resources can be specified in any registered language 🎥
7 Registration of Content Type Elements 📝
this section explains how to register MIME Calendaring and Scheduling Content Type iCalendar object methods and new or modified properties, so let's get into it 🦋
7.1 Registration of New and Modified iCalendar Object Methods
New MIME Calendaring and Scheduling Content Type iCalendar object methods are registered by publishing an IETF Request for Comments (RFC) 📜 Changes to an iCalendar object method are registered by publishing a revision of the RFC that defines the method ✨
7.2 Registration of New Properties
this part defines the procedures for registering new properties, or new enumerated property values, for the MIME Calendaring and Scheduling Content Type with the IANA 🌸 Non-IANA properties can be used by bilateral agreement, as long as the property names follow the "X-" convention 💜
The procedures here are built to allow public comment and review of new properties, while posing only a small hurdle to defining new properties 🫶
Here's how registering a new property goes, step by step 👑
7.2.1 Define the property
A property is defined by filling out the following template 📋
To: ietf-calendar@imc.org
Subject: Registration of text/calendar MIME property XXX
Property name:
Property purpose:
Property value type(s):
Property parameter (s):
Conformance:
Description:
Format definition:
Examples:Here's what each field in the template means 🧚
- Property name: The name of the property, as it will appear in the body of a text/calendar MIME Content-Type "property: value" line, to the left of the colon ":".
- Property purpose: The purpose of the property (e.g., to indicate a delegate for the event or to-do, etc.). Give a short but clear description ✨
- Property value type (s): Any of the valid value types for the property value needs to be specified. The default value type also needs to be specified. If a new value type is specified, it needs to be declared in this section 🎀
- Property parameter (s): Any of the valid property parameters for the property needs to be specified.
- Conformance: The calendar components that the property can appear in needs to be specified.
- Description: Any special notes about the property, how it's to be used, etc. 💅
- Format definition: The ABNF for the property definition needs to be specified.
- Examples: One or more examples of instances of the property need to be specified 🍓
7.2.2 Post the Property definition
The property description MUST be posted to the new property discussion list, ietf-calendar@imc.org 📣
7.2.3 Allow a comment period
Discussion on the new property MUST be allowed to take place on the list for a minimum of two weeks ⏳ Consensus MUST be reached on the property before moving on to the next step 🫶
7.2.4 Submit the property for approval ✨
Okay so once the two-week comment period is over and the proposer is convinced consensus has been reached on the property, the registration application should be submitted to the Method Reviewer for approval 🫶. The Method Reviewer is appointed to the Application Area Directors, and they can either accept or reject the property registration 💅. If it's accepted, the Method Reviewer should pass it on to the IANA so it gets added to the official IANA method registry 🌸. It can be rejected for any of these reasons: 1) Insufficient comment period; 2) Consensus not reached; 3) Technical deficiencies raised on the list or elsewhere have not been addressed 💀. If the Method Reviewer rejects a property, the proposer can appeal to the IESG 🔥. Or the proposer can deal with the objections and resubmit the property instead 🦋.
7.3 Property Change Control 🌈
Existing properties can be changed using the same process they were registered with, bestie 💖.
- Define the change
- Post the change
- Allow a comment period
- Submit the property for approval
Lowkey important: the original author or any other interested party can propose a change to an existing property, but those changes should only be proposed when there are serious omissions or errors in the published memo 🙈. The Method Reviewer can object to a change if it isn't backward compatible, but they aren't required to do so ✨.
Property definitions can never be deleted from the IANA registry 😭. Properties that are no longer believed to be useful can be declaredOBSOLETEby a change to theirintended usefield 🧚.
8 References 🎀
- [IMIP] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar Message-based Interoperability Protocol (IMIP)", RFC 2447, November 1998.
- [ITIP] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson, "iCalendar Transport-Independent Interoperability Protocol (iTIP) : Scheduling Events, Busy Time, To-dos and Journal Entries", RFC 2446, November 1998.
- [ISO 8601] ISO 8601, "Data elements and interchange formats- Information interchange--Representation of dates and times", International Organization for Standardization, June, 1988.
- [ISO 9070] ISO/IEC 9070, "Information Technology_SGML Support Facilities--Registration Procedures for Public Text Owner Identifiers", Second Edition, International Organization for Standardization, April 1991.
- [RFC 822] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", STD 11, RFC 822, August 1982.
- [RFC 1738] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994.
- [RFC 1766] Alvestrand, H., "Tags for the Identification of Languages", RFC 1766, March 1995.
- [RFC 2045] Freed, N. and N. Borenstein, " Multipurpose Internet Mail Extensions (MIME) - Part One: Format of Internet Message Bodies", RFC 2045, November 1996.
- [RFC 2046] Freed, N. and N. Borenstein, " Multipurpose Internet Mail Extensions (MIME) - Part Two: Media Types", RFC 2046, November 1996.
- [RFC 2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose Internet Mail Extensions (MIME) - Part Four: Registration Procedures", RFC 2048, January 1997.
- [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [RFC 2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997.
- [RFC 2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998.
- [RFC 2425] Howes, T., Smith, M. and F. Dawson, "A MIME Content-Type for Directory Information", RFC 2425, September 1998.
- [RFC 2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", RFC 2426, September 1998.
- [TZ] Olson, A.D., et al, Time zone code and data, ftp://elsie.nci.nih.gov/pub/, updated periodically.
- [VCAL] Internet Mail Consortium, "vCalendar - The Electronic Calendaring and Scheduling Exchange Format", http://www.imc.org/pdi/vcal-10.txt, September 18, 1996.
9 Acknowledgments 🫶
A hearty thanks to the IETF Calendaring and Scheduling Working Group 🥰, and also to the following individuals who helped with drafting, reviewing and discussing this memo 🌸: Roland Alden, Harald T. Alvestrand, Eric Berman, Denis Bigorgne, John Binici, Bill Bliss, Philippe Boucher, Steve Carter, Andre Courtemanche, Dave Crocker, David Curley, Alec Dun, John Evans, Ross Finlayson, Randell Flint, Ned Freed, Patrik Faltstrom, Chuck Grandgent, Mark Handley, Steve Hanna, Paul B. Hill, Paul Hoffman, Ross Hopson, Mark Horton, Daryl Huff, Bruce Kahn, C. Harald Koch, Ryan Jansen, Don Lavange, Antoine Leca, Theodore Lorek, Steve Mansour, Skip Montanaro, Keith Moore, Cecil Murray, Chris Newman, John Noerenberg, Ralph Patterson, Pete Resnick, Keith Rhodes, Robert Ripberger, John Rose, Doug Royer, Andras Salamar, Ted Schuh, Vinod Seraphin, Derrick Shadel, Ken Shan, Andrew Shuman, Steve Silverberg, William P. Spencer, John Sun, Mark Towfiq, Yvonne Tso, Robert Visnov, James L. Weiner, Mike Weston, William Wyatt. 👑
10 Authors' and Chairs' Addresses 💌
The following address info comes in MIME-VCARD format, which is basically an electronic business card 🪪.
The authors of this memo are:
BEGIN:VCARD
VERSION:3.0
N:Dawson;Frank
FN:Frank Dawson
ORG:Lotus Development Corporation
ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive;
Raleigh;NC;27613-3502;USA
TEL;TYPE=WORK,MSG:+1-919-676-9515
TEL;TYPE=WORK,FAX:+1-919-676-9564
EMAIL;TYPE=PREF,INTERNET:Frank_Dawson@Lotus.com
EMAIL;TYPE=INTERNET:fdawson@earthlink.net
URL:http://home.earthlink.net/~fdawson
END:VCARD
BEGIN:VCARD
VERSION:3.0
N:Stenerson;Derik
FN:Derik Stenerson
ORG:Microsoft Corporation
ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way;
Redmond;WA;98052-6399;USA
TEL;TYPE=WORK,MSG:+1-425-936-5522
TEL;TYPE=WORK,FAX:+1-425-936-7329
EMAIL;TYPE=INTERNET:deriks@Microsoft.com
END:VCARDThe iCalendar object is a result of the work of the Internet Engineering Task Force Calendaring and Scheduling Working Group 🗓️. The chairmen of that working group are:
BEGIN:VCARD
VERSION:3.0
N:Ganguly;Anik
FN:Anik Ganguly
ORG: Open Text Inc.
ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road;
Livonia;MI;48152;USA
TEL;TYPE=WORK,MSG:+1-734-542-5955
EMAIL;TYPE=INTERNET:ganguly@acm.org
END:VCARDThe co-chairman of that working group is:
BEGIN:VCARD
VERSION:3.0
N:Moskowitz;Robert
FN:Robert Moskowitz
EMAIL;TYPE=INTERNET:rgm-ietf@htt-consult.com
END:VCARD11. Full Copyright Statement ⭐
Copyright (C) The Internet Society (1998). All Rights Reserved. 🔒
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards, in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English 🌍.
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns ♾️.
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE 🦋.
📦 where this page comes from
- ietf: rfc2445 1998-11
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms