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:


Where the API specifies LocalDate as a type, it means a string in the same format as Date, but with the Z 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).


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 getFoos method. The ids argument may be null to fetch all at once.


Standard getFooUpdates method.


Standard setFoos 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 contains information about an event, or recurring series of events, that takes place at a particular time. The object is designed to be easily convertible to/from iCalendar format ([@!RFC5545]) for compatibility with existing calendaring systems.

A CalendarEvent object has the following properties:

When mapping from iCalendar, the LOCATION property should become a single location with just a name property. If the event has a different end time zone to start time zone, this should be added as a second location with just a timeZone property.

If isAllDay is true, then the following restrictions apply:

Any nullable array/object property MUST be null rather than an empty array or object.


Standard getFoos method.


Standard getFooUpdates method


Standard getFooList method.


A FilterOperator object has the following properties:

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 getFooListUpdates method.


Standard setFoos method.

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