JSON Meta Application Protocol (JMAP) for Contacts
Extracted elements (27)
Returning a blobId instead of a data: URI for media lets clients load potentially large image files only when needed and avoids the overhead of Base64 encoding. This is the primary motivation for the blobId extension to JSContact.
Unrestricted Unicode use can cause inconsistent rendering and unexpected results when copying text. Servers MAY restrict characters using the PRECIS FreeformClass (RFC 8264) and may strip or replace forbidden code points rather than rejecting updates, as long as changed properties are returned in the /set response.
ContactCard/query sorting MUST support 'created' and 'updated' properties. Sorting SHOULD support 'name/given', 'name/surname', and 'name/surname2' on the Comparator object.
For group ContactCards (kind='group'), any uid in the members set that cannot be found SHOULD be ignored but preserved, supporting temporary loss of access to shared address books.
If onSuccessSetIsDefault references an id not found or a change not permitted, it MUST be ignored silently and the current default AddressBook remains. No error is returned to the client.
If zero properties are specified on a FilterCondition, it MUST always evaluate to true. If multiple properties are specified, ALL must apply (implicit AND).
In ContactCard/set, the server MUST reject attempts to set a file that is not a recognised image type as the photo for a card. Photos must first be uploaded using the JMAP blob upload mechanism.
isSubscribed SHOULD default to false for AddressBooks in shared accounts the user has access to, and true for new AddressBooks created by the user. If false, the AddressBook and its contents SHOULD only be displayed when explicitly requested.
Text matching SHOULD be case-insensitive. Quoted strings SHOULD be treated as phrase searches. Outside phrases, whitespace SHOULD divide separate tokens that MUST all be present. Tokens MAY be matched on a whole-word basis using stemming.
The AddressBook name MUST NOT be the empty string and MUST NOT be greater than 255 octets in size when encoded as UTF-8.
The isDefault property SHOULD be true for exactly one AddressBook in any account and MUST NOT be true for more than one AddressBook within an account.
The maxAddressBooksPerCard capability value MUST be an integer >= 1, or null for no limit. It specifies the maximum number of AddressBooks assignable to a single ContactCard.
There MUST NOT be more than one ContactCard with the same uid in an Account. A ContactCard MUST belong to at least one AddressBook at all times until it is destroyed.
When modifying shareWith, any attempt to grant a right that the requesting user does not themselves possess MUST be rejected with a 'forbidden' SetError.
When returning ContactCards, any Media with a 'data:' URI SHOULD return a blobId and omit the uri property; the mediaType MUST also be set. Clients MAY send a blobId instead of uri when creating or updating a ContactCard.
A ContactCard is a JSContact Card object (RFC 9553) extended with two JMAP-specific properties: id (immutable, server-set) and addressBookIds (Id[Boolean] map of AddressBook memberships). The id MAY differ from the JSContact uid.
A new blobId property (Id) is defined for Media objects within ContactCards, providing a JMAP blob reference for binary resources such as photos. The value for each key in addressBookIds MUST be true.
AddressBook/set supports two additional request arguments: onDestroyRemoveContents (Boolean, default false) controls whether contacts are removed when an AddressBook is destroyed, and onSuccessSetIsDefault (Id|null) atomically changes the default AddressBook after successful operations.
AddressBookRights object defines four Boolean access rights: mayRead (fetch ContactCards), mayWrite (create/modify/destroy ContactCards), mayShare (modify shareWith), and mayDelete (delete the AddressBook itself).
An AddressBook object has properties: id (immutable, server-set), name (String), description (String|null), sortOrder (UnsignedInt), isDefault (Boolean, server-set), isSubscribed (Boolean), shareWith (Id[AddressBookRights]|null), and myRights (AddressBookRights, server-set).
ContactCard/query FilterCondition supports fields including inAddressBook, uid, hasMember, kind, createdBefore, createdAfter, updatedBefore, updatedAfter, text, name, name/given, name/surname, name/surname2, nickname, organization, email, phone, onlineService, address, and note.
The addressBookHasContents SetError is returned when an attempt is made to destroy an AddressBook that still has at least one ContactCard assigned to it and onDestroyRemoveContents was false.
The urn:ietf:params:jmap:contacts capability indicates support for AddressBook and ContactCard data types and associated API methods. Its value in accountCapabilities MUST contain maxAddressBooksPerCard (UnsignedInt|null) and mayCreateAddressBook (Boolean).
IANA registered the 'urn:ietf:params:jmap:contacts' capability in the JMAP Capabilities registry, the 'AddressBook' and 'ContactCard' types in the JMAP Data Types registry, and 'addressBookHasContents' in the JMAP Error Codes registry.
IANA registered three additional properties in the JSContact Properties registry: 'id' (Card context, reserved), 'addressBookIds' (Card context, reserved), and 'blobId' (Media context, reserved), all since version 1.0.
Contacts consist almost entirely of private, personally identifiable information (PII) and represent users' social connections. Contact servers and clients MUST be mindful of the need to keep all data secure, as privacy leaks can have real-world consequences.
Servers MUST enforce the Access Control Lists (ACLs) set on address books to ensure only authorised data is shared. All security considerations of JMAP (RFC 8620) also apply.