Getting started with iCalendar hosting

Maptiming is going to provide integration with user’s online calendars. I had some basic iCalendar notions (a.k.a. iCal or ICS), but contrary to what I expected, the web is not the endless source of online tutorials, howto’s and problem solving guides if you’re talking about iCalendar…

My basic knowledge was based on using Google Agenda for syncing external calendars and for generating URL’s to sync my Google calendars into other clients. Having a peek into the contents of these URL’s gives an idea how the data is structured. But the contents of the ICS file is only part of the iCalendar story…

This list of standards is copied from the iCalendar wikipage:

  • RFC 5545 Internet Calendaring and Scheduling Core Object Specification (iCalendar)
  • RFC 5546 iCalendar Transport-Independent Interoperability Protocol (iTIP)
  • RFC 6047 iCalendar Message-Based Interoperability Protocol (iMIP)

For browsing the first iCalendar standard, I appreciate the htmlified version on

My first reading was the iCalendar standard, and it didn’t really help, because it only describes how an ICS file looks like, but very little on how to use it. I learned about VEVENT structure, but the use of UID, SEQUENCE and STATUS fields was puzzling me. Here is where my main misconception started: I considered iCalendar to be a file format, like HTML is a file format, and that managing calendar data was all about setting up a host providing (static or dynamic) ICS files on the one hand and downloading and viewing these files in a client on the other, just like you setup a webpage by hosting a set of static or dynamic HTML files and download and view them in a browser.


But that’s not the basic idea of iCalendar. The ICS files are carriers of a message, or a ‘method’ as it’s called in iCalendar terms, not fixed sets of data. Actually the wiki says it loud and clear, but you tend to overlook these statements if you believe you already got the idea by yourself: “iCalendar is a computer file format which allows Internet users to send meeting requests and tasks to other Internet users, via email, or sharing files with an extension of .ics.” The actual datasets (= the calendars) only exist on the side of the sender or the receiver. The messages are used to build up and synchronize the calendars on both ends.

The ‘methods’ are not explained in the iCalendar standard, but in the iTIP standard, and reading of this second standard clarified a lot. These are the supported methods as listed on page 8 of the standard:

  • PUBLISH: Used to publish an iCalendar object to one or more “Calendar Users”. There is no interactivity between the publisher and any other “Calendar User”. An example might include a baseball team publishing its schedule to the public.
  • REQUEST: Used to schedule an iCalendar object with other “Calendar Users”. Requests are interactive in that they require the receiver to respond using the reply methods. Meeting requests, busy-time requests, and the assignment of tasks to other “Calendar Users” are all examples. Requests are also used by the Organizer to update the status of an iCalendar object.
  • REPLY: A reply is used in response to a request to convey Attendee status to the Organizer. Replies are commonly used to respond to meeting and task requests.
  • ADD: Add one or more new instances to an existing recurring iCalendar object.
  • CANCEL: Cancel one or more instances of an existing iCalendar object.
  • REFRESH: Used by an Attendee to request the latest version of an iCalendar object.
  • COUNTER: Used by an Attendee to negotiate a change in an iCalendar object. Examples include the request to change a proposed event time or change the due date for a task.
  • DECLINECOUNTER: Used by the Organizer to decline the proposed counter proposal.

When you’re using some calendar client that allows you to setup meetings and invite others, you’ll recognize these ‘methods’. Then you also know that setting up a meeting is all about exchanging messages: you send an invitation, the invetees respond by accepting the invitation, declining or sending a counter proposal. When you change the meeting, the invitees again get an update message, and so on. All of these messages are in fact nothing more than ICS files transported over mail. But mail is only a carrier of the message and as such not part of iCalendar. You can exchange these ICS messages via different channels, as is also said on the wiki: “iCalendar is designed to be independent of the transport protocol. For example, certain events can be sent by traditional email or whole calendar files can be shared and edited by using a WebDav server, or SyncML. Simple web servers (using just the HTTP protocol) are often used to distribute iCalendar data about an event and to publish busy times of an individual.”

Not only is ICS independent of the communication channel, it is also indepent of the applications that produce or consume these messages, like e.g. your calendar client or the Google Agenda servers. Again from the wiki: “The iCalendar format is designed to transmit calendar-based data, such as events, and intentionally does not describe what to do with that data.”


For my application, MapTiming, I want to keep it simple. I just want to publish events and I don’t need the participants to reply. That means that I’ll only be using the PUBLISH method. Still I want people to stay up to date if events change or get cancelled. It seems like the standard is not up to this! Luckily most calendar clients support syncing of calendar data, which is giving the client an URL for polling an ICS file with method PUBLISH. If the file changes, this is reflected in the local calendar. Each event must therefor have a globally unique UID, so each time an ICS message (file) is transferred, the receiver can identify if it contains information about events that it already knows.

Using the PUBLISH method can go a long way, maybe up to misuse of the standard? I was at some point imagining that it would be nice if users could ‘subscribe’ to an event by providing their email address, so I could send them PUBLISH messages with updated information via mail, rather than having them to sync an URL in their personal calendar. This approach would be more user-friendly, because calendar clients are in general capable of automatically processing an ICS email attachment into one’s personal agenda, but automatically adding a URL as a synced calendar is not always supported, and many people will have a hard time figuring out how to add a subscription to their calendar client. But then it rapidly becomes more complicated, because in my back-end, I must manage these subscriptions and I must foresee the means to unsubscribe and so on… And doing all this, it seems like I’m re-invinting the wheel, since the standard provides all of these features by using REQUEST messages with all the follow-up messages for keeping invitees up to date… But if I want to do this properly, I’m almost rewriting my own Google Agenda server, and that’s overkill.


For now, my conclusion is that if you want to keep users up to date, you either PUBLISH your (dynamic) data on some URL and rely on your users to sync the URL in their calendar, or you ask them for an email address, so you can send them a REQUEST message and follow-up messages if needed. Mixing these up seems like misusing the standard. Or isn’t it? I feel a bit of unease, knowing that syncing calendar URL’s may not be the most user-friendly approach. But this is mainly a concern for the way clients handle the calendar URL, and it can improve over time. With the proper protocal (webdav://, even for read-only ICS data) and the proper headers (“Content-Type: text/calendar; charset=UTF-8; method=PUBLISH”) it should be possible to trigger the client into registering the calendar as a synced calendar and not e.g. into just copying the data to the local calendar and ignoring the URL afterwards…

Probably more on that after doing some more reading and/or testing…

This post is open for comments…


  1. Did you ever make any progress with this?


    1. Hi, actually I didn’t dive into the matter again, sorry… I’m convinced that all technology is there, but so few services are actually using it.


Leave a Reply

Your email address will not be published. Required fields are marked *