Calendars Aren't Just Plain Data

02 Sep, 2025

I've spent the past three months working on-and-off on a Rust implementation of RFC 5545 and its various cousins called calico, after finding that the existing crates were variously either incomplete or extremely stringly-typed. Having now largely finished with the parser implementation, I thought it would be useful to stop and write down some of my thoughts.

Briefly: iCalendar

An iCalendar (.ics) file is really just a list of nested records. The grammar isn't recursive, and instead defines a fixed hierarchy of record types roughly as follows:

1. An .ics file contains zero or more calendar records.
2. Each calendar record is a component with some properties and one or more subcomponents.
3. A component is a record belonging to a calendar which may contain some properties and zero or more subcomponents.
4. A property is a record containing three elements:
   1. A name.
   2. Some optional property parameters.
   3. A value.
5. A property parameter is a key-value pair.

What makes the standard difficult to implement is the fairly complex relationship between various elements of this hierarchy, based on information that may be statically or dynamically known.¹ For example, the permissible parameters and value of a property depend on its name, and the value may also then depend on the particular arrangement of parameters. Similarly, the permissible properties and subcomponents of a component depend on its type and the presence or absence of other properties and subcomponents.

"Plain" Data

The majority of the data stored in a calendar is exactly what you would expect: simple declarations for events, TODOs, timezones, and so on. This is the raw, plain data, and is exactly the kind of thing that you could build a nice DSL for. Frankly, given that we're just concerned with records, the poor man's DSL could just be JSON or YAML.

But there are other aspects of the data that aren't really plain at all. When you define an event component, it requires both a unique identifier (UID) and a timestamp (DTSTAMP)². These values don't exist to record information that any user will see, but instead serve to manage interactions with other calendaring systems. Other values exist to track e.g. the states of attendees, whether or not they have agreed to attend, and any responses they might have sent. In all, a decent chunk of the data in an .ics file is used to negotiate interactions with external systems and record information about itself, and changes too frequently to be reasonably managed by hand.

To paraphrase, a calendar really contains two histories: the primary, nominal history it represents, and a second history about that primary history. A metahistory? More modern RFCs have introduced additional metahistory data, especially RFCs 9073 and 9074.

Why Does This Matter?

I originally began this project because I had a much more interesting goal in mind: designing a plaintext calendaring language.³ I had assumed that the interesting challenge would be designing something that could convey the primary history, with maybe some allowances for pulling in external data directly from .ics files. But it has become increasingly clear to me that the actual hard problem is in the second history: how do you neatly capture the metahistory of a file in the file itself? Can you do it without tooling support? Without metadata files?

It strikes me that people use calendars to communicate with other people just as much as (if not more than) they do to record information for themselves. I don't think a calendaring system is usable if it can't record and interact with the necessary metahistory to make those communications possible, and so I'm now pretty uncertain as to where the project goes from here.

Is there a potential user base for a simpler, plaintext calendar that eschews much of the value provided by metahistory data? Do I even fall into it myself? I genuinely don't know.

#calendars #icalendar #rust