Skip to content

Latest commit

 

History

History
108 lines (78 loc) · 4.02 KB

vdir.rst

File metadata and controls

108 lines (78 loc) · 4.02 KB

The Vdir Storage Format

This document describes a standard for storing calendars and contacts on a filesystem, with the main goal of being easy to implement.

Vdirsyncer synchronizes to vdirs via :storage:`filesystem`. Each vdir (basically just a directory with some files in it) represents a calendar or addressbook.

Basic Structure

The main folder (root) contains an arbitrary number of subfolders (collections), which contain only files (items). Synonyms for "collection" may be "addressbook" or "calendar".

An item is:

  • A vCard file, in which case the file extension must be .vcf, or
  • An iCalendar file, in which case the file extension must be .ics.

An item should contain a UID property as described by the vCard and iCalendar standards. 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 would require multiple VEVENT components per event.

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.

Metadata

Any of the below metadata files may be absent. None of the files listed below have any file extensions.

  • A file called color inside the vdir indicates the vdir'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.

  • Files called displayname and description contain a UTF-8 encoded label/ description, that may be used to represent the vdir in UIs.

  • A file called order inside the vdir includes the relative order of the calendar, a property that is only relevant in UI design.

Writing to vdirs

Creating and modifying items or metadata files should happen atomically.

Writing to a temporary file on the same physical device, and then moving it to the appropriate location is usually a very 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, vdirs 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.

The reason items' filenames don't contain any extra information is simple: The solutions presented induced 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.

vdirsyncer doesn'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.