RFC 5545
Internet Calendaring and Scheduling Core Object Specification (iCalendar)
RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar) ✨
Okay bestie, so this is RFC 5545 🎀 It was written by B. Desruisseaux, Ed., from Oracle, and it's a Standards Track document dated September 2009. It obsoletes RFC 2445, so it's the newer version that replaces it 🦋
Abstract 💖
This doc defines the iCalendar data format for representing and exchanging calendaring and scheduling info, like events, to-dos, journal entries, and free/busy information 📅 The best part is that it's not tied to any one calendar service or protocol, so any app can use it 🧚
Status of This Memo ✨
Okay so this document is an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 🙈 If you want the official standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 💅 Distribution of this memo is unlimited, so share it with everyone 🌸
Copyright and License Notice 🎀
Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. 💜
Okay this part is a little legal, but it matters 🫶 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood on the date of publication. Please actually read these, because they explain your rights and restrictions for this document 👑 Code components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the BSD License ⭐
Heads up: this document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of that material may not have granted the IETF Trust the right to allow modifications outside the IETF Standards Process 💀 Without an adequate license from those copyright holders, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process. The one exception is formatting it for publication as an RFC or translating it into languages other than English 🌈
Table of Contents 🗺️✨
okay bestie, this is the whole map of the spec, so you can see every section and where it lives 💖 section numbers and page numbers are copied exactly so nothing gets lost 🫶
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Basic Grammar and Conventions . . . . . . . . . . . . . . . . 6
2.1. Formatting Conventions . . . . . . . . . . . . . . . . . 6
2.2. Related Memos . . . . . . . . . . . . . . . . . . . . . . 7
3. iCalendar Object Specification . . . . . . . . . . . . . . . 8
3.1. Content Lines . . . . . . . . . . . . . . . . . . . . . . 8
3.1.1. List and Field Separators . . . . . . . . . . . . . . 11
3.1.2. Multiple Values . . . . . . . . . . . . . . . . . . . 11
3.1.3. Binary Content . . . . . . . . . . . . . . . . . . . 11
3.1.4. Character Set . . . . . . . . . . . . . . . . . . . . 12
3.2. Property Parameters . . . . . . . . . . . . . . . . . . . 12
3.2.1. Alternate Text Representation . . . . . . . . . . . . 13
3.2.2. Common Name . . . . . . . . . . . . . . . . . . . . . 15
3.2.3. Calendar User Type . . . . . . . . . . . . . . . . . 15
3.2.4. Delegators . . . . . . . . . . . . . . . . . . . . . 16
3.2.5. Delegatees . . . . . . . . . . . . . . . . . . . . . 16
3.2.6. Directory Entry Reference . . . . . . . . . . . . . . 17
3.2.7. Inline Encoding . . . . . . . . . . . . . . . . . . . 17
3.2.8. Format Type . . . . . . . . . . . . . . . . . . . . . 18
3.2.9. Free/Busy Time Type . . . . . . . . . . . . . . . . . 19
3.2.10. Language . . . . . . . . . . . . . . . . . . . . . . 20
3.2.11. Group or List Membership . . . . . . . . . . . . . . 20
3.2.12. Participation Status . . . . . . . . . . . . . . . . 21
3.2.13. Recurrence Identifier Range . . . . . . . . . . . . . 22
3.2.14. Alarm Trigger Relationship . . . . . . . . . . . . . 23
3.2.15. Relationship Type . . . . . . . . . . . . . . . . . . 24
3.2.16. Participation Role . . . . . . . . . . . . . . . . . 25
3.2.17. RSVP Expectation . . . . . . . . . . . . . . . . . . 25
3.2.18. Sent By . . . . . . . . . . . . . . . . . . . . . . . 26
3.2.19. Time Zone Identifier . . . . . . . . . . . . . . . . 26
3.2.20. Value Data Types . . . . . . . . . . . . . . . . . . 28
3.3. Property Value Data Types . . . . . . . . . . . . . . . . 29
3.3.1. Binary . . . . . . . . . . . . . . . . . . . . . . . 29
3.3.2. Boolean . . . . . . . . . . . . . . . . . . . . . . . 30
3.3.3. Calendar User Address . . . . . . . . . . . . . . . . 30
3.3.4. Date . . . . . . . . . . . . . . . . . . . . . . . . 31
3.3.5. Date-Time . . . . . . . . . . . . . . . . . . . . . . 31
3.3.6. Duration . . . . . . . . . . . . . . . . . . . . . . 34
3.3.7. Float . . . . . . . . . . . . . . . . . . . . . . . . 35
3.3.8. Integer . . . . . . . . . . . . . . . . . . . . . . . 35
3.3.9. Period of Time . . . . . . . . . . . . . . . . . . . 36
3.3.10. Recurrence Rule . . . . . . . . . . . . . . . . . . . 37
3.3.11. Text . . . . . . . . . . . . . . . . . . . . . . . . 45
3.3.12. Time . . . . . . . . . . . . . . . . . . . . . . . . 46
3.3.13. URI . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.3.14. UTC Offset . . . . . . . . . . . . . . . . . . . . . 49
3.4. iCalendar Object . . . . . . . . . . . . . . . . . . . . 49
3.5. Property . . . . . . . . . . . . . . . . . . . . . . . . 50
3.6. Calendar Components . . . . . . . . . . . . . . . . . . . 50
3.6.1. Event Component . . . . . . . . . . . . . . . . . . . 52
3.6.2. To-Do Component . . . . . . . . . . . . . . . . . . . 56
3.6.3. Journal Component . . . . . . . . . . . . . . . . . . 58
3.6.4. Free/Busy Component . . . . . . . . . . . . . . . . . 60
3.6.5. Time Zone Component . . . . . . . . . . . . . . . . . 63
3.6.6. Alarm Component . . . . . . . . . . . . . . . . . . . 72
3.7. Calendar Properties . . . . . . . . . . . . . . . . . . . 77
3.7.1. Calendar Scale . . . . . . . . . . . . . . . . . . . 77
3.7.2. Method . . . . . . . . . . . . . . . . . . . . . . . 78
3.7.3. Product Identifier . . . . . . . . . . . . . . . . . 79
3.7.4. Version . . . . . . . . . . . . . . . . . . . . . . . 80
3.8. Component Properties . . . . . . . . . . . . . . . . . . 81
3.8.1. Descriptive Component Properties . . . . . . . . . . 81
3.8.1.1. Attachment . . . . . . . . . . . . . . . . . . . 81
3.8.1.2. Categories . . . . . . . . . . . . . . . . . . . 82
3.8.1.3. Classification . . . . . . . . . . . . . . . . . 83
3.8.1.4. Comment . . . . . . . . . . . . . . . . . . . . . 84
3.8.1.5. Description . . . . . . . . . . . . . . . . . . . 85
3.8.1.6. Geographic Position . . . . . . . . . . . . . . . 87
3.8.1.7. Location . . . . . . . . . . . . . . . . . . . . 88
3.8.1.8. Percent Complete . . . . . . . . . . . . . . . . 89
3.8.1.9. Priority . . . . . . . . . . . . . . . . . . . . 90
3.8.1.10. Resources . . . . . . . . . . . . . . . . . . . . 92
3.8.1.11. Status . . . . . . . . . . . . . . . . . . . . . 93
3.8.1.12. Summary . . . . . . . . . . . . . . . . . . . . . 94
3.8.2. Date and Time Component Properties . . . . . . . . . 95
3.8.2.1. Date-Time Completed . . . . . . . . . . . . . . . 95
3.8.2.2. Date-Time End . . . . . . . . . . . . . . . . . . 96
3.8.2.3. Date-Time Due . . . . . . . . . . . . . . . . . . 97
3.8.2.4. Date-Time Start . . . . . . . . . . . . . . . . . 99
3.8.2.5. Duration . . . . . . . . . . . . . . . . . . . . 100
3.8.2.6. Free/Busy Time . . . . . . . . . . . . . . . . . 101
3.8.2.7. Time Transparency . . . . . . . . . . . . . . . . 102
3.8.3. Time Zone Component Properties . . . . . . . . . . . 103
3.8.3.1. Time Zone Identifier . . . . . . . . . . . . . . 103
3.8.3.2. Time Zone Name . . . . . . . . . . . . . . . . . 105
3.8.3.3. Time Zone Offset From . . . . . . . . . . . . . . 106
3.8.3.4. Time Zone Offset To . . . . . . . . . . . . . . . 106
3.8.3.5. Time Zone URL . . . . . . . . . . . . . . . . . . 107
3.8.4. Relationship Component Properties . . . . . . . . . . 108
3.8.4.1. Attendee . . . . . . . . . . . . . . . . . . . . 108
3.8.4.2. Contact . . . . . . . . . . . . . . . . . . . . . 111
3.8.4.3. Organizer . . . . . . . . . . . . . . . . . . . . 113
3.8.4.4. Recurrence ID . . . . . . . . . . . . . . . . . . 114
3.8.4.5. Related To . . . . . . . . . . . . . . . . . . . 117
3.8.4.6. Uniform Resource Locator . . . . . . . . . . . . 118
3.8.4.7. Unique Identifier . . . . . . . . . . . . . . . . 119
3.8.5. Recurrence Component Properties . . . . . . . . . . . 120
3.8.5.1. Exception Date-Times . . . . . . . . . . . . . . 120
3.8.5.2. Recurrence Date-Times . . . . . . . . . . . . . . 122
3.8.5.3. Recurrence Rule . . . . . . . . . . . . . . . . . 124
3.8.6. Alarm Component Properties . . . . . . . . . . . . . 134
3.8.6.1. Action . . . . . . . . . . . . . . . . . . . . . 134
3.8.6.2. Repeat Count . . . . . . . . . . . . . . . . . . 135
3.8.6.3. Trigger . . . . . . . . . . . . . . . . . . . . . 135
3.8.7. Change Management Component Properties . . . . . . . 138
3.8.7.1. Date-Time Created . . . . . . . . . . . . . . . . 138
3.8.7.2. Date-Time Stamp . . . . . . . . . . . . . . . . . 139
3.8.7.3. Last Modified . . . . . . . . . . . . . . . . . . 140
3.8.7.4. Sequence Number . . . . . . . . . . . . . . . . . 141
3.8.8. Miscellaneous Component Properties . . . . . . . . . 142
3.8.8.1. IANA Properties . . . . . . . . . . . . . . . . . 142
3.8.8.2. Non-Standard Properties . . . . . . . . . . . . . 142
3.8.8.3. Request Status . . . . . . . . . . . . . . . . . 144
4. iCalendar Object Examples . . . . . . . . . . . . . . . . . . 146
5. Recommended Practices . . . . . . . . . . . . . . . . . . . . 150
6. Internationalization Considerations . . . . . . . . . . . . . 151
7. Security Considerations . . . . . . . . . . . . . . . . . . . 151
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 151
8.1. iCalendar Media Type Registration . . . . . . . . . . . . 151
8.2. New iCalendar Elements Registration . . . . . . . . . . . 155
8.2.1. iCalendar Elements Registration Procedure . . . . . . 155
8.2.2. Registration Template for Components . . . . . . . . 155
8.2.3. Registration Template for Properties . . . . . . . . 156
8.2.4. Registration Template for Parameters . . . . . . . . 156
8.2.5. Registration Template for Value Data Types . . . . . 157
8.2.6. Registration Template for Values . . . . . . . . . . 157
8.3. Initial iCalendar Elements Registries . . . . . . . . . . 158
8.3.1. Components Registry . . . . . . . . . . . . . . . . . 158
8.3.2. Properties Registry . . . . . . . . . . . . . . . . . 158
8.3.3. Parameters Registry . . . . . . . . . . . . . . . . . 161
8.3.4. Value Data Types Registry . . . . . . . . . . . . . . 162
8.3.5. Calendar User Types Registry . . . . . . . . . . . . 162
8.3.6. Free/Busy Time Types Registry . . . . . . . . . . . . 163
8.3.7. Participation Statuses Registry . . . . . . . . . . . 163
8.3.8. Relationship Types Registry . . . . . . . . . . . . . 164
8.3.9. Participation Roles Registry . . . . . . . . . . . . 164
8.3.10. Actions Registry . . . . . . . . . . . . . . . . . . 165
8.3.11. Classifications Registry . . . . . . . . . . . . . . 165
8.3.12. Methods Registry . . . . . . . . . . . . . . . . . . 165
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 165
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 166
10.1. Normative References . . . . . . . . . . . . . . . . . . 166
10.2. Informative References . . . . . . . . . . . . . . . . . 167
Appendix A. Differences from RFC 2445 . . . . . . . . . . . . . 169
A.1. New Restrictions . . . . . . . . . . . . . . . . . . . . 169
A.2. Restrictions Removed . . . . . . . . . . . . . . . . . . 169
A.3. Deprecated Features . . . . . . . . . . . . . . . . . . . 169The map is in place, so the real content (starting with Section 1, Introduction) is next 🦋💜
1. Introduction ✨
okay so calendaring and scheduling has been blowing up over the last decade 📅 enterprise and inter-enterprise business now runs on scheduling events and actions super fast, so this stuff matters a LOT 😭 this memo is all about getting dissimilar calendaring and scheduling apps to actually talk to each other 🫶 it defines a MIME content type for swapping electronic calendaring and scheduling info. The Internet Calendaring and Scheduling Core Object Specification, aka iCalendar, lets you capture and exchange the stuff normally stored inside a calendaring and scheduling app, like a Personal Information Manager (PIM) or a Group-Scheduling product 💖
The iCalendar format is giving "exchange format between apps or systems" ✨ it's defined in terms of a MIME content type, which means the object can travel over several transports, including but not limited to SMTP, HTTP, a file system, desktop interactive protocols like a memory-based clipboard or drag/drop, point-to-point asynchronous communication, wired-network transport, or some form of unwired transport such as infrared 🦋
The memo also defines iCalendar object methods that map this content type to a set of messages for calendaring and scheduling ops, like requesting, replying to, modifying, and canceling meetings or appointments, to-dos, and journal entries 📝 those same methods can be used to define other ops too, like requesting for and replying with free/busy time data. That scheduling protocol is the iCalendar Transport-independent Interoperability Protocol (iTIP), defined in [2446bis] 🎀
Last but not least, the memo includes a formal grammar for the content type, based on the Internet ABNF defined in [RFC5234]. You literally need this ABNF to build a parser, and it's the definitive reference whenever the prose leaves you confused 🤓 extra restrictions that are too hard to express in ABNF get written as comments inside the ABNF. Comments that carry normative statements count just as much as the main text, so treat them that way 💅
2. Basic Grammar and Conventions ✨
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. these are the requirement-words of the memo, so read them the way [RFC2119] says 💜
This memo uses both descriptive prose and a more formal notation to define the calendaring and scheduling format 🧚
The notation used in this memo is the ABNF notation of [RFC5234]. if you're planning to implement this format, get comfy with that notation first, or the specs will be a total maze 🙈
All numeric values in this memo are written in decimal notation 🔢
All names of properties, property parameters, enumerated property values, and property parameter values are case-insensitive. however, all other property values are case-sensitive, unless otherwise stated 🌸
Note: All indented editorial notes, such as this one, are intended to provide the reader with additional information. The information is not essential to the building of an implementation conformant with this memo. The information is provided to highlight a particular feature or characteristic of the memo.
The format for the iCalendar object is based on the syntax of the text/directory media type [RFC2425]. the iCalendar object is NOT a profile of the text/directory media type [RFC2425], but it does reuse a number of the elements from the [RFC2425] specification 🎀
2.1. Formatting Conventions 💅
The elements defined in this memo are described in prose. A lot of the terms used here already mean something different in everyday usage than they do in this memo's standards usage, so some formatting conventions show up to keep things clear 🦋 when this memo references elements of the calendaring and scheduling model, the core object (this memo), or the interoperability protocol [2446bis], those references follow a few rules.
Calendaring and scheduling roles are referred to in quoted strings of text, with the first character of each word in uppercase. For example, "Organizer" refers to a role of a "Calendar User" within the scheduling protocol defined by [2446bis]. Calendar components defined by this memo are referred to with capitalized, quoted strings of text. All calendar components start with the letter "V". For example, "VEVENT" refers to the event calendar component, "VTODO" refers to the to-do calendar component, and "VJOURNAL" refers to the daily journal calendar component 📅
Scheduling methods defined by iTIP [2446bis] are referred to with capitalized, quoted strings of text too. For example, "REQUEST" refers to the method for requesting that a scheduling calendar component be created or modified, and "REPLY" refers to the method a recipient of a request uses to update their status with the "Organizer" of the calendar component 💌
Properties defined by this memo are referred to with capitalized, quoted strings of text, followed by the word "property". For example, the "ATTENDEE" property refers to the iCalendar property used to convey the calendar address of a calendar user 🧾 Property parameters defined by this memo are referred to with lowercase, quoted strings of text, followed by the word "parameter". For example, the "value" parameter refers to the iCalendar property parameter used to override the default value type for a property value 🌈
Enumerated values defined by this memo are referred to with capitalized text, either alone or followed by the word "value". For example, the "MINUTELY" value can be used with the "FREQ" component of the "RECUR" value type to specify repeating components based on an interval of one minute or more ⏰
The following table lists the different characters from the [US-ASCII] character set that are referenced in this document. For each character, the table gives the character name used throughout this document, along with its US-ASCII decimal codepoint 🔢
+------------------------+-------------------+
| Character name | Decimal codepoint |
+------------------------+-------------------+
| HTAB | 9 |
| LF | 10 |
| CR | 13 |
| DQUOTE | 22 |
| SPACE | 32 |
| PLUS SIGN | 43 |
| COMMA | 44 |
| HYPHEN-MINUS | 45 |
| PERIOD | 46 |
| SOLIDUS | 47 |
| COLON | 58 |
| SEMICOLON | 59 |
| LATIN CAPITAL LETTER N | 78 |
| LATIN CAPITAL LETTER T | 84 |
| LATIN CAPITAL LETTER X | 88 |
| LATIN CAPITAL LETTER Z | 90 |
| BACKSLASH | 92 |
| LATIN SMALL LETTER N | 110 |
+------------------------+-------------------+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 specifies a core specification of objects, value types, properties, and property parameters.
- iTIP [2446bis] specifies an interoperability protocol for scheduling between different implementations 🤝
- iCalendar Message-Based Interoperability Protocol (iMIP) [2447bis] specifies an Internet email binding for [2446bis] 📧
This memo doesn't try to repeat the specification of concepts or definitions from these other memos. Wherever possible, it points you to the memo that actually specifies them, so you're not reading the same thing twice 💜
3. iCalendar Object Specification 🦋
The following sections define the details of a Calendaring and Scheduling Core Object Specification. The Calendaring and Scheduling Core Object is a collection of calendaring and scheduling information. Typically, this information will consist of an iCalendar stream with one or more iCalendar objects. The body of the iCalendar object consists of a sequence of calendar properties and one or more calendar components 📦
Section 3.1 defines the content line format; Section 3.2 defines the property parameter format; Section 3.3 defines the data types for property values; Section 3.4 defines the iCalendar object format; Section 3.5 defines the iCalendar property format; Section 3.6 defines the calendar component format; Section 3.7 defines calendar properties; and Section 3.8 defines calendar component properties 🗺️
This information is meant to be an integral part of the MIME content type registration. It can also be used independently of that registration. In particular, this memo has direct applicability as a calendaring and scheduling exchange format in file-, memory-, or network-based transport mechanisms 🌈
3.1. Content Lines ✨
okay so the whole iCalendar object is just a stack of lines of text, called content lines 📝. Each one ends with a line break, and that line break is a CRLF pair (a CR character followed by an LF character) 🎀.
Lines of text SHOULD NOT be longer than 75 octets, not counting the line break 🙈. Long content lines SHOULD be split up across multiple lines with a "folding" trick 🦋. Basically, a long line can be chopped between any two characters, as long as you slip in a CRLF that's immediately followed by one single linear white-space character (that's a SPACE or an HTAB) 💅. And any CRLF that's followed right away by a linear white-space character gets ignored (aka removed) when you're processing the content type 🧚.
Here's a quick example. This line:
DESCRIPTION:This is a long description that exists on a long line.can be folded into this:
DESCRIPTION:This is a lo
ng description
that exists on a long line.Going from the folded version back to the single-line version is called "unfolding" 🌈. You do it by removing the CRLF and the linear white-space character that comes right after it.
When you're parsing a content line, folded lines MUST first be unfolded using the unfolding procedure we just covered, no skipping 😤.
⚠️ ngl, very simple implementations can accidentally fold lines right in the middle of a UTF-8 multi-octet sequence 💀. So implementations need to unfold lines in a way that properly restores the original sequence.
The content info in an iCalendar object is formatted with a syntax that's similar to the one in [RFC2425] 🌸. Basically, it's just CRLF-separated content lines. Here's the notation that defines those lines:
contentline = name *(";" param ) ":" value CRLF
; This ABNF is just a general definition for an initial parsing
; of the content line into its property name, parameter list,
; and value string
; When parsing a content line, folded lines MUST first
; be unfolded according to the unfolding procedure
; described above. When generating a content line, lines
; longer than 75 octets SHOULD be folded according to
; the folding procedure described above.
name = iana-token / x-name
iana-token = 1*(ALPHA / DIGIT / "-")
; iCalendar identifier registered with IANA
x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-")
; Reserved for experimental use.
vendorid = 3*(ALPHA / DIGIT)
; Vendor identification
param = param-name "=" param-value *("," param-value)
; Each property defines the specific ABNF for the parameters
; allowed on the property. Refer to specific properties for
; precise parameter ABNF.
param-name = iana-token / x-name
param-value = paramtext / quoted-string
paramtext = *SAFE-CHAR
value = *VALUE-CHAR
quoted-string = DQUOTE *QSAFE-CHAR DQUOTE
QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII
; Any character except CONTROL and DQUOTE
SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E
/ NON-US-ASCII
; Any character except CONTROL, DQUOTE, ";", ":", ","
VALUE-CHAR = WSP / %x21-7E / NON-US-ASCII
; Any textual character
NON-US-ASCII = UTF8-2 / UTF8-3 / UTF8-4
; UTF8-2, UTF8-3, and UTF8-4 are defined in [RFC3629]
CONTROL = %x00-08 / %x0A-1F / %x7F
; All the controls except HTABThe property value part of a content line has a format that depends on the property. Check the section for each property to see its exact format 🧁.
Names of properties, property parameters, enumerated property values and property parameter values are all case-insensitive 🙈. But all other property values are case-sensitive, unless the document says otherwise 🔥.
3.1.1. List and Field Separators 🍓
Some properties and parameters allow a list of values. Values in a list MUST be separated by a COMMA character 🎀. The order of values in a list doesn't mean anything. For parameter values that are written as quoted-strings (like the ones that hold URI values), those quoted-strings are separated by a COMMA character too 💜.
Some property values are made up of multiple parts. These structured property values MUST have their parts separated by a SEMICOLON character 🌈.
Some properties allow a list of parameters. Each parameter in that list MUST be separated by a SEMICOLON character 🦋.
Parameter values that contain a COLON character, a SEMICOLON character or a COMMA character MUST be placed in quoted text 🫶.
Here's an example. The SEMICOLON separates the parameters from each other, and the COMMA separates the values in a value list ✨:
ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT:mailto:
jsmith@example.com
RDATE;VALUE=DATE:19970304,19970504,19970704,199709043.1.2. Multiple Values 🌸
Some properties can have multiple values. The general rule is to just create a new content line for each value, and repeat the property name each time 🧚. But some properties can pack multiple values into one property by separating them with a COMMA character, so it's worth noting that 👀. Check the individual property definitions to see whether a property allows multiple values and which of those two forms it uses.
Multi-valued properties MUST NOT be used to specify multiple language variants of the same value 🙅♀️. And calendar applications SHOULD display all values 💖.
3.1.3. Binary Content 📎
Binary content in an iCalendar object SHOULD be referenced with a URI inside a property value 🔗. That means the binary content SHOULD be placed in an external MIME entity that the iCalendar object can point to with a URI. If that's not doable for your app, you can include binary content inside the iCalendar object, but only after you've encoded it as text with the "BASE64" encoding method from [RFC4648] 🌈. Inline binary content SHOULD only be used in apps where special circumstances demand that the iCalendar object be one single entity 😭.
A property that contains inline binary content MUST specify the "ENCODING" property parameter 💅. Binary content placed outside the iCalendar object MUST be referenced by a uniform resource identifier (URI) 🦋.
This example has an "ATTACH" property that points to an attachment outside the iCalendar object with a URI:
ATTACH:http://example.com/public/quarterly-report.docThis one has an "ATTACH" property with inline binary encoded content:
ATTACH;FMTTYPE=text/plain;ENCODING=BASE64;VALUE=BINARY:VGhlIH
F1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy43.1.4. Character Set 🍭
There isn't a property parameter for declaring the charset used in a property value 🙃. The default charset for an iCalendar stream is UTF-8, as defined in [RFC3629] 💜.
The "charset" Content-Type parameter MUST be used in MIME transports to specify the charset being used 🫶.
3.2. Property Parameters 🎀
A property can have attributes attached to it. These "property parameters" hold meta-information about the property or its value 🧁. They're used for things like where to find an alternate text representation of a value, the language of a text value, the value type, and other attributes ✨.
Parameter values that contain the COLON, SEMICOLON, or COMMA character separators MUST be specified as quoted-string text values 🔥. Parameter values MUST NOT contain the DQUOTE character 🙅♀️. DQUOTE is the delimiter for parameter values that have restricted characters or URI text. For example:
DESCRIPTION;ALTREP="cid:part1.0001@example.org":The Fall'98 Wild
Wizards Conference - - Las Vegas\, NV\, USAParameter values that aren't in quoted-strings are case-insensitive 🌈.
The general property parameters defined by this memo use the following notation 🧚:
icalparameter = altrepparam ; Alternate text representation
/ cnparam ; Common name
/ cutypeparam ; Calendar user type
/ delfromparam ; Delegator
/ deltoparam ; Delegatee
/ dirparam ; Directory entry
/ encodingparam ; Inline encoding
/ fmttypeparam ; Format type
/ fbtypeparam ; Free/busy time type
/ languageparam ; Language for text
/ memberparam ; Group or list membership
/ partstatparam ; Participation status
/ rangeparam ; Recurrence identifier range
/ trigrelparam ; Alarm trigger relationship
/ reltypeparam ; Relationship type
/ roleparam ; Participation role
/ rsvpparam ; RSVP expectation
/ sentbyparam ; Sent by
/ tzidparam ; Reference to time zone object
/ valuetypeparam ; Property value data type
/ other-param
other-param = (iana-param / x-param)
iana-param = iana-token "=" param-value *("," param-value)
; Some other IANA-registered iCalendar parameter.
x-param = x-name "=" param-value *("," param-value)
; A non-standard, experimental parameter.Applications MUST ignore x-param and iana-param values they don't recognize 💀.
3.2.1. Alternate Text Representation 🎀
okay so ALTREP is the parameter name, and it lets you point at a fancier version of a text value 💅 Think rich text or HTML vibes. The thing is, a property using this parameter MUST also include a value that shows the default representation of the text. The URI goes in a quoted-string, always. No cap, that's non-negotiable 😭
altrepparam = "ALTREP" "=" DQUOTE uri DQUOTEThis parameter gives you a URI that points to an alternate representation for a textual property value. A property using this parameter MUST also include a value that reflects the default representation of the text value. The URI parameter value MUST be specified in a quoted-string.
Note: There's no restriction on which URI schemes you can use here 🦋 But Content Identifier (CID) [RFC2392], HTTP [RFC2616], and HTTPS [RFC2818] are the schemes most commonly used by current implementations, so those are the ones you'll see everywhere ✨
Here's an example, bestie 🌸
DESCRIPTION;ALTREP="CID:part3.msg.970415T083000@example.com":
Project XYZ Review Meeting will include the following agenda
items: (a) Market Overview\, (b) Finances\, (c) Project Man
agementThe "ALTREP" property parameter value might point to a "text/html" content portion. So the HTML part looks like this 💖
Content-Type:text/html
Content-Id:<part3.msg.970415T083000@example.com>
<html>
<head>
<title></title>
</head>
<body>
<p>
<b>Project XYZ Review Meeting</b> will include
the following agenda items:
<ol>
<li>Market Overview</li>
<li>Finances</li>
<li>Project Management</li>
</ol>
</p>
</body>
</html>3.2.2. Common Name 🧚
The CN parameter is giving "display name" energy ✨ It sets the common name for the calendar user the property is talking about. It's text, and it's meant for display, so people can see a nice name instead of a raw address. Iconic 💅
cnparam = "CN" "=" param-valueThis parameter can be used on properties with a CAL-ADDRESS value type. It specifies the common name for the calendar user named in the property. The parameter value is text, and it can be used as display text for the calendar address.
Example:
ORGANIZER;CN="John Smith":mailto:jsmith@example.com3.2.3. Calendar User Type 🦋
CUTYPE tells you what kind of calendar user you're dealing with 👑 It can be an individual, a group, a resource, a room, or unknown. If you don't specify it on a property that allows it, the default is INDIVIDUAL, so you're basically a person unless proven otherwise 🙈
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 INDIVIDUALThis parameter can be used on properties with a CAL-ADDRESS value type. It identifies the type of calendar user named in the property. If it's not specified on a property that allows this parameter, the default is INDIVIDUAL.
Applications MUST treatx-nameandiana-tokenvalues they don't recognize the same way as they would the UNKNOWN value. So if an app doesn't know a type, it treats it like UNKNOWN, no drama 🫶
Example:
ATTENDEE;CUTYPE=GROUP:mailto:ietf-calsch@example.org3.2.4. Delegators 🌈
DELEGATED-FROM is for the people who handed off their spot ✨ It lists the calendar users who delegated their participation to the calendar user in the property. Think of it as the "who passed me the baton" parameter 🥹
delfromparam = "DELEGATED-FROM" "=" DQUOTE cal-address
DQUOTE *("," DQUOTE cal-address DQUOTE)This parameter can be used on properties with a CAL-ADDRESS value type. It specifies the calendar users who delegated their participation in a group-scheduled event or to-do to the calendar user in the property. Each individual calendar address parameter value MUST be specified in a quoted-string.
Example:
ATTENDEE;DELEGATED-FROM="mailto:jsmith@example.com":mailto:
jdoe@example.com3.2.5. Delegatees 💜
DELEGATED-TO is the flip side of that 🔄 It lists the calendar users that the calendar user in the property has delegated participation to. So it's the "I passed it on to these people" parameter 💅
deltoparam = "DELEGATED-TO" "=" DQUOTE cal-address DQUOTE
*("," DQUOTE cal-address DQUOTE)This parameter can be used 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. Each individual calendar address parameter value MUST be specified in a quoted-string.
Example:
ATTENDEE;DELEGATED-TO="mailto:jdoe@example.com","mailto:jqpublic
@example.com":mailto:jsmith@example.com3.2.6. Directory Entry Reference 📖
DIR is basically a pointer to a directory entry for the calendar user 🧭 The value is a URI, and it MUST be in a quoted-string, because we're consistent in this house 🫶
dirparam = "DIR" "=" DQUOTE uri DQUOTEThis parameter can be used on properties with a CAL-ADDRESS value type. It points to the directory entry for the calendar user named in the property. The parameter value is a URI. The URI parameter value MUST be specified in a quoted-string.
Note: No restriction is imposed on URI schemes here either, but CID [RFC2392], DATA [RFC2397], FILE [RFC1738], FTP [RFC1738], HTTP [RFC2616], HTTPS [RFC2818], LDAP [RFC4516], and MID [RFC2392] are the schemes most commonly used by current implementations 🌸
Example:
ORGANIZER;DIR="ldap://example.com:6666/o=ABC%20Industries,
c=US???(cn=Jim%20Dolittle)":mailto:jimdo@example.com3.2.7. Inline Encoding 🍓
ENCODING tells you how the inline property value is encoded 🧁 The default is 8BIT, which is just text. BASE64 is for binary stuff encoded in base64. Also, if your value type is ;VALUE=BINARY, you MUST include ;ENCODING=BASE64. No skipping that step, bestie 😭
encodingparam = "ENCODING" "="
( "8BIT"
; "8bit" text encoding is defined in [RFC2045]
/ "BASE64"
; "BASE64" binary encoding format is defined in [RFC4648]
)This property parameter identifies 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 using the "BASE64" encoding defined in [RFC2045].
If the value type parameter is ";VALUE=BINARY", then the inline encoding parameter MUST be specified with the value ";ENCODING=BASE64".
Example:
ATTACH;FMTTYPE=text/plain;ENCODING=BASE64;VALUE=BINARY:TG9yZW
0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaW
5nIGVsaXQsIHNlZCBkbyBlaXVzbW9kIHRlbXBvciBpbmNpZGlkdW50IHV0IG
xhYm9yZSBldCBkb2xvcmUgbWFnbmEgYWxpcXVhLiBVdCBlbmltIGFkIG1pbm
ltIHZlbmlhbSwgcXVpcyBub3N0cnVkIGV4ZXJjaXRhdGlvbiB1bGxhbWNvIG
xhYm9yaXMgbmlzaSB1dCBhbGlxdWlwIGV4IGVhIGNvbW1vZG8gY29uc2VxdW
F0LiBEdWlzIGF1dGUgaXJ1cmUgZG9sb3IgaW4gcmVwcmVoZW5kZXJpdCBpbi
B2b2x1cHRhdGUgdmVsaXQgZXNzZSBjaWxsdW0gZG9sb3JlIGV1IGZ1Z2lhdC
BudWxsYSBwYXJpYXR1ci4gRXhjZXB0ZXVyIHNpbnQgb2NjYWVjYXQgY3VwaW
RhdGF0IG5vbiBwcm9pZGVudCwgc3VudCBpbiBjdWxwYSBxdWkgb2ZmaWNpYS
BkZXNlcnVudCBtb2xsaXQgYW5pbSBpZCBlc3QgbGFib3J1bS4=3.2.8. Format Type 🎀
FMTTYPE says what kind of content the referenced object is ✨ Like, an FTP URI doesn't always tell you the content type by itself, so this parameter fills that gap 🫶 The value MUST be the text for either an IANA-registered media type or a non-standard media type. Strict but fair 💅
fmttypeparam = "FMTTYPE" "=" type-name "/" subtype-name
; Where "type-name" and "subtype-name" are
; defined in Section 4.2 of [RFC4288].This parameter can be used on properties that reference an object. It specifies the media type [RFC4288] of the referenced object. For example, on the "ATTACH" property, an FTP type URI value does not, by itself, necessarily convey the type of content associated with the resource. The parameter value MUST be the text for either an IANA-registered media type or a non-standard media type.
Example:
ATTACH;FMTTYPE=application/msword:ftp://example.com/pub/docs/
agenda.doc3.2.9. Free/Busy Time Type 🦋
FBTYPE is for saying whether a free/busy time slot is free or busy 🕐 There are a few flavours: FREE, BUSY, BUSY-UNAVAILABLE, and BUSY-TENTATIVE 🌈 If you leave it off on a property that allows this parameter, you get BUSY by default. Also, unknown x-name and iana-token values MUST be treated the same as BUSY, so nothing breaks just because a type is new to you 🫶
fbtypeparam = "FBTYPE" "=" ("FREE" / "BUSY"
/ "BUSY-UNAVAILABLE" / "BUSY-TENTATIVE"
/ x-name
; Some experimental iCalendar free/busy type.
/ iana-token)
; Some other IANA-registered iCalendar free/busy type.This parameter specifies the free or busy time type. The value FREE means the time interval is free for scheduling. The value BUSY means the interval is busy because one or more events have been scheduled for it. The value BUSY-UNAVAILABLE means the interval is busy and can't be scheduled. The value BUSY-TENTATIVE means the interval is busy because one or more events have been tentatively scheduled for it. If it's not specified on a property that allows this parameter, the default is BUSY.
Applications MUST treatx-nameandiana-tokenvalues they don't recognize the same way as they would the BUSY value. So unknown means BUSY, periodt 💀
Example: The following is an example of this parameter on a "FREEBUSY" property.
FREEBUSY;FBTYPE=BUSY:19980415T133000Z/19980415T170000Z3.2.10. Language 🌸
LANGUAGE tells you what language the text is in, for text values in a property or property parameter 🗣️ The value follows [RFC5646], so it's a proper language tag ✨
languageparam = "LANGUAGE" "=" language
language = Language-Tag
; As defined in [RFC5646].This parameter identifies the language of the text in the property value and in all property parameter values of the property. The value of the "LANGUAGE" property parameter is the one defined in [RFC5646].
When it's sent inside a MIME entity, the Content-Language header field can set the default language for the whole body part. Otherwise, no default language is assumed 🙈
Here are some examples of this parameter on the "SUMMARY" and "LOCATION" properties 🍓
SUMMARY;LANGUAGE=en-US:Company Holiday Party
LOCATION;LANGUAGE=en:Germany
LOCATION;LANGUAGE=no:Tyskland3.2.11. Group or List Membership
Parameter Name: MEMBER 💖
Purpose: okay so this one tells everyone which group or list the calendar user belongs to 👯♀️
Format Definition: here's the grammar, bestie 🧚
memberparam = "MEMBER" "=" DQUOTE cal-address DQUOTE
*("," DQUOTE cal-address DQUOTE)Description: you can put this on any property with a CAL-ADDRESS value type ✨ The value is either one calendar address inside a quoted-string, or a COMMA-separated list where each address gets its own quoted-string. The individual calendar address parameter values MUST each be specified in a quoted-string. No skipping the quotes, it's giving strict 🙈
Example:
ATTENDEE;MEMBER="mailto:ietf-calsch@example.org":mailto:
jsmith@example.com
ATTENDEE;MEMBER="mailto:projectA@example.com","mailto:pr
ojectB@example.com":mailto:janedoe@example.com3.2.12. Participation Status
Parameter Name: PARTSTAT 🦋
Purpose: this is how you show whether the calendar user is in, out, or still thinking about it 💅
Format Definition: the grammar changes depending on which component it's attached to, so here's all three 👑
partstatparam = "PARTSTAT" "="
(partstat-event
/ partstat-todo
/ partstat-jour)
partstat-event = ("NEEDS-ACTION" ; Event needs action
/ "ACCEPTED" ; Event accepted
/ "DECLINED" ; Event declined
/ "TENTATIVE" ; Event tentatively
; accepted
/ "DELEGATED" ; Event delegated
/ x-name ; Experimental status
/ iana-token) ; Other IANA-registered
; status
; These are the participation statuses for a "VEVENT".
; Default is NEEDS-ACTION.
partstat-todo = ("NEEDS-ACTION" ; To-do needs action
/ "ACCEPTED" ; To-do accepted
/ "DECLINED" ; To-do declined
/ "TENTATIVE" ; To-do tentatively
; accepted
/ "DELEGATED" ; To-do delegated
/ "COMPLETED" ; To-do completed
; COMPLETED property has
; DATE-TIME completed
/ "IN-PROCESS" ; To-do in process of
; being completed
/ x-name ; Experimental status
/ iana-token) ; Other IANA-registered
; status
; These are the participation statuses for a "VTODO".
; Default is NEEDS-ACTION.
partstat-jour = ("NEEDS-ACTION" ; Journal needs action
/ "ACCEPTED" ; Journal accepted
/ "DECLINED" ; Journal declined
/ x-name ; Experimental status
/ iana-token) ; Other IANA-registered
; status
; These are the participation statuses for a "VJOURNAL".
; Default is NEEDS-ACTION.Description: this one goes on CAL-ADDRESS properties too, and it's all about the calendar user's participation status for a group-scheduled "VEVENT", "VTODO", or "VJOURNAL" 🎀 Each component has its own list of allowed values, so the value MUST match one of the ones allowed for that component. If you don't specify it on a property that allows it, the default is NEEDS-ACTION. And here's the bit that's lowkey important 🫶: applications MUST treat any x-name or iana-token value they don't recognise exactly the same way they'd treat NEEDS-ACTION.
Example:
ATTENDEE;PARTSTAT=DECLINED:mailto:jsmith@example.com3.2.13. Recurrence Identifier Range
Parameter Name: RANGE 🌸
Purpose: this tells you how far the changes reach, starting from the instance the recurrence identifier points to 🔥
Format Definition: here's the grammar 🧚
rangeparam = "RANGE" "=" "THISANDFUTURE"
; To specify the instance specified by the recurrence identifier
; and all subsequent recurrence instances.Description: put this on any property that specifies a recurrence identifier 💜 It sets the effective range of recurrence instances, starting from that recurrence identifier. If you leave it off an allowed property, the default is just the single instance the recurrence identifier value points at. The only value allowed is "THISANDFUTURE", which covers that instance plus every instance after it. The value "THISANDPRIOR" is deprecated by this revision of iCalendar, so it MUST NOT be generated by applications. Don't be that person 💀
Example:
RECURRENCE-ID;RANGE=THISANDFUTURE:19980401T133000Z3.2.14. Alarm Trigger Relationship
Parameter Name: RELATED ⏰
Purpose: this decides whether the alarm goes off relative to the start or the end of the calendar component 🌈
Format Definition: here's the grammar, nothing fancy 🍓
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 ✨ The value START makes the alarm trigger off the start of the calendar component, and END makes it trigger off the end. If you don't specify it on an allowed property, the default is START.
Example:
TRIGGER;RELATED=END:PT5M3.2.15. Relationship Type
Parameter Name: RELTYPE 🫧
Purpose: this one describes the hierarchy between the component and the one it points to, like who's the parent, child, or sibling 👑
Format Definition: here's the grammar 🧚
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 goes on any property that references another related calendar 💖 The value tells you what the referenced component is to this one. PARENT means the referenced component is a superior of the component. CHILD means it's a subordinate. SIBLING means it's a peer. If you don't specify it on an allowable property, the default is PARENT. Applications MUST treat any x-name or iana-token value they don't recognise exactly the same way they'd treat PARENT. Main character energy, but make it make sense 💅
Example:
RELATED-TO;RELTYPE=SIBLING:19960401-080045-4000F192713@
example.com3.2.16. Participation Role
Parameter Name: ROLE 🎭
Purpose: this shows what role the calendar user plays, like chair, required, optional, or just copied for info 🌟
Format Definition: here's the grammar 🧚
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: you can put this on CAL-ADDRESS properties ✨ It sets the participation role for the calendar user in the group schedule calendar component. If you don't specify it on a property that allows it, the default is REQ-PARTICIPANT. And again, applications MUST treat any x-name or iana-token value they don't recognise exactly the same way they'd treat REQ-PARTICIPANT 🫶
Example:
ATTENDEE;ROLE=CHAIR:mailto:mrbig@example.com3.2.17. RSVP Expectation
Parameter Name: RSVP 💌
Purpose: this says whether the calendar user is expected to reply, and it's giving "please answer me" energy 🥹
Format Definition: here's the grammar 🧚
rsvpparam = "RSVP" "=" ("TRUE" / "FALSE")
; Default is FALSEDescription: this can go on CAL-ADDRESS properties 🌸 It tells you whether a reply is expected from the calendar user. The "Organizer" uses it to ask an "Attendee" of a group-scheduled event or to-do for a participation status reply. If you don't specify it on a property that allows it, the default is FALSE.
Example:
ATTENDEE;RSVP=TRUE:mailto:jsmith@example.com3.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 sending invites for their boss 💼
Format Definition: here's the grammar 🧚
sentbyparam = "SENT-BY" "=" DQUOTE cal-address DQUOTEDescription: this goes on CAL-ADDRESS properties 💜 The value is the calendar user who is acting on behalf of the one the property is about. The parameter value MUST be a mailto URI as defined in [RFC2368]. And each individual calendar address parameter value MUST be specified in a quoted-string, so keep those quotes on 🎀
Example:
ORGANIZER;SENT-BY="mailto:sray@example.com":mailto:
jsmith@example.com3.2.19. Time Zone Identifier 🌍
Parameter Name: TZID 💖
Purpose: okay so this param tells you which time zone definition to use for the time bit in a property value 🕰️. It basically names the VTIMEZONE component that explains how to read that time 🗺️.
Format Definition: here's the notation 📝
tzidparam = "TZID" "=" [tzidprefix] paramtext
tzidprefix = "/"Description: bestie, this one is a must-have 🫶. The TZID parameter MUST be specified on DTSTART, DTEND, DUE, EXDATE, and RDATE whenever the value type is DATE-TIME or TIME and the value is neither UTC nor "floating" time. (Check the DATE-TIME or TIME value type definitions if you want the full tea on UTC and "floating time" formats 📖.) The param holds a text value that uniquely identifies the VTIMEZONE calendar component used to evaluate the time portion of the property ✨. The value of the TZID parameter will be equal to the value of the TZID property for the matching time zone definition 🎀. An individual VTIMEZONE calendar component MUST be specified for each unique TZID parameter value in the iCalendar object 💅.
Also, the parameter MUST be specified on any property with a DATE-TIME value that isn't UTC or "floating" 🙅♀️. Skipping or ignoring VTIMEZONE definitions in iCalendar objects may lead to inconsistent understanding of the local time at any given location 😬. That's how plans get messy, fr fr.
If there's a SOLIDUS character as a prefix, that means this TZID is a 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 TZ database [TZDB]. The specification of globally unique time zone identifiers is not addressed by this document and is left for future study.
Here are some examples of this property parameter 🧚:
DTSTART;TZID=America/New_York:19980119T020000
DTEND;TZID=America/New_York:19980119T030000The TZID property parameter MUST NOT be applied to DATE properties, or to DATE-TIME or TIME properties whose time values are specified in UTC 🙈. Not allowed, no cap.
Local time in a DATE-TIME or 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 🌸.
For more info, check the sections on the value types DATE-TIME and TIME 📚.
3.2.20. Value Data Types 🎀
Parameter Name: VALUE 💜
Purpose: this one explicitly sets the value type format for a property value 🦋.
Format Definition: the notation goes like this 💅
valuetypeparam = "VALUE" "=" valuetype
valuetype = ("BINARY"
/ "BOOLEAN"
/ "CAL-ADDRESS"
/ "DATE"
/ "DATE-TIME"
/ "DURATION"
/ "FLOAT"
/ "INTEGER"
/ "PERIOD"
/ "RECUR"
/ "TEXT"
/ "TIME"
/ "URI"
/ "UTC-OFFSET"
/ x-name
; Some experimental iCalendar value type.
/ iana-token)
; Some other IANA-registered iCalendar value type.Description: this param specifies the value type and format of the property value ✨. Property values MUST be of a single value type. For example, a RDATE property can't mix DATE-TIME and TIME value types 🙅.
If the property's value is the default value type, you don't need to specify this param 🌷. But if the default value type gets overridden by another allowable value type, then this parameter MUST be specified 🔥.
Applications MUST preserve the value data for x-name and iana-token values that they don't recognize, without trying to interpret or parse the value data 🫶.
3.3. Property Value Data Types 🌈
The properties in an iCalendar object are strongly typed 👑. The definition of each property restricts the value to one of the value data types (or just "value types") defined in this section 💖. The value type for a property is either specified implicitly as the default value type, or explicitly 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 🎀.
3.3.1. Binary 🧁
Value Name: BINARY 💜
Purpose: this value type identifies properties that contain a character encoding of inline binary data 🦋. Like, an inline attachment of a document could be included in an iCalendar object 📎.
Format Definition: the notation is 📝
binary = *(4b-char) [b-end]
; A "BASE64" encoded character string, as defined by [RFC4648].
b-end = (2b-char "==") / (3b-char "=")
b-char = ALPHA / DIGIT / "+" / "/"Description: property values with this value type MUST also include the inline encoding parameter sequence of ;ENCODING=BASE64 🔐. So all inline binary data MUST first be character encoded using the "BASE64" encoding method defined in [RFC2045] 🍓. No additional content value encoding (BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🙅.
Example: here's a "BASE64" encoded binary value 🌸
ATTACH;FMTTYPE=image/vnd.microsoft.icon;ENCODING=BASE64;VALUE
=BINARY:AAABAAEAEBAQAAEABAAoAQAAFgAAACgAAAAQAAAAIAAAAAEABAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAAAgIAAAICAgADAwMAA////AAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAMwAAAAAAABNEMQAAAAAAAkQgAAAAAAJEREQgAA
ACECQ0QgEgAAQxQzM0E0AABERCRCREQAADRDJEJEQwAAAhA0QwEQAAAAAERE
AAAAAAAAREQAAAAAAAAkQgAAAAAAAAMgAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAA3.3.2. Boolean ✅
Value Name: BOOLEAN 💖
Purpose: this value type identifies properties that contain either a "TRUE" or "FALSE" Boolean value 🌗.
Format Definition: the notation is 📝
boolean = "TRUE" / "FALSE"Description: these values are case-insensitive text 🔤. No additional content value encoding (BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🙅.
Example: here's a hypothetical property with a BOOLEAN value type ✨
TRUE3.3.3. Calendar User Address 📬
Value Name: CAL-ADDRESS 💌
Purpose: this value type identifies properties that contain a calendar user address 🏡.
Format Definition: the notation is 📝
cal-address = uriDescription: the value is a URI as defined by [RFC3986], 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 [RFC2368] 📧. No additional content value encoding (BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🙅.
Example: 🦢
mailto:jane_doe@example.com3.3.4. Date 📅
Value Name: DATE 🗓️
Purpose: this value type identifies values that contain a calendar date 🌷.
Format Definition: the notation is 📝
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 permits it, multiple "date" values can be written as a COMMA-separated list 🍭. The format is based on the [ISO.8601.2004] complete representation, basic format for a calendar date 🧠. The text is a four-digit year, a two-digit month, and a two-digit day of the month, with no separator characters between the year, month, and day 💕. No additional content value encoding (BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🙅.
Example: July 14, 1997 looks like this 🎂
199707143.3.5. Date-Time 💖
Value Name: DATE-TIME
Purpose: Okay, this one is for values that pin down an exact calendar date and time of day. Super precise, no vibes-based guessing. 🎀
Format Definition: This value type is defined by the following notation:
date-time = date "T" time ;As specified in the DATE and TIME
;value definitionsDescription: If the property allows it, you can list several "DATE-TIME" values separated by COMMA characters. ✨ There's no extra content value encoding here (aka the BACKSLASH character encoding, see Section 3.3.11), so don't go hunting for one. 💅
The "DATE-TIME" value type is for values that have a precise calendar date and time of day. The format is based on the [ISO.8601.2004] complete representation, basic format for a calendar date and time of day. Text-wise, it's the "date", then a LATIN CAPITAL LETTER T (the time designator), then the "time" format, all smooshed together. 🌸
The "DATE-TIME" value type shows time values in three forms:
Before we get to those, here's one that is NOT allowed. The form of date and time with UTC offset MUST NOT be used. For example, this is not valid for a DATE-TIME value:
19980119T230000-0800 ;Invalid time formatFORM #1: DATE WITH LOCAL TIME
This is a DATE-TIME value with no UTC designator and no time zone reference. For example, this is January 18, 1998, at 11 PM:
19980118T230000These values are "floating" and aren't tied to any particular time zone. They mean the same hour, minute, and second no matter which time zone is being observed. Think of an event saying someone is busy from 11:00 AM to 1:00 PM every day, no matter where they are. That's when you'd use a local time. 🦋
The recipient of an iCalendar object with a local time property value, and no relative time zone info, SHOULD interpret the value as being fixed to whatever time zone the "ATTENDEE" is in at any given moment. So two "Attendees" in different time zones who get the same floating event definition might be participating at different actual times. Floating time SHOULD only be used where that is the reasonable behavior. 🫶
In most cases, though, you want a fixed time. To properly communicate a fixed time in a property value, either UTC time or local time with time zone reference MUST be specified. 👑
Using local time in a DATE-TIME value without the "TZID" property parameter counts as floating time, even if there are "VTIMEZONE" calendar components in the iCalendar object. 🙈
FORM #2: DATE WITH UTC TIME
The date with UTC time (aka absolute time) is marked by a LATIN CAPITAL LETTER Z suffix, the UTC designator, tacked onto the end of the time value. For example, this is January 19, 1998, at 0700 UTC:
19980119T070000ZThe "TZID" property parameter MUST NOT be applied to DATE-TIME properties whose time values are specified in UTC. 💀
FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE
Here you use the "TZID" property parameter to point at the right time zone definition. "TZID" gets covered in detail in Section 3.2.19. For example, this is 2:00 A.M. in New York on January 19, 1998:
TZID=America/New_York:19980119T020000If, based on the referenced time zone's definition, the local time happens more than once (when changing from daylight to standard time), the DATE-TIME value refers to the first occurrence. So TZID=America/New_York:20071104T013000 means November 4, 2007 at 1:30 A.M. EDT (UTC-04:00).
If the local time doesn't happen at all (when changing from standard to daylight time), the DATE-TIME value is interpreted using the UTC offset from before the gap. So TZID=America/New_York:20070311T023000 means March 11, 2007 at 3:30 A.M. EDT (UTC-04:00), one hour after 1:30 A.M. EST (UTC-05:00). ⭐
A time value MUST only specify the second 60 when specifying a positive leap second. For example:
19970630T235960ZImplementations that do not support leap seconds SHOULD interpret the second 60 as equivalent to the second 59.
Example: The following represents July 14, 1997, at 1:30 PM in New York City in each of the three time formats, using the "DTSTART" property.
DTSTART:19970714T133000 ; Local time
DTSTART:19970714T173000Z ; UTC time
DTSTART;TZID=America/New_York:19970714T133000
; Local time and time
; zone reference3.3.6. Duration ⏳
Value Name: DURATION
Purpose: This value type is for properties that hold a span of time, like how long something lasts. 🌈
Format Definition: This value type is defined by the following notation:
dur-value = (["+"] / "-") "P" (dur-date / dur-time / dur-week)
dur-date = dur-day [dur-time]
dur-time = "T" (dur-hour / dur-minute / dur-second)
dur-week = 1*DIGIT "W"
dur-hour = 1*DIGIT "H" [dur-minute]
dur-minute = 1*DIGIT "M" [dur-second]
dur-second = 1*DIGIT "S"
dur-day = 1*DIGIT "D"Description: If the property allows it, you can list multiple "duration" values separated by a COMMA. 🍓 The format is based on the [ISO.8601.2004] complete representation, basic format, with designators for the duration of time. It can express nominal durations (weeks and days) and accurate durations (hours, minutes, and seconds). Heads up: unlike [ISO.8601.2004], this value type doesn't support the "Y" and "M" designators for years and months.
The length of a week or a day depends on where it sits in the calendar. When the time scale has discontinuities, like switching from standard time to daylight time and back, working out the exact duration means adding or subtracting the change in duration from that discontinuity. Leap seconds MUST NOT be considered when computing an exact duration. When computing an exact duration, the greatest order time components MUST be added first. That means the number of days MUST be added first, followed by the number of hours, number of minutes, and number of seconds. 🧚
Negative durations are typically used to schedule an alarm to trigger before an associated time (see Section 3.8.6.3).
No additional content value encoding (i.e., BACKSLASH character encoding, see Section 3.3.11) are defined for this value type.
Example: A duration of 15 days, 5 hours, and 20 seconds would be:
P15DT5H0M20SA duration of 7 weeks would be:
P7W3.3.7. Float 🦋
Value Name: FLOAT
Purpose: This value type is for properties that contain a real-number value. 💜
Format Definition: This value type is defined by the following notation:
float = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]Description: If the property allows it, you can list multiple "float" values separated by a COMMA. No additional content value encoding (i.e., BACKSLASH character encoding, see Section 3.3.11) is defined for this value type.
Example:
1000000.0000001
1.333
-3.143.3.8. Integer 🔥
Value Name: INTEGER
Purpose: This value type is for properties that contain a signed integer value. 🎀
Format Definition: This value type is defined by the following notation:
integer = (["+"] / "-") 1*DIGITDescription: If the property allows it, you can list multiple "integer" values separated by a COMMA. 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, see Section 3.3.11) is defined for this value type.
Example:
1234567890
-1234567890
+1234567890
4321098763.3.9. Period of Time 🌸
Value Name: PERIOD
Purpose: This value type is for values that contain a precise period of time. ✨
Format Definition: This value type is defined by the following notation:
period = period-explicit / period-start
period-explicit = date-time "/" date-time
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and end. The start MUST
; be before the end.
period-start = date-time "/" dur-value
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and positive duration
; of time.Description: If the property allows it, you can list multiple "period" values separated by a COMMA. There are two forms of period, bestie. 🫶
Form one: the period is identified by its start and its end. This is based on the [ISO.8601.2004] complete representation, basic format for the "DATE-TIME" start, then a SOLIDUS character, then the "DATE-TIME" end. The start of the period MUST be before the end of the period.
Form two: the period is defined by a start and a positive duration of time. This is based on the [ISO.8601.2004] complete representation, basic format for the "DATE-TIME" start, then a SOLIDUS character, then the [ISO.8601.2004] basic format for the "DURATION" of the period. 👑
Example: The period starting at 18:00:00 UTC, on January 1, 1997 and ending at 07:00:00 UTC on January 2, 1997 would be:
19970101T180000Z/19970102T070000ZThe period starting at 18:00:00 on January 1, 1997 and lasting 5 hours and 30 minutes would be:
19970101T180000Z/PT5H30MNo additional content value encoding (i.e., BACKSLASH character encoding, see Section 3.3.11) is defined for this value type.
3.3.10. Recurrence Rule 🌈
Value Name: RECUR
Purpose: This value type is for properties that contain a recurrence rule specification. 💖
Format Definition: This value type is defined by the following notation:
recur = recur-rule-part *( ";" recur-rule-part )
;
; The rule parts are not ordered in any
; particular sequence.
;
; The FREQ rule part is REQUIRED,
; but MUST NOT occur more than once.
;
; The UNTIL or COUNT rule parts are OPTIONAL,
; but they MUST NOT occur in the same 'recur'.
;
; The other rule parts are OPTIONAL,
; but MUST NOT occur more than once. recur-rule-part = ( "FREQ" "=" freq )
/ ( "UNTIL" "=" enddate )
/ ( "COUNT" "=" 1*DIGIT )
/ ( "INTERVAL" "=" 1*DIGIT )
/ ( "BYSECOND" "=" byseclist )
/ ( "BYMINUTE" "=" byminlist )
/ ( "BYHOUR" "=" byhrlist )
/ ( "BYDAY" "=" bywdaylist )
/ ( "BYMONTHDAY" "=" bymodaylist )
/ ( "BYYEARDAY" "=" byyrdaylist )
/ ( "BYWEEKNO" "=" bywknolist )
/ ( "BYMONTH" "=" bymolist )
/ ( "BYSETPOS" "=" bysplist )
/ ( "WKST" "=" weekday )
freq = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"
/ "WEEKLY" / "MONTHLY" / "YEARLY"
enddate = date / date-time
byseclist = ( seconds *("," seconds) )
seconds = 1*2DIGIT ;0 to 60
byminlist = ( minutes *("," minutes) )
minutes = 1*2DIGIT ;0 to 59
byhrlist = ( hour *("," hour) )
hour = 1*2DIGIT ;0 to 23
bywdaylist = ( weekdaynum *("," weekdaynum) )
weekdaynum = [[plus / minus] ordwk] weekday
plus = "+"
minus = "-"
ordwk = 1*2DIGIT ;1 to 53
weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
;FRIDAY, and SATURDAY days of the week.
bymodaylist = ( monthdaynum *("," monthdaynum) )
monthdaynum = [plus / minus] ordmoday
ordmoday = 1*2DIGIT ;1 to 31
byyrdaylist = ( yeardaynum *("," yeardaynum) )
yeardaynum = [plus / minus] ordyrday
ordyrday = 1*3DIGIT ;1 to 366
bywknolist = ( weeknum *("," weeknum) )
weeknum = [plus / minus] ordwk
bymolist = ( monthnum *("," monthnum) )
monthnum = 1*2DIGIT ;1 to 12
bysplist = ( setposday *("," setposday) )
setposday = yeardaynumDescription: okay so this value type is a structured value made up of a list of one or more recurrence grammar parts 🎀. Each rule part is a NAME=VALUE pair, and the rule parts are separated from each other by the SEMICOLON character ✨. The rule parts aren't in any particular order, which is very chill 💅. Individual rule parts MUST only be specified once 🙈. Compliant applications MUST accept rule parts in any sequence, but to keep things backward compatible with apps that predate this revision of iCalendar, the FREQ rule part MUST be the first rule part specified in a RECUR value 👑.
The FREQ rule part is the main character 👑 because it tells you what kind of recurrence rule you're looking at. This rule part MUST be specified in the recurrence rule. The valid values are SECONDLY (repeating on an interval of a second or more), MINUTELY (a minute or more), HOURLY (an hour or more), DAILY (a day or more), WEEKLY (a week or more), MONTHLY (a month or more), and YEARLY (a year or more) 🗓️.
The INTERVAL rule part holds a positive integer for how often the rule repeats 🔁. 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. For example, inside a DAILY rule, a value of "8" means every eight days 🦋.
The UNTIL rule part sets a DATE or DATE-TIME value that bounds the rule in an inclusive way 🚪. If the UNTIL value lines up with the recurrence, that DATE or DATE-TIME becomes the last instance of the recurrence 🏁. The value of the UNTIL rule part MUST have the same value type as the "DTSTART" property. If the "DTSTART" property is a date with local time, then the UNTIL rule part MUST also be a date with local time. If the "DTSTART" property is a date with UTC time, or a date with local time and a time zone reference, then the UNTIL rule part MUST be a date with UTC time. For the "STANDARD" and "DAYLIGHT" sub-components, the UNTIL rule part MUST always be a date with UTC time. If it's specified as a DATE-TIME value, then it MUST be in a UTC time format. If UNTIL isn't present and COUNT isn't present either, the "RRULE" is considered to repeat forever ♾️.
The COUNT rule part sets how many occurrences the recurrence gets, so it's the range bound 🔢. The "DTSTART" property value always counts as the first occurrence 🥇.
The BYSECOND rule part takes a COMMA-separated list of seconds within a minute, and valid values are 0 to 60 ⏱️. The BYMINUTE rule part takes a COMMA-separated list of minutes within an hour, with valid values 0 to 59 🕐. The BYHOUR rule part takes a COMMA-separated list of hours of the day, with valid values 0 to 23 🌙. The BYSECOND, BYMINUTE and BYHOUR rule parts MUST NOT be specified when the associated "DTSTART" property has a DATE value type 🙅♀️. These rule parts MUST be ignored in a RECUR value that breaks the rule above (for example, ones generated by applications that predate this revision of iCalendar). Honestly, that's a whole mood 😭.
The BYDAY rule part takes a COMMA-separated list of days of the week 📅. SU is Sunday, MO is Monday, TU is Tuesday, WE is Wednesday, TH is Thursday, FR is Friday, and SA is Saturday ☀️.
Each BYDAY value can also start with a positive (+n) or negative (-n) integer ➕➖. When it's there, it means the nth occurrence of a specific day within a MONTHLY or YEARLY "RRULE" 🎯. The numeric value in a BYDAY rule part with FREQ set to YEARLY works like an offset within the month when BYMONTH is present, and like an offset within the year when BYWEEKNO or BYMONTH is present 🧮. 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 BYDAY rule part MUST NOT be specified with a numeric value when the FREQ rule part is not set to MONTHLY or YEARLY. And the BYDAY rule part MUST NOT be specified with a numeric value when FREQ is set to YEARLY and the BYWEEKNO rule part is specified 🚫.
Here's the fun bit 🤩. For example, within a MONTHLY rule, +1MO (or just 1MO) is the first Monday of the month, whereas -1MO is the last Monday of the month 🏆.
The BYMONTHDAY rule part takes a COMMA-separated list of days of the month. Valid values are 1 to 31 or -31 to -1 📍. For example, -10 is the tenth to last day of the month 🔟. The BYMONTHDAY rule part MUST NOT be specified when the FREQ rule part is set to WEEKLY 🙅♀️.
The BYYEARDAY rule part takes 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 last day of the year (March 1st) 🎆. The BYYEARDAY rule part MUST NOT be specified when the FREQ rule part is set to DAILY, WEEKLY, or MONTHLY 🛑.
The BYWEEKNO rule part takes a COMMA-separated list of ordinals for weeks of the year. Valid values are 1 to 53 or -53 to -1 📊. These match up with the week numbering defined in [ISO.8601.2004] 🗂️. A week is a seven day period that starts on the day defined as the week start (see WKST) 🗓️. Week number one of the calendar year is the first week that contains at least four (4) days in that calendar year 🥳. This rule part MUST NOT be used when the FREQ rule part is set to anything other than YEARLY. For example, 3 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 rule part takes a COMMA-separated list of months of the year. Valid values are 1 to 12 🌕.
The WKST rule part sets the day the workweek starts 💼. 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 rule part is specified. It also matters in a YEARLY "RRULE" when a BYWEEKNO rule part is specified. The default value is MO 🗝️.
The BYSETPOS rule part takes a COMMA-separated list of values that picks out the nth occurrence within the set of recurrence instances the rule specifies 🎯. BYSETPOS works on a set of recurrence instances within one interval of the recurrence rule. For example, in a WEEKLY rule, the interval would be one week. A set of recurrence instances starts at the beginning of the interval defined by the FREQ rule part 🧩. Valid values are 1 to 366 or -366 to -1. It MUST only be used in conjunction with another BYxxx rule part. For example, "the last work day of the month" could be written as:
FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 💼✨
Each BYSETPOS value can include a positive (+n) or negative (-n) integer. When it's there, it means the nth occurrence of that specific occurrence within the set of occurrences the rule specifies ➕.
Recurrence rules can generate recurrence instances with an invalid date (for example, February 30) or a nonexistent local time (for example, 1:30 AM on a day when the local time jumps forward by an hour at 1:00 AM) 🙃. Those recurrence instances MUST be ignored and MUST NOT be counted as part of the recurrence set. Not it 🙅♀️.
The information you need to figure out each recurrence instance's start time and date, but that isn't in the rule itself, comes from the Start Time ("DTSTART") component attribute 🧭. For example, "FREQ=YEARLY;BYMONTH=1" doesn't pick a specific day of the month or a time. That info is the same as what's in "DTSTART" 📝.
BYxxx rule parts tweak the recurrence in some way 🎀. BYxxx rule parts for a period that is the same as or longer than the frequency usually reduce or limit how many occurrences get generated ✂️. For example, "FREQ=DAILY;BYMONTH=1" cuts the instances down from every day (if BYMONTH isn't present) to every day in January ❄️. BYxxx rule parts for a period shorter than the frequency usually expand the number of occurrences 📈. For example, "FREQ=YEARLY;BYMONTH=1,2" bumps the days in the yearly set from 1 (if BYMONTH isn't present) up to 2 🌟.
If you stack up multiple BYxxx rule parts 💅, they get applied in a specific order. First you work out the FREQ and INTERVAL rule parts. Then the BYxxx parts hit the current set of occurrences in this exact order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR, BYMINUTE, BYSECOND and BYSETPOS. COUNT and UNTIL get evaluated last 🎀
This table is your cheat sheet for whether each BYxxx part expands or limits the set, depending on your FREQ value 🧚 If the table says "N/A", that BYxxx part MUST NOT be used with that FREQ value. BYDAY is extra special and has its own notes right under the table 👑
+----------+--------+--------+-------+-------+------+-------+------+
| |SECONDLY|MINUTELY|HOURLY |DAILY |WEEKLY|MONTHLY|YEARLY|
+----------+--------+--------+-------+-------+------+-------+------+
|BYMONTH |Limit |Limit |Limit |Limit |Limit |Limit |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYWEEKNO |N/A |N/A |N/A |N/A |N/A |N/A |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYYEARDAY |Limit |Limit |Limit |N/A |N/A |N/A |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYMONTHDAY|Limit |Limit |Limit |Limit |N/A |Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYDAY |Limit |Limit |Limit |Limit |Expand|Note 1 |Note 2|
+----------+--------+--------+-------+-------+------+-------+------+
|BYHOUR |Limit |Limit |Limit |Expand |Expand|Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYMINUTE |Limit |Limit |Expand |Expand |Expand|Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYSECOND |Limit |Expand |Expand |Expand |Expand|Expand |Expand|
+----------+--------+--------+-------+-------+------+-------+------+
|BYSETPOS |Limit |Limit |Limit |Limit |Limit |Limit |Limit |
+----------+--------+--------+-------+-------+------+-------+------+- Note 1: Limit if BYMONTHDAY is present; otherwise, special expand for MONTHLY.
- Note 2: Limit if BYYEARDAY or BYMONTHDAY is present; otherwise, special expand for WEEKLY if BYWEEKNO present; otherwise, special expand for MONTHLY if BYMONTH present; otherwise, special expand for YEARLY.
Here's an example of evaluating multiple BYxxx rule parts 🌸
DTSTART;TZID=America/New_York:19970105T083000
RRULE:FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9;
BYMINUTE=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". Next, "BYDAY=SU" turns that into "every Sunday in January, every other year". Then "BYHOUR=8,9" gives you "every Sunday in January at 8 AM and 9 AM, every other year". Then "BYMINUTE=30" makes it "every Sunday in January at 8:30 AM and 9:30 AM, every other year". Lastly, since the RRULE doesn't say anything about 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" 💖 Same vibe if the BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY, or BYMONTH part is missing: the minute, hour, day, or month just gets grabbed from DTSTART instead ✨
If the computed local start time of a recurrence instance doesn't exist, or happens more than once, for the specified time zone, the instance time gets read the same way as an explicit DATE-TIME value for that date and time, as described in Section 3.3.5. Bestie, daylight saving chaos is real 🙈
No extra content value encoding (that's BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🫶
Example: here's a rule for 10 occurrences that happen every other day 🍓
FREQ=DAILY;COUNT=10;INTERVAL=2There are other examples in Section 3.8.5.3, so go check those out too 🧁
3.3.11. Text 🎀
Value Name: TEXT
Purpose: This value type is for values that hold human-readable text 📖
Format Definition: This value type is defined by the following notation:
text = *(TSAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR)
; Folded according to description above
ESCAPED-CHAR = ("\\" / "\;" / "\," / "\N" / "\n")
; \\ encodes \, \N or \n encodes newline
; \; encodes ;, \, encodes ,
TSAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-5B /
%x5D-7E / NON-US-ASCII
; Any character except CONTROLs not needed by the current
; character set, DQUOTE, ";", ":", "\", ","Description: If the property allows it, you can put multiple TEXT values in a COMMA-separated list 💅
The language the text is written in can be set with the "LANGUAGE" property parameter 🌈
An intentional formatted line break MUST only be included in a TEXT property value by writing the line break as a BACKSLASH followed by a LATIN SMALL LETTER N or a LATIN CAPITAL LETTER N, so \n or \N 🍓
TEXT values can also have special characters that act as delimiters, like a COMMA for lists or a SEMICOLON for structured values 👑 So that those characters can show up inside TEXT values, they MUST be escaped with a BACKSLASH. A BACKSLASH inside a TEXT value MUST be escaped with another BACKSLASH. A COMMA inside a TEXT value MUST be escaped with a BACKSLASH. A SEMICOLON inside a TEXT value MUST be escaped with a BACKSLASH. But a COLON inside a TEXT value SHALL NOT be escaped with a BACKSLASH, so don't even try 🙅♀️
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.3.3.12. Time ⏰
Value Name: TIME
Purpose: This value type is for values that hold a time of day ☀️
Format Definition: This value type is defined by the following notation:
time = time-hour time-minute time-second [time-utc]
time-hour = 2DIGIT ;00-23
time-minute = 2DIGIT ;00-59
time-second = 2DIGIT ;00-60
;The "60" value is used to account for positive "leap" seconds.
time-utc = "Z"Description: If the property allows it, you can put multiple "time" values in a COMMA-separated list. No extra content value encoding (that's BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🫶
The TIME value type shows a time of day, and the format is based on the [ISO.8601.2004] complete representation, basic format for a time of day 🧠 It's a two-digit, 24-hour hour (so 00-23), a two-digit minute (00-59), and a two-digit second (00-60). The seconds value of 60 MUST only be used to account for positive "leap" seconds 🕰️ Fractions of a second are not supported by this format.
Just like the DATE-TIME definition above, TIME values come in three forms 🦋
The form of time with a UTC offset MUST NOT be used. For example, this is not a valid time value:
230000-0800 ;Invalid time formatFORM #1 LOCAL TIME
Local time is just a time value with no UTC designator and no time zone reference. For example, 11:00 PM:
230000Local times are "floating" and aren't bound to any particular time zone. They show the same hour, minute, and second no matter which time zone is being observed 🌍 For example, an event can say that someone is busy from 11:00 AM to 1:00 PM every day, no matter what time zone they're in. That's when you'd use a local time. When an iCalendar recipient gets a property value that's a local time with no time zone info, it SHOULD interpret the value as fixed to whatever time zone the "ATTENDEE" is in at any given moment. That means two "Attendees" may join the same event at different UTC times. Floating time SHOULD only be used where that's reasonable behavior 🙃
In most cases you actually 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.
The use of local time in a TIME value without the "TZID" property parameter is to be interpreted as floating time, no matter whether VTIMEZONE calendar components exist in the iCalendar object 🙌
FORM #2: UTC TIME
UTC time (also called absolute time) is marked with a LATIN CAPITAL LETTER Z suffix, the UTC designator, added onto the time value. For example, this represents 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
This form is local time with a reference to time zone information. You use the "TZID" property parameter to point at the right time zone definition. "TZID" is covered in detail in Section 3.2.19 ✨
Example: the following represents 8:30 AM in New York in winter, five hours behind UTC, in each of the three formats 🗽
083000
133000Z
TZID=America/New_York:0830003.3.13. URI 🔗
Value Name: URI
Purpose: This value type is for values that hold a uniform resource identifier (URI), a reference to the property value 📍
Format Definition: This value type is defined by the following notation:
uri = <As defined in Section 3 of [RFC3986]>Description: This value type is handy for pointing at binary info, especially when the values are big or just not something you want to cram straight into the iCalendar object 📦
Property values with this value type MUST follow the generic URI syntax defined in [RFC3986].
When a property parameter value is a URI value type, the URI MUST be specified as a quoted-string value 💜
No extra content value encoding (that's BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🫧
Example: here's a URI for a network file 🌸
http://example.com/my-report.txt3.3.14. UTC Offset 🌍
Value Name: UTC-OFFSET
Purpose: this value type is for properties that hold an offset from UTC to local time, aka how far your clock is from the world clock 🕰️
Format Definition: it's defined with this notation:
utc-offset = time-numzone
time-numzone = ("+" / "-") time-hour time-minute [time-second]Description: the PLUS SIGN character MUST be specified for positive UTC offsets (i.e., ahead of UTC) ➕. The HYPHEN-MINUS character MUST be specified for negative UTC offsets (i.e., behind of UTC) ➖. The value of -0000 and -000000 are not allowed 🙅♀️. The time-second, if present, MUST NOT be 60; if absent, it defaults to zero ⏱️.
No additional content value encoding (i.e., BACKSLASH character encoding, see Section 3.3.11) is defined for this value type 🙈.
Example: these UTC offsets are for standard time in New York (five hours behind UTC) and Geneva (one hour ahead of UTC) 🗽🇨🇭:
-0500
+01003.4. iCalendar Object 🎀
The Calendaring and Scheduling Core Object is a collection of calendaring and scheduling information 📅. Typically, this information will consist of an iCalendar stream with a single iCalendar object. However, multiple iCalendar objects can be sequentially grouped together in an iCalendar stream 🧚. The first line and last line of the iCalendar object MUST contain a pair of iCalendar object delimiter strings. The syntax for an iCalendar stream is as follows:
icalstream = 1*icalobject
icalobject = "BEGIN" ":" "VCALENDAR" CRLF
icalbody
"END" ":" "VCALENDAR" CRLFThe following is a simple example of an iCalendar object 💖:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
UID:19970610T172345Z-AF23B2@example.com
DTSTAMP:19970610T172345Z
DTSTART:19970714T170000Z
DTEND:19970715T040000Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR3.5. Property 💅
A property is the definition of an individual attribute describing a calendar object or a calendar component ✨. A property takes the form defined by the "contentline" notation defined in Section 3.1.
Here's an example of a property:
DTSTART:19960415T133000ZThis memo imposes no ordering of properties within an iCalendar object 🙃.
Property names, parameter names, and enumerated parameter values are case-insensitive 🫶. For example, the property name DUE is the same as due and Due, and DTSTART;TZID=America/New_York:19980714T120000 is the same as DtStart;TzID=America/New_York:19980714T120000 💜.
3.6. Calendar Components 🦋
The body of the iCalendar object is a sequence of calendar properties and one or more calendar components 🌸. The calendar properties are attributes that apply to the calendar object as a whole. The calendar components are collections of properties that express a particular calendar semantic. For example, a calendar component can specify an event, a to-do, a journal entry, time zone information, free/busy time information, or an alarm ⏰.
The body of the iCalendar object is defined by the following notation:
icalbody = calprops component
calprops = *(
;
; The following are REQUIRED,
; but MUST NOT occur more than once.
;
prodid / version /
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
calscale / method /
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
x-prop / iana-prop
;
)
component = 1*(eventc / todoc / journalc / freebusyc /
timezonec / iana-comp / x-comp)
iana-comp = "BEGIN" ":" iana-token CRLF
1*contentline
"END" ":" iana-token CRLF
x-comp = "BEGIN" ":" x-name CRLF
1*contentline
"END" ":" x-name CRLFAn iCalendar object MUST include the "PRODID" and "VERSION" calendar properties 🎁. On top of that, it MUST include at least one calendar component 🧁. Special forms of iCalendar objects are possible for publishing just busy time (i.e., only a "VFREEBUSY" calendar component) or time zone (i.e., only a "VTIMEZONE" calendar component) information 🕒. A complex iCalendar object that captures a complete snapshot of a calendar's contents is also possible (e.g., a composite of many different calendar components) 📚. More commonly, though, an iCalendar object will consist of just a single "VEVENT", "VTODO", or "VJOURNAL" calendar component 🥰.
Applications MUST ignore x-comp and iana-comp values they don't recognize. Applications that support importing iCalendar objects SHOULD support all of the component types defined in this document, and SHOULD NOT silently drop any components, as that can lead to user data loss 💀🚫.
3.6.1. Event Component 🎉
Component Name: VEVENT
Purpose: provides 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 REQUIRED,
; but MUST NOT occur more than once.
;
dtstamp / uid /
;
; The following is REQUIRED if the component
; appears in an iCalendar object that doesn't
; specify the "METHOD" property; otherwise, it
; is OPTIONAL; in any case, it MUST NOT occur
; more than once.
;
dtstart /
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
class / created / description / geo /
last-mod / location / organizer / priority /
seq / status / summary / transp /
url / recurid /
;
; The following is OPTIONAL,
; but SHOULD NOT occur more than once.
;
rrule /
;
; 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 / rstatus / related /
resources / rdate / x-prop / iana-prop
;
)Description: a VEVENT calendar component is a grouping of component properties, possibly including VALARM calendar components, that represents a scheduled amount of time on a calendar 📆. For example, it can be an activity, like a one-hour-long department meeting from 8:00 AM to 9:00 AM tomorrow 🧑💼. Generally, an event takes up time on an individual calendar, so it shows up as an opaque interval in a search for busy time 🙈. Alternatively, the event can have its Time Transparency set to "TRANSPARENT" to keep it from blocking time in busy-time searches 👻.
The VEVENT is also the calendar component used to specify an anniversary or daily reminder within a calendar 🎂. These events use a DATE value type for the DTSTART property instead of the default value type of DATE-TIME. If such a VEVENT has a DTEND property, it MUST be specified as a DATE value also. An anniversary-type VEVENT can span more than one date (i.e., the DTEND property value is set to a calendar date after the DTSTART property value) 🗓️. If such a VEVENT has a DURATION property, it MUST be specified as a dur-day or dur-week value.
The DTSTART property for a VEVENT specifies the inclusive start of the event 🚀. For recurring events, it also specifies the very first instance in the recurrence set 🔁. The DTEND property for a VEVENT calendar component specifies the non-inclusive end of the event 🛑. For cases where a VEVENT calendar component specifies a DTSTART property with a DATE value type but no DTEND nor DURATION property, the event's duration is taken to be one day 🌞. For cases where a VEVENT calendar component specifies a DTSTART property with a DATE-TIME value type but no DTEND property, the event ends on the same calendar date and time of day specified by the DTSTART property ⏳.
The VEVENT calendar component cannot be nested within another calendar component 🙅♀️. However, VEVENT calendar components can be related to each other, or to a VTODO or a VJOURNAL calendar component, with 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@example.com
DTSTAMP:19970901T130000Z
DTSTART:19970903T163000Z
DTEND:19970903T190000Z
SUMMARY:Annual Employee Review
CLASS:PRIVATE
CATEGORIES:BUSINESS,HUMAN RESOURCES
END:VEVENTAnd here's a VEVENT for a reminder that won't be opaque, but transparent, to busy-time searches 🧠:
BEGIN:VEVENT
UID:19970901T130000Z-123402@example.com
DTSTAMP:19970901T130000Z
DTSTART:19970401T163000Z
DTEND:19970402T010000Z
SUMMARY:Laurel is in sensitivity awareness class.
CLASS:PUBLIC
CATEGORIES:BUSINESS,HUMAN RESOURCES
TRANSP:TRANSPARENT
END:VEVENTNow an anniversary that happens every year 💍🥂:
BEGIN:VEVENT
UID:19970901T130000Z-123403@example.com
DTSTAMP:19970901T130000Z
DTSTART;VALUE=DATE:19971102
SUMMARY:Our Blissful Anniversary
TRANSP:TRANSPARENT
CLASS:CONFIDENTIAL
CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
RRULE:FREQ=YEARLY
END:VEVENTLast one: a multi-day event running from June 28th, 2007 to July 8th, 2007 inclusively 🎶. The DTEND property is set to July 9th, 2007, since DTEND specifies the non-inclusive end of the event 🎷.
BEGIN:VEVENT
UID:20070423T123432Z-541111@example.com
DTSTAMP:20070423T123432Z
DTSTART;VALUE=DATE:20070628
DTEND;VALUE=DATE:20070709
SUMMARY:Festival International de Jazz de Montreal
TRANSP:TRANSPARENT
END:VEVENT3.6.2. To-Do Component ✅
Component Name: VTODO
Purpose: Group together the calendar properties that describe a to-do, aka the little tasks your brain keeps nagging you about 📝
Format Definition: A "VTODO" calendar component is defined by the following notation:
todoc = "BEGIN" ":" "VTODO" CRLF
todoprop *alarmc
"END" ":" "VTODO" CRLF
todoprop = *(
;
; The following are REQUIRED,
; but MUST NOT occur more than once.
;
dtstamp / uid /
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
class / completed / created / description /
dtstart / geo / last-mod / location / organizer /
percent / priority / recurid / seq / status /
summary / url /
;
; The following is OPTIONAL,
; but SHOULD NOT occur more than once.
;
rrule /
;
; Either 'due' or 'duration' MAY appear in
; a 'todoprop', but 'due' and 'duration'
; MUST NOT occur in the same 'todoprop'.
; If 'duration' appear in a 'todoprop',
; then 'dtstart' MUST also appear in
; the same 'todoprop'.
;
due / duration /
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
attach / attendee / categories / comment / contact /
exdate / rstatus / related / resources /
rdate / x-prop / iana-prop
;
)Description: A "VTODO" calendar component is a bundle of component properties, plus possibly some "VALARM" calendar components, that together represent an action item or assignment 💅 For example, it can track a piece of work assigned to a specific person, like "turn in travel expense today" 🧾
Quick but important tea ☕: the "VTODO" calendar component cannot be nested inside another calendar component. BUT "VTODO" components can still be linked to each other, or to a "VEVENT" or a "VJOURNAL" calendar component, using the "RELATED-TO" property. Iconic web of connections 🕸️
Also, a "VTODO" calendar component that doesn't have "DTSTART" and "DUE" (or "DURATION") properties is giving floating task energy 🦋. It shows up on every successive calendar date until it's completed. Literally haunting your calendar until you do it 💀
Examples: The following is an example of a "VTODO" calendar component that needs to be completed before May 1st, 2007. At midnight on May 1st, 2007, this to-do is officially overdue 😭
BEGIN:VTODO
UID:20070313T123432Z-456553@example.com
DTSTAMP:20070313T123432Z
DUE;VALUE=DATE:20070501
SUMMARY:Submit Quebec Income Tax Return for 2006
CLASS:CONFIDENTIAL
CATEGORIES:FAMILY,FINANCE
STATUS:NEEDS-ACTION
END:VTODONext up is a "VTODO" calendar component that was due before 1:00 P.M. UTC on July 9th, 2007, and got completed on July 7th, 2007 at 10:00 A.M. UTC. Early finisher behavior, I'm obsessed 🏆
BEGIN:VTODO
UID:20070514T103211Z-123404@example.com
DTSTAMP:20070514T103211Z
DTSTART:20070514T110000Z
DUE:20070709T130000Z
COMPLETED:20070707T100000Z
SUMMARY:Submit Revised Internet-Draft
PRIORITY:1
STATUS:NEEDS-ACTION
END:VTODO3.6.3. Journal Component 📓
Component Name: VJOURNAL
Purpose: Group together the component properties that describe a journal entry 🌸
Format Definition: A "VJOURNAL" calendar component is defined by the following notation:
journalc = "BEGIN" ":" "VJOURNAL" CRLF
jourprop
"END" ":" "VJOURNAL" CRLF
jourprop = *(
;
; The following are REQUIRED,
; but MUST NOT occur more than once.
;
dtstamp / uid /
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
class / created / dtstart /
last-mod / organizer / recurid / seq /
status / summary / url /
;
; The following is OPTIONAL,
; but SHOULD NOT occur more than once.
;
rrule /
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
attach / attendee / categories / comment /
contact / description / exdate / related / rdate /
rstatus / x-prop / iana-prop
;
)Description: A "VJOURNAL" calendar component is a bundle of component properties that represent one or more descriptive text notes tied to a particular calendar date 🧠 The "DTSTART" property is how you pin the journal entry to its date. Usually that's a DATE value, but a DATE-TIME value works too 🕰️ Journal entries can be things like a daily record from a legislative body, a log of individual phone calls for the day, or an ordered list of accomplishments. The "VJOURNAL" calendar component can also be used to attach a document to a calendar date 📎
Here's the tea 🫖: a "VJOURNAL" calendar component doesn't take up any time on a calendar. So it plays zero role in free or busy time searches. It's basically giving TRANSPARENT energy, so it's invisible to those searches 👻
Same rule as the to-do: the "VJOURNAL" calendar component cannot be nested inside another calendar component. But "VJOURNAL" components can be related to each other, or to a "VEVENT" or a "VTODO" calendar component, using the "RELATED-TO" property 🔗
Example: The following is an example of the "VJOURNAL" calendar component 🌈
BEGIN:VJOURNAL
UID:19970901T130000Z-123405@example.com
DTSTAMP:19970901T130000Z
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.\n3. Henry Miller (Handsoff Insurance): Car was
totaled by tree. Is looking into a loaner car. 555-2323
(tel).
END:VJOURNAL3.6.4. Free/Busy Component ✨
Component Name: VFREEBUSY 🎀
Purpose: okay so this bundles up properties that describe either a request for free/busy time, a response to one, or a published set of busy time 💅
Format Definition: a VFREEBUSY calendar component is defined like this 🌸
freebusyc = "BEGIN" ":" "VFREEBUSY" CRLF
fbprop
"END" ":" "VFREEBUSY" CRLF
fbprop = *(
;
; The following are REQUIRED,
; but MUST NOT occur more than once.
;
dtstamp / uid /
;
; The following are OPTIONAL,
; but MUST NOT occur more than once.
;
contact / dtstart / dtend /
organizer / url /
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
attendee / comment / freebusy / rstatus / x-prop /
iana-prop
;
)Description: a VFREEBUSY component is a grouping of properties that can represent a request for free or busy time info, a reply to that request, or a published set of busy time info 🦋
When it's used to request free/busy time, the ATTENDEE property names the calendar users whose free/busy time is being asked for. The ORGANIZER property names the calendar user doing the asking. DTSTART and DTEND set the window of time being requested. UID and DTSTAMP are there to help keep multiple requests in the right order 🧚
When it's used to reply to a request, the ATTENDEE property names the calendar user who's responding. The ORGANIZER property names the calendar user who originally made the request. The FREEBUSY property carries the free/busy info (if there is any). UID and DTSTAMP again help keep multiple replies in order 💜
When it's used to publish busy time, the ORGANIZER property names the calendar user the published busy time belongs to. DTSTART and DTEND set an inclusive time window that wraps around the busy time info. FREEBUSY holds the published busy time info itself. DTSTAMP gives the DATE-TIME when the iCalendar object was created ✨
The VFREEBUSY component cannot be nested inside another calendar component 🙈 You can have several VFREEBUSY components in one iCalendar object though! That's how you group free/busy info into neat little collections, like one group per month 🍓
This component is meant for iCalendar object methods that involve requests for free time, requests for busy time, requests for both, and the replies to all of those 🫶
Free/busy info lives in the FREEBUSY property. It's a terse way of showing time periods, and you can put one or more FREEBUSY properties in a VFREEBUSY component 🌈
When a VFREEBUSY component has DTSTART and DTEND, those two SHOULD be written before any FREEBUSY properties. Keep that order, bestie 🎀
The recurrence properties (RRULE,RDATE,EXDATE) are not allowed inside aVFREEBUSYcomponent. Any recurring events get turned into their individual busy time periods using theFREEBUSYproperty instead 💀
Example: here's a VFREEBUSY component being used to request free or busy time info 🔥
BEGIN:VFREEBUSY
UID:19970901T082949Z-FA43EF@example.com
ORGANIZER:mailto:jane_doe@example.com
ATTENDEE:mailto:john_public@example.com
DTSTART:19971015T050000Z
DTEND:19971016T050000Z
DTSTAMP:19970901T083000Z
END:VFREEBUSYAnd this is a VFREEBUSY component replying to that request with busy time info 💖
BEGIN:VFREEBUSY
UID:19970901T095957Z-76A912@example.com
ORGANIZER:mailto:jane_doe@example.com
ATTENDEE:mailto:john_public@example.com
DTSTAMP:19970901T100000Z
FREEBUSY:19971015T050000Z/PT8H30M,
19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M
URL:http://example.com/pub/busy/jpublic-01.ifb
COMMENT:This iCalendar file contains busy time information for
the next three months.
END:VFREEBUSYAnd finally, a VFREEBUSY component publishing busy time info 🦋
BEGIN:VFREEBUSY
UID:19970901T115957Z-76A912@example.com
DTSTAMP:19970901T120000Z
ORGANIZER:jsmith@example.com
DTSTART:19980313T141711Z
DTEND:19980410T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
URL:http://www.example.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY3.6.5. Time Zone Component 🌍
Component Name: VTIMEZONE 👑
Purpose: this groups properties that define a time zone 💅
Format Definition: a VTIMEZONE calendar component is defined like this 🎀
timezonec = "BEGIN" ":" "VTIMEZONE" CRLF
*(
;
; '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 are OPTIONAL,
; and MAY occur more than once.
;
x-prop / iana-prop
;
)
"END" ":" "VTIMEZONE" CRLF
standardc = "BEGIN" ":" "STANDARD" CRLF
tzprop
"END" ":" "STANDARD" CRLF
daylightc = "BEGIN" ":" "DAYLIGHT" CRLF
tzprop
"END" ":" "DAYLIGHT" CRLF
tzprop = *(
;
; The following are REQUIRED,
; but MUST NOT occur more than once.
;
dtstart / tzoffsetto / tzoffsetfrom /
;
; The following is OPTIONAL,
; but SHOULD NOT occur more than once.
;
rrule /
;
; The following are OPTIONAL,
; and MAY occur more than once.
;
comment / rdate / tzname / x-prop / iana-prop
;
)Description: a time zone is uniquely defined by the set of time measurement rules that a governing body sets for a geographic area 🌸 Those rules describe, at minimum, the base offset from UTC for that zone, which people often call the Standard Time offset ✨ Lots of places move their Standard Time forward or back by one hour to deal with seasonal changes in daylight hours. That's usually called Daylight Saving Time 🌞 Some places shift their clocks by a fraction of an hour instead 🙈 Standard Time is also known as 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 have changed since 1967. Each line is one description or rule for a particular observance 🗽
Effective Observance Rule
+-----------+--------------------------+--------+--------------+
| Date | (Date-Time) | Offset | Abbreviation |
+-----------+--------------------------+--------+--------------+
| 1967-1973 | last Sun in Apr, 02:00 | -0400 | EDT |
| | | | |
| 1967-2006 | last Sun in Oct, 02:00 | -0500 | EST |
| | | | |
| 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-2006 | first Sun in Apr, 02:00 | -0400 | EDT |
| | | | |
| 2007-* | second Sun in Mar, 02:00 | -0400 | EDT |
| | | | |
| 2007-* | first Sun in Nov, 02:00 | -0500 | EST |
+-----------+--------------------------+--------+--------------+Note: the spec for a global time zone registry isn't covered in this document and is left for future study 🔮 Still, implementers may find the TZ database [TZDB] super useful! It's an informal, public-domain collection of time zone info that volunteer Internet participants currently maintain, and it's used in several operating systems 🫶 It holds current and historical time zone info for lots of locations around the globe. It gives you a time zone identifier for every unique time zone rule set in actual use since 1970, and its historical data goes all the way back to when standard time was introduced ⭐
Interoperability between two calendaring and scheduling apps depends on being able to capture and convey date and time info in an unambiguous format. That matters a LOT for recurring events, to-dos, and journal entries 😭 Specifying current time zone info is a big part of making that work 💅
If a VTIMEZONE component is present, it defines the set of Standard Time and Daylight Saving Time observances (or rules) for one particular time zone over a given interval of time 🧚 A VTIMEZONE component cannot be nested inside other calendar components. Multiple VTIMEZONE components can exist in an iCalendar object. When that happens, each VTIMEZONE MUST represent a unique time zone definition 🌈 This is super necessary for some kinds of events, like airline flights, that start in one time zone and end in another ✈️ Iconic. Periodt.
So, bestie 🧚, the VTIMEZONE component is where we make sure everyone's on the same time zone page 💅. VTIMEZONE MUST include the "TZID" property and at least one definition of a "STANDARD" or "DAYLIGHT" sub-component 🎀. The "STANDARD" or "DAYLIGHT" sub-component MUST include the "DTSTART", "TZOFFSETFROM", and "TZOFFSETTO" properties ✨.
Every single unique "TZID" parameter value in the iCalendar object MUST get its own "VTIMEZONE" component 🦋. And if a recurring calendar component points at a "VTIMEZONE", that "VTIMEZONE" MUST give valid time zone info for all of the recurrence instances 💖. No skipping, no vibes-only guessing 😭.
Each "VTIMEZONE" is made of one or more sub-components that describe the rule for one particular observance, which is either Standard Time or Daylight Saving Time 🌸. 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 time zone can have several different definitions of its observances across a stretch of time 🧠. Each observance gets described with either a "STANDARD" or "DAYLIGHT" sub-component, and together those sub-components describe 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 you care about, then use that observance's offset value 🔥. Easy peasy.
The top-level properties of a "VTIMEZONE" calendar component are:
The mandatory "TZID" property is a text value that uniquely identifies the "VTIMEZONE" calendar component within the scope of an iCalendar object 👑.
The optional "LAST-MODIFIED" property is a UTC value that tells you when 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 anyone who might need to interpret the object can access 🫶. This SHOULD NOT normally be a "file" URL or any other URL that isn't widely accessible 🙈.
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 date with a local time value ⭐.
The mandatory "TZOFFSETFROM" property gives the UTC offset that is in use when the onset of this time zone observance begins 🌙. "TZOFFSETFROM" gets combined with "DTSTART" to define the effective onset for the time zone sub-component definition 💜. For example, here's the moment 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 could be used for displaying dates 📅.
The onset DATE-TIME values for the observance defined by the time zone sub-component are defined by the "DTSTART", "RRULE", and "RDATE" properties 🎯.
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" for this purpose:
- If 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"TZOFFSETFROM"properties MUST be used when generating the onset DATE-TIME values (instances) from the"RRULE"🧁.
The "RDATE" property can also define the onset of the observance by listing the individual onset dates and times 📌. "RDATE" in this usage MUST be specified as a date with local time value, relative to the UTC offset specified in the "TZOFFSETFROM" property 🌷.
The optional "COMMENT" property is also allowed for descriptive, explanatory text 💬.
Example: Here are some examples of the "VTIMEZONE" calendar component 🎀✨.
This one shows all the time zone rules for New York City since April 30, 1967 at 03:00:00 EDT 🗽💖:
BEGIN:VTIMEZONE
TZID:America/New_York
LAST-MODIFIED:20050809T050000Z
BEGIN:DAYLIGHT
DTSTART:19670430T020000
RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=-1SU;UNTIL=19730429T070000Z
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
BEGIN:STANDARD
DTSTART:19671029T020000
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU;UNTIL=20061029T060000Z
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19740106T020000
RDATE:19750223T020000
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
BEGIN:DAYLIGHT
DTSTART:19760425T020000
RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=-1SU;UNTIL=19860427T070000Z
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
BEGIN:DAYLIGHT
DTSTART:19870405T020000
RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=1SU;UNTIL=20060402T070000Z
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
BEGIN:DAYLIGHT
DTSTART:20070311T020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
BEGIN:STANDARD
DTSTART:20071104T020000
RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
END:VTIMEZONEThis next one shows time zone info for New York City using only the "DTSTART" property 🧚♀️. Heads up, this is only suitable for a recurring event that starts on or later than March 11, 2007 at 03:00:00 EDT (i.e., the earliest effective transition date and time) and ends no later than March 9, 2008 at 01:59:59 EST (i.e., latest valid date and time for EST in this scenario) 🚨. For example, this works for a recurring event that occurs every Friday, 8:00 A.M.-9:00 A.M., starting June 1, 2007, ending December 31, 2007,
BEGIN:VTIMEZONE
TZID:America/New_York
LAST-MODIFIED:20050809T050000Z
BEGIN:STANDARD
DTSTART:20071104T020000
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:20070311T020000
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONEThis is a simple one showing the current time zone rules for New York City using a "RRULE" recurrence pattern 🌸. There's no effective end date on either the Standard Time or Daylight Time rule, so this info is valid for a recurring event starting today and continuing indefinitely ♾️.
BEGIN:VTIMEZONE
TZID:America/New_York
LAST-MODIFIED:20050809T050000Z
TZURL:http://zones.example.com/tz/America-New_York.ics
BEGIN:STANDARD
DTSTART:20071104T020000
RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:20070311T020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONEThis one shows a set of rules for a fictitious time zone where the Daylight Time rule has an effective end date, meaning after that date Daylight Time is no longer observed 🛸🕰️.
BEGIN:VTIMEZONE
TZID:Fictitious
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:VTIMEZONEAnd this last one is a fictitious zone where the first Daylight Time rule has an effective end date 🌟. A second Daylight Time rule picks up right where the first one left off 💅✨.
BEGIN:VTIMEZONE
TZID:Fictitious
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:VTIMEZONE3.6.6. Alarm Component ⏰
Component Name: VALARM 🔔
Purpose: Okay so this one is a grouping of component properties that defines an alarm. It's giving reminder energy 💅
Format Definition: A VALARM calendar component is defined by the following notation:
alarmc = "BEGIN" ":" "VALARM" CRLF
(audioprop / dispprop / emailprop)
"END" ":" "VALARM" CRLF
audioprop = *(
;
; '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 / iana-prop
;
)
dispprop = *(
;
; The following are 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 / iana-prop
;
)
emailprop = *(
;
; 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 / iana-prop
;
)Description: A VALARM calendar component is basically a grouping of component properties that acts as a reminder or alarm for an event or a to-do. 🥹 For example, it may be used to define a reminder for a pending event or an overdue to-do.
The VALARM calendar component MUST include the ACTION and TRIGGER properties. The ACTION property further constrains the VALARM calendar component in the following ways:
When the action is AUDIO, the alarm can also include one and only one ATTACH property, which MUST point to a sound resource, which is rendered when the alarm is triggered. 🎵
When the action is DISPLAY, the alarm MUST also include a DESCRIPTION property, which contains the text to be displayed when the alarm is triggered. 🌸
When the action is EMAIL, the alarm MUST include a DESCRIPTION property, which contains the text to be used as the message body, a SUMMARY property, which contains the text to be used as the message subject, and one or more ATTENDEE properties, which contain the email address of attendees to receive the message. It can also include one or more ATTACH properties, which are intended to be sent as message attachments. When the alarm is triggered, the email message is sent. 📧✨
The VALARM calendar component MUST only appear within either a VEVENT or VTODO calendar component. VALARM calendar components cannot be nested. Multiple mutually independent VALARM calendar components can be specified for a single VEVENT or VTODO calendar component. Main character energy, but make it organised 👑
The TRIGGER property specifies when the alarm will be triggered. It specifies a duration prior to the start of an event or a to-do. The trigger edge may be explicitly set to be relative to the START or END of the event or to-do with the RELATED parameter of the TRIGGER property. The TRIGGER property value type can alternatively be set to an absolute calendar date with UTC time. ⏱️
In an alarm 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. In an alarm in a VEVENT calendar component set to trigger on the END of the event, either the DTEND property MUST be present, or the DTSTART and DURATION properties MUST both be present. In an alarm in a VTODO calendar component set to trigger on the END of the to-do, either the DUE property MUST be present, or the DTSTART and DURATION properties MUST both be present. 🫶
The alarm can be defined such that it triggers repeatedly. A definition of an alarm with a repeating trigger MUST include both the DURATION and REPEAT properties. The DURATION property specifies the delay period, after which the alarm will repeat. The REPEAT property specifies the number of additional repetitions that the alarm will be triggered. This repetition count is in addition to the initial triggering of the alarm. Both of these properties MUST be present in order to specify a repeating alarm. If one of these two properties is absent, then the alarm will not repeat beyond the initial trigger. 🔁
The ACTION property is used within the VALARM calendar component to specify the type of action invoked when the alarm is triggered. The VALARM properties provide enough information for a specific action to be invoked. It is typically the responsibility of a "Calendar User Agent" (CUA) to deliver the alarm in the specified fashion. An ACTION property value of AUDIO specifies an alarm that causes a sound to be played to alert the user; DISPLAY specifies an alarm that causes a text message to be displayed to the user; and EMAIL specifies an alarm that causes an electronic email message to be delivered to one or more email addresses. 🔔💖
In an AUDIO alarm, if the optional ATTACH property is included, it MUST specify an audio sound resource. The intention is that the sound will be played as the alarm effect. If an ATTACH property is specified that does not refer to a sound resource, or if the specified sound resource cannot be rendered (because its format is unsupported, or because it cannot be retrieved), then the CUA or other entity responsible for playing the sound may choose a fallback action, such as playing a built-in default sound, or playing no sound at all. 🙈
In a DISPLAY alarm, the intended alarm effect is for the text value of the DESCRIPTION property to be displayed to the user. 🌈
In an EMAIL alarm, the intended alarm effect is for an email message to be composed and delivered to all the addresses specified by the ATTENDEE properties in 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. 💌
Note: Implementations should carefully consider whether they accept alarm components from untrusted sources, e.g., when importing calendar objects from external sources. One reasonable policy is to always ignore alarm components that the calendar user has not set herself, or at least ask for confirmation in such a case. 🚨 This is a big deal, bestie, please don't skip it 😭
Example: The following example is for a VALARM calendar component that specifies an audio alarm that will sound at a precise time and repeat 4 more times at 15-minute intervals: 🔊
BEGIN:VALARM
TRIGGER;VALUE=DATE-TIME:19970317T133000Z
REPEAT:4
DURATION:PT15M
ACTION:AUDIO
ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/
sounds/bell-01.aud
END:VALARMThe following example is for a VALARM calendar component that specifies a display alarm that will trigger 30 minutes before the scheduled start of the event or of the to-do it is associated with and will repeat 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 for a VALARM calendar component that specifies an email alarm that will trigger 2 days before the scheduled due DATE-TIME of a to-do with which it is associated. It does not repeat. The email has a subject, body, and attachment link. 📨🦋
BEGIN:VALARM
TRIGGER;RELATED=END:-P2D
ACTION:EMAIL
ATTENDEE:mailto:john_doe@example.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/msword:http://example.com/
templates/agenda.doc
END:VALARM3.7. Calendar Properties 🧁
The Calendar Properties are attributes that apply to the iCalendar object, as a whole. These properties do not appear within a calendar component. They SHOULD be specified after the BEGIN:VCALENDAR delimiter string and prior to any calendar component. 📅✨
3.7.1. Calendar Scale 🌍
Property Name: CALSCALE
Purpose: This property defines the calendar scale used for the calendar information specified in the iCalendar object. 🗓️
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: This property can be specified once in an iCalendar object. The default value is "GREGORIAN". 💜
Description: This memo is based on the Gregorian calendar scale. The Gregorian calendar scale is assumed if this property is not specified in the iCalendar object. It is expected that other calendar scales will be defined in other specifications or by future versions of this memo. Iconic behaviour, honestly 👑
Format Definition: This property is defined by the following notation:
calscale = "CALSCALE" calparam ":" calvalue CRLF
calparam = *(";" other-param)
calvalue = "GREGORIAN"Example: The following is an example of this property:
CALSCALE:GREGORIAN3.7.2. Method 💅
Property Name: METHOD
Purpose: okay so this one tells you which iCalendar object method the calendar object is tied to 🦋
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be specified on this property ✨
Conformance: this property can be specified once in an iCalendar object.
Description: when it shows up in a MIME message entity, the value of this property MUST be the same as the Content-Type "method" parameter value. And if either the METHOD property or the Content-Type "method" parameter is specified, then the other MUST also be specified. bestie, they're a package deal 🫶
No methods are defined by this specification. That's handled by other specs, like the iCalendar Transport-independent Interoperability Protocol (iTIP) defined by [2446bis]. 🧚
If this property is not present in the iCalendar object, then a scheduling transaction MUST NOT be assumed. In that case the iCalendar object is just carrying a snapshot of some calendar info, without any intention of conveying a scheduling semantic. no scheduling vibes here, just vibes 🌸
Format Definition: this property is defined by the following notation:
method = "METHOD" metparam ":" metvalue CRLF
metparam = *(";" other-param)
metvalue = iana-tokenExample: the following is a hypothetical example of this property, conveying that the iCalendar object is a scheduling request 📨
METHOD:REQUEST3.7.3. Product Identifier 🎀
Property Name: PRODID
Purpose: this property specifies the identifier for the product that created the iCalendar object. it's the product's little ID card 🪪
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: the property MUST be specified once in an iCalendar object. no skipping this one, babe 👑
Description: the vendor of the implementation SHOULD assure that this is a globally unique identifier. a technique like an FPI value, as defined in [ISO.9070.1991], is the move here ✨
This property SHOULD NOT be used to alter the interpretation of an iCalendar object beyond the semantics specified in this memo. For example, it is not to be used to further the understanding of non-standard properties. it's not a sneaky side door, periodt 🙈
Format Definition: this property is defined by the following notation:
prodid = "PRODID" pidparam ":" pidvalue CRLF
pidparam = *(";" other-param)
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//EN3.7.4. Version 🦋
Property Name: VERSION
Purpose: this property specifies the identifier matching the highest version number, or the minimum and maximum range, of the iCalendar specification that's needed to interpret the iCalendar object. it's the "you need at least this version to read me" note 📜
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: this property MUST be specified once in an iCalendar object. literally non-negotiable 💀
Description: a value of "2.0" corresponds to this memo. ✨
Format Definition: this property is defined by the following notation:
version = "VERSION" verparam ":" vervalue CRLF
verparam = *(";" other-param)
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 object.Example: the following is an example of this property:
VERSION:2.03.8. Component Properties 🧚
the following properties can appear within calendar components, as specified by each component property definition. these are the extras that live inside the components themselves 💖
3.8.1. Descriptive Component Properties 🌸
the following properties specify descriptive information about calendar components. basically the captions on the calendar 📝
3.8.1.1. Attachment 📎
Property Name: ATTACH
Purpose: this property gives you a way to attach a document object to a calendar component. like a little PDF clip on your event 📄
Value Type: the default value type for this property is URI. The value type can also be set to BINARY to indicate inline binary encoded content information. 🔥
Property Parameters: IANA, non-standard, inline encoding, and value data type property parameters can be specified on this property. The format type parameter can be specified on this property, and it is RECOMMENDED for inline binary encoded content information.
Conformance: this property can be specified multiple times in a "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar component, with the exception of AUDIO alarm, which only allows this property to occur once. the AUDIO alarm is the one exception, no cap 🔔
Description: this property is used in "VEVENT", "VTODO", and "VJOURNAL" calendar components to associate a resource (e.g., a document) with the calendar component. In "VALARM" calendar components, it's used to specify an audio sound resource or an email message attachment. The property can be specified as a URI pointing to a resource, or as inline binary encoded content. so many options, iconic 🦋
When this property is specified as inline binary encoded content, calendar applications MAY attempt to guess the media type of the resource by inspecting its content, if and only if the media type of the resource is not given by the "FMTTYPE" parameter. If the media type is still unknown, calendar applications SHOULD treat it as type "application/octet-stream". guessing is allowed, but only when the FMTTYPE isn't there, and the fallback is the octet-stream vibe 🤷♀️
Format Definition: this property is defined by the following notation:
attach = "ATTACH" attachparam ( ":" uri ) /
(
";" "ENCODING" "=" "BASE64"
";" "VALUE" "=" "BINARY"
":" binary
)
CRLF
attachparam = *(
;
; The following is OPTIONAL for a URI value,
; RECOMMENDED for a BINARY value,
; and MUST NOT occur more than once.
;
(";" fmttypeparam) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)Example: the following are examples of this property:
ATTACH:CID:jsmith.part3.960817T083000.xyzMail@example.com
ATTACH;FMTTYPE=application/postscript:ftp://example.com/pub/
reports/r-960812.ps3.8.1.2. Categories 🏷️
Property Name: CATEGORIES
Purpose: this property defines the categories for a calendar component. think of it as hashtags for your events #️⃣
Value Type: TEXT
Property Parameters: IANA, 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 is used to specify categories or subtypes of the calendar component. The categories are useful for searching for a calendar component of a particular type and category, so you can find your stuff fast 🔍 Within the "VEVENT", "VTODO", or "VJOURNAL" calendar components, you can specify more than one category as a COMMA-separated list of categories. stack those tags, queen 👑
Format Definition: this 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.
;
(";" other-param)
;
)Example: the following are examples of this property:
CATEGORIES:APPOINTMENT,EDUCATION
CATEGORIES:MEETING3.8.1.3. Classification 🔒
Property Name: CLASS
Purpose: this property defines the access classification for a calendar component. it's how the owner signals who's allowed to see what 👀
Value Type: TEXT
Property Parameters: IANA and 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 inside a calendar application. It gives a way to capture the scope of access the calendar owner intends for the information in one calendar entry. Its usefulness depends on the other security pieces of a calendar system, like user authentication, authorization, access rights, access role, and so on, so the actual meaning of each classification can't be fully defined by this memo alone. 🧩 Also, because most exchange processes using this memo are pretty "blind," these classifications can't act as an enforcement statement for a system receiving an iCalendar object. They're more of a "here's what the owner intended" note than a bouncer at the door 🚪 If it's not specified in a component that allows this property, the default value is PUBLIC. Applications MUST treat x-name and iana-token values they don't recognize the same way they would treat the PRIVATE value. unknown values get the PRIVATE treatment, that's the rule 🫣
Format Definition: this property is defined by the following notation:
class = "CLASS" classparam ":" classvalue CRLF
classparam = *(";" other-param)
classvalue = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / iana-token
/ x-name
;Default is PUBLICExample: the following is an example of this property:
CLASS:PUBLIC3.8.1.4. Comment 💬
Property Name: COMMENT 🎀
Purpose: okay so this one is for non-processing info, basically a little note meant for the calendar user to read 👀 It doesn't change how anything gets handled.
Value Type: TEXT ✨
Property Parameters: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property 🌸
Conformance: this property can be specified multiple times in VEVENT, VTODO, VJOURNAL, and VFREEBUSY calendar components, and also in the STANDARD and DAYLIGHT sub-components 💅
Description: bestie, it's just how you leave a comment for the calendar user 🫶
Format Definition: this 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.
;
(";" other-param)
;
)Example: here's 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. - - John3.8.1.5. Description 📝
Property Name: DESCRIPTION 🌈
Purpose: this one gives a fuller description of the calendar component than the SUMMARY property does, so it's the lore dump 📚✨
Value Type: TEXT 💖
Property Parameters: IANA, 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: okay so in VEVENT and VTODO, this is where you put the lengthy textual descriptions tied to the activity 🫠
In VJOURNAL, it holds one or more textual journal entries. Main character diary energy 📖🌸
In VALARM, it does double duty: it captures the display text for a DISPLAY category of alarm, and the body text for an EMAIL category of alarm 🔔💌
Format Definition: this 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.
;
(";" other-param)
;
)Example: here's an example with formatted line breaks in the property value 🍓
DESCRIPTION:Meeting to provide technical review for "Phoenix"
design.\nHappy Face Conference Room. Phoenix design team
MUST attend this meeting.\nRSVP to team leader.3.8.1.6. Geographic Position 🌍
Property Name: GEO 🗺️
Purpose: this property holds the global position for the activity described by a calendar component. Location, but make it planetary 🪐✨
Value Type: FLOAT. The value MUST be two SEMICOLON-separated FLOAT values. This one is strict, no cap 🧐
Property Parameters: IANA and 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 then longitude, in that order (so it's "LAT LON" ordering) 🌸 Longitude is the location east or west of the prime meridian, as a positive or negative real number respectively. Latitude and longitude values MAY be specified up to six decimal places, which allows accuracy to within one meter of geographical position 📏✨ Receiving applications MUST accept values of this precision, and MAY truncate values of greater precision. Iconic behavior, honestly 💅
Values for latitude and longitude shall be expressed 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 number of degrees by a decimal point 🔢
Latitudes north of the equator shall be specified with a plus sign (+), or by the absence of a minus sign (-), in front of the digits for degrees. Latitudes south of the Equator shall be designated with a minus sign (-) in front of the digits for degrees. A point on the Equator shall be assigned to the Northern Hemisphere 🧭
Longitudes east of the prime meridian shall be specified with a plus sign (+), or by the absence of a minus sign (-), in front of the digits for degrees. Longitudes west of the meridian shall be designated with a minus sign (-) in front of the digits for degrees. A point on the prime meridian shall be assigned to the Eastern Hemisphere. A point on the 180th meridian shall be assigned to the Western Hemisphere. There's one exception to this last convention 👀 For the special condition of describing a band of latitude around the earth, the East Bounding Coordinate data element shall be assigned the value +180 (180) degrees 🌈
Any spatial address with a latitude of +90 (90) or -90 degrees will specify the position at the North or South Pole, respectively 🐧❄️ The component for longitude may have any legal value.
Apart from the special condition described above, this form is specified in [ANSI INCITS 61-1986] 📚
The simple formula for converting degrees-minutes-seconds into decimal degrees is:
decimal = degrees + minutes/60 + seconds/3600.Format Definition: this property is defined by the following notation:
geo = "GEO" geoparam ":" geovalue CRLF
geoparam = *(";" other-param)
geovalue = float ";" float
;Latitude and Longitude componentsExample: here's an example of this property 🦋
GEO:37.386013;-122.0829323.8.1.7. Location 📍
Property Name: LOCATION 🏠
Purpose: this defines the intended venue for the activity in a calendar component. Where we slay 💃
Value Type: TEXT ✨
Property Parameters: IANA, 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 specific venues like conference or meeting rooms right here 🚪 You can also add an alternate representation, which is a URI pointing to directory info with a more structured description of the location 🗺️ For example, the alternate representation could be an LDAP URL [RFC4516] pointing to an LDAP server entry, or a CID URL [RFC2392] pointing to a MIME body part with a Virtual-Information Card (vCard) [RFC2426] for the location. Very organized, very iconic 💼🫶
Format Definition: this 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.
;
(";" other-param)
;
)Example: here are some examples of this property 🧚
LOCATION:Conference Room - F123\, Bldg. 002
LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":
Conference Room - F123\, Bldg. 0023.8.1.8. Percent Complete ✅
Property Name: PERCENT-COMPLETE 📊
Purpose: an assignee or delegatee of a to-do uses this to tell the "Organizer" how far along the to-do is 🙌
Value Type: INTEGER 🔢
Property Parameters: IANA and non-standard property parameters can be specified on this property 💖
Conformance: this property can be specified once in a VTODO calendar component 🌸
Description: the value is a positive integer from 0 to 100 🍓 A value of "0" means the to-do hasn't started yet. A value of "100" means it's been completed. Anything in between shows partial progress 📈
When a to-do is assigned to multiple people, the value shows the percent complete for just that person's portion of it. 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", then "B" has finished 50% of their part 🫶✨
Format Definition: this property is defined by the following notation:
percent = "PERCENT-COMPLETE" pctparam ":" integer CRLF
pctparam = *(";" other-param)Example: here's an example showing 39% completion 🌈
PERCENT-COMPLETE:393.8.1.9. Priority ✨
okay bestie, let's talk priority 💅 this is how a calendar component gets ranked, from "drop everything" to "whenever, no rush" 🫶
Property Name: PRIORITY 🏷️
Purpose: this property defines the relative priority for a calendar component 🎯
Value Type: INTEGER 🔢
Property Parameters: IANA and non-standard property parameters can be specified on this property 🎀
Conformance: this property can be specified in VEVENT and VTODO calendar components 🍓
Description: so the priority is an integer from 0 to 9 🧚 0 means undefined, so basically no priority at all 💀 1 is the highest, 2 is the second highest, and then it keeps going down in ordinal priority until 9, which is the lowest. literally the bottom of the pile 🫠
Now for the mapping stuff, because a CUA with its own scheme still needs to fit in 🧩
- A CUA using a three-level scheme of "HIGH", "MEDIUM", and "LOW" gets mapped so that a value from 1 to 4 means "HIGH" priority. A value of 5 is the normal or "MEDIUM" priority, and a value from 6 to 9 means "LOW" priority. 🔥
- A CUA using a priority schema of "A1", "A2", "A3", "B1", "B2", ..., "C3" gets mapped so that 1 means "A1", 2 means "A2", 3 means "A3", and so on, all the way up to 9 meaning "C3" 🌈
Other integer values are reserved for future use, so don't go poking at them yet 🙈
Within a "VEVENT" calendar component, this property specifies a priority for the event. it's super useful when more than one event is scheduled for a given time period 📅✨
Within a "VTODO" calendar component, this property specified a priority for the to-do. it helps you prioritize multiple action items for a given time period 🦋
Format Definition: here's the notation, bestie 📝
priority = "PRIORITY" prioparam ":" priovalue CRLF
;Default is zero (i.e., undefined).
prioparam = *(";" other-param)
priovalue = integer ;Must be in the range [0..9]
; All other values are reserved for future use.Example: here's a property with the highest priority 👑
PRIORITY:1and here's one with the next highest priority 🥈
PRIORITY:2and here's one with no priority. this is equivalent to not specifying the "PRIORITY" property at all 🫥
PRIORITY:03.8.1.10. Resources 🪑
Property Name: RESOURCES 🏷️
Purpose: this property defines the equipment or resources expected for an activity specified by a calendar component 📽️
Value Type: TEXT 💬
Property Parameters: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property 🎀
Conformance: this property can be specified once in "VEVENT" or "VTODO" calendar components 🍓
Description: the property value is arbitrary text 🌷 you can list more than one resource by separating them with COMMA-separated values, so think easel, projector, and VCR all in one line 📚
Format Definition: here's the 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.
;
(";" other-param)
;
)Example: here's the property in action 🎨
RESOURCES:EASEL,PROJECTOR,VCR
RESOURCES;LANGUAGE=fr:Nettoyeur haute pression3.8.1.11. Status 🚦
Property Name: STATUS 🏷️
Purpose: this property defines the overall status or confirmation for the calendar component 💖
Value Type: TEXT 💬
Property Parameters: IANA and non-standard property parameters can be specified on this property 🎀
Conformance: this property can be specified once 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 a meeting is tentative, confirmed, or cancelled 📅 in a "VTODO", the Organizer can say an action item needs action, is completed, is in process or being worked on, or has been cancelled ✅ and in a "VJOURNAL", the Organizer can say a journal entry is draft, final, or has been cancelled or removed 📓
Format Definition: here's the notation 📝
status = "STATUS" statparam ":" statvalue CRLF
statparam = *(";" other-param)
statvalue = (statvalue-event
/ statvalue-todo
/ statvalue-jour)
statvalue-event = "TENTATIVE" ;Indicates event is tentative.
/ "CONFIRMED" ;Indicates event is definite.
/ "CANCELLED" ;Indicates event was cancelled.
;Status values for a "VEVENT"
statvalue-todo = "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-jour = "DRAFT" ;Indicates journal is draft.
/ "FINAL" ;Indicates journal is final.
/ "CANCELLED" ;Indicates journal is removed.
;Status values for "VJOURNAL".Example: here's what it looks like for each component 🎀
For a "VEVENT" calendar component:
STATUS:TENTATIVEFor a "VTODO" calendar component:
STATUS:NEEDS-ACTIONFor a "VJOURNAL" calendar component:
STATUS:DRAFT3.8.1.12. Summary 📝
Property Name: SUMMARY 🏷️
Purpose: this property defines a short summary or subject for the calendar component 💜
Value Type: TEXT 💬
Property Parameters: IANA, 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: this property is used in "VEVENT", "VTODO", and "VJOURNAL" components to capture a short, one-line summary of the activity or journal entry ✨
In a "VALARM" calendar component, this property captures the subject of an EMAIL category of alarm 📧
Format Definition: here's the 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.
;
(";" other-param)
;
)Example: here's the property 🌸
SUMMARY:Department Party3.8.2. Date and Time Component Properties ⏰
The following properties specify date and time related information in calendar components 🕰️
3.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: IANA and non-standard property parameters can be specified on this property 🎀
Conformance: the property can be specified in a "VTODO" calendar component 🍓 the value MUST be specified as a date with UTC time 🌍
Description: this property defines the date and time that a to-do was actually completed 💅
Format Definition: here's the notation 📝
completed = "COMPLETED" compparam ":" date-time CRLF
compparam = *(";" other-param)Example: here's the property 🧁
COMPLETED:19960401T150000Z3.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. the value type can be set to a DATE value type 🔁
Property Parameters: IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property 🎀
Conformance: this property can be specified in "VEVENT" or "VFREEBUSY" calendar components 🍓
Description: in the "VEVENT" calendar component, this property defines the date and time the event ends 🎬 the value type of this property MUST be the same as the "DTSTART" property, and its value MUST be later in time than the value of the "DTSTART" property 🕓 furthermore, this property MUST be specified as a date with local time if and only if the "DTSTART" property is also specified as a date with local time 🌙
In the "VFREEBUSY" calendar 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 🌍 and the value MUST be later in time than the value of the "DTSTART" property ⏩
Format Definition: here's the 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.
;
(";" other-param)
;
)
dtendval = date-time / date
;Value MUST match value typeExample: here are two versions 🦋
DTEND:19960401T150000Z
DTEND;VALUE=DATE:199807043.8.2.3. Date-Time Due 📅
Property Name: DUE 💖
Purpose: okay so this one defines the date and time that a to-do is expected to be completed. It's the deadline, bestie 💅
Value Type: the default value type is DATE-TIME ✨. You can also set it to a DATE value type 🌸
Property Parameters: IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property 🎀
Conformance: this can be specified once in a VTODO calendar component 🫶
Description: this defines the date and time before which a to-do is expected to be completed 👑. If the VTODO also specifies a DTSTART property, then the value type of DUE MUST be the same as the DTSTART value type, and the DUE value MUST be later in time than the DTSTART value 😭. Also, DUE MUST be specified as a date with local time if and only if DTSTART is also specified as a date with local time 🙈
Format Definition: this 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.
;
(";" other-param)
;
)
dueval = date-time / date
;Value MUST match value typeExample: here's what it looks like 🍓
DUE:19980430T000000Z3.8.2.4. Date-Time Start 🚀
Property Name: DTSTART 💜
Purpose: this one 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 💅. You can set the value type to a DATE value type too ✨
Property Parameters: IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property 🎀
Conformance: this can be specified once in the VEVENT, VTODO, or VFREEBUSY calendar components, and also in the STANDARD and DAYLIGHT sub-components 🌸. This property is REQUIRED in all types of recurring calendar components that specify the RRULE property 🔁. It's also REQUIRED in VEVENT calendar components contained in iCalendar objects that don't specify the METHOD property 👑
Description: inside a VEVENT, this defines the start date and time for the event 🎉
Inside a VFREEBUSY, this defines the start date and time for the free or busy time information. The time MUST be specified in UTC time 🌍
Inside the STANDARD and DAYLIGHT sub-components, this defines the effective start date and time for a time zone specification 🕰️. This property is REQUIRED within each STANDARD and DAYLIGHT sub-component included in VTIMEZONE calendar components, and it MUST be specified as a date with local time without the TZID property parameter 😭
Format Definition: this 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.
;
(";" other-param)
;
)
dtstval = date-time / date
;Value MUST match value typeExample: here's an example 🍓
DTSTART:19980118T073000Z3.8.2.5. Duration ⏳
Property Name: DURATION 🫧
Purpose: this property specifies a positive duration of time 💖
Value Type: DURATION 🌷
Property Parameters: IANA and non-standard property parameters can be specified on this property 🎀
Conformance: this can be specified in VEVENT, VTODO, or VALARM calendar components 🔔
Description: in a VEVENT, you can use this instead of an explicit end DATE-TIME to give the event's length ⏱️. In a VTODO, you can use it to give the to-do's duration instead of an explicit due DATE-TIME 📝. In a VALARM, it sets the delay period before an alarm repeats 🔁. When DURATION relates to a DTSTART that's specified as a DATE value, then DURATION MUST be specified as a dur-day or dur-week value 📅
Format Definition: this property is defined by the following notation 🧚
duration = "DURATION" durparam ":" dur-value CRLF
;consisting of a positive duration of time.
durparam = *(";" other-param)Example: this one specifies an interval of one hour, zero minutes, and zero seconds 🕐
DURATION:PT1H0M0SAnd this one specifies an interval of 15 minutes 🌟
DURATION:PT15M3.8.2.6. Free/Busy Time 🟢🔴
Property Name: FREEBUSY 💫
Purpose: this defines one or more free or busy time intervals 🦋
Value Type: PERIOD 🌸
Property Parameters: IANA, non-standard, and free/busy time type property parameters can be specified on this property 🎀
Conformance: this can be specified in a VFREEBUSY calendar component 💅
Description: these time periods can be written 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 🌍
FREEBUSY properties within the VFREEBUSY calendar component SHOULD be sorted in ascending order, based on start time and then end time, with the earliest periods first 🥇
The FREEBUSY property can have more than one value, separated by the COMMA character. In that case, the FREEBUSY property values MUST all be of the same FBTYPE property parameter type (for example, all values of a particular FBTYPE listed together in a single property) 👯
Format Definition: this 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.
;
(";" other-param)
;
)
fbvalue = period *("," period)
;Time value MUST be in the UTC time format.Example: here are some examples 🍓
FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:19970308T160000Z/PT8H30M FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H
,19970308T230000Z/19970309T000000Z3.8.2.7. Time Transparency 🪟
Property Name: TRANSP 🫧
Purpose: this defines whether or not an event is transparent to busy time searches 👀
Value Type: TEXT 💖
Property Parameters: IANA and non-standard property parameters can be specified on this property 🎀
Conformance: this can be specified once in a VEVENT calendar component ✨
Description: time transparency is basically whether an event looks like it eats up time on a calendar 🕵️♀️. Events that really take up the individual's or resource's time SHOULD be recorded as OPAQUE, so they show up in free/busy time searches 🧱. Other events, which don't take up the individual's (or resource's) time, SHOULD be recorded as TRANSPARENT, so they're invisible to free/busy time searches 🫥
Format Definition: this property is defined by the following notation 🧚
transp = "TRANSP" transparam ":" transvalue CRLF
transparam = *(";" other-param)
transvalue = "OPAQUE"
;Blocks or opaque on busy time searches.
/ "TRANSPARENT"
;Transparent on busy time searches.
;Default value is OPAQUEExample: for an event that's transparent (doesn't block free/busy time searches) 🦋
TRANSP:TRANSPARENTAnd for an event that's opaque (blocks free/busy time searches) 🧱
TRANSP:OPAQUE3.8.3. Time Zone Component Properties 🌍
The following properties specify time zone information in calendar components 🗺️
3.8.3.1. Time Zone Identifier 🕰️
Property Name: TZID 🧭
Purpose: this specifies the text value that uniquely identifies the VTIMEZONE calendar component within the scope of an iCalendar object 🆔
Value Type: TEXT 💜
Property Parameters: IANA and 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 a time zone calendar component gets referenced by, from any iCalendar properties whose value type is DATE-TIME or TIME and that aren't meant to be UTC or "floating" times 🏷️. If there's a SOLIDUS character as a prefix, that means this TZID is a unique ID in a globally defined time zone registry (when such a registry is defined) 🌐
Note: this document doesn't define a naming convention for time zone identifiers 🙈. Implementers may want to use the naming conventions from existing time zone specifications, like the public-domain TZ database [TZDB] 📚. Globally unique time zone identifiers aren't addressed by this document and are left for future study 🔮
Format Definition: this property is defined by the following notation 🧚
tzid = "TZID" tzidpropparam ":" [tzidprefix] text CRLF
tzidpropparam = *(";" other-param)
;tzidprefix = "/"
; Defined previously. Just listed here for reader convenience.Example: these are examples of non-globally unique time zone identifiers 🗽
TZID:America/New_York TZID:America/Los_AngelesAnd this is a fictitious globally unique time zone identifier 🌈
TZID:/example.org/America/New_York3.8.3.2. Time Zone Name 🌸
Property Name: TZNAME
Purpose: Okay so this one gives a zone its everyday nickname 💅, the customary designation for a time zone description.
Value Type: TEXT
Property Parameters: IANA, non-standard, and language property parameters can be specified on this one 🎀.
Conformance: You can slap this on "STANDARD" and "DAYLIGHT" sub-components ✨.
Description: It's a customary name you can show when you're displaying dates that land during the observance the time zone sub-component defines. Basically, the name people actually use for that stretch of time 🦋.
Format Definition: Here's the notation, bestie 🧚:
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.
;
(";" other-param)
;
)Example: Here are some examples of this property 💖:
TZNAME:EST
TZNAME;LANGUAGE=fr-CA:HNE3.8.3.3. Time Zone Offset From 🌈
Property Name: TZOFFSETFROM
Purpose: This property says what offset was in use right before this time zone observance kicked in 🕰️.
Value Type: UTC-OFFSET
Property Parameters: IANA and non-standard property parameters can be specified here.
Conformance: This property MUST be specified in "STANDARD" and "DAYLIGHT" sub-components. No skipping, periodt 💅.
Description: This is the offset that was in use before this time observance. It's what gets used to work out the absolute time when the switch 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 showing how many hours, and maybe minutes, away from UTC you are. Positive numbers are zones east of the prime meridian, so they're ahead of UTC 🌅. Negative numbers are zones west of the prime meridian, so they're behind UTC 🌙.
Format Definition: Here's how it's written:
tzoffsetfrom = "TZOFFSETFROM" frmparam ":" utc-offset
CRLF
frmparam = *(";" other-param)Example: Here are some examples 🍓:
TZOFFSETFROM:-0500
TZOFFSETFROM:+13453.8.3.4. Time Zone Offset To 🦋
Property Name: TZOFFSETTO
Purpose: This one says what offset is in use during this time zone observance ✨.
Value Type: UTC-OFFSET
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: This property MUST be specified in "STANDARD" and "DAYLIGHT" sub-components. Non-negotiable, bestie 👑.
Description: This is the offset in use during this time zone observance, and it's what you use to figure out the absolute time for the new observance 🧮. The value is a signed numeric showing the number of hours, and possibly minutes, from UTC. Positive numbers are zones east of the prime meridian, so ahead of UTC 🌞. Negative numbers are zones west of the prime meridian, so behind UTC 🌛.
Format Definition: Here's the notation 💜:
tzoffsetto = "TZOFFSETTO" toparam ":" utc-offset CRLF
toparam = *(";" other-param)Example: Here are some examples 🌸:
TZOFFSETTO:-0400
TZOFFSETTO:+12453.8.3.5. Time Zone URL 🔥
Property Name: TZURL
Purpose: This property gives a "VTIMEZONE" component a link to a network location where it can grab an up-to-date copy of itself 🌐. Lowkey iconic.
Value Type: URI
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: You can specify this property in a "VTIMEZONE" calendar component ✨.
Description: Same idea as the purpose: a "VTIMEZONE" component can point to a network location where you can fetch a fresh version of itself. It's basically a hook for dealing with changes that government bodies make to time zone definitions, which happen more than you'd think 🙈. Retrieving that resource gives you an iCalendar object with one "VTIMEZONE" component and a METHOD property set to PUBLISH 🎀.
Format Definition: Here's the notation 🧚:
tzurl = "TZURL" tzurlparam ":" uri CRLF
tzurlparam = *(";" other-param)Example: Here's one example 💖:
TZURL:http://timezones.example.org/tz/America-Los_Angeles.ics3.8.4. Relationship Component Properties 💜
The following properties spell out relationship information in calendar components. This is where we get into who's connected to what 🫶.
3.8.4.1. Attendee 🎀
Property Name: ATTENDEE
Purpose: This property defines an "Attendee" within a calendar component 🙋♀️.
Value Type: CAL-ADDRESS
Property Parameters: IANA, 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 be specified on this property. That's a lot of parameters, so buckle up 😭.
Conformance: 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 publishing the calendar information. So, for example, that's not an iCalendar object that publishes a calendar user's busy time, event, to-do, or journal 🙅♀️. This property is not specified in an iCalendar object that only has a time zone definition, or that defines calendar components that aren't group-scheduled components but only live on a single user's calendar 💀.
Description: This property MUST only be specified within calendar components, and it's used to name participants, non-participants, and the chair of a group-scheduled calendar entity 🌈. It's also specified within an "EMAIL" category of the "VALARM" calendar component, to give an email address that should get the email type of iCalendar alarm 📧.
Here's the parameter rundown 🍓. 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 shows the status of the attendee's participation. RSVP tells you whether a reply is wanted. CUTYPE says what type of calendar user this is. MEMBER lists the groups the attendee belongs to. DELEGATED-TO lists the calendar users the original request got delegated to, and DELEGATED-FROM lists who it got delegated from. SENT-BY says who is acting on behalf of the "ATTENDEE". And DIR is the URI pointing to the directory info for the attendee 🗂️. These can be used on an "ATTENDEE" property in either a "VEVENT", "VTODO", or "VJOURNAL" calendar component ✨. They MUST NOT be specified in an "ATTENDEE" property in a "VFREEBUSY" or "VALARM" calendar component 🚫. If you use the LANGUAGE property parameter, the language you name applies to the CN parameter 🌍.
A recipient who has been delegated a request MUST inherit the RSVP and ROLE values from the attendee who delegated it to them 🫶. And you can have multiple attendees, just by including multiple "ATTENDEE" properties in the calendar component 👯.
Format Definition: Here's the notation 💅:
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.
;
(";" other-param)
;
)Example: Here are some examples of this property's use for a to-do 📝:
ATTENDEE;MEMBER="mailto:DEV-GROUP@example.com":
mailto:joecool@example.com
ATTENDEE;DELEGATED-FROM="mailto:immud@example.com":
mailto:ildoit@example.comHere's this property used for specifying multiple attendees to an event 👑:
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;CN=Henry
Cabot:mailto:hcabot@example.com
ATTENDEE;ROLE=REQ-PARTICIPANT;DELEGATED-FROM="mailto:bob@
example.com";PARTSTAT=ACCEPTED;CN=Jane Doe:mailto:jdoe@
example.comAnd here's the property with a URI to the directory info for the attendee 🧚:
ATTENDEE;CN=John Smith;DIR="ldap://example.com:6666/o=ABC%
20Industries,c=US???(cn=Jim%20Dolittle)":mailto:jimdo@
example.comHere's the property with "delegatee" and "delegator" info for an event 🌈:
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;DELEGATED-FROM=
"mailto:iamboss@example.com";CN=Henry Cabot:mailto:hcabot@
example.com
ATTENDEE;ROLE=NON-PARTICIPANT;PARTSTAT=DELEGATED;DELEGATED-TO=
"mailto:hcabot@example.com";CN=The Big Cheese:mailto:iamboss
@example.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Jane Doe
:mailto:jdoe@example.comExample: And finally, here's the property's use when another calendar user is acting on behalf of the "Attendee" 🫶:
ATTENDEE;SENT-BY=mailto:jan_doe@example.com;CN=John Smith:
mailto:jsmith@example.com3.8.4.2. Contact 📇
Property Name: CONTACT
Purpose: okay so this one is for contact info tied to the calendar component 💖 It can be the actual textual info, or a reference that points you to the info somewhere else ✨
Value Type: TEXT
Property Parameters: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property 🎀
Conformance: this can be specified in a VEVENT, VTODO, VJOURNAL, or VFREEBUSY calendar component 🦋
Description: the property value is textual contact info, like a name, a company, and a phone number 📞 There can also be an alternative representation, which is a URI pointing to an alternate form of the contact info, such as a vCard [RFC2426] 🌸
Format Definition: this property is defined by the following notation:
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.
;
(";" other-param)
;
)Example: here's an example referencing plain textual contact info 💅
CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234Here's an example with an alternate representation of an LDAP URI pointing to a directory entry with the contact info 🧚
CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234And here's one with an alternate representation of a MIME body part holding the contact info, like a vCard [RFC2426] embedded in a text/directory media type [RFC2425] 💜
CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com":
Jim Dolittle\, ABC Industries\, +1-919-555-1234Last one! This example references a network resource, like a vCard [RFC2426] object with the contact info 🌈
CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim
Dolittle\, ABC Industries\, +1-919-555-12343.8.4.3. Organizer 👑
Property Name: ORGANIZER
Purpose: this one defines the organizer for a calendar component 🎀
Value Type: CAL-ADDRESS
Property Parameters: IANA, non-standard, language, common name, directory entry reference, and sent-by property parameters can be specified on this property 💖
Conformance: this 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 📅 And it MUST NOT be specified in an iCalendar object that specifies only a time zone definition, or that defines calendar components that aren't group-scheduled but are only on a single user's calendar 🙈
Description: this is specified within the VEVENT, VTODO, and VJOURNAL calendar components to say who the organizer of a group-scheduled calendar entity is ✨ In a VFREEBUSY component, it's used to specify the calendar user who is requesting the free or busy time 🦋 When publishing a VFREEBUSY calendar component, it's used to specify the calendar the published busy time came from 🌸
The property has the parameters CN, which gives the common or display name associated with the "Organizer", DIR, which points to the directory information associated with the "Organizer", and SENT-BY, which names another calendar user acting on behalf of the "Organizer" 🧚 Non-standard parameters may also be specified on this property 💅 If the LANGUAGE property parameter is specified, the identified language applies to the CN parameter value 🌈
Format Definition: this property is defined by the following notation:
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.
;
(";" other-param)
;
)Example: here's a basic example of this property 💜
ORGANIZER;CN=John Smith:mailto:jsmith@example.comHere's one with a pointer to the directory info for the organizer 🍓
ORGANIZER;CN=JohnSmith;DIR="ldap://example.com:6666/o=DC%20Ass
ociates,c=US???(cn=John%20Smith)":mailto:jsmith@example.comAnd last but not least, this one is used by another calendar user who is 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@example.com":
mailto:jsmith@example.com3.8.4.4. Recurrence ID 🔁
Property Name: RECURRENCE-ID
Purpose: this is used together with the UID and SEQUENCE properties to identify one specific instance of a recurring VEVENT, VTODO, or VJOURNAL calendar component 💖 The property value is the original value of the DTSTART property of that recurrence instance ✨
Value Type: the default value type is DATE-TIME 🎀 The value type can be set to a DATE value type 🦋 This property MUST have the same value type as the DTSTART property contained within the recurring component 👑 Furthermore, this property MUST be specified as a date with local time if and only if the DTSTART property contained within the recurring component is specified as a date with local time 🌸
Property Parameters: IANA, non-standard, value data type, time zone identifier, and recurrence identifier range parameters can be specified on this property 🧚
Conformance: this can be specified in an iCalendar object containing a recurring calendar component 💅
Description: the full range of calendar components in a recurrence set is referenced by just the UID property value that goes with the component 🌈 The RECURRENCE-ID property lets you point at an individual instance within that recurrence set 💜
If the value of the DTSTART property is a DATE type value, then the value MUST be the calendar date for the recurrence instance 📅
The DATE-TIME value is set to the time when the original recurrence instance would occur 🍓 So if you want to change a Friday meeting to Thursday, the DATE-TIME is still set to the original Friday meeting 🙈
The RECURRENCE-ID property is used together with the UID and SEQUENCE properties to identify a particular instance of a recurring event, to-do, or journal 🫶 For a given pair of UID and SEQUENCE property values, the RECURRENCE-ID value for a recurrence instance is fixed 🔒
The RANGE parameter is used to specify the effective range of recurrence instances starting from the instance named by the RECURRENCE-ID property value ✨ The only value the range parameter can take is THISANDFUTURE, which means the range covers the given recurrence instance and all subsequent instances 🦋 Subsequent instances are determined by their RECURRENCE-ID value, not their current scheduled start time 🌸 Subsequent instances defined in separate components are not impacted by the given recurrence instance 🧚 When the given recurrence instance is rescheduled, all subsequent instances are also rescheduled by the same time difference 💅 For instance, if the given recurrence instance is rescheduled to start 2 hours later, then all subsequent instances are also rescheduled 2 hours later 🌈
Similarly, if the duration of the given recurrence instance is modified, then all subsequent instances are also modified to have this same duration 💜
Note: TheRANGEparameter may not be appropriate to reschedule specific subsequent instances of complex recurring calendar components 💀 Assuming an unbounded recurring calendar component scheduled to occur on Mondays and Wednesdays, theRANGEparameter could not be used to reschedule only the future Monday instances to occur on Tuesday instead 🙈 In such cases, the calendar application could simply truncate the unbounded recurring calendar component (i.e., with theCOUNTorUNTILrule parts), and create two new unbounded recurring calendar components for the future instances 🫶
Format Definition: this 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.
;
(";" other-param)
;
)
ridval = date-time / date
;Value MUST match value typeExample: here are examples of this property 🎀
RECURRENCE-ID;VALUE=DATE:19960401
RECURRENCE-ID;RANGE=THISANDFUTURE:19960120T120000Z3.8.4.5. Related To ✨
Property Name: RELATED-TO 🔗
Purpose: Okay so this one is how you point at another calendar component and say "this thing is connected to THAT thing" 💖 It's basically a relationship link, and it's giving main character energy 💅
Value Type: TEXT
Property Parameters: IANA, non-standard, and relationship type property parameters can be specified on this property 🎀
Conformance: This property can be specified in the VEVENT, VTODO, and VJOURNAL calendar components 🌸
Description: The value is the persistent, globally unique identifier of another calendar component 🆔 In that component, this same value shows up as the UID property, so they match up like puzzle pieces 🧩
By default, the value points to a component that has a PARENT relationship to the one doing the referencing. The RELTYPE parameter lets you either spell out that default PARENT relationship or override it and go with CHILD or SIBLING instead 👑 PARENT means the component is a subordinate of the referenced one. CHILD means it's a superior of the referenced one. SIBLING means it's a peer of the referenced one. Choose your fighter, bestie 🫶
Changes to a referenced component can have an implicit impact on the related one 😭 Like, if a group event changes its start or end date or time, the dependent events need their dates changed in a matching way. And if a PARENT component gets cancelled or deleted, there's an implied impact on its related CHILD components 💀 This property is only there to share info about the relationship, though. It's up to the target calendar system to maintain any property implications of that relationship 🦋
Format Definition: This 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.
;
(";" other-param)
;
)Example: The following is an example of this property 🧚
RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com
RELATED-TO:19960401-080045-4000F192713-0052@example.com3.8.4.6. Uniform Resource Locator 🌈
Property Name: URL
Purpose: This property defines a Uniform Resource Locator (URL) associated with the iCalendar object 🔗 It's the link to the calendar stuff, basically 💜
Value Type: URI
Property Parameters: IANA and non-standard property parameters can be specified on this property 🍓
Conformance: This property can be specified once in the VEVENT, VTODO, VJOURNAL, or VFREEBUSY calendar components ✨
Description: This property may be used in a calendar component to point to a location 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, and it doesn't standardize the format of the resource the property value points to, so that part's totally open 🌸 One important rule though: if both the URL property and the Content-Location MIME header are specified, they MUST point to the same resource 🚨
Format Definition: This property is defined by the following notation:
url = "URL" urlparam ":" uri CRLF
urlparam = *(";" other-param)Example: The following is an example of this property 🎀
URL:http://example.com/pub/calendars/jsmith/mytime.ics3.8.4.7. Unique Identifier 🆔
Property Name: UID
Purpose: This property defines the persistent, globally unique identifier for the calendar component 👑 It's the component's forever name, iykyk 💖
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be specified on this property 🌸
Conformance: The property MUST be specified in the VEVENT, VTODO, VJOURNAL, or VFREEBUSY calendar components 🚨
Description: The UID itself MUST be a globally unique identifier 😤 And the generator of the identifier MUST guarantee that it's unique. There are several algorithms that can do this, and honestly it's a whole vibe 🧠
A good method 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 an "@" 🌐 On the left-hand side, you put a mix of the current calendar date and time of day (formatted as a DATE-TIME value) plus some other currently unique, maybe sequential, identifier from the system, like a process id number 🔢 Using a DATE-TIME 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 of the host itself or otherwise, so 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 referenced VEVENT, VTODO, or VJOURNAL calendar component 💌 The full range of calendar components in a recurrence set gets referenced by just the UID property value for that component, and the RECURRENCE-ID property lets you point at one individual instance inside that recurrence set 🔁
This property is a big deal for group-scheduling apps, because 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 🤝 This identifier gets created by the calendar system that generates the iCalendar object 💅
Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence. Do not chop those UTF-8 characters in half, bestie 💀
Format Definition: This property is defined by the following notation:
uid = "UID" uidparam ":" text CRLF
uidparam = *(";" other-param)Example: The following is an example of this property 🦋
UID:19960401T080045Z-4000F192713-0052@example.com3.8.5. Recurrence Component Properties 🔁
The following properties specify recurrence information in calendar components ✨
3.8.5.1. Exception Date-Times 🚫
Property Name: EXDATE
Purpose: This property defines the list of DATE-TIME exceptions for recurring events, to-dos, journal entries, or time zone definitions 🗓️ It's the "nope, not that day" list 💅
Value Type: The default value type for this property is DATE-TIME. The value type can be set to DATE 🎀
Property Parameters: IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property 🌈
Conformance: This property can be specified in recurring VEVENT, VTODO, and VJOURNAL calendar components, as well as in the STANDARD and DAYLIGHT sub-components of the VTIMEZONE calendar component 🧚
Description: The exception dates, if specified, are used in computing the recurrence set 🧮 The recurrence set is the complete set of recurrence instances for a calendar component. It's generated by looking at the initial DTSTART property along with the RRULE, RDATE, and EXDATE properties inside the recurring component 🔄 The DTSTART property defines the first instance in the recurrence set 🥇
The DTSTART property value SHOULD match the pattern of the recurrence rule, if one is specified 🎯 If a DTSTART value doesn't match the rule's pattern, the recurrence set generated from it is undefined 🤷♀️ The final recurrence set comes from gathering all the start DATE-TIME values generated by any of the specified RRULE and RDATE properties, and then excluding any start DATE-TIME values specified by EXDATE properties ✂️ That means EXDATE values take precedence over the inclusion properties (RDATE and RRULE) 👑 When duplicate instances get generated by RRULE and RDATE, only one recurrence is considered, and the duplicates are ignored 🙈
The EXDATE property can be used to exclude the value specified in DTSTART 🙅♀️ But even then, the original DTSTART date MUST still be maintained by the calendaring and scheduling system 🫶 Why? Because that original DTSTART value has inherent usage dependencies on other properties, like RECURRENCE-ID 🔗
Format Definition: This 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.
;
(";" other-param)
;
)
exdtval = date-time / date
;Value MUST match value typeExample: The following is an example of this property 🌸
EXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z3.8.5.2. Recurrence Date-Times ✨
okay bestie, RDATE is giving "here are some extra dates, please also show up on these" 🎀
Property Name: RDATE
Purpose: This property lists the DATE-TIME values for recurring events, to-dos, journal entries, or time zone definitions. 💖
Value Type: The default is DATE-TIME, but you can switch it to DATE or PERIOD. 🦋
Property Parameters: IANA, non-standard, value data type, and time zone identifier property parameters can all go on this one 🧚
Conformance: You can put this in recurring VEVENT, VTODO, and VJOURNAL components, and also in the STANDARD and DAYLIGHT sub-components of VTIMEZONE 🌸
Description: RDATE can hang out with an RRULE to make one big combined set of repeats 🔥 When both show up in a recurring component, the instances are the union of what each one makes. Iconic teamwork.
The recurrence dates, if you include them, get used when building the recurrence set. The recurrence set is the full list of instances for a calendar component. To build it, you start with the DTSTART property, then look at the RRULE, RDATE, and EXDATE properties inside that component. DTSTART is the first instance in the set. The DTSTART value SHOULD match the pattern of the recurrence rule, if there is one. If DTSTART doesn't match the rule's pattern, the recurrence set is undefined, so please don't do that 🙈
Then you gather every start DATE-TIME from all the RRULE and RDATE properties, and remove any start DATE-TIME values listed in EXDATE properties. That means EXDATE wins over the inclusion properties (RDATE and RRULE) 👑 If RRULE and RDATE make the same instance twice, it only counts once. Duplicates get ignored, no drama 💅
Format Definition: This property is written in 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.
;
(";" other-param)
;
)
rdtval = date-time / date / period
;Value MUST match value typeExample: Here are some examples of this property 🍓
RDATE:19970714T123000Z
RDATE;TZID=America/New_York:19970714T083000
RDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z,
19960404T010000Z/PT3H
RDATE;VALUE=DATE:19970101,19970120,19970217,19970421
19970526,19970704,19970901,19971014,19971128,19971129,199712253.8.5.3. Recurrence Rule ✨
this one is the repeat-pattern queen 👑 RRULE is basically "here's how this thing keeps happening" 🌈
Property Name: RRULE
Purpose: This property defines a rule or repeating pattern for recurring events, to-dos, journal entries, or time zone definitions. 🎀
Value Type: RECUR 💜
Property Parameters: IANA and non-standard property parameters can go on this property 🧚
Conformance: You can use this in recurring VEVENT, VTODO, and VJOURNAL components, and also in the STANDARD and DAYLIGHT sub-components of VTIMEZONE. It SHOULD NOT be specified more than once. Using multiple RRULE properties gives an undefined recurrence set, so, not it 🙈
Description: The recurrence rule, if you have one, gets used to build the recurrence set. Same as before: the set is the complete list of instances for a calendar component, built from DTSTART plus the RRULE, RDATE, and EXDATE properties inside that component. DTSTART is the first instance. The DTSTART value SHOULD be synchronized with the recurrence rule, if there is one. A recurrence set made with a DTSTART that isn't synchronized with the rule is undefined 💀 The final set is made by gathering all the start DATE-TIME values from the RRULE and RDATE properties, then dropping any start DATE-TIME values listed in EXDATE properties. EXDATE takes precedence over the inclusion properties (RDATE and RRULE). Duplicates from RRULE and RDATE only count once and get ignored after that ✨
The DTSTART property in the iCalendar object defines the first instance of the recurrence. In most cases, a DTSTART of DATE-TIME value type used with a recurrence rule should be specified as a date with local time and time zone reference, so that every instance starts at the same local time even when time zones change 🌸
If the duration of the recurring component is given with the DTEND or DUE property, then that exact same duration applies to every member of the recurrence set 🦋 If the duration is given with the DURATION property instead, then the same nominal duration applies to every member, but the exact duration of each instance depends on its start time. For example, instances with a nominal duration of one day will have an exact duration of more or less than 24 hours on a day when a time zone shift happens 🙃 You can change the duration of one specific recurrence in an exception component, or just by using an RDATE property with the PERIOD value type.
Format Definition: This property is written in the following notation:
rrule = "RRULE" rrulparam ":" recur CRLF
rrulparam = *(";" other-param)Example: All of these examples assume the Eastern United States time zone 🗽
Daily for 10 occurrences:
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
==> (1997 9:00 AM EDT) September 2-11Daily until December 24, 1997:
DTSTART;TZID=America/New_York: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=America/New_York:19970902T090000
RRULE:FREQ=DAILY;INTERVAL=2
==> (1997 9:00 AM EDT) September 2,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;
December 1,3,...Every 10 days, 5 occurrences:
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
==> (1997 9:00 AM EDT) September 2,12,22;
October 2,12Every day in January, for 3 years:
DTSTART;TZID=America/New_York:19980101T090000
RRULE:FREQ=YEARLY;UNTIL=20000131T140000Z;
BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA
or
RRULE:FREQ=DAILY;UNTIL=20000131T140000Z;BYMONTH=1
==> (1998 9:00 AM EST)January 1-31
(1999 9:00 AM EST)January 1-31
(2000 9:00 AM EST)January 1-31Weekly for 10 occurrences:
DTSTART;TZID=America/New_York: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=America/New_York: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=America/New_York: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 3, 17
...Weekly on Tuesday and Thursday for five weeks:
DTSTART;TZID=America/New_York: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, starting on Monday, September 1, 1997:
DTSTART;TZID=America/New_York:19970901T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU;
BYDAY=MO,WE,FR
==> (1997 9:00 AM EDT) September 1,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=America/New_York: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 first Friday for 10 occurrences:
DTSTART;TZID=America/New_York:19970905T090000
RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR
==> (1997 9:00 AM EDT) September 5;October 3
(1997 9:00 AM EST) November 7;December 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 first Friday until December 24, 1997:
DTSTART;TZID=America/New_York: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 first and last Sunday of the month for 10 occurrences:
DTSTART;TZID=America/New_York: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=America/New_York: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 16The examples are "forever"-style RRULEs, so the first ones are about the last day of the month, then every 18 months, and so on. Let's go 💅
Monthly on the third-to-the-last day of the month, forever 🗓️
DTSTART;TZID=America/New_York: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 for 10 occurrences 🎀
DTSTART;TZID=America/New_York: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=America/New_York: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=America/New_York: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=America/New_York: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=America/New_York: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 10Heads up: since none of the BYDAY, BYMONTHDAY, or BYYEARDAY parts are specified here, the day gets pulled from "DTSTART". 🧠
Every other year on January, February, and March for 10 occurrences 🍓
DTSTART;TZID=America/New_York: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 third year on the 1st, 100th, and 200th day for 10 occurrences 🧚
DTSTART;TZID=America/New_York: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=America/New_York: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 (the default start of the week is Monday), forever 🌈
DTSTART;TZID=America/New_York: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=America/New_York: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=America/New_York: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=America/New_York:19970902T090000
EXDATE;TZID=America/New_York: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=America/New_York: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 4 years, the first Tuesday after a Monday in November, forever (U.S. Presidential Election day) 🇺🇸
DTSTART;TZID=America/New_York: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 third instance into the month of one of Tuesday, Wednesday, or Thursday, for the next 3 months 🔥
DTSTART;TZID=America/New_York: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 second-to-last weekday of the month 🎀
DTSTART;TZID=America/New_York: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=America/New_York: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=America/New_York: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=America/New_York: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=America/New_York: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 generated days depend on WKST 🧁
DTSTART;TZID=America/New_York:19970805T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=MO
==> (1997 EDT) August 5,10,19,24Change only WKST from MO to SU and the results come out different 👀
DTSTART;TZID=America/New_York:19970805T090000
RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=SU
==> (1997 EDT) August 5,17,19,31An example where an invalid date (February 30, which doesn't exist) gets ignored 🙃
DTSTART;TZID=America/New_York:20070115T090000
RRULE:FREQ=MONTHLY;BYMONTHDAY=15,30;COUNT=5
==> (2007 EST) January 15,30
(2007 EST) February 15
(2007 EDT) March 15,303.8.6. Alarm Component Properties ⏰
The following properties specify alarm information in calendar components. 🔔
3.8.6.1. Action 💥
Property Name: ACTION
Purpose: This is the action that runs when an alarm goes off.
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: This property MUST be specified once in a VALARM calendar component. Exactly once, no more, no less 🙌
Description: Every VALARM has a particular type of action attached to it, and this property is where that type gets set. Applications MUST ignore alarms with x-name and iana-token values they don't recognize 🙅♀️
Format Definition: This property is defined by the following notation:
action = "ACTION" actionparam ":" actionvalue CRLF
actionparam = *(";" other-param)
actionvalue = "AUDIO" / "DISPLAY" / "EMAIL"
/ iana-token / x-nameExample: The following are examples of this property in a VALARM calendar component:
ACTION:AUDIO
ACTION:DISPLAY3.8.6.2. Repeat Count 🔁
Property Name: REPEAT
Purpose: This property sets how many times the alarm repeats after the initial trigger.
Value Type: INTEGER
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: This property can be specified in a VALARM calendar component. 💕
Description: This property defines how many times an alarm repeats after its initial trigger. If the alarm triggers more than once, then this property MUST be specified along with the DURATION property. Bestie, don't skip the DURATION 😭
Format Definition: This property is defined by the following notation:
repeat = "REPEAT" repparam ":" integer CRLF
;Default is "0", zero.
repparam = *(";" other-param)Example: The following is an example of this property for an alarm that repeats 4 additional times with a 5-minute delay after the initial triggering of the alarm: ⏳
REPEAT:4
DURATION:PT5M3.8.6.3. Trigger ⏰
okay so this is the property that decides WHEN the alarm goes off 🔔✨ its name is TRIGGER and it's giving main character energy because the whole alarm lives or dies by it 💅
Property Name: TRIGGER
Purpose: this one sets when an alarm will trigger 🦋
Value Type: the default is DURATION 🌸 you can also switch it to a DATE-TIME value type, but then the value MUST specify a UTC-formatted DATE-TIME value 🌈
Property Parameters: you can use IANA, non-standard, value data type, time zone identifier, or trigger relationship property parameters on this one 🎀 the trigger relationship property parameter MUST only be specified when the value type is "DURATION" (no sneaking it onto an absolute time, bestie 🙈)
Conformance: this property MUST be specified in the "VALARM" calendar component 👑
Description: so the big idea is that this property defines when an alarm will trigger ✨ the default value type is DURATION, which means it's a relative time for when the alarm goes off, and the default duration is measured from the start of the event or to-do the alarm is attached to 🧚 you can also explicitly say it should count from the end or the start of that event or to-do using the "RELATED" parameter 💖 a value of START makes the alarm trigger off the start, and a value of END makes it trigger off the end 🍓
positive or negative durations are both allowed here 💜 a positive duration fires the alarm after the start or end of the event or to-do, and a negative one fires it before 🌈 (so a negative duration is basically the "heads up" vibe ⭐)
the "RELATED" parameter is NOT valid when the value type is DATE-TIME (aka an absolute date and time alarm, which is a whole different energy 🫶) if you go with DATE-TIME, the property value MUST be specified in the UTC time format 🌸 and if you put an absolute trigger on an alarm for a recurring event or to-do, the alarm only goes off at that one specified absolute DATE-TIME, plus any repeating instances you've also set up 🔁 slightly unhinged, but it works ✨
if the trigger is relative to START, then the "DTSTART" property MUST be present in the associated "VEVENT" or "VTODO" calendar component 💅 if an alarm is for an event and the trigger is relative to the END, then the "DTEND" property OR the "DTSTART" and "DURATION " properties MUST be present in the associated "VEVENT" calendar component 🎀 and if it's a to-do with an END-relative trigger, then either the "DUE" property OR the "DTSTART" 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 📅 get triggered relative to 00:00:00 of the user's configured time zone on that date 🌍 and if no configured time zone can be found for the user, it falls back to 00:00:00 UTC on that date 🫶 for example, if DTSTART is a DATE value set to 19980205, then the duration trigger is relative to 19980205T000000 America/New_York for a user who has the America/New_York time zone configured 🗽
Format Definition: this property is defined by the following notation:
trigger = "TRIGGER" (trigrel / trigabs) CRLF
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.
;
(";" other-param)
;
) ":" dur-value
trigabs = *(
;
; The following is REQUIRED,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" "DATE-TIME") /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
) ":" date-timeExample: here are some cute examples 🧁
A trigger set 15 minutes prior to the start of the event or to-do 🌙
TRIGGER:-PT15MA trigger set five minutes after the end of an event or the due date of a to-do ⏰
TRIGGER;RELATED=END:PT5MA trigger set to an absolute DATE-TIME 💜
TRIGGER;VALUE=DATE-TIME:19980101T050000Z3.8.7. Change Management Component Properties 📝
okay this next bit is all about the change management properties 🗂️ they're the ones that keep track of what changed in calendar components and when 💖
3.8.7.1. Date-Time Created 🌷
Property Name: CREATED
Purpose: this property specifies the date and time that 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, so if you've ever checked a file's "created" info, same energy 📁
Value Type: DATE-TIME 🕰️
Property Parameters: IANA and non-standard property parameters can be specified on this property ✨
Conformance: the property can be specified once in "VEVENT", "VTODO", or "VJOURNAL" calendar components 🌸 the value MUST be specified as a date with UTC time 🌍
Description: this property is the same idea as the Purpose, really 💅 it specifies the date and time that the calendar information was created by the calendar user agent in the calendar store 🦋
Format Definition: this property is defined by the following notation:
created = "CREATED" creaparam ":" date-time CRLF
creaparam = *(";" other-param)Example: here's what it looks like 🧚
CREATED:19960329T133000Z3.8.7.2. Date-Time Stamp 🕓
Property Name: DTSTAMP
Purpose: okay this one's a little more layered 🧩 if the iCalendar object specifies a "METHOD" property, then this property tells you when that instance of the iCalendar object was created 💜 if the iCalendar object does NOT specify a "METHOD" property, then it tells you when the information for the calendar component was last revised in the calendar store 🌈
Value Type: DATE-TIME ⏳
Property Parameters: IANA and 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 👑
Description: the value MUST be specified in the UTC time format 🌍
this property is also super useful for protocols like [2447bis] that have inherent latency issues when delivering content 🐢 this property helps keep iCalendar messages in the right order 📬
for an iCalendar object that specifies a "METHOD" property, this one is different from "CREATED" and "LAST-MODIFIED" 🙃 those two are about when the particular calendar data in the calendar store was created and last modified 🗃️ this is different from when the iCalendar object representation of the calendar service information was created or last modified 🫶
for an iCalendar object that doesn't specify a "METHOD" property, this property is equivalent to "LAST-MODIFIED" 💖
Format Definition: this property is defined by the following notation:
dtstamp = "DTSTAMP" stmparam ":" date-time CRLF
stmparam = *(";" other-param)Example: 🌟
DTSTAMP:19971210T080000Z3.8.7.3. Last Modified ✏️
Property Name: LAST-MODIFIED
Purpose: this property specifies the date and time that 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, so think "last edited" vibes 📝
Value Type: DATE-TIME 🕰️
Property Parameters: IANA and non-standard property parameters can be specified on this property 🌸
Conformance: this property can be specified in the "VEVENT", "VTODO", "VJOURNAL", or "VTIMEZONE" calendar components 🦋
Description: the property value MUST be specified in the UTC time format 🌍
Format Definition: this property is defined by the following notation:
last-mod = "LAST-MODIFIED" lstparam ":" date-time CRLF
lstparam = *(";" other-param)Example: here's a cute one 🎀
LAST-MODIFIED:19960817T133000Z3.8.7.4. Sequence Number 🔢
Property Name: SEQUENCE
Purpose: this property defines the revision sequence number of the calendar component within a sequence of revisions 🌈
Value Type: INTEGER 🔟
Property Parameters: IANA and 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 0 🍼 it gets monotonically incremented by the "Organizer's" CUA each time the "Organizer" makes a significant revision to the calendar component 📈
the "Organizer" includes this property in an iCalendar object that it sends to an "Attendee" to specify the current version of the calendar component 📤
the "Attendee" includes this property in an iCalendar object that it sends to the "Organizer" to specify which version of the calendar component it's referring to 📥
a change to 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 🙋
recurrence instances of a recurring component MAY have different sequence numbers 🌀
Format Definition: this property is defined by the following notation:
seq = "SEQUENCE" seqparam ":" integer CRLF
; Default is "0"
seqparam = *(";" other-param)Example: here's a calendar component that was just created by the "Organizer" 🐣
SEQUENCE:0and here's one that the "Organizer" has revised two different times 🔁
SEQUENCE:23.8.8. Miscellaneous Component Properties 🎁
okay the last little grab bag 🛍️ these properties cover a bunch of miscellaneous features of calendar components 💜
3.8.8.1. IANA Properties 🌐
Property Name: an IANA-registered property name 🏷️
Value Type: the default value type is TEXT 📝 the value type can be set to any value type 🌈
Property Parameters: any parameter can be specified on this property ✨
Description: this spec lets other properties registered with IANA be specified in any calendar components 🦋 compliant applications are expected to be able to parse these other IANA-registered properties, but they can ignore them if they want 🫶
Format Definition: this property is defined by the following notation:
iana-prop = iana-token *(";" icalparameter) ":" value CRLFExample: here are some examples of properties that might be registered with IANA 💅
DRESSCODE:CASUAL
NON-SMOKING;VALUE=BOOLEAN:TRUE3.8.8.2. Non-Standard Properties ✨
Property Name: Any property name with a "X-" prefix 🎀
Purpose: okay so this one is the escape hatch for making up your own properties 🧚 It gives implementers a framework for defining non-standard properties, and it's literally giving "build your own adventure" 💅
Value Type: The default value type is TEXT. The value type can be set to any value type. So you can go wild 🌈
Property Parameters: IANA, non-standard, and language property parameters can be specified on this property.
Conformance: This property can be specified in any calendar component. Any component, bestie 🦋
Description: The MIME Calendaring and Scheduling Content Type gives us a "standard mechanism for doing non-standard things" 😭 It's the whole vibe. This extension support is there so implementers can "push the envelope" on the existing version of the memo 🔥
Extension properties are named with the prefix text "X-", which is the two-character sequence of the LATIN CAPITAL LETTER X character followed by the HYPHEN-MINUS character. This works for both property names and property parameter names ✨ It is recommended that vendors tack on another short prefix text after that sentinel to identify the vendor. That makes the extensions way easier to read 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. Parsing is the main requirement, and ignoring is totally allowed 💜
Right now there is no registration authority for names of extension properties and property parameters. The value type for this property is TEXT. Optionally, the value type can be any of the other valid value types 🍓
Format Definition: This property is defined by the following notation:
x-prop = x-name *(";" icalparameter) ":" value CRLFExample: The following might be the ABC vendor's extension for an audio-clip form of subject property 🎧
X-ABC-MMSUBJ;VALUE=URI;FMTTYPE=audio/basic:http://www.example.
org/mysubj.au3.8.8.3. Request Status ✨
Property Name: REQUEST-STATUS
Purpose: This property defines the status code returned for a scheduling request. It's the reply that tells you how your request went 💌
Value Type: TEXT
Property Parameters: IANA, non-standard, and language property parameters can be specified on this property.
Conformance: The property can be specified in the "VEVENT", "VTODO", "VJOURNAL", or "VFREEBUSY" calendar component. Four components, so many options 🌸
Description: This property is used to return status code information related to the processing of an associated iCalendar object. It's basically the receipt 🧾 The value type for this property is TEXT.
The value has three parts: 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 💅
The short return status is a PERIOD character separated pair or 3-tuple of integers, like "3.1" or "3.1.1". The successive levels of integers give you a successively finer level of status code granularity. So the more numbers, the more detail, periodt 🔍
The following are the initial classes for the return status code. Individual iCalendar object methods 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 | Longer Return Status Description |
| Return | |
| Status | |
| Code | |
+--------+----------------------------------------------------------+
| 1.xx | Preliminary success. This class of status code |
| | indicates that the request has been initially processed |
| | but that completion is pending. |
| | |
| 2.xx | Successful. This class of status code indicates that |
| | the request was completed successfully. 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. |
+--------+----------------------------------------------------------+Format Definition: This 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.
;
(";" languageparam) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
statcode = 1*DIGIT 1*2("." 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: The following are some possible examples of this property. Look at how the COMMA and SEMICOLON separator characters in the property value get BACKSLASH character escaped, because they show up inside 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@example.com4. iCalendar Object Examples ✨
okay so these examples are purely for vibes and understanding 🧚 they're informational, so they show what valid iCalendar objects look like without being the rules themselves 💅
Our first one is a three-day conference that kicks off at 2:30 P.M. UTC on September 18, 1996 and wraps up at 10:00 P.M. UTC on September 20, 1996 🌸
BEGIN:VCALENDAR
PRODID:-//xyz Corp//NONSGML PDA Calendar Version 1.0//EN
VERSION:2.0
BEGIN:VEVENT
DTSTAMP:19960704T120000Z
UID:uid1@example.com
ORGANIZER:mailto:jsmith@example.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 from 8:30 AM EST to 9:30 AM EST on March 12, 1998 🎀 The organizer invited a whole group of calendar users, and there's a time zone definition for Eastern United States time, so the times line up properly 🦋
BEGIN:VCALENDAR
PRODID:-//RDU Software//NONSGML HandCal//EN
VERSION:2.0
BEGIN:VTIMEZONE
TZID:America/New_York
BEGIN:STANDARD
DTSTART:19981025T020000
TZOFFSETFROM:-0400
TZOFFSETTO:-0500
TZNAME:EST
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19990404T020000
TZOFFSETFROM:-0500
TZOFFSETTO:-0400
TZNAME:EDT
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
DTSTAMP:19980309T231000Z
UID:guid-1.example.com
ORGANIZER:mailto:mrbig@example.com
ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
mailto:employee-A@example.com
DESCRIPTION:Project XYZ Review Meeting
CATEGORIES:MEETING
CLASS:PUBLIC
CREATED:19980309T130000Z
SUMMARY:XYZ Project Review
DTSTART;TZID=America/New_York:19980312T083000
DTEND;TZID=America/New_York:19980312T093000
LOCATION:1CP Conference Room 4350
END:VEVENT
END:VCALENDARNow this one is an iCalendar object riding inside a MIME message, as a single body part with a text/calendar Content Type 💌 It's giving email-with-a-calendar-attached energy 💅
TO:jsmith@example.com
FROM:jdoe@example.com
MIME-VERSION:1.0
MESSAGE-ID:<id3@example.com>
CONTENT-TYPE:text/calendar; method="xyz"; component="VEVENT"
BEGIN:VCALENDAR
METHOD:xyz
VERSION:2.0
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VEVENT
DTSTAMP:19970324T120000Z
SEQUENCE:0
UID:uid3@example.com
ORGANIZER:mailto:jdoe@example.com
ATTENDEE;RSVP=TRUE:mailto:jsmith@example.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://example.com/pub/
conf/bkgrnd.ps
END:VEVENT
END:VCALENDARHere's a to-do that's due on April 15, 1998 📝 It has an audio alarm that pings the calendar user at noon the day before the to-do is expected to be finished, then repeats hourly four more times 🔔 This to-do has been edited twice since it was first created, so it's had a little glow-up 🌈
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VTODO
DTSTAMP:19980130T134500Z
SEQUENCE:2
UID:uid4@example.com
ORGANIZER:mailto:unclesam@example.com
ATTENDEE;PARTSTAT=ACCEPTED:mailto:jqpublic@example.com
DUE:19980415T000000
STATUS:NEEDS-ACTION
SUMMARY:Submit Income Taxes
BEGIN:VALARM
ACTION:AUDIO
TRIGGER:19980403T120000Z
ATTACH;FMTTYPE=audio/basic:http://example.com/pub/audio-
files/ssbanner.aud
REPEAT:4
DURATION:PT1H
END:VALARM
END:VTODO
END:VCALENDARNext is a journal entry 📓 Meeting minutes with the agenda, the attendees, and the decisions all in one spot, very main character ✨
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ABC Corporation//NONSGML My Product//EN
BEGIN:VJOURNAL
DTSTAMP:19970324T120000Z
UID:uid5@example.com
ORGANIZER:mailto:jsmith@example.com
STATUS:DRAFT
CLASS:PUBLIC
CATEGORIES: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:VCALENDARLast example for this part is published busy time information 🕒 This iCalendar object could be stored at http://www.example.com/calendar/busytime/jsmith.ifb, and it lists the free/busy periods for that calendar 🦋
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//RDU Software//NONSGML HandCal//EN
BEGIN:VFREEBUSY
ORGANIZER:mailto:jsmith@example.com
DTSTART:19980313T141711Z
DTEND:19980410T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
URL:http://www.example.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY
END:VCALENDAR5. Recommended Practices 💖
these practices are here so that certain cases get handled consistently for an iCalendar object 🫶 here's the lineup:
- Content lines longer than 75 octets SHOULD be folded 📏
- When the combination of the
RRULEandRDATEproperties in a recurring component produces multiple instances having the same start DATE-TIME value, they should get collapsed into, and treated as, a single instance 👯 If theRDATEproperty is specified as a PERIOD value, the duration of the recurrence instance is the one given by theRDATEproperty, not the duration of the recurrence instance defined by theDTSTARTproperty 🌙 - When a calendar user gets several requests for the same calendar component (for example, a REQUEST for a
VEVENTcalendar component) because they're on multiple mailing lists named in theATTENDEEproperties of the request, they SHOULD respond to only one of the requests 📬 The calendar user SHOULD also say which mailing list they're a member of, using theMEMBERparameter of theATTENDEEproperty 🎀 - An implementation can truncate a
SUMMARYproperty value to 255 octets, but it MUST NOT truncate the value in the middle of a UTF-8 multi-octet sequence 💀 Bestie, don't split a character in half 🙈 - If seconds of the minute are not supported by an implementation, then a value of
00SHOULD be specified for the seconds component in a time value ⏰ 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 include:ANNIVERSARY,APPOINTMENT,BUSINESS,EDUCATION,HOLIDAY,MEETING,MISCELLANEOUS,NON-WORKING HOURS,NOT IN OFFICE,PERSONAL,PHONE CALL,SICK DAY,SPECIAL OCCASION,TRAVEL,VACATION🏖️ Categories can be specified in any registered language 🌍 - Some possible English values for the
RESOURCESproperty include:CATERING,CHAIRS,COMPUTER PROJECTOR,EASEL,OVERHEAD PROJECTOR,SPEAKER PHONE,TABLE,TV,VCR,VIDEO PHONE,VEHICLE🪑 Resources can be specified in any registered language 🌈
6. Internationalization Considerations 🌍
okay the language part is simple and iconic 💅 Applications MUST generate iCalendar streams in the UTF-8 charset, and they MUST accept an iCalendar stream in the UTF-8 or US-ASCII charset 🫶
7. Security Considerations 🔐
this section is seriously important, bestie 😭 Calendaring and scheduling information is super privacy-sensitive, so the protocol used to transmit it should have capabilities to protect the information from possible threats: eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle attacks 🕵️♀️💀
As this document only defines the data format and media type of text/calendar, and that format is independent of any calendar service or protocol, it's up to the actual protocol specifications to cover these threats and how to mitigate them. Those specs include iTIP [2446bis], iMIP [2447bis], and "Calendaring Extensions to WebDAV (CalDAV)" [RFC4791] 🔥
8. IANA Considerations 🦋
8.1. iCalendar Media Type Registration ✨
Okay bestie, this is where iCalendar gets its official MIME content-type ID card 🪪💖. The Calendaring and Scheduling Core Object Specification is meant to be used as a MIME content type, so here's the whole registration form, serving full main-character energy 💅:
To: ietf-types@iana.org
Subject: Registration of media type text/calendar
Type name: text
Subtype name: calendar
Required parameters: none
Optional parameters: charset, method, component, and optinfoThe charset parameter comes from [RFC2046] and is used for subtypes of the "text" media type 🌸. It shows which charset the body part is using. This revision of iCalendar supports UTF-8, and using any other charset is deprecated by this revision. Still, this revision says compliant applications MUST accept iCalendar streams that use either UTF-8 or US-ASCII, so nobody gets left out 🫶.
The method parameter is a big one 🦋. It carries the iCalendar object method or transaction semantics for the calendaring and scheduling info, and it also identifies the restricted set of properties and values the iCalendar object is made of. Applications should treat it as a guide when they interpret the body part. It SHOULD NOT be used to exclude or require specific pieces of information, unless the method definition specifically calls for that. Unless a particular method definition forbids it, a text/calendar content type can contain any set of properties the Calendaring and Scheduling Core Object Specification allows. Here's the strict part 🙈: the "method" parameter MUST be specified, and it MUST be set to the same value as the "METHOD" component property of the iCalendar objects in the stream, but only if all of those objects have a "METHOD" component property set to that same value.
Its value is defined like this:
method = 1*(ALPHA / DIGIT / "-")
; IANA-registered iCalendar object methodThe component parameter tells you what type of iCalendar calendar component is in the body part 🍓. If the iCalendar object holds more than one component type, then multiple component parameters MUST be specified.
Its value is defined like this:
component = "VEVENT"
/ "VTODO"
/ "VJOURNAL"
/ "VFREEBUSY"
/ "VTIMEZONE"
/ iana-token
/ x-nameThe optinfo parameter carries optional info about the iCalendar object in the body part 🧚. It can only specify semantics that the iCalendar object already defines and that can be figured out by parsing the body part. On top of that, the optional info in this parameter MUST be consistent with what the iCalendar object says. For example, it can be used to pass along the "Attendee" response status for a meeting request. The value is a string, and the parameter can show up multiple times.
Its value is defined like this:
optinfo = infovalue / qinfovalue
infovalue = iana-token / x-name
qinfovalue = DQUOTE (infovalue) DQUOTEEncoding considerations: This media type can contain 8bit characters 🌈. That means quoted-printable or base64 MIME Content-Transfer-Encodings might be needed when iCalendar objects travel over protocols limited to the 7bit repertoire. Also, a text valued property in the content entity can have its special characters escaped with a BACKSLASH character, so the content values can end up encoded twice. Double encoding, bestie, yikes 💀.
Security considerations: See Section 7 🔐.
Interoperability considerations: This media type is meant to define one common format for sharing calendaring and scheduling info between different systems 🤝. It's heavily based on the earlier [VCAL] industry specification.
Published specification: This specification 📜.
Applications that use this media type: This media type is built for widespread use by Internet calendaring and scheduling apps ✨. Apps in the workflow and document management area might find this content type useful too. The iTIP [2446bis], iMIP [2447bis], and CalDAV [RFC4791] Internet protocols also use this media type directly 💜.
Additional information:
- Magic number(s): None.
- File extension(s): The file extension "ics" designates a file holding (an arbitrary set of) calendaring and scheduling info that matches this MIME content type 📅. The file extension "ifb" designates a file holding free or busy time info that matches this MIME content type 🕒.
- Macintosh file type code(s): On Apple Macintosh operating systems, the file type code "iCal" designates a file holding calendaring and scheduling info that matches this MIME media type 🍎. The file type code "iFBf" designates a file holding free or busy time info that matches this MIME media type 🫧.
Person & email address to contact for further information: See the "Author's Address" section of this document 📮.
Intended usage: COMMON ✅
Restrictions on usage: There are no restrictions on where this media type can be used 🎉.
Author: See the "Author's Address" section of this document 🎀.
Change controller: IETF 👑.
8.2. New iCalendar Elements Registration ✨
This section explains how to register new or modified iCalendar elements with IANA 🦋. Those elements are components, properties, parameters, value data types, and values.
8.2.1. iCalendar Elements Registration Procedure 🗂️
The IETF will create a mailing list, icalendar@ietf.org, for public chat about iCalendar element proposals before anything gets registered 💬. Using the mailing list is strongly encouraged, so please use it 🥹. The IESG will appoint a designated expert who keeps an eye on the icalendar@ietf.org list and reviews registrations.
Registration of new iCalendar elements MUST be reviewed by the designated expert and published in an RFC 📄. Here's the strict rule 😤: a Standards Track RFC is REQUIRED for registering new value data types that modify existing properties, and it's REQUIRED for registering participation status values to be used in "VEVENT" calendar components. A Standards Track RFC is also REQUIRED for registering iCalendar elements that modify iCalendar elements previously documented in a Standards Track RFC.
The registration process starts when a completed registration template, defined in the sections below, is sent to icalendar@ietf.org and iana@iana.org 📨. The designated expert is expected to tell IANA and the submitter within two weeks whether the registration is approved, approved with minor changes, or rejected with cause ⏳. If a registration is rejected with cause, it can be re-submitted once the concerns listed in the cause are fixed 🔁. Decisions made by the designated expert can be appealed to the IESG Applications Area Director, and then to the IESG. These appeals follow the normal appeals procedure for IESG decisions ⚖️.
8.2.2. Registration Template for Components 🧩
A component is defined by filling out the following template.
- Component name: The name of the component.
- Purpose: The purpose of the component. Give a short but clear description.
- Format definition: The ABNF for the component definition needs to be specified.
- Description: Any special notes about the component, how it is to be used, etc.
- Example(s): One or more examples of instances of the component need to be specified.
8.2.3. Registration Template for Properties 🎀
A property is defined by filling out the following template.
- Property name: The name of the property.
- Purpose: The purpose of the property. Give a short but clear description.
- Value type: Any of the valid value types for the property value need to be specified. The default value type also needs to be specified.
- Property parameters: Any of the valid property parameters for the property MUST be specified.
- Conformance: The calendar components in which the property can appear MUST be specified.
- Description: Any special notes about the property, how it is to be used, etc.
- Format definition: The ABNF for the property definition needs to be specified.
- Example(s): One or more examples of instances of the property need to be specified.
8.2.4. Registration Template for Parameters 🌷
A parameter is defined by filling out the following template.
- Parameter name: The name of the parameter.
- Purpose: The purpose of the parameter. Give a short but clear description.
- Format definition: The ABNF for the parameter definition needs to be specified.
- Description: Any special notes about the parameter, how it is to be used, etc.
- Example(s): One or more examples of instances of the parameter need to be specified.
8.2.5. Registration Template for Value Data Types 🔢
A value data type is defined by filling out the following template.
- Value name: The name of the value type.
- Purpose: The purpose of the value type. Give a short but clear description.
- Format definition: The ABNF for the value type definition needs to be specified.
- Description: Any special notes about the value type, how it is to be used, etc.
- Example(s): One or more examples of instances of the value type need to be specified.
8.2.6. Registration Template for Values 🍭
A value is defined by filling out the following template.
- Value: The value literal.
- Purpose: The purpose of the value. Give a short but clear description.
- Conformance: The calendar properties and/or parameters that can take this value need to be specified.
- Example(s): One or more examples of instances of the value need to be specified.
Here's a fictitious example of registering an iCalendar value, just for fun 🕵️♀️:
- Value:
TOP-SECRET - Purpose: This value is used to specify the access classification of top-secret calendar components.
- Conformance: This value can be used with the "CLASS" property.
- Example(s): The following is an example of this value used with the "CLASS" property:
CLASS:TOP-SECRET8.3. Initial iCalendar Elements Registries 📚
IANA created and maintains the following registries for iCalendar elements, with pointers to the appropriate reference documents 🗃️✨.
8.3.1. Components Registry ✨
okay so this one's the components registry, and it's already been seeded with the starter set 💖 every row is a component, its status, and where it's defined in the spec. VCALENDAR, VEVENT, VTODO, VJOURNAL, VFREEBUSY, VTIMEZONE, VALARM, plus STANDARD and DAYLIGHT, which both point back to the VTIMEZONE section 🌸
+-----------+---------+-------------------------+
| Component | Status | Reference |
+-----------+---------+-------------------------+
| VCALENDAR | Current | RFC 5545, Section 3.4 |
| | | |
| VEVENT | Current | RFC 5545, Section 3.6.1 |
| | | |
| VTODO | Current | RFC 5545, Section 3.6.2 |
| | | |
| VJOURNAL | Current | RFC 5545, Section 3.6.3 |
| | | |
| VFREEBUSY | Current | RFC 5545, Section 3.6.4 |
| | | |
| VTIMEZONE | Current | RFC 5545, Section 3.6.5 |
| | | |
| VALARM | Current | RFC 5545, Section 3.6.6 |
| | | |
| STANDARD | Current | RFC 5545, Section 3.6.5 |
| | | |
| DAYLIGHT | Current | RFC 5545, Section 3.6.5 |
+-----------+---------+-------------------------+8.3.2. Properties Registry 🎀
this is the big one, bestie 😭 it's the starter list of every property, with its status and section reference. the one that's marked Deprecated is EXRULE, and it points back to the older [RFC2445] spec, so you know where it came from 🦋
+------------------+------------+----------------------------+
| Property | Status | Reference |
+------------------+------------+----------------------------+
| CALSCALE | Current | RFC 5545, Section 3.7.1 |
| METHOD | Current | RFC 5545, Section 3.7.2 |
| | | |
| PRODID | Current | RFC 5545, Section 3.7.3 |
| | | |
| VERSION | Current | RFC 5545, Section 3.7.4 |
| | | |
| ATTACH | Current | RFC 5545, Section 3.8.1.1 |
| | | |
| CATEGORIES | Current | RFC 5545, Section 3.8.1.2 |
| | | |
| CLASS | Current | RFC 5545, Section 3.8.1.3 |
| | | |
| COMMENT | Current | RFC 5545, Section 3.8.1.4 |
| | | |
| DESCRIPTION | Current | RFC 5545, Section 3.8.1.5 |
| | | |
| GEO | Current | RFC 5545, Section 3.8.1.6 |
| | | |
| LOCATION | Current | RFC 5545, Section 3.8.1.7 |
| | | |
| PERCENT-COMPLETE | Current | RFC 5545, Section 3.8.1.8 |
| | | |
| PRIORITY | Current | RFC 5545, Section 3.8.1.9 |
| | | |
| RESOURCES | Current | RFC 5545, Section 3.8.1.10 |
| | | |
| STATUS | Current | RFC 5545, Section 3.8.1.11 |
| | | |
| SUMMARY | Current | RFC 5545, Section 3.8.1.12 |
| | | |
| COMPLETED | Current | RFC 5545, Section 3.8.2.1 |
| | | |
| DTEND | Current | RFC 5545, Section 3.8.2.2 |
| | | |
| DUE | Current | RFC 5545, Section 3.8.2.3 |
| | | |
| DTSTART | Current | RFC 5545, Section 3.8.2.4 |
| | | |
| DURATION | Current | RFC 5545, Section 3.8.2.5 |
| | | |
| FREEBUSY | Current | RFC 5545, Section 3.8.2.6 |
| | | |
| TRANSP | Current | RFC 5545, Section 3.8.2.7 |
| | | |
| TZID | Current | RFC 5545, Section 3.8.3.1 |
| | | |
| TZNAME | Current | RFC 5545, Section 3.8.3.2 |
| | | |
| TZOFFSETFROM | Current | RFC 5545, Section 3.8.3.3 |
| | | |
| TZOFFSETTO | Current | RFC 5545, Section 3.8.3.4 |
| | | |
| TZURL | Current | RFC 5545, Section 3.8.3.5 |
| | | |
| ATTENDEE | Current | RFC 5545, Section 3.8.4.1 |
| | | |
| CONTACT | Current | RFC 5545, Section 3.8.4.2 |
| | | |
| ORGANIZER | Current | RFC 5545, Section 3.8.4.3 |
| | | |
| RECURRENCE-ID | Current | RFC 5545, Section 3.8.4.4 |
| | | |
| RELATED-TO | Current | RFC 5545, Section 3.8.4.5 |
| | | |
| URL | Current | RFC 5545, Section 3.8.4.6 |
| | | |
| UID | Current | RFC 5545, Section 3.8.4.7 |
| | | |
| EXDATE | Current | RFC 5545, Section 3.8.5.1 |
| | | |
| EXRULE | Deprecated | [RFC2445], Section 4.8.5.2 |
| | | |
| RDATE | Current | RFC 5545, Section 3.8.5.2 |
| | | |
| RRULE | Current | RFC 5545, Section 3.8.5.3 |
| | | |
| ACTION | Current | RFC 5545, Section 3.8.6.1 |
| | | |
| REPEAT | Current | RFC 5545, Section 3.8.6.2 |
| | | |
| TRIGGER | Current | RFC 5545, Section 3.8.6.3 |
| | | |
| CREATED | Current | RFC 5545, Section 3.8.7.1 |
| | | |
| DTSTAMP | Current | RFC 5545, Section 3.8.7.2 |
| | | |
| LAST-MODIFIED | Current | RFC 5545, Section 3.8.7.3 |
| | | |
| SEQUENCE | Current | RFC 5545, Section 3.8.7.4 |
| | | |
| REQUEST-STATUS | Current | RFC 5545, Section 3.8.8.3 |
+------------------+------------+----------------------------+8.3.3. Parameters Registry 💜
last table for this bit, and it's the starter set for parameters 🧚 each row is a parameter name, its status, and where it's described in section 3.2. VALUE is the last one on the list, and it's Current, obviously 💅
+----------------+---------+--------------------------+
| Parameter | Status | Reference |
+----------------+---------+--------------------------+
| ALTREP | Current | RFC 5545, Section 3.2.1 |
| | | |
| CN | Current | RFC 5545, Section 3.2.2 |
| | | |
| CUTYPE | Current | RFC 5545, Section 3.2.3 |
| | | |
| DELEGATED-FROM | Current | RFC 5545, Section 3.2.4 |
| | | |
| DELEGATED-TO | Current | RFC 5545, Section 3.2.5 |
| | | |
| DIR | Current | RFC 5545, Section 3.2.6 |
| | | |
| ENCODING | Current | RFC 5545, Section 3.2.7 |
| | | |
| FMTTYPE | Current | RFC 5545, Section 3.2.8 |
| | | |
| FBTYPE | Current | RFC 5545, Section 3.2.9 |
| | | |
| LANGUAGE | Current | RFC 5545, Section 3.2.10 |
| | | |
| MEMBER | Current | RFC 5545, Section 3.2.11 |
| | | |
| PARTSTAT | Current | RFC 5545, Section 3.2.12 |
| | | |
| RANGE | Current | RFC 5545, Section 3.2.13 |
| | | |
| RELATED | Current | RFC 5545, Section 3.2.14 |
| | | |
| RELTYPE | Current | RFC 5545, Section 3.2.15 |
| | | |
| ROLE | Current | RFC 5545, Section 3.2.16 |
| | | |
| RSVP | Current | RFC 5545, Section 3.2.17 |
| | | |
| SENT-BY | Current | RFC 5545, Section 3.2.18 |
| | | |
| TZID | Current | RFC 5545, Section 3.2.19 |
| | | |
| VALUE | Current | RFC 5545, Section 3.2.20 |
+----------------+---------+--------------------------+8.3.4. Value Data Types Registry 💖
Here's the table we used to set up the value data types registry 🎀
+-----------------+---------+--------------------------+
| Value Data Type | Status | Reference |
+-----------------+---------+--------------------------+
| BINARY | Current | RFC 5545, Section 3.3.1 |
| | | |
| BOOLEAN | Current | RFC 5545, Section 3.3.2 |
| | | |
| CAL-ADDRESS | Current | RFC 5545, Section 3.3.3 |
| | | |
| DATE | Current | RFC 5545, Section 3.3.4 |
| | | |
| DATE-TIME | Current | RFC 5545, Section 3.3.5 |
| | | |
| DURATION | Current | RFC 5545, Section 3.3.6 |
| | | |
| FLOAT | Current | RFC 5545, Section 3.3.7 |
| | | |
| INTEGER | Current | RFC 5545, Section 3.3.8 |
| | | |
| PERIOD | Current | RFC 5545, Section 3.3.9 |
| | | |
| RECUR | Current | RFC 5545, Section 3.3.10 |
| | | |
| TEXT | Current | RFC 5545, Section 3.3.11 |
| | | |
| TIME | Current | RFC 5545, Section 3.3.12 |
| | | |
| URI | Current | RFC 5545, Section 3.3.13 |
| | | |
| UTC-OFFSET | Current | RFC 5545, Section 3.3.14 |
+-----------------+---------+--------------------------+8.3.5. Calendar User Types Registry ✨
Next up is the calendar user types registry, which got its starter table right here 💅
+--------------------+---------+-------------------------+
| Calendar User Type | Status | Reference |
+--------------------+---------+-------------------------+
| INDIVIDUAL | Current | RFC 5545, Section 3.2.3 |
| | | |
| GROUP | Current | RFC 5545, Section 3.2.3 |
| | | |
| RESOURCE | Current | RFC 5545, Section 3.2.3 |
| | | |
| ROOM | Current | RFC 5545, Section 3.2.3 |
| | | |
| UNKNOWN | Current | RFC 5545, Section 3.2.3 |
+--------------------+---------+-------------------------+8.3.6. Free/Busy Time Types Registry 🦋
The free/busy time types registry starts with this table 🫶
+---------------------+---------+-------------------------+
| Free/Busy Time Type | Status | Reference |
+---------------------+---------+-------------------------+
| FREE | Current | RFC 5545, Section 3.2.9 |
| | | |
| BUSY | Current | RFC 5545, Section 3.2.9 |
| | | |
| BUSY-UNAVAILABLE | Current | RFC 5545, Section 3.2.9 |
| | | |
| BUSY-TENTATIVE | Current | RFC 5545, Section 3.2.9 |
+---------------------+---------+-------------------------+8.3.7. Participation Statuses Registry 🌸
For the participation statuses registry, the starting values are in this table 🍓
+--------------------+---------+--------------------------+
| Participant Status | Status | Reference |
+--------------------+---------+--------------------------+
| NEEDS-ACTION | Current | RFC 5545, Section 3.2.12 |
| | | |
| ACCEPTED | Current | RFC 5545, Section 3.2.12 |
| | | |
| DECLINED | Current | RFC 5545, Section 3.2.12 |
| | | |
| TENTATIVE | Current | RFC 5545, Section 3.2.12 |
| | | |
| DELEGATED | Current | RFC 5545, Section 3.2.12 |
| | | |
| COMPLETED | Current | RFC 5545, Section 3.2.12 |
| | | |
| IN-PROCESS | Current | RFC 5545, Section 3.2.12 |
+--------------------+---------+--------------------------+8.3.8. Relationship Types Registry 🧚
The relationship types registry was seeded using this table 💜
+-------------------+---------+--------------------------+
| Relationship Type | Status | Reference |
+-------------------+---------+--------------------------+
| CHILD | Current | RFC 5545, Section 3.2.15 |
| | | |
| PARENT | Current | RFC 5545, Section 3.2.15 |
| | | |
| SIBLING | Current | RFC 5545, Section 3.2.15 |
+-------------------+---------+--------------------------+8.3.9. Participation Roles Registry 👑
The participation roles registry got set up with this table 🎀
+-----------------+---------+--------------------------+
| Role Type | Status | Reference |
+-----------------+---------+--------------------------+
| CHAIR | Current | RFC 5545, Section 3.2.16 |
| | | |
| REQ-PARTICIPANT | Current | RFC 5545, Section 3.2.16 |
| | | |
| OPT-PARTICIPANT | Current | RFC 5545, Section 3.2.16 |
| | | |
| NON-PARTICIPANT | Current | RFC 5545, Section 3.2.16 |
+-----------------+---------+--------------------------+8.3.10. Actions Registry ⭐
The actions registry was initialized with this one 🔥
+-----------+------------+----------------------------+
| Action | Status | Reference |
+-----------+------------+----------------------------+
| AUDIO | Current | RFC 5545, Section 3.8.6.1 |
| | | |
| DISPLAY | Current | RFC 5545, Section 3.8.6.1 |
| | | |
| EMAIL | Current | RFC 5545, Section 3.8.6.1 |
| | | |
| PROCEDURE | Deprecated | [RFC2445], Section 4.8.6.1 |
+-----------+------------+----------------------------+Heads up: PROCEDURE is marked Deprecated and points back to [RFC2445], Section 4.8.6.1, not to RFC 5545. It's still in the table, just with that status 💀
8.3.11. Classifications Registry 🌈
Last one for this group: the classifications registry, seeded with this table 🦋
+----------------+---------+---------------------------+
| Classification | Status | Reference |
+----------------+---------+---------------------------+
| PUBLIC | Current | RFC 5545, Section 3.8.1.3 |
| | | |
| PRIVATE | Current | RFC 5545, Section 3.8.1.3 |
| | | |
| CONFIDENTIAL | Current | RFC 5545, Section 3.8.1.3 |
+----------------+---------+---------------------------+8.3.12. Methods Registry 🙈
Bestie, there are no values defined in this document for the property "METHOD" 🥲
9. Acknowledgments 🫶
The editor of this document wants to give a huge thank-you to Frank Dawson and Derik Stenerson, the original authors of RFC 2445 💜 They laid the groundwork that everything here is built on ✨
Then there's this whole squad of people who helped with drafting, reviewing, and talking this memo through 🌸 Joe Abley, Hervey Allen, Steve Allen, Jay Batson, Oliver Block, Stephane Bortzmeyer, Chris Bryant, Tantek Celik, Mark Crispin, Cyrus Daboo, Mike Douglass, Andrew N. Dowden, Lisa Dusseault, Lars Eggert, Gren Eliot, Pasi Eronen, Ben Fortuna, Ned Freed, Neal Gafter, Ted Hardie, Tim Hare, Jeffrey Harris, Helge Hess, Paul B. Hill, Thomas Hnetila, Russ Housley, Leif Johansson, Ciny Joy, Bruce Kahn, Reinhold Kainhofer, Martin Kiff, Patrice Lapierre, Michiel van Leeuwen, Jonathan Lennox, Jeff McCullough, Bill McQuillan, Alexey Melnikov, John W. Noerenberg II, Chuck Norris, Mark Paterson, Simon Pilette, Arnaud Quillaud, Robert Ransdell, Julian F. Reschke, Caleb Richardson, Sam Roberts, Dan Romascanu, Mike Samuel, George Sexton, Nigel Swinson, Clint Talbert, Simon Vaillancourt, Magnus Westerlund, and Sandy Wills 🎀
A special shoutout to the working group chairs, Aki Niemi and Eliot Lear, for their support and guidance 👑
The editor also wants to thank the Calendaring and Scheduling Consortium for advice with this spec, and for organizing interoperability testing events that helped refine it 🦋
10. References 📚
10.1. Normative References 💖
okay bestie, these are the docs this spec is built on, so you can't skip them 🫶 every one is a must-read if you're implementing this 🤓
[ISO.8601.2004]International Organization for Standardization, "Data elements and interchange formats -- Information interchange -- Representation of dates and times", 2004.[ISO.9070.1991]International Organization for Standardization, "Information Technology_SGML Support Facilities -- Registration Procedures for Public Text Owner Identifiers, Second Edition", April 1991.[RFC2045]Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.[RFC2046]Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996.[RFC2119]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.[RFC2368]Hoffman, P., Masinter, L., and J. Zawinski, "The mailto URL scheme", RFC 2368, July 1998.[RFC3629]Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.[RFC3986]Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.[RFC4288]Freed, N. and J. Klensin, "Media Type Specifications and Registration Procedures", BCP 13, RFC 4288, December 2005.[RFC4648]Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006.[RFC5234]Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008.[RFC5646]Phillips, A., Ed., and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009.[US-ASCII]American National Standards Institute, "Coded Character Set - 7-bit American Standard Code for Information Interchange", ANSI X3.4, 1986.
10.2. Informative References 🦋
these ones are the nice-to-know extras 🌈 still super useful for context, just not strictly required to implement
[2446bis]Daboo, C., "iCalendar Transport-Independent Interoperability Protocol (iTIP)", Work in Progress, April 2009.[2447bis]Melnikov, A., "iCalendar Message-Based Interoperability Protocol (iMIP)", Work in Progress, June 2008.[ANSI INCITS 61-1986]International Committee for Information Technology, "Representation of Geographic Point Locations for Information Interchange (formerly ANSI X3.61-1986 (R1997))", ANSI INCITS 61-1986 (R2007), 2007.[RFC1738]Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994.[RFC2392]Levinson, E., "Content-ID and Message-ID Uniform Resource Locators", RFC 2392, August 1998.[RFC2397]Masinter, L., "The "data" URL scheme", RFC 2397, August 1998.[RFC2425]Howes, T., Smith, M., and F. Dawson, "A MIME Content-Type for Directory Information", RFC 2425, September 1998.[RFC2426]Dawson, F. and T. Howes, "vCard MIME Directory Profile", RFC 2426, September 1998.[RFC2445]Dawson, F. and Stenerson, D., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 2445, November 1998.[RFC2616]Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.[RFC2818]Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.[RFC4516]Smith, M. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006.[RFC4791]Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, March 2007.[TZDB]Eggert, P. and A.D. Olson, "Sources for Time Zone and Daylight Saving Time Data", July 2009,<http://www.twinsun.com/tz/tz-link.htm>.[VCAL]Internet Mail Consortium, "vCalendar: The Electronic Calendaring and Scheduling Exchange Format", September 1996,<http://www.imc.org/pdi/vcal-10.txt>.
Appendix A. Differences from RFC 2445 🎀
this appendix is the big "what changed since RFC 2445" tea ☕ it's a list of every change made to the iCalendar core object spec since that version, so if you're upgrading, this is your cheat sheet 💅
A.1. New Restrictions 🔥
these are the brand-new rules, so hold on tight 🫣
- The
DTSTARTproperty SHOULD be synchronized with the recurrence rule, if specified. - The
RRULEproperty SHOULD NOT occur more than once in a component. - The
BYHOUR,BYMINUTE, andBYSECONDrule parts MUST NOT be specified in theRRULEproperty when theDTSTARTproperty is specified as a DATE value. - The value type of the
DTENDorDUEproperties MUST match the value type ofDTSTARTproperty. - The
DURATIONproperty can no longer appear inVFREEBUSYcomponents.
A.2. Restrictions Removed 🫶
good news, some rules got relaxed ✨
- The
DTSTARTandDTENDproperties are no longer required to be specified as date with local time and time zone reference when used with a recurrence rule.
A.3. Deprecated Features 💀
RIP to these, they're officially out 🪦
- The
EXRULEproperty can no longer be specified in a component. - The
THISANDPRIORvalue can no longer be used with theRANGEparameter. - The
PROCEDUREvalue can no longer be used with theACTIONproperty. - The value type
RECURno longer allows multiple values to be specified by a COMMA-separated list of values. x-namerule parts can no longer be specified in properties ofRECURvalue type (e.g.,RRULE).x-paramcan be used onRECURvalue type properties instead.
Author's Address 🌸
and here's who wrote it, bestie 🧚
Bernard Desruisseaux (editor)
Oracle Corporation
600 blvd. de Maisonneuve West
Suite 1900
Montreal, QC H3A 3J2
CANADA
EMail: bernard.desruisseaux@oracle.com
URI: http://www.oracle.com/📦 where this page comes from
- ietf: rfc5545 2009-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms