vdir: various clarifications and rewording

Author: WhyNotHugo

content/specs/vdir.md

@@ -5,103 +5,155 @@ date: 2025-03-31
 categories: specs
 ---
 
-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 [`filesystem`]. Each vdir (basically just
-a directory with some files in it) represents a calendar or address book.
-
-[`filesystem`]: https://vdirsyncer.pimutils.org/en/stable/config.html#storage-filesystem
+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
 
-The main folder (root) contains an arbitrary number of subfolders
-(collections), which contain only files (items). Synonyms for "collection" may
-be "address book" or "calendar".
+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 is:
+- A [vCard] file, in which case the file extension MUST be `.vcf`.
+- An [iCalendar] file, in which case the file extension MUST be `.ics`.
 
-- 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`.
+[vCard]: https://tools.ietf.org/html/rfc6350
+[iCalendar]: https://tools.ietf.org/html/rfc5545
 
-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.
+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
+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.
+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.
+they MUST NOT assume that the metadata they included will be preserved by other
+programs.
 
-[vCard]: https://tools.ietf.org/html/rfc6350
-[iCalendar]: https://tools.ietf.org/html/rfc5545
+Filenames SHOULD be URL-safe, such that can be retained when synchronising to
+WebDAV collections.
 
 # Metadata
 
-Any of the below metadata files may be absent. None of the files listed below
-have any file extensions.
+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 the vdir's color, a
+- 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
+  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 `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].
+
+[rfc4918 section 15.2]: https://www.rfc-editor.org/rfc/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`][ccd] and
+  [`CARDDAV:addressbook-description`][cad] properties in CalDAV and CardDAV
+  respectively.
+
+[ccd]: https://www.rfc-editor.org/rfc/rfc4791#section-5.2.1
+[cad]: https://www.rfc-editor.org/rfc/rfc6352#section-6.2.1
+
+- 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.
 
-- A file called `order` inside the vdir includes the relative order
-  of the calendar, a property that is only relevant in UI design.
+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 *should* happen [atomically].
+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.
 
 [atomically]: https://en.wikipedia.org/wiki/Atomicity_%28programming%29
 
+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 a very effective solution. For this
-purpose, files with the extension `.tmp` may be created inside collections.
+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.
+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.
+- 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.
+- 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.
 
-[CardDAV]: http://tools.ietf.org/html/rfc6352
-[CalDAV]: http://tools.ietf.org/search/rfc4791
+[CardDav]: https://www.rfc-editor.org/rfc/rfc6352
+[CalDAV]: https://www.rfc-editor.org/rfc/rfc4791
 
 ## Performance
 
-Currently, vdirs suffer from a rather major performance problem, one which
+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.
 
-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.
+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.
+
+[vdirsyncer]: https://vdirsyncer.pimutils.org/en/stable/
+[pimsync]: https://pimsync.whynothugo.nl/
+
+# 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.
+
+[the vdirsyncer documentation]: https://vdirsyncer.pimutils.org/en/stable/vdir.html
+
+## Version 1.1.0 (2025-03-31)
+
+Published this specification separately, including several clarifications and
+minor rewording.
 
-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.
+Added a recommendation for item filenames to be URL-safe.