iCalendar

Greetings,

iCalendar is a "data format for representing and exchanging calendaring and scheduling information such as events, to-dos, journal entries, and free/busy information, independent of any particular calendar service or protocol."

The iCalendar data format is specified in RFC 5545.

Quick summary of the iCalendar format

An iCalendar file contains one or more iCalendar objects. Each iCalendar object has a sequence of properties followed by one or more components. Each component has properties that describe the component. A few of the components may nest other components. Each property has a value. Each property may have metadata. The metadata is called parameters. Thus, each property has a value and zero or more parameters.

Purpose of this web page

What parameters (metadata) may be associated to each property? How is each component characterized; that is, what properties are used to describe each component? The purpose of this document is to answer those questions using a friendly table format, with plenty of links to appropriate sections in the specification.

Kinda neat how I created this web page

This web page was auto-generated from this XML document. This XSLT program was used to transform the XML document to HTML.

Let's go!

Now, click on these links to see tables of iCalendar information:

Properties and their parameters

Parameters and their values

Components and their properties

iCalendar datatypes

Complete list of codependencies

The minimal freebusy

Created by Roger Costello, September 1, 2017.

Top

(*) Notes

vevent: There may be either dtend or duration, or neither. But not both.

vtodo: There may be either due or duration, or neither. But not both. If duration occurs, then dtstart must also occur.

valarm (action=audio): There must be both duration and repeat, or neither.

valarm (action=display): There must be both duration and repeat, or neither.

valarm (action=email): There must be both duration and repeat, or neither.

Nested Components

An iCalendar object contains one or more of these components: vevent, vtodo, vjournal, vfreebusy, vtimezone, iana-comp, x-comp.

A vevent component contains zero or more valarm components.

A vtodo component contains zero or more valarm components.

A vtimezone component contains either one or more standard component or one or more daylight components.

Top

Parameters

altrep

cn

cutype

delegated-from

delegated-to

dir

encoding

fmttype

fbtype

iana

language

member

non-standard

partstat

range

related

reltype

role

rsvp

sent-by

tzid

value

iCalendar Datatypes

binary

boolean

cal-address

date

date-time

duration

float

integer

period

recur

text

time

uri

utc-offset

Top

iCalendar Codependencies

1. The CALSCALE property can be specified *once* in an iCalendar object.
2. The METHOD property can be specified *once* in an iCalendar object.
3. The PRODID property MUST be specified in an iCalendar object.
4. The PRODID property MUST be specified *once* in an iCalendar object.
5. The VERSION property MUST be specified in an iCalendar object.
6. The VERSION property MUST be specified *once* in an iCalendar object.
7. The CALSCALE property cannot be specified within a component.
8. The METHOD property cannot be specified within a component.
9. The PRODID property cannot be specified within a component.
10. The VERSION property cannot be specified within a component.
11. An iCalendar object MUST include at least one calendar component.
12. An iCalendar object may contain only these components: VEVENT, VTODO, VJOURNAL, VFREEBUSY, VTIMEZONE.
13. The DTSTAMP property MUST be specified in a vevent component.
14. The DTSTAMP property MUST occur *once* in a vevent component.
15. The UID property MUST be specified in a vevent component.
16. The UID property MUST occur *once* in a vevent component.
17. The DTSTART property is REQUIRED in a vevent component if the iCalendar object does not specify a METHOD property.
18. The CLASS property MUST NOT occur more than *once* in a vevent component.
19. The CREATED property MUST NOT occur more than *once* in a vevent component.
20. The DESCRIPTION property MUST NOT occur more than *once* in a vevent component.
21. The GEO property MUST NOT occur more than *once* in a vevent component.
22. The LAST-MOD property MUST NOT occur more than *once* in a vevent component.
23. The LOCATION property MUST NOT occur more than *once* in a vevent component.
24. The ORGANIZER property MUST NOT occur more than *once* in a vevent component.
25. The PRIORITY property MUST NOT occur more than *once* in a vevent component.
26. The SEQ property MUST NOT occur more than *once* in a vevent component.
27. The STATUS property MUST NOT occur more than *once* in a vevent component.
28. The SUMMARY property MUST NOT occur more than *once* in a vevent component.
29. The TRANSP property MUST NOT occur more than *once* in a vevent component.
30. The URL property MUST NOT occur more than *once* in a vevent component.
31. The RECURRENCE-ID property MUST NOT occur more than *once* in a vevent component.
32. A vevent component may contain either the DTEND property or the DURATION property, but not both.
33. If a vevent component has a DTSTART property with a DATE value, then the DTEND property (if it exists) must have a DATE value.
34. If a vevent component has a DTSTART property with a DATE value and a DTEND property with a DATE value and the DTEND property value is set to a calendar date after the DTSTART property value, then if such a vevent has a DURATION property, it MUST be specified as a "dur-day" or "dur-week" value.
35. A vevent component cannot be nested within another calendar component.
36. The only nested component allowed in a vevent component is the valarm component.
37. A vevent component may contain only these properties: dtstamp, uid, dtstart, class, created, description, geo, last-mod, location, organizer, priority, seq, status, summary, transp, url, recurid, rrule, dtend, duration, attach, attendee, categories, comment, contact, exdate, rstatus, related, resources, rdate
38. If a vevent component contains nested valarm component(s), the valarm component(s) must be last, i.e., no properties may occur after the valarm component(s).
39. The DTSTAMP property MUST be specified in a vtodo component.
40. The DTSTAMP property MUST occur *once* in a vtodo component.
41. The UID property MUST be specified in a vtodo component.
42. The UID property MUST occur *once* in a vtodo component.
43. The CLASS property MUST NOT occur more than *once* in a vtodo component.
44. The COMPLETED property MUST NOT occur more than *once* in a vtodo component.
45. The CREATED property MUST NOT occur more than *once* in a vtodo component.
46. The DESCRIPTION property MUST NOT occur more than *once* in a vtodo component.
47. The DTSTART property MUST NOT occur more than *once* in a vtodo component.
48. The GEO property MUST NOT occur more than *once* in a vtodo component.
49. The LAST-MOD property MUST NOT occur more than *once* in a vtodo component.
50. The LOCATION property MUST NOT occur more than *once* in a vtodo component.
51. The ORGANIZER property MUST NOT occur more than *once* in a vtodo component.
52. The PERCENT-COMPLETE property MUST NOT occur more than *once* in a vtodo component.
53. The PRIORITY property MUST NOT occur more than *once* in a vtodo component.
54. The RECURRENCE-ID property MUST NOT occur more than *once* in a vtodo component.
55. The SEQ property MUST NOT occur more than *once* in a vtodo component.
56. The STATUS property MUST NOT occur more than *once* in a vtodo component.
57. The SUMMARY property MUST NOT occur more than *once* in a vtodo component.
58. The URL property MUST NOT occur more than *once* in a vtodo component.
59. The DUE property MUST NOT occur more than *once* in a vtodo component.
60. A vtodo component may contain either the DUE property or the DURATION property, but not both.
61. If the DURATION property occurs in a vtodo component, then DTSTART must also occur.
62. A vtodo component cannot be nested within another calendar component.
63. The only nested component allowed in a vtodo component is the valarm component.
64. A vtodo component may contain only these properties: dtstamp, uid, class, completed, created, description, dtstart, geo, last-mod, location,organizer, percent, priority, recurid, seq, status, summary, url, rrule, due, duration, attach, attendee, categories, comment, contact, exdate, rstatus, related, resources, rdate.
65. If a vtodo component contains nested valarm component(s), the valarm component(s) must be last, i.e., no properties may occur after the valarm component(s).
66. The DTSTAMP property MUST be specified in a vjournal component.
67. The DTSTAMP property MUST occur *once* in a vjournal component.
68. The UID property MUST be specified in a vjournal component.
69. The UID property MUST occur *once* in a vjournal component.
70. The CLASS property MUST NOT occur more than *once* in a vjournal component.
71. The CREATED property MUST NOT occur more than *once* in a vjournal component.
72. The DTSTART property MUST NOT occur more than *once* in a vjournal component.
73. The LAST-MOD property MUST NOT occur more than *once* in a vjournal component.
74. The ORGANIZER property MUST NOT occur more than *once* in a vjournal component.
75. The RECURRENCE-ID property MUST NOT occur more than *once* in a vjournal component.
76. The SEQ property MUST NOT occur more than *once* in a vjournal component.
77. The STATUS property MUST NOT occur more than *once* in a vjournal component.
78. The SUMMARY property MUST NOT occur more than *once* in a vjournal component.
79. The URL property MUST NOT occur more than *once* in a vjournal component.
80. The RRULE property MUST NOT occur more than *once* in a vjournal component.
81. A vjournal component may contain only these properties: dtstamp, uid, class, created, dtstart, last-mod, organizer, recurid, seq, status, summary, url, rrule, attach, attendee, categories, comment, contact, description, exdate, related, rdate, rstatus.
82. No nested components allowed in a vjournal component.
83. A vjournal component cannot be nested within another calendar component.
84. The DTSTAMP property MUST be specified in a vfreebusy component.
85. The DTSTAMP property MUST occur *once* in a vfreebusy component.
86. The UID property MUST be specified in a vfreebusy component.
87. The UID property MUST occur *once* in a vfreebusy component.
88. The CONTACT property MUST NOT occur more than *once* in a vfreebusy component.
89. The DTSTART property MUST NOT occur more than *once* in a vfreebusy component.
90. The DTEND property MUST NOT occur more than *once* in a vfreebusy component.
91. The ORGANIZER property MUST NOT occur more than *once* in a vfreebusy component.
92. The URL property MUST NOT occur more than *once* in a vfreebusy component.
93. A vfreebusy component may contain only these properties: dtstamp, uid, contact, dtstart, dtend, organizer, url, attendee, comment, freebusy, rstatus.
94. The RRULE property MUST NOT occur in a vfreebusy component.
95. The RDATE property MUST NOT occur in a vfreebusy component.
96. The EXDATE property MUST NOT occur in a vfreebusy component.
97. No nested components allowed in a vfreebusy component.
98. A vfreebusy component cannot be nested within another calendar component.
99. The TZID property MUST be specified in a vtimezone component.
100. The TZID property MUST occur *once* in a vtimezone component.
101. The LAST-MOD property MUST NOT occur more than *once* in a vtimezone component.
102. The only nested components allowed in a vtimezone component are the standard and daylight components.
103. The vtimezone component MUST include a standard component or a daylight component.
104. If a vtimezone component contains a standard component, then it MUST NOT contain a daylight component.
105. If a vtimezone component contains a daylight component, then it MUST NOT contain a standard component.
106. A vtimezone component may contain only these properties: tzid, last-mod, tzurl.
107. A vtimezone component cannot be nested within another calendar component.
108. The DTSTART property MUST be specified in a standard component.
109. The DTSTART property MUST occur *once* in a standard component.
110. The TZOFFSETTO property MUST be specified in a standard component.
111. The TZOFFSETTO property MUST occur *once* in a standard component.
112. The TZOFFSETFROM property MUST be specified in a standard component.
113. The TZOFFSETFROM property MUST occur *once* in a standard component.
114. The RRULE property MUST NOT occur more than *once* in a standard component.
115. A standard component may contain only these properties: dtstart, tzoffsetto, tzoffsetfrom, rrule, comment, rdate, tzname.
116. No nested components allowed in a standard component.
117. The DTSTART property MUST be specified in a daylight component.
118. The DTSTART property MUST occur *once* in a daylight component.
119. The TZOFFSETTO property MUST be specified in a daylight component.
120. The TZOFFSETTO property MUST occur *once* in a daylight component.
121. The TZOFFSETFROM property MUST be specified in a daylight component.
122. The TZOFFSETFROM property MUST occur *once* in a daylight component.
123. The RRULE property MUST NOT occur more than *once* in a daylight component.
124. A daylight component may contain only these properties: dtstart, tzoffsetto, tzoffsetfrom, rrule, comment, rdate, tzname.
125. No nested components allowed in a daylight component.
126. The ACTION property MUST be specified in a valarm component.
127. The ACTION property MUST occur *once* in a valarm component.
128. The TRIGGER property MUST be specified in a valarm component.
129. The TRIGGER property MUST occur *once* in a valarm component.
130. No nested components allowed in a valarm component.
131. The valarm component with ACTION=AUDIO MUST include a duration property or a repeat property.
132. If a valarm component with ACTION=AUDIO contains a duration property, then it MUST NOT contain a repeat property.
133. If a valarm component with ACTION=AUDIO contains a repeat property, then it MUST NOT contain a duration property.
134. The ATTACH property MUST NOT occur more than *once* in a valarm component with ACTION=AUDIO.
135. A valarm component with ACTION=AUDIO may contain only these properties: action, trigger, duration, repeat, attach.
136. A valarm component with ACTION=DISPLAY MUST contain a description property.
137. The DESCRIPTION property MUST occur *once* in a valarm component with ACTION=DISPLAY.
138. The valarm component with ACTION=AUDIO MUST include a duration property or a repeat property.
139. If a valarm component with ACTION=DISPLAY contains a duration property, then it MUST contain a repeat property.
140. If a valarm component with ACTION=DISPLAY contains a repeat property, then it MUST contain a duration property.
141. A valarm component with ACTION=DISPLAY may contain only these properties: action, trigger, description, duration, repeat.
142. A valarm component with ACTION=EMAIL MUST contain a description property.
143. The DESCRIPTION property MUST occur *once* in a valarm component with ACTION=EMAIL.
144. A valarm component with ACTION=EMAIL MUST contain a summary property.
145. The SUMMARY property MUST occur *once* in a valarm component with ACTION=EMAIL.
146. A valarm component with ACTION=EMAIL MUST contain an attendee property.
147. The valarm component with ACTION=EMAIL MUST include a duration property or a repeat property.
148. If a valarm component with ACTION=EMAIL contains a duration property, then it MUST contain a repeat property.
149. If a valarm component with ACTION=EMAIL contains a repeat property, then it MUST contain a duration property.
150. The ATTACH property MUST NOT occur more than *once* in a valarm component with ACTION=EMAIL.
151. A valarm component with ACTION=EMAIL may contain only these properties: action, trigger, description, summary, attendee, duration, repeat, attach.
152. If the DTEND property has a VALUE parameter, the value of the VALUE parameter must be either DATE-TIME or DATE.
153. The DTEND property may have a VALUE parameter. The VALUE parameter MUST NOT occur more than *once*.
154. The value of VALUE of DTEND MUST be the same as the DTSTART property
155. The value of DTEND MUST be later in time than the value of the DTSTART property.
156. The DTEND 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.
157. The DTEND property may have a TZID parameter. The TZID parameter MUST NOT occur more than *once*.
158. Within the VFREEBUSY calendar component, the DTEND property defines the end date and time for the free or busy time information. The time MUST be specified in the UTC time format.
159. If the DTEND property has a VALUE parameter and its value is 'DATE-TIME' (or there is no VALUE parameter), and the value of DTEND is not either a UTC or a "floating" time, then the TZID parameter MUST be specified.
160. If the DTSTART property has a VALUE parameter, the value of the VALUE parameter must be either DATE-TIME or DATE.
161. The DTSTART property may have a VALUE parameter. The VALUE parameter MUST NOT occur more than *once*.
162. The DTSTART property may have a TZID parameter. The TZID parameter MUST NOT occur more than *once*.
163. If the DTSTART property has a VALUE parameter and its value is 'DATE-TIME' (or there is no VALUE parameter), and the value of DTSTART is not either a UTC or a "floating" time, then the TZID parameter MUST be specified.
164. An individual VTIMEZONE calendar component MUST be specified for each unique TZID parameter value specified in the iCalendar object. The value of the TZID property parameter MUST equal the value of the TZID property for the matching time zone definition. The TZID parameter in VEVENT must match a TZID property in a VTIMEZONE component.
165. An individual VTIMEZONE calendar component MUST be specified for each unique TZID parameter value specified in the iCalendar object. The value of the TZID property parameter MUST equal the value of the TZID property for the matching time zone definition. The TZID parameter in VTODO must match a TZID property in a VTIMEZONE component.
166. An individual VTIMEZONE calendar component MUST be specified for each unique TZID parameter value specified in the iCalendar object. The value of the TZID property parameter MUST equal the value of the TZID property for the matching time zone definition. The TZID parameter in VJOURNAL must match a TZID property in a VTIMEZONE component.
167. An individual VTIMEZONE calendar component MUST be specified for each unique TZID parameter value specified in the iCalendar object. The value of the TZID property parameter MUST equal the value of the TZID property for the matching time zone definition. The TZID parameter in VFREEBUSY must match a TZID property in a VTIMEZONE component.
168. If the DUE property has a VALUE parameter, the value of the VALUE parameter must be either DATE-TIME or DATE.
169. The DUE property may have a VALUE parameter. The VALUE parameter MUST NOT occur more than *once*.
170. The value of VALUE of DUE MUST be the same as the DTSTART property
171. The value of DUE MUST be later in time than the value of the DTSTART property.
172. The DUE 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.
173. The DUE property may have a TZID parameter. The TZID parameter MUST NOT occur more than *once*.
174. If the DUE property has a VALUE parameter and its value is 'DATE-TIME' (or there is no VALUE parameter), and the value of DUE is not either a UTC or a "floating" time, then the TZID parameter MUST be specified.
175. When the DURATION property relates to a DTSTART property that is specified as a DATE value, then the DURATION property MUST be specified as a dur-day or dur-week. value.
176. The FREEBUSY time periods can be specified as either a start and end DATE-TIME or a start DATE-TIME and DURATION. The date and time MUST be a UTC time format.
177. The FREEBUSY property may have a FBTYPE parameter. The FBTYPE parameter MUST NOT occur more than *once*.
178. The "FREEBUSY" property can specify more than one value, separated by the COMMA character. In such cases, the "FREEBUSY" property values MUST all be of the same "FBTYPE" property parameter type (e.g., all values of a particular "FBTYPE" listed together in a single property).
179. The value of the TRANSP property must be either OPAQUE or TRANSPARENT.
180. The TZNAME property may have a LANGUAGE parameter. The LANGUAGE parameter MUST NOT occur more than *once*.
181. The CN parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
182. The CN parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
183. The ROLE parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
184. The ROLE parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
185. The PARTSTAT parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
186. The PARTSTAT parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
187. The RSVP parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
188. The RSVP parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
189. The CUTYPE parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
190. The CUTYPE parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
191. The MEMBER parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
192. The MEMBER parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
193. The DELEGATED-TO parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
194. The DELEGATED-TO parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
195. The DELEGATED-FROM parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
196. The DELEGATED-FROM parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
197. The SENT-BY parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
198. The SENT-BY parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
199. The DIR parameter MUST NOT be used with an ATTENDEE property that is within a VFREEBUSY.
200. The DIR parameter MUST NOT be used with an ATTENDEE property that is within a VALARM.
201. The CONTACT property may have a ALTREP parameter. The ALTREP parameter MUST NOT occur more than *once*.
202. The CONTACT property may have a LANGUAGE parameter. The LANGUAGE parameter MUST NOT occur more than *once*.
203. The ORGANIZER property may have a CN parameter. The CN parameter MUST NOT occur more than *once*.
204. The ORGANIZER property may have a DIR parameter. The DIR parameter MUST NOT occur more than *once*.
205. The ORGANIZER property may have a SENT-BY parameter. The SENT-BY parameter MUST NOT occur more than *once*.
206. The ORGANIZER property may have a LANGUAGE parameter. The LANGUAGE parameter MUST NOT occur more than *once*.
207. If the RECURID property has a VALUE parameter, the value of the VALUE parameter must be either DATE-TIME or DATE.
208. The RECURID property may have a VALUE parameter. The VALUE parameter MUST NOT occur more than *once*.
209. The value of VALUE of RECURID MUST be the same as the DTSTART property
210. The RECURID 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.
211. The RECURID property may have a TZID parameter. The TZID parameter MUST NOT occur more than *once*.
212. The RECURID property may have a RANGE parameter. The RANGE parameter MUST NOT occur more than *once*.
213. The RELATED-TO property can only be used in the "VEVENT", "VTODO", and "VJOURNAL" calendar components.
214. The RELATED-TO property may have a RELTYPE parameter. The RELTYPE parameter MUST NOT occur more than *once*.
215. The "RELTYPE" property parameter is used to either explicitly state the default PARENT relationship type to the referenced calendar component or to override the default PARENT relationship type and specify either a CHILD or SIBLING relationship.
216. The URL property can only be used in the "VEVENT", "VTODO", "VJOURNAL" and "VFREEBUSY" calendar components.
217. The URL property MUST NOT occur more than *once*.
218. The URL property has no parameters.
219. The UID property can only be used in the "VEVENT", "VTODO", "VJOURNAL" and "VFREEBUSY" calendar components.
220. Implementations MUST be able to receive and persist values of at least 255 octets for the UID property, and they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.
221. The UID property has no parameters.
222. If the EXDATE property has a VALUE parameter, the value of the VALUE parameter must be either DATE-TIME or DATE.
223. The EXDATE property may have a VALUE parameter. The VALUE parameter MUST NOT occur more than *once*.
224. The EXDATE property may have a TZID parameter. The TZID parameter MUST NOT occur more than *once*.
225. The EXDATE property can only be used in the "VEVENT", "VTODO", "VJOURNAL", "STANDARD", and "DAYLIGHT" calendar components.
226. If the RDATE property has a VALUE parameter, the value of the VALUE parameter must be either DATE-TIME, DATE, or PERIOD.
227. The RDATE property may have a VALUE parameter. The VALUE parameter MUST NOT occur more than *once*.
228. The RDATE property may have a TZID parameter. The TZID parameter MUST NOT occur more than *once*.
229. The RDATE property can only be used in the "VEVENT", "VTODO", "VJOURNAL", "STANDARD", and "DAYLIGHT" calendar components.
230. The RRULE SHOULD NOT be specified more than once. The recurrence set generated with multiple "RRULE" properties is undefined.
231. Use "DTSTART" with "RRULE". The "DTSTART" property specified within the iCalendar object defines the first instance of the recurrence.
232. Use a TZID parameter with DTSTART when there is a RRULE. In most cases, a "DTSTART" property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.
233. The RDATE property can only be used in the "VEVENT", "VTODO", "VJOURNAL", "STANDARD", and "DAYLIGHT" calendar components.

Top

The Minimal Freebusy

There is a theoretical minimal set of properties. But in practice, a freebusy object containing the minimal set of properties is not useful. Additional properties must be provided. The following table summarizes the properties needed for each use of freebusy.

A freebusy component is nested within an iCalendar object. Every iCalendar object must have at least two properties: prodid and version. The prodid property identifies the application used to create the object. For example, Microsoft Outlook produces this:

PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN

The version property identifies which version of the iCalendar specification the object conforms to. A value of "2.0" corresponds to the latest specification.

VERSION:2.0

Here is the skeletal structure of an iCalendar object containing a freebusy component:

BEGIN:VCALENDAR
PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN
VERSION:2.0
BEGIN:VFREEBUSY
...
END:VFREEBUSY
END:VCALENDAR
                            

There are only two required properties in a freebusy component: dtstamp and uid. The dtstamp property specifies when the iCalendar data was last modified (or, depending on the use of freebusy, when it was created). Here’s an example of this property:

DTSTAMP:20170828T114600Z

Read that as: The object was last modified on August 28, 2017 at 11:46am Zulu.

The value of a uid property represents a globally unique identifier for the component. Here’s an example:

UID:20170828T114600Z@example.com

So, here is a minimal iCalendar object containing a freebusy component:

BEGIN:VCALENDAR
PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN
VERSION:2.0
BEGIN:VFREEBUSY
DTSTAMP:20170828T114600Z
UID:20170828T114600Z@example.com
END:VFREEBUSY
END:VCALENDAR
                                

However, that is just a theoretical object. It has no practical use.

There are three common uses for freebusy:

1. Request: I want to know when you are free or busy, so I send you a request for free/busy information.
2. Reply: You reply to my request for free/busy information.
3. Publish: I want to publish, to whoever happens to view my calendar, the times that I am busy.

To accomplish these, additional properties are required, above and beyond the theoretic minimum.

Request for Free/Busy Information

Here are the additional properties needed to make a request for free/busy information: The attendee property specifies the calendar users whose free/busy time is being requested. The organizer property specifies the calendar user who is requesting the free/busy time. The dtstart and dtend properties specify the window of time for which free/busy information is requested.

The following example is a request by Jane Doe for free/busy information of John Public and Sally Smith for the period September 1, 2017 to September 2, 2017.

BEGIN:VCALENDAR
PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN
VERSION:2.0 
METHOD:REQUEST
BEGIN:VFREEBUSY
DTSTAMP:20170828T114600Z
UID:20170828T114600Z@example.com
ORGANIZER:mailto:jane_doe@example.com
ATTENDEE:mailto:john_public@example.com
ATTENDEE:mailto:sally_smith@example.com
DTSTART:20170901T000000Z
DTEND:20170902T000000Z
END:VFREEBUSY
END:VCALENDAR
                                

Reply to a Request for Free/Busy Information

Here are the additional properties needed to reply to a request for free/busy information: The attendee property specifies the calendar user responding to the free/busy time request. The organizer property specifies the calendar user that originally requested the free/busy time. The freebusy property specifies the times when the user is busy and the times when the user is free.

The following example is John Public’s reply to a request by Jane Doe for free/busy information. John Public is busy up to 10am and then busy again after noon. He is free between 10am and noon.

BEGIN:VCALENDAR
PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN
VERSION:2.0 
METHOD:REPLY
BEGIN:VFREEBUSY
DTSTAMP:20170828T114600Z
UID:20170828T114600Z@example.com
ORGANIZER:mailto:jane_doe@example.com
ATTENDEE:mailto:john_public@example.com
DTSTART:20170901T000000Z
DTEND:20170902T000000Z
FREEBUSY;FBTYPE=BUSY:20170901T000000Z/20170901T100000Z
FREEBUSY;FBTYPE=FREE:20170901T100001Z/20170901T120000Z
FREEBUSY;FBTYPE=BUSY:20170901T120001Z/20170902T000000Z
END:VFREEBUSY
END:VCALENDAR
                                

Publish Busy Times

The third use of the freebusy component is for publishing busy times. The organizer property specifies the calendar user associated with the published busy times. The dtstart and dtend properties specify an inclusive time window that surrounds the busy times information. The freebusy property specifies the published busy time information. The dtstamp property specifies the date-time that the iCalendar object was created.

The following example shows the times that Jane Doe is busy: between September 1 and September 2 she is busy up to 10am and after noon.

BEGIN:VCALENDAR
PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN
VERSION:2.0
METHOD:PUBLISH
BEGIN:VFREEBUSY
DTSTAMP:20170828T114600Z
UID:20170828T114600Z@example.com
ORGANIZER:mailto:jane_doe@example.com
DTSTART:20170901T000000Z
DTEND:20170902T000000Z
FREEBUSY;FBTYPE=BUSY:20170901T000000Z/20170901T100000Z
FREEBUSY;FBTYPE=BUSY:20170901T120001Z/20170902T000000Z
END:VFREEBUSY
END:VCALENDAR
                                

Top