Fork me on GitHub

JMAP Calendars

This document specifies a data model for synchronising calendar data with a server using JMAP.

Introduction

JMAP is a generic protocol for synchronising data, such as mail, calendars or contacts, between a client and a server. It is optimised for mobile and web environments, and aims to provide a consistent interface to different data types.

This specification defines a data model for synchronising calendar data between a client and a server using JMAP.

Notational conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [@!RFC2119].

Type signatures, examples and property descriptions in this document follow the conventions established in Section 1.1 of https://tools.ietf.org/html/draft-ietf-jmap-core-05.

Object properties may also have a set of attributes defined along with the type signature. These have the following meanings:

Data types defined in the core specification are used in this document.

The Date datatypes

Where LocalDate is given as a type, it means a string in the same format as Date, but with the time-offset omitted from the end. The interpretation in absolute time depends upon the time zone for the event, which may not be a fixed offset (for example when daylight saving time occurs). For example, "2014-10-30T14:12:00".

Terminology

The same terminology is used in this document as in the core JMAP specification.

Addition to the capabilities object

The capabilities object is returned as part of the standard JMAP Session object; see the JMAP spec. Servers supporting this specification MUST add a property called {TODO: URI for this spec} to the capabilities object. The value of this is an empty object.

Calendars

A Calendar is a named collection of events. All events are associated with one, and only one, calendar.

A Calendar object has the following properties:

Calendar/get

Standard “/get” method. The ids argument may be null to fetch all at once.

Calendar/changes

Standard “/changes” method.

Calendar/set

Standard “/set” method.

A calendar MAY be deleted that is currently associated with one or more events. In this case, the events belonging to this calendar MUST also be deleted. Conceptually, this MUST happen prior to the calendar itself being deleted, and MUST generate a push event that modifies the state of the CalendarEvent type for the account.

Calendar events

A CalendarEvent object contains information about an event, or recurring series of events, that takes place at a particular time. It is a JSEvent object, as defined in https://tools.ietf.org/html/draft-ietf-calext-jscalendar-00, with the following additional properties:

CalendarEvent/get

Standard “/get” method.

CalendarEvent/changes

Standard “/changes” method

CalendarEvent/set

Standard “/set” method.

When an event is created, updated or destroyed, the server MUST also ensure the following:

CalendarEvent/copy

Standard “/copy” method.

CalendarEvent/query

Standard “/query” method.

Filtering

A FilterCondition object has the following properties:

If zero properties are specified on the FilterCondition, the condition MUST always evaluate to true. If multiple properties are specified, ALL must apply for the condition to be true (it is equivalent to splitting the object into one-property conditions and making them all the child of an AND filter operator).

The exact semantics for matching String fields is deliberately not defined to allow for flexibility in indexing implementation, subject to the following:

Sorting

The following properties MUST be supported for sorting:

CalendarEvent/queryChanges

Standard “/queryChanges” method.