Abstract

This document specifies a data model for synchronising contact data with a server using the JSON Meta Application Protocol (JMAP).¶

Status of This Memo

This is an Internet Standards Track document.¶

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9610.¶

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

The JSON Meta Application Protocol (JMAP) [RFC8620] 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 AddressBooks.¶

An 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 MUST NOT be the empty string and MUST NOT be greater than 255 octets in size when encoded as UTF-8.¶

description: String|null (default: null)

An optional long-form description of the AddressBook that provides 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³¹.¶

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 that 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. The UI may offer to the user the option of subscribing to it.¶

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

A map of the Principal id (Section 2 of [RFC9670]) 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 or if the server does not support [RFC9670]. The value may be modified only if the user has the "mayShare" 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.¶

mayShare: Boolean

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

mayDelete: Boolean

The user may delete the AddressBook itself.¶

4. Examples

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

[
  ["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": {
        "3f1502e0-63fe-4335-9ff3-e739c188f5dd": {
          "mayRead": true,
          "mayWrite": false,
          "mayShare": false,
          "mayDelete": false
        }
      },
      "myRights": {
        "mayRead": true,
        "mayWrite": true,
        "mayShare": 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,
        "mayShare": true,
        "mayDelete": false
      }
    }],
    "notFound": [],
    "state": "~4144"
  }, "0"],
  ["ContactCard/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
      },
      "oldState": "~4144",
      "newState": "~4148"
    }
  }, "0"]
]

5. Internationalisation Considerations

Experience has shown that unrestricted use of Unicode can lead to problems such as inconsistent rendering, users reading text and interpreting it differently than intended, and unexpected results when copying text from one location to another. Servers MAY choose to mitigate this by restricting the set of characters allowed in otherwise unconstrained String fields. The FreeformClass, as documented in Section 4.3 of [RFC8264], might be a good starting point for this.¶

Attempts to set a value containing code points outside of the permissible set can be handled in a few ways by the server. The server could choose to strip the forbidden characters or replace them with U+FFFD (the Unicode replacement character) and store the resulting string. This is likely to be appropriate for non-printable characters -- such as the "Control Codes" defined in Section 23.1 of [UNICODE], excluding newline (U+000A), carriage return (U+000D), and tab (U+0009) -- that can end up in data accidentally due to copy-and-paste issues but are invisible to the end user. JMAP allows the server to transform data on create/update as long as any changed properties are returned to the client in the "/set" response so it knows what has changed, as per Section 5.3 of [RFC8620]. Alternatively, the server MAY just reject the create/update with an "invalidProperties" SetError.¶

6. 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 contact servers and clients MUST be mindful of the need to keep all data secure.¶

Servers MUST enforce the Access Control Lists (ACLs) set on address books to ensure only authorised data is shared.¶

7. IANA Considerations

8. References

Author's Address