Listen to Fastmail CEO Bron Gondwana talk about JMAP on the Digital Citizen Podcast

JMAP Tasks

This document specifies a data model for synchronizing todo/task data with a server using JMAP.

Introduction

JMAP ([@!RFC8620] – JSON Meta Application Protocol) is a generic protocol for synchronizing data, such as mail, calendars or contacts, between a client and a server. It is optimized for mobile and web environments, and aims to provide a consistent interface to different data types.

JMAP for Calendars ([@!I-D.ietf-jmap-calendars]) defines a data model for synchronizing calendar data between a client and a server using JMAP. The data model is designed to allow a server to provide consistent access to the same data via CalDAV [@?RFC4791] as well as JMAP.

While CalDAV defines access to tasks, JMAP for Calendars does not. This specification fills this gap and defines a data model for synchronizing task data between a client and a server using JMAP. It is built upon JMAP for Calendars and reuses most of its definitions. For better readability, this document only outlines differences between this specification and JMAP for Calendars. If not stated otherwise, the same specifics that apply to Calendar, CalendarEvent and CalendarEventNotification objects as defined in the aforementioned specification also apply to similar data types introduced in this specification.

Notational Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [@!RFC2119] [@!RFC8174] when, and only when, they appear in all capitals, as shown here.

Type signatures, examples, and property descriptions in this document follow the conventions established in Section 1.1 of [@!RFC8620]. Data types defined in the core specification are also used in this document.

Terminology

The same terminology is used in this document as in the core JMAP specification, see [@!RFC8620], Section 1.6.

The terms ParticipantIdentity, TaskList, Task and TaskNotification are used to refer to the data types defined in this document and instances of those data types.

Data Model Overview

Similar to JMAP for Calendar, an Account (see [@!RFC8620], Section 1.6.2) contains zero or more TaskList objects, which is a named collection of Tasks belonging to a Principal (see [@!I-D.ietf-jmap-sharing] Section XXX). Task lists can also provide defaults, such as alerts and a color, to apply to tasks in the calendar. Clients commonly let users toggle visibility of tasks belonging to a particular task list on/off.

A Task is a representation of a single task or recurring series of Tasks in JSTask [@!I-D.ietf-calext-jscalendar] format. Recurrence rules and alerts as defined in JMAP for Calendars (see [@!I-D.ietf-jmap-calendars] Section XXX) apply.

Just like the CalendarEventNotification objects (see [@!I-D.ietf-jmap-calendars] Section XXX), TaskNotification objects keep track of the history of changes made to a task by other users. Similarly, the ShareNotification type (see [@!I-D.ietf-jmap-sharing] Section XXX) notifies the user when their access to another user’s task list is granted or revoked.

Use cases for task systems vary. Only a few systems will require implementation of all available features defined within this specification. For this reason, this document describes several extensions to the core task properties and objects through which support for a certain feature MUST be advertised via capabilities. In addition to the core features advertised via urn:ietf:params:jmap:tasks support for recurrences, assignees, alerts, localizations as well as custom time zones can be advertised.

Addition to the Capabilities Object

The capabilities object is returned as part of the JMAP Session object; see [@!RFC8620], Section 2. This document defines six additional capability URIs.

urn:ietf:params:jmap:tasks

This represents support for the core properties and objects of the TaskList, Task and TaskNotification data types and associated API methods. The value of this property in the JMAP Session capabilities property is an empty object.

The value of this property in an account’s accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:

urn:ietf:params:jmap:tasks:recurrences

This represents support for the recurrence properties and objects of the TaskList, Task and TaskNotification data types and associated API methods. The value of this property in the JMAP Session capabilities property is an empty object.

The value of this property in an account’s accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:

urn:ietf:params:jmap:tasks:assignees

This represents support for the assignee properties and objects of the TaskList, Task and TaskNotification data types and associated API methods. The value of this property in the JMAP Session capabilities property is an empty object.

The value of this property in an account’s accountCapabilities property is an object that MUST contain the following information on server capabilities and permissions for that account:

urn:ietf:params:jmap:tasks:alerts

This represents support for the alerts properties and objects of the TaskList, Task and TaskNotification data types and associated API methods. The value of this property in the JMAP Session capabilities property and the account’s accountCapabilities property is an empty object.

urn:ietf:params:jmap:tasks:multilingual

This represents support for the multilingual properties and objects of the TaskList, Task and TaskNotification data types and associated API methods. The value of this property in the JMAP Session capabilities property and the account’s accountCapabilities property is an empty object.

urn:ietf:params:jmap:tasks:customtimezones

This represents support for the custom time zone properties and objects of the TaskList, Task and TaskNotification data types and associated API methods. The value of this property in the JMAP Session capabilities property and the account’s accountCapabilities property is an empty object.

Principals

For systems that also support JMAP Sharing [@!I-D.ietf-jmap-sharing], the tasks capability is used to indicate that this principal may be used with tasks.

Principal Capability urn:ietf:params:jmap:tasks

A “urn:ietf:params:jmap:tasks” property is added to the Principal “capabilities” object, the value of which is an object with the following properties:

TaskLists

A TaskList is a named collection of tasks. All tasks are associated with exactly one TaskList.

A TaskList object has the following core properties:

A TaskRights object has the following properties:

The user is an owner for a task if the Task object has a “participant” property, and one of the Participant objects both:

  1. Has the “chair” role.
  2. Corresponds to one of the user’s ParticipantIdentity objects in the account.

A task has no owner if its participant property is null or omitted.

Alerts extension

A TaskList has the following alerts properties:

TaskList/get

This is a standard “/get” method as described in [@!RFC8620], Section 5.1. The ids argument may be null to fetch all at once.

TaskList/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

TaskList/set

This is the “Calendar/set” method as described in [@!I-D.ietf-jmap-calendars], Section XXX.

The “role” and “shareWith” properties may only be set by users that have the mayAdmin right. The value is shared across all users, although users without the mayAdmin right cannot see the value.

When modifying the shareWith property, the user cannot give a right to a principal if the principal did not already have that right and the user making the change also does not have that right. Any attempt to do so must be rejected with a forbidden SetError.

Users can subscribe or unsubscribe to a task list by setting the “isSubscribed” property. The server MAY forbid users from subscribing to certain task lists even though they have permission to see them, rejecting the update with a forbidden SetError.

The “timeZone”, “defaultAlertsWithoutTime” and “defaultAlertsWithTime” properties are stored per-user if the task list account’s “shareesActAs” capability is “self”, and may be set by any user who is subscribed to the task list and has the mayUpdatePrivate right. Each user gets the default value for these properties as the initial value; they do not inherit an initial value from the task list owner.

If the task list account’s “shareesActAs” capability is “secretary” these properties are instead shared, and may only be set by users that have the mayAdmin right.

The following properties may be set by anyone who is subscribed to the task list and are all stored per-user:

The “name” and “color” properties are initially inherited from the owner’s copy of the task list, but if set by a sharee that user gets their own copy of the property; it does not change for any other principals. If the value of the property in the owner’s task list changes after this, it does not overwrite the sharee’s value.

The “sortOrder” property is initally the default value for each sharee; it is not inherited from the owner.

The following extra SetError types are defined:

For “destroy”:

Tasks

A Task object contains information about a task. It is a JSTask object, as defined in [@!I-D.ietf-calext-jscalendar]. However, as use-cases of task systems vary, this Section defines relevant parts of the JSTask object to implement the core task capability as well as several extensions to it. Only the core capability MUST be implemented by any task system. Implementers can choose the extensions that fit their own use case. For example, the recurrence extension allows having a Task object represent a series of recurring Tasks.

The core JSTask objects are Task, Link, Location, Relation and VirtualLocation. The core properties are JSTask’s Metadata Properties (Section 4.1), What and Where Properties (Section 4.2), Task Properties (Section 5.2) as well as priority (Section 4.4.1), privacy (Section 4.4.3), replyTo (Section 4.4.4) and timeZone (Section 4.7.1).

On top of the JSTask properties, a Task object has the following additional core properties:

Extensions to JSCalendar data types

This document extends one JSCalendar data type with new values.

Relation

The keys for relation of the Relation object are extended by the following values:

Additional JSCalendar properties

This document defines five new core JSCalendar properties for the JSTask object.

mayInviteSelf

Type: Boolean (default: false)

If true, any user that has access to the task may add themselves to it as a participant with the “attendee” role. This property MUST NOT be altered in the recurrenceOverrides; it may only be set on the master object.

mayInviteOthers

Type: Boolean (default: false)

If true, any current participant with the “attendee” role may add new participants with the “attendee” role to the task. This property MUST NOT be altered in the recurrenceOverrides; it may only be set on the master object.

hideAttendees

Type: Boolean (default: false)

If true, only the owners of the task may see the full set of participants. Other sharees of the task may only see the owners and themselves. This property MUST NOT be altered in the recurrenceOverrides; it may only be set on the master object.

estimatedWork

Type: UnignedInt|null (default: null)

This specifies the estimated amount of work the task takes to complete. The number SHOULD be in Fibonacci scale without any actual unit. In the of Agile software development or Scrum it is known as complexity or story points.

impact

Type: String|null (default: null)

This specifies the impact or severity of the task, but does not say anything about prioritization. Usually, the priority of a task is based upon its impact and urgency. Some examples are: minor, trivial, major or block.

Properties similar in JMAP for Calendar

Attachments and per-user properties are described in [@!I-D.ietf-jmap-calendars], Section XXX.

Recurrences extension

For the recurrence extension, the JSCalendar objects NDay and RecurrenceRule as well as the Recurrence Properties (Section 4.3) need to be supported.

Properties similar in JMAP for Calendar

Recurrences and updates to recurrences are described in [@!I-D.ietf-jmap-calendars], Section XXX

Assignees extension

For the assignees extension, the JSCalendar object Participant as well as all Sharing and Scheduling Properties (Section 4.4) need to be supported.

Extensions to JSCalendar data types

The assignees extension extends one JSCalendar data type with new values.

Participants

The Participant object, as defined in [@!I-D.ietf-calext-jscalendar] Section 4.4.6 is used to represent participants. This spec extends the keys for the roles property with the following value:

Alerts extension

For the alerts extension, the JSCalendar objects Alert, AbsoluteTrigger and OffsetTrigger as well as all Alerts Properties (Section 4.4) need to be supported.

Multilingual extension

For the multilingual extension, the JSCalendar Multilingual Properties (Section 4.6) need to be supported.

Custom Time Zones extension

For the custom time zones extension, the JSCalendar objects TimeZone and TimeZoneRule as well as all Time Zone Properties (Section 4.7) need to be supported.

Task/get

This is the “CalendarEvent/get” method as described in [@!I-D.ietf-jmap-calendars], Section XXX.

TODO redefine this here. Similar to “TaskList/get” we only need to replace a few definitions. Copy+Paste most of the stuff.

Task/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

Task/set

This is the “CalendarEvent/set” method as described in [@!I-D.ietf-jmap-calendars], Section XXX.

TODO copy+paste most stuff from “CalendarEvent/set”. It should be fine to just reference patching.

Task/copy

This is a standard “/copy” method as described in [@!RFC8620], Section 5.4.

Task/query

This is the “CalendarEvent/query” method as described in [@!I-D.ietf-jmap-calendars], Section XXX.

TODO copy+paste most stuff from “CalendarEvent/query”. Mainly filtering should be different.

Task/queryChanges

This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.

Task Notifications

The TaskNotification data type records changes made by external entities to tasks in task lists the user is subscribed to. Notifications are stored in the same Account as the Task that was changed.

This is the same specification as the CalendarEventNotification object from [@!I-D.ietf-jmap-calendars], Section XXX. Only the object properties differ slightly and are therefore fully described in this document.

Object Properties

The TaskNotification object has the following properties:

To reduce data, if the change only affects a single instance of a recurring task, the server MAY set the task and taskPatch properties for the instance; the taskId MUST still be for the master task.

TaskNotification/get

This is a standard “/get” method as described in [@!RFC8620], Section 5.1.

TaskNotification/changes

This is a standard “/changes” method as described in [@!RFC8620], Section 5.2.

TaskNotification/set

This is a standard “/changes” method as described in [@!RFC8620], Section 5.3.

Only destroy is supported; any attempt to create/update MUST be rejected with a forbidden SetError.

TaskNotification/query

This is a standard “/query” method as described in [@!RFC8620], Section 5.5.

Filtering

A FilterCondition object has the following properties:

Sorting

The “created” property MUST be supported for sorting.

TaskNotification/queryChanges

This is a standard “/queryChanges” method as described in [@!RFC8620], Section 5.6.

Security Considerations

All security considerations of JMAP for Calendars [@!I-D.ietf-jmap-calendars] apply to this specification.

IANA Considerations

JMAP Capability Registration for “tasks”

IANA will register the “tasks” JMAP Capability as follows:

Capability Name: urn:ietf:params:jmap:tasks

Specification document: this document

Intended use: common

Change Controller: IETF

Security and privacy considerations: this document, Section XXX

JSCalendar Property Registrations

All IANA registrations for JSTask are described in JMAP for Calendars [@!I-D.ietf-jmap-calendars].