pimutils

The Vdir storage format

This specification describes a convention for storing calendars and address books in a filesystem, with the main goal of being ease of implementation, and compatibility with existing standards.

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:

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 can be retained when synchronising to WebDAV collections.

Metadata

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

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:

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

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)