What's the difference between CREATED and DTSTAMP in the iCalendar format?

Question

In the iCalendar spec I find the following about DTSTAMP:

This property is different than the "CREATED" and "LAST-MODIFIED" properties. These two properties are used to specify when the particular calendar data in the calendar store was created and last modified. This is different than when the iCalendar object representation of the calendar service information was created or last modified.

What does that mean? I'm storing events in a database and want to generate an iCal file. I assume CREATED should be set to whenever the event was created, but what should I set DTSTAMP to?

Answer 1

VEVENT vs. an event in a calendar application

A *.ical or *.ics file, or another comparable data stream contains messages sent from one calendar application to another one. The calendar applications store events as objects.

You can enter an event in your calendar by clicking and typing, but another way is to import an ical file with VEVENT messages. Don't think of those VEVENT messages as duplicates of the application's event-objects. Think of it as duplicates of your clicking and typing.

With this idea in mind, it is easy to understand, that a VEVENT not only can create an event. It also can change an existing event, and it even can delete an event from the application.

And now let's have a look on some fields that are important in this context:

---

CREATED

This is the timestamp of when an event-object was created in a calendar application. Each event-object can be identified by a unique Identifier (UID).

---

DTSTAMP

This is the timestamp of the creation of a VEVENT-message in an ical or ics file. There are different types of such VEVENT-message, creating a new event-object is just one of them. You also can change existing events and even cancel events if you add the correct UID to the VEVENT-message to identify which event-object it belongs to. So for one event-object in your calendar application (identified by its UID) you can receive many VEVENT-events, each with its own DTSTAMP, but all referring to an event with just one CREATED date.

---

SEQUENCE

This is not a timestamp but a number (an integer). If you omit a sequence number, it is treated as SEQUENCE:0. If you have more than one VEVENTs (received in one or more files) for the same event-object (same UID), then they will be processed by increasing sequence numbers. DTSTAMP just tells you when the VEVENT was created, but it does not influence the order of execution, which is defined by the field SEQUENCE. So make sure, that every change in your callendar application sets a new DTSTAMP for VEVENT together with an incremented SEQUENCE number.

---

LAST-MODIFIED

This again is a timestamp of an object in a calendar application. When you receive an ical-file with a VEVENT-message who's DTSTAMP is today, 9 a.m., and you feed it into you application at 10 a.m., then 10 a.m. is the value of LAST-MODIFIED.

---

How can CREATED and LAST-MODIFIED make sense in VEVENT?

As shown before, CREATED and LAST-MODIFIED are properties of an object in a calendar application, while VEVENT is a message that contains properties, from which a calendar application can create, modify or delete its objects. The message can't know when you will import it into your application, so it can't know when you will create or modify the object. Or can it know? Why should those object-properties be part of the message?

The answer is: To be able to export and import the objects of a calendar application. You have two devices (lets say a mobile phone and a desktop computer) and want to keep the calendars on both devices synchronized? Then you need messages from one device sent to the other one containing all relevant data, including the timestamps for CREATED and LAST-MODIFIED.

Since VEVENT-messages are not only used to mimic clicking and typing as described above, but also to synchronized event-objects across different instances of calendar-applications, you sometimes also need CREATED and LAST-MODIFIED in VEVENT-messages.