Fork me on GitHub

JMAP Calendars

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


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

The underlying format used for this specification is JSON. Consequently, the terms “object” and “array” as well as the four primitive types (strings, numbers, booleans, and null) are to be interpreted as described in Section 1 of [@!RFC7159]. Unless otherwise noted, all the property names and values are case sensitive.

Some examples in this document contain “partial” JSON documents used for illustrative purposes. In these examples, three periods “…” are used to indicate a portion of the document that has been removed for compactness.

Types signatures are given for all JSON objects in this document. The following conventions are used:

The Date datatypes

Where Date is given as a type, it means a string in [@!RFC3339] date-time format. To ensure a normalised form, the time-secfrac MUST always be omitted and any letters in the string (e.g. “T” and “Z”) MUST be upper-case. For example, "2014-10-30T14:12:00+08:00".

Where UTCDate is given as a type, it means a Date where the time-offset component MUST be Z (i.e. it must be in UTC time). For example, "2014-10-30T06:12:00Z".

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


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.


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:


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


Standard /changes method.


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, with the following additional properties:


Standard /get method.


Standard /changes method


Standard /query method.


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:


The following properties MUST be supported for sorting:


Standard /queryChanges method.


Standard /set method.

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