JMAP for Contacts

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 21 September 2024.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

JMAP ([RFC8620] JSON Meta Application Protocol) 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 contacts between a client and a server using JMAP.¶

2. AddressBooks

An AddressBook is a named collection of ContactCards. All ContactCards are associated with one or more AddressBook.¶

A AddressBook object has the following properties:¶

• id: Id (immutable; server-set)¶

  The id of the AddressBook.¶

• name: String¶

  The user-visible name of the AddressBook. This may be any UTF-8 string of at least 1 character in length and maximum 255 octets in size.¶

• description: String|null (default: null)¶

  An optional longer-form description of the AddressBook, to provide context in shared environments where users need more than just the name.¶

• sortOrder: UnsignedInt (default: 0)¶

  Defines the sort order of AddressBooks when presented in the client's UI, so it is consistent between devices. The number MUST be an integer in the range 0 <= sortOrder < 2^31.¶

  An AddressBook with a lower order is to be displayed before a AddressBook with a higher order in any list of AddressBooks in the client's UI. AddressBooks with equal order should be sorted in alphabetical order by name. The sorting should take into account locale-specific character order convention.¶

• isDefault: Boolean (server-set)¶

  This SHOULD be true for exactly one AddressBook in any account, and MUST NOT be true for more than one AddressBook within an account. The default AddressBook should be used by clients whenever they need to choose an AddressBook for the user within this account, and they do not have any other information on which to make a choice. For example, if the user creates a new contact card, the client may automatically set the card as belonging to the default AddressBook from the user's primary account.¶

• isSubscribed: Boolean¶

  True if the user has indicated they wish to see this AddressBook in their client. This should default to false for AddressBooks in shared accounts the user has access to and true for any new AddressBooks created by the user themself.¶

  If false, the AddressBook and its contents should only be displayed when the user explicitly requests it or to offer it for the user to subscribe to.¶

• shareWith: Id[AddressBookRights]|null (default: null)¶

  A map of Principal id to rights for principals this AddressBook is shared with. The principal to which this AddressBook belongs MUST NOT be in this set. This is null if the AddressBook is not shared with anyone. May be modified only if the user has the mayAdmin right. The account id for the principals may be found in the urn:ietf:params:jmap:principals:owner capability of the Account to which the AddressBook belongs.¶

• myRights: AddressBookRights (server-set)¶

  The set of access rights the user has in relation to this AddressBook.¶

An AddressBookRights object has the following properties:¶

• mayRead: Boolean¶

  The user may fetch the ContactCards in this AddressBook.¶

• mayWrite: Boolean¶

  The user may create, modify or destroy all ContactCards in this AddressBook, or move them to or from this AddressBook.¶

• mayAdmin: Boolean¶

  The user may modify the "shareWith" property for this AddressBook.¶

• mayDelete: Boolean¶

  The user may delete the AddressBook itself.¶

3. ContactCards

A ContactCard object contains information about a person, company, or other entity, or represents a group of such entities. It is a JSContact Card object, as defined in Section 2 of [I-D.ietf-calext-jscontact], with the following additional properties:¶

• id: Id (immutable; server-set)¶

  The id of the ContactCard. The id uniquely identifies a ContactCard with a particular "uid" within a particular account.¶

• addressBookIds: Id[Boolean]¶

  The set of AddressBook ids this ContactCard belongs to. A card MUST belong to at least one AddressBook at all times (until it is destroyed). The set is represented as an object, with each key being an AddressBook id. The value for each key in the object MUST be true.¶

For any Media object in the card (see Section 2.6.4 of [I-D.ietf-calext-jscontact]), a new property is defined:¶

• blobId: Id¶

  An id for the Blob representing the binary contents of the resource.¶

When returning ContactCards, any Media with a data: URI SHOULD return a blobId property and omit the uri property, as this lets clients load the (potentially large) image file only when needed, and avoids the overhead of Base64 encoding. The "mediaType" property MUST also be set. Similarly, when creating or updating a ContactCard, clients MAY send a blobId instead of the uri property for a Media object.¶

A contact card with a "kind" property equal to "group" represents a group of contacts. Clients often present these separately from other contact cards. The "members" property, as defined in Section 2.1.6 of [I-D.ietf-calext-jscontact], contains a set of UIDs for other contacts that are the members of this group. Clients should consider the group to contain any ContactCard with a matching UID, from any account they have access to with support for the urn:ietf:params:jmap:contacts capability. UIDs that cannot be found SHOULD be ignored but preserved. For example, suppose a user adds contacts from a shared address book to their private group, then temporarily loses access to this address book. The UIDs cannot be resolved so the contacts will disappear from the group. However, if they are given permission to access the data again the UIDs will be found and the contacts will reappear.¶

4. Examples

For brevity, in the following examples only the "methodCalls" property of the Request object, and the "methodResponses" property of the Response object is shown.¶

[
  ["AddressBook/get", {
    "accountId": "a0x9"
  }, "0"],
  ["ContactCard/get", {
    "accountId": "a0x9"
  }, "1"]
]

[
  ["AddressBook/get", {
    "accountId": "a0x9",
    "list": [{
        "id": "062adcfa-105d-455c-bc60-6db68b69c3f3",
        "name": "Personal",
        "description": null,
        "sortOrder": 0,
        "isDefault": true,
        "isSubscribed": true,
        "shareWith": null,
        "myRights": {
          "mayRead": true,
          "mayWrite": true,
          "mayAdmin": true,
          "mayDelete": false
        }
      }, {
        "id": "cd40089d-35f9-4fd7-980b-ba3a9f1d74fe",
        "name": "Autosaved",
        "description": null,
        "sortOrder": 1,
        "isDefault": false,
        "isSubscribed": true,
        "shareWith": null,
        "myRights": {
          "mayRead": true,
          "mayWrite": true,
          "mayAdmin": true,
          "mayDelete": false
        }
      }],
      "notFound": [],
      "state": "~4144"
  }, "0"],
  ["Contact/get", {
    "accountId": "a0x9",
    "list": [{
        "id": "3",
        "addressBookIds": {
          "062adcfa-105d-455c-bc60-6db68b69c3f3": true
        },
        "name": {
          "components": [
            { "kind": "given", "value": "Joe" },
            { "kind": "surname", "value": "Bloggs" }
          ],
          "isOrdered": true
        },
        "emails": {
          "0": {
          "contexts": {
            "private": true
          },
          "address": "joe.bloggs@example.com"
          }
        }
      }],
      "notFound": [],
      "state": "ewarbckaqJ::112"
  }, "1"]
]

[
  ["AddressBook/set", {
    "accountId": "a0x9",
    "onSuccessSetIsDefault": "cd40089d-35f9-4fd7-980b-ba3a9f1d74fe"
  }, "0"]
]

[
  ["AddressBook/set", {
    "accountId": "a0x9",
    "updated": {
      "cd40089d-35f9-4fd7-980b-ba3a9f1d74fe": {
        "isDefault": true
      },
      "062adcfa-105d-455c-bc60-6db68b69c3f3": {
        "isDefault": false
      }
    }
  }, "0"]
]

5. Security considerations

All security considerations of JMAP ([RFC8620]) apply to this specification. Additional considerations specific to the data types and functionality introduced by this document are described in the following subsection.¶

Contacts consist almost entirely of private, personally identifiable information, and represent the social connections of users. Privacy leaks can have real world consequences, and contacts servers and clients MUST be mindful of the need to keep all data secure.¶

Servers MUST enforce the ACLs set on address books to ensure only authorised data is shared.¶

6. IANA Considerations

Author's Address