=======================
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.

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.

The filename *must* consist of the ``ident``, followed by the file extension.
The ``ident`` is either the ``UID``, if the item has one, else a string with
similar properties as the ``UID``:

   Type name: UID

   Type purpose: To specify a value that represents a globally unique
   identifier corresponding to the individual or resource associated
   with the vCard.

   -- The vCard_ RFC

One reason this format was chosen is due to its compatibility with the CardDAV_
and CalDAV_ standards.

.. _vCard: https://tools.ietf.org/html/rfc6350
.. _iCalendar: https://tools.ietf.org/html/rfc5545
.. _CardDAV: http://tools.ietf.org/html/rfc6352
.. _CalDAV: http://tools.ietf.org/search/rfc4791

Writing to vdirs
================

Creating and modifying items *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.

.. _atomically: https://en.wikipedia.org/wiki/Atomicity_%28programming%29

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.