Abstract

This specification describes a convention for storing calendars and address books in a filesystem, where each file represent an individual record, while each directory represents a collection.

Status of This Memo

This is a proposed standard currently in use by a selection of programs:

• khal: CLI calendar application
• khard: CLI vCard client
• pimsync: synchronise calendars and address books. Improved reimplementation of vdirsyncer.
• tdx: CLI todo manager for iCalendar files, written in Go
• todoman: CLI tasks manager
• vdirsyncer: synchronize calendars and address books, including data from khal and todoman

Plus some minor utilities:

• ab-bday: Generate birthday iCalendar events for vCard contacts.
• ab-tidy: Bulk-rename vCard files to match the formatted name of the contact.

Basic Structure

A main (root) directory contains an arbitrary number of subdirectories. Each subdirectory is a collection (an address book or a calendar). Each of these collections contains items, which may be contacts or calendar components (events, todos and/or journal entries) respectively.

An item may only be one of the following two types:

• A vCard file, as defined in RFC6450, in which case the file extension MUST be .vcf.
• An iCalendar file, as defined in RFC5545, in which case the file extension MUST be .ics.

An item SHOULD contain a UID property as described by the vCard and iCalendar specifications. If it contains more than one UID property, the values of those MUST NOT differ.

The file MUST contain exactly one event, task or contact. In most cases this also implies only one VEVENT/VTODO/VCARD component per file, but e.g. recurrence exceptions require multiple VEVENT components per event.

Filenames

The filename should have similar properties as the UID of the file content. However, there is no requirement for these two to be the same. Programs may choose to store additional metadata in that filename, however, at the same time they MUST NOT assume that the metadata they included will be preserved by other programs.

Filenames SHOULD be URL-safe, such that may be retained when synchronising to CalDAV (see: RFC4791) or CardDAV (see: RFC6352) collections.

Metadata

Any following metadata files may optionally be present. None of the files listed below have any file extensions.

• A file called color inside the vdir indicates that collection’s color, a property that is only relevant in UI design.

  Its content is an ASCII-encoded hex-RGB value of the form #RRGGBB. For example, a file content of #FF0000 indicates that the vdir has a red (user-visible) color. No short forms or informal values such as red (as known from CSS, for example) are allowed. The prefixing # MUST be present.

• A file called displayname contain a UTF-8 encoded label description that is suitable for presentation to the user. This property is a counterpart to the DAV:displayname WebDAV property defined in rfc4918 section 15.2.

• A description contain a UTF-8 encoded description, which provides a human-readable description of a calendar or an address book. This property is a counterpart to the CALDAV:calendar-description and CARDDAV:addressbook-description properties in CalDAV and CardDAV respectively.

• A file called order inside the vdir includes the relative order of a collection. This property is only use for presentational purposes. Its value shall be a numeric string, and collections shall be sorted relative to this value.

These properties and their names were chosen to match existing CalDAV and CardDAV properties, given that a vdir is commonly synchronised using one of these two protocols.

Property files with an invalid content SHOULD be ignored. Application software SHOULD warn the user of the invalidity when appropriate.

Writing to vdirs

Creating and modifying items or metadata files MUST happen atomically. That is, a file matching one of the extensions mentioned above must never be partially written; if it exists, it must be complete.

This requirement has two purposes:

• Ensure that one program will never read an item which has only partially been written by another tool.
• Ensure that a fatal system crash shall never result in a corrupt item.

Writing to a temporary file on the same physical device, and then moving it to the appropriate location is usually an effective solution. For this purpose, files with the extension .tmp may be created inside collections.

When changing an item, the original filename MUST be used.

Reading from vdirs

• Any file ending with the .tmp or no file extension MUST NOT be treated as an item.

• The ident part of the filename SHOULD NOT be parsed to improve the speed of item lookup.

Considerations

The primary reason this format was chosen is due to its compatibility with the CardDAV and CalDAV standards.

Performance

Currently, a vdir suffer from a rather major performance problem, one which current implementations try to mitigate by building up indices of the collections for faster search and lookup.

Item filenames convey not additional information within the scope of this specification. Any attempt to encode information in these results in duplication of data, where one duplicate might become out of date because of bad implementations. As it stands right now, an index format could be formalized separately though.

Synchronisation tools such as vdirsyncer or pimsync don’t really have to bother about efficient item lookup, because its synchronization algorithm needs to fetch the whole list of items anyway. Detecting changes is easily implemented by checking the files’ modification time.

History

Version 1.0.0

The original version of this was published as part of the vdirsyncer documentation. However, the conventions described in this document are intended to be adopted by other command line and desktop tools operating on calendar and address book collections.

Version 1.1.0 (2025-03-31)

• Publish this specification separately.
• Several minor clarifications and rewording.
• Recommend for item filenames to be URL-safe.
• Specify that properties with invalid data should be ignored.