···
+
Internet Engineering Task Force (IETF) N. Jenkins
+
Request for Comments: 8620 Fastmail
+
Category: Standards Track C. Newman
+
The JSON Meta Application Protocol (JMAP)
+
This document specifies a protocol for clients to efficiently query,
+
fetch, and modify JSON-based data objects, with support for push
+
notification of changes and fast resynchronisation and for out-of-
+
band binary data upload/download.
+
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/rfc8620.
+
Copyright (c) 2019 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 Simplified BSD License text as described in Section 4.e of
+
the Trust Legal Provisions and are provided without warranty as
+
described in the Simplified BSD License.
+
Jenkins & Newman Standards Track [Page 1]
+
RFC 8620 JMAP July 2019
+
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
+
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
+
1.2. The Id Data Type . . . . . . . . . . . . . . . . . . . . 6
+
1.3. The Int and UnsignedInt Data Types . . . . . . . . . . . 6
+
1.4. The Date and UTCDate Data Types . . . . . . . . . . . . . 7
+
1.5. JSON as the Data Encoding Format . . . . . . . . . . . . 7
+
1.6. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7
+
1.6.1. User . . . . . . . . . . . . . . . . . . . . . . . . 7
+
1.6.2. Accounts . . . . . . . . . . . . . . . . . . . . . . 7
+
1.6.3. Data Types and Records . . . . . . . . . . . . . . . 8
+
1.7. The JMAP API Model . . . . . . . . . . . . . . . . . . . 8
+
1.8. Vendor-Specific Extensions . . . . . . . . . . . . . . . 9
+
2. The JMAP Session Resource . . . . . . . . . . . . . . . . . . 9
+
2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 14
+
2.2. Service Autodiscovery . . . . . . . . . . . . . . . . . . 15
+
3. Structured Data Exchange . . . . . . . . . . . . . . . . . . 16
+
3.1. Making an API Request . . . . . . . . . . . . . . . . . . 16
+
3.2. The Invocation Data Type . . . . . . . . . . . . . . . . 16
+
3.3. The Request Object . . . . . . . . . . . . . . . . . . . 16
+
3.3.1. Example Request . . . . . . . . . . . . . . . . . . . 18
+
3.4. The Response Object . . . . . . . . . . . . . . . . . . . 18
+
3.4.1. Example Response . . . . . . . . . . . . . . . . . . 19
+
3.5. Omitting Arguments . . . . . . . . . . . . . . . . . . . 19
+
3.6. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 19
+
3.6.1. Request-Level Errors . . . . . . . . . . . . . . . . 20
+
3.6.2. Method-Level Errors . . . . . . . . . . . . . . . . . 21
+
3.7. References to Previous Method Results . . . . . . . . . . 22
+
3.8. Localisation of User-Visible Strings . . . . . . . . . . 27
+
3.9. Security . . . . . . . . . . . . . . . . . . . . . . . . 28
+
3.10. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 28
+
4. The Core/echo Method . . . . . . . . . . . . . . . . . . . . 28
+
4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 28
+
5. Standard Methods and Naming Convention . . . . . . . . . . . 29
+
5.1. /get . . . . . . . . . . . . . . . . . . . . . . . . . . 29
+
5.2. /changes . . . . . . . . . . . . . . . . . . . . . . . . 30
+
5.3. /set . . . . . . . . . . . . . . . . . . . . . . . . . . 34
+
5.4. /copy . . . . . . . . . . . . . . . . . . . . . . . . . . 40
+
5.5. /query . . . . . . . . . . . . . . . . . . . . . . . . . 42
+
5.6. /queryChanges . . . . . . . . . . . . . . . . . . . . . . 48
+
5.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . 51
+
5.8. Proxy Considerations . . . . . . . . . . . . . . . . . . 58
+
6. Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . 58
+
6.1. Uploading Binary Data . . . . . . . . . . . . . . . . . . 59
+
6.2. Downloading Binary Data . . . . . . . . . . . . . . . . . 60
+
6.3. Blob/copy . . . . . . . . . . . . . . . . . . . . . . . . 61
+
Jenkins & Newman Standards Track [Page 2]
+
RFC 8620 JMAP July 2019
+
7. Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
+
7.1. The StateChange Object . . . . . . . . . . . . . . . . . 63
+
7.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 64
+
7.2. PushSubscription . . . . . . . . . . . . . . . . . . . . 64
+
7.2.1. PushSubscription/get . . . . . . . . . . . . . . . . 67
+
7.2.2. PushSubscription/set . . . . . . . . . . . . . . . . 68
+
7.2.3. Example . . . . . . . . . . . . . . . . . . . . . . . 69
+
7.3. Event Source . . . . . . . . . . . . . . . . . . . . . . 71
+
8. Security Considerations . . . . . . . . . . . . . . . . . . . 73
+
8.1. Transport Confidentiality . . . . . . . . . . . . . . . . 73
+
8.2. Authentication Scheme . . . . . . . . . . . . . . . . . . 73
+
8.3. Service Autodiscovery . . . . . . . . . . . . . . . . . . 73
+
8.4. JSON Parsing . . . . . . . . . . . . . . . . . . . . . . 74
+
8.5. Denial of Service . . . . . . . . . . . . . . . . . . . . 74
+
8.6. Connection to Unknown Push Server . . . . . . . . . . . . 74
+
8.7. Push Encryption . . . . . . . . . . . . . . . . . . . . . 75
+
8.8. Traffic Analysis . . . . . . . . . . . . . . . . . . . . 76
+
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 76
+
9.1. Assignment of jmap Service Name . . . . . . . . . . . . . 76
+
9.2. Registration of Well-Known URI Suffix for JMAP . . . . . 76
+
9.3. Registration of the jmap URN Sub-namespace . . . . . . . 77
+
9.4. Creation of "JMAP Capabilities" Registry . . . . . . . . 77
+
9.4.1. Preliminary Community Review . . . . . . . . . . . . 77
+
9.4.2. Submit Request to IANA . . . . . . . . . . . . . . . 78
+
9.4.3. Designated Expert Review . . . . . . . . . . . . . . 78
+
9.4.4. Change Procedures . . . . . . . . . . . . . . . . . . 78
+
9.4.5. JMAP Capabilities Registry Template . . . . . . . . . 79
+
9.4.6. Initial Registration for JMAP Core . . . . . . . . . 79
+
9.4.7. Registration for JMAP Error Placeholder in JMAP
+
Capabilities Registry . . . . . . . . . . . . . . . . 80
+
9.5. Creation of "JMAP Error Codes" Registry . . . . . . . . . 80
+
9.5.1. Expert Review . . . . . . . . . . . . . . . . . . . . 80
+
9.5.2. JMAP Error Codes Registry Template . . . . . . . . . 81
+
9.5.3. Initial Contents for the JMAP Error Codes Registry . 81
+
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 86
+
10.1. Normative References . . . . . . . . . . . . . . . . . . 86
+
10.2. Informative References . . . . . . . . . . . . . . . . . 89
+
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 90
+
Jenkins & Newman Standards Track [Page 3]
+
RFC 8620 JMAP July 2019
+
The JSON Meta Application Protocol (JMAP) is used 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 is for the generic mechanism of data
+
synchronisation. Further specifications define the data models for
+
different data types that may be synchronised via JMAP.
+
JMAP is designed to make efficient use of limited network resources.
+
Multiple API calls may be batched in a single request to the server,
+
reducing round trips and improving battery life on mobile devices.
+
Push connections remove the need for polling, and an efficient delta
+
update mechanism ensures a minimum amount of data is transferred.
+
JMAP is designed to be horizontally scalable to a very large number
+
of users. This is facilitated by separate endpoints for users after
+
login, the separation of binary and structured data, and a data model
+
for sharing that does not allow data dependencies between accounts.
+
1.1. 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.
+
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 [RFC8259]. 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 compatibility with publishing requirements, line breaks have been
+
inserted inside long JSON strings, with the following continuation
+
lines indented. To form the valid JSON example, any line breaks
+
inside a string must be replaced with a space and any other white
+
space after the line break removed.
+
Jenkins & Newman Standards Track [Page 4]
+
RFC 8620 JMAP July 2019
+
Unless otherwise specified, examples of API exchanges only show the
+
methodCalls array of the Request object or the methodResponses array
+
of the Response object. For compactness, the rest of the Request/
+
Response object is omitted.
+
Type signatures are given for all JSON values in this document. The
+
following conventions are used:
+
o "*" - The type is undefined (the value could be any type, although
+
permitted values may be constrained by the context of this value).
+
o "String" - The JSON string type.
+
o "Number" - The JSON number type.
+
o "Boolean" - The JSON boolean type.
+
o "A[B]" - A JSON object where the keys are all of type "A", and the
+
values are all of type "B".
+
o "A[]" - An array of values of type "A".
+
o "A|B" - The value is either of type "A" or of type "B".
+
Other types may also be given, with their representation defined
+
elsewhere in this document.
+
Object properties may also have a set of attributes defined along
+
with the type signature. These have the following meanings:
+
o "server-set" -- Only the server can set the value for this
+
property. The client MUST NOT send this property when creating a
+
new object of this type.
+
o "immutable" -- The value MUST NOT change after the object is
+
o "default" -- (This is followed by a JSON value). The value that
+
will be used for this property if it is omitted in an argument or
+
when creating a new object of this type.
+
Jenkins & Newman Standards Track [Page 5]
+
RFC 8620 JMAP July 2019
+
All record ids are assigned by the server and are immutable.
+
Where "Id" is given as a data type, it means a "String" of at least 1
+
and a maximum of 255 octets in size, and it MUST only contain
+
characters from the "URL and Filename Safe" base64 alphabet, as
+
defined in Section 5 of [RFC4648], excluding the pad character ("=").
+
This means the allowed characters are the ASCII alphanumeric
+
characters ("A-Za-z0-9"), hyphen ("-"), and underscore ("_").
+
These characters are safe to use in almost any context (e.g.,
+
filesystems, URIs, and IMAP atoms). For maximum safety, servers
+
SHOULD also follow defensive allocation strategies to avoid creating
+
risks where glob completion or data type detection may be present
+
(e.g., on filesystems or in spreadsheets). In particular, it is wise
+
o Ids starting with a dash
+
o Ids starting with digits
+
o Ids that contain only digits
+
o Ids that differ only by ASCII case (for example, A vs. a)
+
o the specific sequence of three characters "NIL" (because this
+
sequence can be confused with the IMAP protocol expression of the
+
A good solution to these issues is to prefix every id with a single
+
alphabetical character.
+
1.3. The Int and UnsignedInt Data Types
+
Where "Int" is given as a data type, it means an integer in the range
+
-2^53+1 <= value <= 2^53-1, the safe range for integers stored in a
+
floating-point double, represented as a JSON "Number".
+
Where "UnsignedInt" is given as a data type, it means an "Int" where
+
the value MUST be in the range 0 <= value <= 2^53-1.
+
Jenkins & Newman Standards Track [Page 6]
+
RFC 8620 JMAP July 2019
+
1.4. The Date and UTCDate Data Types
+
Where "Date" is given as a type, it means a string in "date-time"
+
format [RFC3339]. To ensure a normalised form, the "time-secfrac"
+
MUST always be omitted if zero, and any letters in the string (e.g.,
+
"T" and "Z") MUST be uppercase. For example,
+
"2014-10-30T14:12:00+08:00".
+
Where "UTCDate" is given as a type, it means a "Date" where the
+
"time-offset" component MUST be "Z" (i.e., it must be in UTC time).
+
For example, "2014-10-30T06:12:00Z".
+
1.5. JSON as the Data Encoding Format
+
JSON is a text-based data interchange format as specified in
+
[RFC8259]. The Internet JSON (I-JSON) format defined in [RFC7493] is
+
a strict subset of this, adding restrictions to avoid potentially
+
confusing scenarios (for example, it mandates that an object MUST NOT
+
have two members with the same name).
+
All data sent from the client to the server or from the server to the
+
client (except binary file upload/download) MUST be valid I-JSON
+
according to the RFC and is therefore case sensitive and encoded in
+
A user is a person accessing data via JMAP. A user has a set of
+
permissions determining the data that they can see.
+
An account is a collection of data. A single account may contain an
+
arbitrary set of data types, for example, a collection of mail,
+
contacts, and calendars. Most JMAP methods take a mandatory
+
"accountId" argument that specifies on which account the operations
+
An account is not the same as a user, although it is common for a
+
primary account to directly belong to the user. For example, you may
+
have an account that contains data for a group or business, to which
+
multiple users have access.
+
Jenkins & Newman Standards Track [Page 7]
+
RFC 8620 JMAP July 2019
+
A single set of credentials may provide access to multiple accounts,
+
for example, if another user is sharing their work calendar with the
+
authenticated user or if there is a group mailbox for a support-desk
+
In the event of a severe internal error, a server may have to
+
reallocate ids or do something else that violates standard JMAP data
+
constraints for an account. In this situation, the data on the
+
server is no longer compatible with cached data the client may have
+
from before. The server MUST treat this as though the account has
+
been deleted and then recreated with a new account id. Clients will
+
then be forced to throw away any data with the old account id and
+
refetch all data from scratch.
+
1.6.3. Data Types and Records
+
JMAP provides a uniform interface for creating, retrieving, updating,
+
and deleting various types of objects. A "data type" is a collection
+
of named, typed properties, just like the schema for a database
+
table. Each instance of a data type is called a "record".
+
The id of a record is immutable and assigned by the server. The id
+
MUST be unique among all records of the *same type* within the *same
+
account*. Ids may clash across accounts or for two records of
+
different types within the same account.
+
1.7. The JMAP API Model
+
JMAP uses HTTP [RFC7230] to expose API, push, upload, and download
+
resources. All HTTP requests MUST use the "https://" scheme (HTTP
+
over TLS [RFC2818]). All HTTP requests MUST be authenticated.
+
An authenticated client can fetch the user's Session object with
+
details about the data and capabilities the server can provide as
+
shown in Section 2. The client may then exchange data with the
+
server in the following ways:
+
1. The client may make an API request to the server to get or set
+
structured data. This request consists of an ordered series of
+
method calls. These are processed by the server, which then
+
returns an ordered series of responses. This is described in
+
2. The client may download or upload binary files from/to the
+
server. This is detailed in Section 6.
+
3. The client may connect to a push channel on the server, to be
+
notified when data has changed. This is explained in Section 7.
+
Jenkins & Newman Standards Track [Page 8]
+
RFC 8620 JMAP July 2019
+
1.8. Vendor-Specific Extensions
+
Individual services will have custom features they wish to expose
+
over JMAP. This may take the form of extra data types and/or methods
+
not in the spec, extra arguments to JMAP methods, or extra properties
+
on existing data types (which may also appear in arguments to methods
+
that take property names).
+
The server can advertise custom extensions it supports by including
+
the identifiers in the capabilities object. Identifiers for vendor
+
extensions MUST be a URL belonging to a domain owned by the vendor,
+
to avoid conflict. The URL SHOULD resolve to documentation for the
+
changes the extension makes.
+
The client MUST opt in to use an extension by passing the appropriate
+
capability identifier in the "using" array of the Request object, as
+
described in Section 3.3. The server MUST only follow the
+
specifications that are opted into and behave as though it does not
+
implement anything else when processing a request. This is to ensure
+
compatibility with clients that don't know about a specific custom
+
extension and for compatibility with future versions of JMAP.
+
2. The JMAP Session Resource
+
You need two things to connect to a JMAP server:
+
1. The URL for the JMAP Session resource. This may be requested
+
directly from the user or discovered automatically based on a
+
username domain (see Section 2.2 below).
+
2. Credentials to authenticate with. How to obtain credentials is
+
out of scope for this document.
+
A successful authenticated GET request to the JMAP Session resource
+
MUST return a JSON-encoded *Session* object, giving details about the
+
data and capabilities the server can provide to the client given
+
those credentials. It has the following properties:
+
o capabilities: "String[Object]"
+
An object specifying the capabilities of this server. Each key is
+
a URI for a capability supported by the server. The value for
+
each of these keys is an object with further information about the
+
server's capabilities in relation to that capability.
+
The client MUST ignore any properties it does not understand.
+
Jenkins & Newman Standards Track [Page 9]
+
RFC 8620 JMAP July 2019
+
The capabilities object MUST include a property called
+
"urn:ietf:params:jmap:core". The value of this property is an
+
object that MUST contain the following information on server
+
capabilities (suggested minimum values for limits are supplied
+
that allow clients to make efficient use of the network):
+
* maxSizeUpload: "UnsignedInt"
+
The maximum file size, in octets, that the server will accept
+
for a single file upload (for any purpose). Suggested minimum:
+
* maxConcurrentUpload: "UnsignedInt"
+
The maximum number of concurrent requests the server will
+
accept to the upload endpoint. Suggested minimum: 4.
+
* maxSizeRequest: "UnsignedInt"
+
The maximum size, in octets, that the server will accept for a
+
single request to the API endpoint. Suggested minimum:
+
* maxConcurrentRequests: "UnsignedInt"
+
The maximum number of concurrent requests the server will
+
accept to the API endpoint. Suggested minimum: 4.
+
* maxCallsInRequest: "UnsignedInt"
+
The maximum number of method calls the server will accept in a
+
single request to the API endpoint. Suggested minimum: 16.
+
* maxObjectsInGet: "UnsignedInt"
+
The maximum number of objects that the client may request in a
+
single /get type method call. Suggested minimum: 500.
+
* maxObjectsInSet: "UnsignedInt"
+
The maximum number of objects the client may send to create,
+
update, or destroy in a single /set type method call. This is
+
the combined total, e.g., if the maximum is 10, you could not
+
create 7 objects and destroy 6, as this would be 13 actions,
+
which exceeds the limit. Suggested minimum: 500.
+
Jenkins & Newman Standards Track [Page 10]
+
RFC 8620 JMAP July 2019
+
* collationAlgorithms: "String[]"
+
A list of identifiers for algorithms registered in the
+
collation registry, as defined in [RFC4790], that the server
+
supports for sorting when querying records.
+
Specifications for future capabilities will define their own
+
properties on the capabilities object.
+
Servers MAY advertise vendor-specific JMAP extensions, as
+
described in Section 1.8. To avoid conflict, an identifier for a
+
vendor-specific extension MUST be a URL with a domain owned by the
+
vendor. Clients MUST opt in to any capability it wishes to use
+
o accounts: "Id[Account]"
+
A map of an account id to an Account object for each account (see
+
Section 1.6.2) the user has access to. An *Account* object has
+
the following properties:
+
A user-friendly string to show when presenting content from
+
this account, e.g., the email address representing the owner of
+
* isPersonal: "Boolean"
+
This is true if the account belongs to the authenticated user
+
rather than a group account or a personal account of another
+
user that has been shared with them.
+
* isReadOnly: "Boolean"
+
This is true if the entire account is read-only.
+
* accountCapabilities: "String[Object]"
+
The set of capability URIs for the methods supported in this
+
account. Each key is a URI for a capability that has methods
+
you can use with this account. The value for each of these
+
keys is an object with further information about the account's
+
permissions and restrictions with respect to this capability,
+
as defined in the capability's specification.
+
The client MUST ignore any properties it does not understand.
+
Jenkins & Newman Standards Track [Page 11]
+
RFC 8620 JMAP July 2019
+
The server advertises the full list of capabilities it supports
+
in the capabilities object, as defined above. If the
+
capability defines new methods, the server MUST include it in
+
the accountCapabilities object if the user may use those
+
methods with this account. It MUST NOT include it in the
+
accountCapabilities object if the user cannot use those methods
+
For example, you may have access to your own account with mail,
+
calendars, and contacts data and also a shared account that
+
only has contacts data (a business address book, for example).
+
In this case, the accountCapabilities property on the first
+
account would include something like
+
"urn:ietf:params:jmap:mail", "urn:ietf:params:jmap:calendars",
+
and "urn:ietf:params:jmap:contacts", while the second account
+
would just have the last of these.
+
Attempts to use the methods defined in a capability with one of
+
the accounts that does not support that capability are rejected
+
with an "accountNotSupportedByMethod" error (see "Method-Level
+
Errors", Section 3.6.2).
+
o primaryAccounts: "String[Id]"
+
A map of capability URIs (as found in accountCapabilities) to the
+
account id that is considered to be the user's main or default
+
account for data pertaining to that capability. If no account
+
being returned belongs to the user, or in any other way there is
+
no appropriate way to determine a default account, there MAY be no
+
entry for a particular URI, even though that capability is
+
supported by the server (and in the capabilities object).
+
"urn:ietf:params:jmap:core" SHOULD NOT be present.
+
The username associated with the given credentials, or the empty
+
The URL to use for JMAP API requests.
+
Jenkins & Newman Standards Track [Page 12]
+
RFC 8620 JMAP July 2019
+
o downloadUrl: "String"
+
The URL endpoint to use when downloading files, in URI Template
+
(level 1) format [RFC6570]. The URL MUST contain variables called
+
"accountId", "blobId", "type", and "name". The use of these
+
variables is described in Section 6.2. Due to potential encoding
+
issues with slashes in content types, it is RECOMMENDED to put the
+
"type" variable in the query section of the URL.
+
The URL endpoint to use when uploading files, in URI Template
+
(level 1) format [RFC6570]. The URL MUST contain a variable
+
called "accountId". The use of this variable is described in
+
o eventSourceUrl: "String"
+
The URL to connect to for push events, as described in
+
Section 7.3, in URI Template (level 1) format [RFC6570]. The URL
+
MUST contain variables called "types", "closeafter", and "ping".
+
The use of these variables is described in Section 7.3.
+
A (preferably short) string representing the state of this object
+
on the server. If the value of any other property on the Session
+
object changes, this string will change. The current value is
+
also returned on the API Response object (see Section 3.4),
+
allowing clients to quickly determine if the session information
+
has changed (e.g., an account has been added or removed), so they
+
need to refetch the object.
+
To ensure future compatibility, other properties MAY be included on
+
the Session object. Clients MUST ignore any properties they are not
+
Implementors must take care to avoid inappropriate caching of the
+
Session object at the HTTP layer. Since the client should only
+
refetch when it detects there is a change (via the sessionState
+
property of an API response), it is RECOMMENDED to disable HTTP
+
caching altogether, for example, by setting "Cache-Control: no-cache,
+
no-store, must-revalidate" on the response.
+
Jenkins & Newman Standards Track [Page 13]
+
RFC 8620 JMAP July 2019
+
In the following example Session object, the user has access to their
+
own mail and contacts via JMAP, as well as read-only access to shared
+
mail from another user. The server is advertising a custom
+
"https://example.com/apis/foobar" capability.
+
"urn:ietf:params:jmap:core": {
+
"maxSizeUpload": 50000000,
+
"maxConcurrentUpload": 8,
+
"maxSizeRequest": 10000000,
+
"maxConcurrentRequest": 8,
+
"maxCallsInRequest": 32,
+
"maxObjectsInGet": 256,
+
"maxObjectsInSet": 128,
+
"collationAlgorithms": [
+
"urn:ietf:params:jmap:mail": {}
+
"urn:ietf:params:jmap:contacts": {},
+
"https://example.com/apis/foobar": {
+
"name": "john@example.com",
+
"accountCapabilities": {
+
"urn:ietf:params:jmap:mail": {
+
"maxMailboxesPerEmail": null,
+
"urn:ietf:params:jmap:contacts": {
+
Jenkins & Newman Standards Track [Page 14]
+
RFC 8620 JMAP July 2019
+
"name": "jane@example.com",
+
"accountCapabilities": {
+
"urn:ietf:params:jmap:mail": {
+
"maxMailboxesPerEmail": 1,
+
"urn:ietf:params:jmap:mail": "A13824",
+
"urn:ietf:params:jmap:contacts": "A13824"
+
"username": "john@example.com",
+
"apiUrl": "https://jmap.example.com/api/",
+
"downloadUrl": "https://jmap.example.com
+
/download/{accountId}/{blobId}/{name}?accept={type}",
+
"uploadUrl": "https://jmap.example.com/upload/{accountId}/",
+
"eventSourceUrl": "https://jmap.example.com
+
/eventsource/?types={types}&closeafter={closeafter}&ping={ping}",
+
"state": "75128aab4b1b"
+
2.2. Service Autodiscovery
+
There are two standardised autodiscovery methods in use for Internet
+
o DNS SRV (see [RFC2782], [RFC6186], and [RFC6764])
+
o .well-known/servicename (see [RFC8615])
+
A JMAP-supporting host for the domain "example.com" SHOULD publish a
+
SRV record "_jmap._tcp.example.com" that gives a hostname and port
+
(usually port "443"). The JMAP Session resource is then
+
"https://${hostname}[:${port}]/.well-known/jmap" (following any
+
If the client has a username in the form of an email address, it MAY
+
use the domain portion of this to attempt autodiscovery of the JMAP
+
Jenkins & Newman Standards Track [Page 15]
+
RFC 8620 JMAP July 2019
+
3. Structured Data Exchange
+
The client may make an API request to the server to get or set
+
structured data. This request consists of an ordered series of
+
method calls. These are processed by the server, which then returns
+
an ordered series of responses.
+
3.1. Making an API Request
+
To make an API request, the client makes an authenticated POST
+
request to the API resource, which is defined by the "apiUrl"
+
property in the Session object (see Section 2).
+
The request MUST be of type "application/json" and consist of a
+
single JSON-encoded "Request" object, as defined in Section 3.3. If
+
successful, the response MUST also be of type "application/json" and
+
consist of a single "Response" object, as defined in Section 3.4.
+
3.2. The Invocation Data Type
+
Method calls and responses are represented by the *Invocation* data
+
type. This is a tuple, represented as a JSON array containing three
+
1. A "String" *name* of the method to call or of the response.
+
2. A "String[*]" object containing named *arguments* for that method
+
3. A "String" *method call id*: an arbitrary string from the client
+
to be echoed back with the responses emitted by that method call
+
(a method may return 1 or more responses, as it may make implicit
+
calls to other methods; all responses initiated by this method
+
call get the same method call id in the response).
+
3.3. The Request Object
+
A *Request* object has the following properties:
+
The set of capabilities the client wishes to use. The client MAY
+
include capability identifiers even if the method calls it makes
+
do not utilise those capabilities. The server advertises the set
+
of specifications it supports in the Session object (see
+
Section 2), as keys on the "capabilities" property.
+
Jenkins & Newman Standards Track [Page 16]
+
RFC 8620 JMAP July 2019
+
o methodCalls: "Invocation[]"
+
An array of method calls to process on the server. The method
+
calls MUST be processed sequentially, in order.
+
o createdIds: "Id[Id]" (optional)
+
A map of a (client-specified) creation id to the id the server
+
assigned when a record was successfully created.
+
As described later in this specification, some records may have a
+
property that contains the id of another record. To allow more
+
efficient network usage, you can set this property to reference a
+
record created earlier in the same API request. Since the real id
+
is unknown when the request is created, the client can instead
+
specify the creation id it assigned, prefixed with a "#" (see
+
Section 5.3 for more details).
+
As the server processes API requests, any time it successfully
+
creates a new record, it adds the creation id to this map (see the
+
"create" argument to /set in Section 5.3), with the server-
+
assigned real id as the value. If it comes across a reference to
+
a creation id in a create/update, it looks it up in the map and
+
replaces the reference with the real id, if found.
+
The client can pass an initial value for this map as the
+
"createdIds" property of the Request object. This may be an empty
+
object. If given in the request, the response will also include a
+
createdIds property. This allows proxy servers to easily split a
+
JMAP request into multiple JMAP requests to send to different
+
servers. For example, it could send the first two method calls to
+
server A, then the third to server B, before sending the fourth to
+
server A again. By passing the createdIds of the previous
+
response to the next request, it can ensure all of these still
+
resolve. See Section 5.8 for further discussion of proxy
+
Future specifications MAY add further properties to the Request
+
object to extend the semantics. To ensure forwards compatibility, a
+
server MUST ignore any other properties it does not understand on the
+
Jenkins & Newman Standards Track [Page 17]
+
RFC 8620 JMAP July 2019
+
"using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail" ],
+
[ "method3", {}, "c3" ]
+
3.4. The Response Object
+
A *Response* object has the following properties:
+
o methodResponses: "Invocation[]"
+
An array of responses, in the same format as the "methodCalls" on
+
the Request object. The output of the methods MUST be added to
+
the "methodResponses" array in the same order that the methods are
+
o createdIds: "Id[Id]" (optional; only returned if given in the
+
A map of a (client-specified) creation id to the id the server
+
assigned when a record was successfully created. This MUST
+
include all creation ids passed in the original createdIds
+
parameter of the Request object, as well as any additional ones
+
added for newly created records.
+
o sessionState: "String"
+
The current value of the "state" string on the Session object, as
+
described in Section 2. Clients may use this to detect if this
+
object has changed and needs to be refetched.
+
Unless otherwise specified, if the method call completed
+
successfully, its response name is the same as the method name in the
+
Jenkins & Newman Standards Track [Page 18]
+
RFC 8620 JMAP July 2019
+
3.4.1. Example Response
+
[ "anotherResponseFromMethod2", {
+
"sessionState": "75128aab4b1b"
+
3.5. Omitting Arguments
+
An argument to a method may be specified to have a default value. If
+
omitted by the client, the server MUST treat the method call the same
+
as if the default value had been specified. Similarly, the server
+
MAY omit any argument in a response that has the default value.
+
Unless otherwise specified in a method description, null is the
+
default value for any argument in a request or response where this is
+
allowed by the type signature. Other arguments may only be omitted
+
if an explicit default value is defined in the method description.
+
There are three different levels of granularity at which an error may
+
When an API request is made, the request as a whole may be rejected
+
due to rate limiting, malformed JSON, request for an unknown
+
capability, etc. In this case, the entire request is rejected with
+
an appropriate HTTP error response code and an additional JSON body
+
with more detail for the client.
+
Provided the request itself is syntactically valid (the JSON is valid
+
and when decoded, it matches the type signature of a Request object),
+
the methods within it are executed sequentially by the server. Each
+
Jenkins & Newman Standards Track [Page 19]
+
RFC 8620 JMAP July 2019
+
method may individually fail, for example, if invalid arguments are
+
given or an unknown method name is called.
+
Finally, methods that make changes to the server state often act upon
+
a number of different records within a single call. Each record
+
change may be separately rejected with a SetError, as described in
+
3.6.1. Request-Level Errors
+
When an HTTP error response is returned to the client, the server
+
SHOULD return a JSON "problem details" object as the response body,
+
The following problem types are defined:
+
o "urn:ietf:params:jmap:error:unknownCapability"
+
The client included a capability in the "using" property of the
+
request that the server does not support.
+
o "urn:ietf:params:jmap:error:notJSON"
+
The content type of the request was not "application/json" or the
+
request did not parse as I-JSON.
+
o "urn:ietf:params:jmap:error:notRequest"
+
The request parsed as JSON but did not match the type signature of
+
o "urn:ietf:params:jmap:error:limit"
+
The request was not processed as it would have exceeded one of the
+
request limits defined on the capability object, such as
+
maxSizeRequest, maxCallsInRequest, or maxConcurrentRequests. A
+
"limit" property MUST also be present on the "problem details"
+
object, containing the name of the limit being applied.
+
"type": "urn:ietf:params:jmap:error:unknownCapability",
+
"detail": "The Request object used capability
+
'https://example.com/apis/foobar', which is not supported
+
Jenkins & Newman Standards Track [Page 20]
+
RFC 8620 JMAP July 2019
+
"type": "urn:ietf:params:jmap:error:limit",
+
"limit": "maxSizeRequest",
+
"detail": "The request is larger than the server is willing to
+
3.6.2. Method-Level Errors
+
If a method encounters an error, the appropriate "error" response
+
MUST be inserted at the current point in the "methodResponses" array
+
and, unless otherwise specified, further processing MUST NOT happen
+
within that method call.
+
Any further method calls in the request MUST then be processed as
+
normal. Errors at the method level MUST NOT generate an HTTP-level
+
An "error" response looks like this:
+
"type": "unknownMethod"
+
The response name is "error", and it MUST have a type property.
+
Other properties may be present with further information; these are
+
detailed in the error type descriptions where appropriate.
+
With the exception of when the "serverPartialFail" error is returned,
+
the externally visible state of the server MUST NOT have changed if
+
an error is returned at the method level.
+
The following error types are defined, which may be returned for any
+
method call where appropriate:
+
"serverUnavailable": Some internal server resource was temporarily
+
unavailable. Attempting the same operation later (perhaps after a
+
backoff with a random factor) may succeed.
+
"serverFail": An unexpected or unknown error occurred during the
+
processing of the call. A "description" property should provide more
+
details about the error. The method call made no changes to the
+
server's state. Attempting the same operation again is expected to
+
fail again. Contacting the service administrator is likely necessary
+
to resolve this problem if it is persistent.
+
Jenkins & Newman Standards Track [Page 21]
+
RFC 8620 JMAP July 2019
+
"serverPartialFail": Some, but not all, expected changes described by
+
the method occurred. The client MUST resynchronise impacted data to
+
determine server state. Use of this error is strongly discouraged.
+
"unknownMethod": The server does not recognise this method name.
+
"invalidArguments": One of the arguments is of the wrong type or is
+
otherwise invalid, or a required argument is missing. A
+
"description" property MAY be present to help debug with an
+
explanation of what the problem was. This is a non-localised string,
+
and it is not intended to be shown directly to end users.
+
"invalidResultReference": The method used a result reference for one
+
of its arguments (see Section 3.7), but this failed to resolve.
+
"forbidden": The method and arguments are valid, but executing the
+
method would violate an Access Control List (ACL) or other
+
"accountNotFound": The accountId does not correspond to a valid
+
"accountNotSupportedByMethod": The accountId given corresponds to a
+
valid account, but the account does not support this method or data
+
"accountReadOnly": This method modifies state, but the account is
+
read-only (as returned on the corresponding Account object in the
+
JMAP Session resource).
+
Further possible errors for a particular method are specified in the
+
Further general errors MAY be defined in future RFCs. Should a
+
client receive an error type it does not understand, it MUST treat it
+
the same as the "serverFail" type.
+
3.7. References to Previous Method Results
+
To allow clients to make more efficient use of the network and avoid
+
round trips, an argument to one method can be taken from the result
+
of a previous method call in the same request.
+
To do this, the client prefixes the argument name with "#" (an
+
octothorpe). The value is a ResultReference object as described
+
below. When processing a method call, the server MUST first check
+
the arguments object for any names beginning with "#". If found, the
+
result reference should be resolved and the value used as the "real"
+
Jenkins & Newman Standards Track [Page 22]
+
RFC 8620 JMAP July 2019
+
argument. The method is then processed as normal. If any result
+
reference fails to resolve, the whole method MUST be rejected with an
+
"invalidResultReference" error. If an arguments object contains the
+
same argument name in normal and referenced form (e.g., "foo" and
+
"#foo"), the method MUST return an "invalidArguments" error.
+
A *ResultReference* object has the following properties:
+
The method call id (see Section 3.2) of a previous method call in
+
The required name of a response to that method call.
+
A pointer into the arguments of the response selected via the name
+
and resultOf properties. This is a JSON Pointer [RFC6901], except
+
it also allows the use of "*" to map through an array (see the
+
1. Find the first response with a method call id identical to the
+
"resultOf" property of the ResultReference in the
+
"methodResponses" array from previously processed method calls in
+
the same request. If none, evaluation fails.
+
2. If the response name is not identical to the "name" property of
+
the ResultReference, evaluation fails.
+
3. Apply the "path" to the arguments object of the response (the
+
second item in the response array) following the JSON Pointer
+
algorithm [RFC6901], except with the following addition in
+
"Evaluation" (see Section 4):
+
If the currently referenced value is a JSON array, the reference
+
token may be exactly the single character "*", making the new
+
referenced value the result of applying the rest of the JSON
+
Pointer tokens to every item in the array and returning the
+
results in the same order in a new array. If the result of
+
applying the rest of the pointer tokens to each item was itself
+
an array, the contents of this array are added to the output
+
rather than the array itself (i.e., the result is flattened from
+
an array of arrays to a single array). If the result of applying
+
Jenkins & Newman Standards Track [Page 23]
+
RFC 8620 JMAP July 2019
+
the rest of the pointer tokens to a value was itself an array,
+
its items should be included individually in the output rather
+
than including the array itself (i.e., the result is flattened
+
from an array of arrays to a single array).
+
As a simple example, suppose we have the following API request
+
After executing the first method call, the "methodResponses" array
+
"hasMoreChanges": false,
+
"created": [ "f1", "f4" ],
+
To execute the "Foo/get" call, we look through the arguments and find
+
there is one with a "#" prefix. To resolve this, we apply the
+
1. Find the first response with method call id "t0". The "Foo/
+
changes" response fulfils this criterion.
+
2. Check that the response name is the same as in the result
+
reference. It is, so this is fine.
+
3. Apply the "path" as a JSON Pointer to the arguments object. This
+
simply selects the "created" property, so the result of
+
evaluating is: [ "f1", "f4" ].
+
Jenkins & Newman Standards Track [Page 24]
+
RFC 8620 JMAP July 2019
+
The JMAP server now continues to process the "Foo/get" call as though
+
Now, a more complicated example using the JMAP Mail data model: fetch
+
the "from"/"date"/"subject" for every Email in the first 10 Threads
+
in the inbox (sorted newest first):
+
"filter": { "inMailbox": "id_of_inbox" },
+
"sort": [{ "property": "receivedAt", "isAscending": false }],
+
"collapseThreads": true,
+
"properties": [ "threadId" ]
+
"path": "/list/*/threadId"
+
"path": "/list/*/emailIds"
+
"properties": [ "from", "receivedAt", "subject" ]
+
Jenkins & Newman Standards Track [Page 25]
+
RFC 8620 JMAP July 2019
+
After executing the first 3 method calls, the "methodResponses" array
+
"queryState": "abcdefg",
+
"canCalculateChanges": true,
+
"ids": [ "msg1023", "msg223", "msg110", "msg93", "msg91",
+
"msg38", "msg36", "msg33", "msg11", "msg1" ]
+
"emailIds": [ "msg1020", "msg1021", "msg1023" ]
+
"emailIds": [ "msg201", "msg223" ]
+
To execute the final "Email/get" call, we look through the arguments
+
and find there is one with a "#" prefix. To resolve this, we apply
+
1. Find the first response with method call id "t2". The "Thread/
+
get" response fulfils this criterion.
+
Jenkins & Newman Standards Track [Page 26]
+
RFC 8620 JMAP July 2019
+
2. "Thread/get" is the name specified in the result reference, so
+
3. Apply the "path" as a JSON Pointer to the arguments object.
+
1. "list": get the array of thread objects
+
2. "*": for each of the items in the array:
+
a. "emailIds": get the array of Email ids
+
b. Concatenate these into a single array of all the ids in
+
The JMAP server now continues to process the "Email/get" call as
+
though the arguments were:
+
"ids": [ "msg1020", "msg1021", "msg1023", "msg201", "msg223", ... ],
+
"properties": [ "from", "receivedAt", "subject" ]
+
The ResultReference performs a similar role to that of the creation
+
id, in that it allows a chained method call to refer to information
+
not available when the request is generated. However, they are
+
different things and not interchangeable; the only commonality is the
+
octothorpe used to indicate them.
+
3.8. Localisation of User-Visible Strings
+
If returning a custom string to be displayed to the user, for
+
example, an error message, the server SHOULD use information from the
+
Accept-Language header of the request (as defined in Section 5.3.5 of
+
[RFC7231]) to choose the best available localisation. The Content-
+
Language header of the response (see Section 3.1.3.2 of [RFC7231])
+
SHOULD indicate the language being used for user-visible strings.
+
For example, suppose a request was made with the following header:
+
Accept-Language: fr-CH, fr;q=0.9, de;q=0.8, en;q=0.7, *;q=0.5
+
and a method generated an error to display to the user. The server
+
has translations of the error message in English and German. Looking
+
at the Accept-Language header, the user's preferred language is
+
French. Since we don't have a translation for this, we look at the
+
Jenkins & Newman Standards Track [Page 27]
+
RFC 8620 JMAP July 2019
+
next most preferred, which is German. We have a German translation,
+
so the server returns this and indicates the language chosen in a
+
Content-Language header like so:
+
As always, the server must be strict about data received from the
+
client. Arguments need to be checked for validity; a malicious user
+
could attempt to find an exploit through the API. In case of invalid
+
arguments (unknown/insufficient/wrong type for data, etc.), the
+
method MUST return an "invalidArguments" error and terminate.
+
Method calls within a single request MUST be executed in order.
+
However, method calls from different concurrent API requests may be
+
interleaved. This means that the data on the server may change
+
between two method calls within a single API request.
+
4. The Core/echo Method
+
The "Core/echo" method returns exactly the same arguments as it is
+
given. It is useful for testing if you have a valid authenticated
+
connection to a JMAP API endpoint.
+
Jenkins & Newman Standards Track [Page 28]
+
RFC 8620 JMAP July 2019
+
5. Standard Methods and Naming Convention
+
JMAP provides a uniform interface for creating, retrieving, updating,
+
and deleting objects of a particular type. For a "Foo" data type,
+
records of that type would be fetched via a "Foo/get" call and
+
modified via a "Foo/set" call. Delta updates may be fetched via a
+
"Foo/changes" call. These methods all follow a standard format as
+
Some types may not have all these methods. Specifications defining
+
types MUST specify which methods are available for the type.
+
Objects of type Foo are fetched via a call to "Foo/get".
+
It takes the following arguments:
+
The id of the account to use.
+
The ids of the Foo objects to return. If null, then *all* records
+
of the data type are returned, if this is supported for that data
+
type and the number of records does not exceed the
+
"maxObjectsInGet" limit.
+
o properties: "String[]|null"
+
If supplied, only the properties listed in the array are returned
+
for each Foo object. If null, all properties of the object are
+
returned. The id property of the object is *always* returned,
+
even if not explicitly requested. If an invalid property is
+
requested, the call MUST be rejected with an "invalidArguments"
+
The response has the following arguments:
+
The id of the account used for the call.
+
Jenkins & Newman Standards Track [Page 29]
+
RFC 8620 JMAP July 2019
+
A (preferably short) string representing the state on the server
+
for *all* the data of this type in the account (not just the
+
objects returned in this call). If the data changes, this string
+
MUST change. If the Foo data is unchanged, servers SHOULD return
+
the same state string on subsequent requests for this data type.
+
When a client receives a response with a different state string to
+
a previous call, it MUST either throw away all currently cached
+
objects for the type or call "Foo/changes" to get the exact
+
An array of the Foo objects requested. This is the *empty array*
+
if no objects were found or if the "ids" argument passed in was
+
also an empty array. The results MAY be in a different order to
+
the "ids" in the request arguments. If an identical id is
+
included more than once in the request, the server MUST only
+
include it once in either the "list" or the "notFound" argument of
+
This array contains the ids passed to the method for records that
+
do not exist. The array is empty if all requested ids were found
+
or if the "ids" argument passed in was either null or an empty
+
The following additional error may be returned instead of the "Foo/
+
"requestTooLarge": The number of ids requested by the client exceeds
+
the maximum number the server is willing to process in a single
+
When the state of the set of Foo records in an account changes on the
+
server (whether due to creation, updates, or deletion), the "state"
+
property of the "Foo/get" response will change. The "Foo/changes"
+
method allows a client to efficiently update the state of its Foo
+
cache to match the new state on the server. It takes the following
+
The id of the account to use.
+
Jenkins & Newman Standards Track [Page 30]
+
RFC 8620 JMAP July 2019
+
The current state of the client. This is the string that was
+
returned as the "state" argument in the "Foo/get" response. The
+
server will return the changes that have occurred since this
+
o maxChanges: "UnsignedInt|null"
+
The maximum number of ids to return in the response. The server
+
MAY choose to return fewer than this value but MUST NOT return
+
more. If not given by the client, the server may choose how many
+
to return. If supplied by the client, the value MUST be a
+
positive integer greater than 0. If a value outside of this range
+
is given, the server MUST reject the call with an
+
"invalidArguments" error.
+
The response has the following arguments:
+
The id of the account used for the call.
+
This is the "sinceState" argument echoed back; it's the state from
+
which the server is returning changes.
+
This is the state the client will be in after applying the set of
+
changes to the old state.
+
o hasMoreChanges: "Boolean"
+
If true, the client may call "Foo/changes" again with the
+
"newState" returned to get further updates. If false, "newState"
+
is the current server state.
+
An array of ids for records that have been created since the old
+
An array of ids for records that have been updated since the old
+
Jenkins & Newman Standards Track [Page 31]
+
RFC 8620 JMAP July 2019
+
An array of ids for records that have been destroyed since the old
+
If a record has been created AND updated since the old state, the
+
server SHOULD just return the id in the "created" list but MAY return
+
it in the "updated" list as well.
+
If a record has been updated AND destroyed since the old state, the
+
server SHOULD just return the id in the "destroyed" list but MAY
+
return it in the "updated" list as well.
+
If a record has been created AND destroyed since the old state, the
+
server SHOULD remove the id from the response entirely. However, it
+
MAY include it in just the "destroyed" list or in both the
+
"destroyed" and "created" lists.
+
If a "maxChanges" is supplied, or set automatically by the server,
+
the server MUST ensure the number of ids returned across "created",
+
"updated", and "destroyed" does not exceed this limit. If there are
+
more changes than this between the client's state and the current
+
server state, the server SHOULD generate an update to take the client
+
to an intermediate state, from which the client can continue to call
+
"Foo/changes" until it is fully up to date. If it is unable to
+
calculate an intermediate state, it MUST return a
+
"cannotCalculateChanges" error response instead.
+
When generating intermediate states, the server may choose how to
+
divide up the changes. For many types, it will provide a better user
+
experience to return the more recent changes first, as this is more
+
likely to be what the user is most interested in. The client can
+
then continue to page in the older changes while the user is viewing
+
the newer data. For example, suppose a server went through the
+
And a client asks for changes from state "B". The server might first
+
get the ids of records created, updated, or destroyed between states
+
D and E, returning them with:
+
Jenkins & Newman Standards Track [Page 32]
+
RFC 8620 JMAP July 2019
+
The client will then ask for the change from state "B-D-E", and the
+
server can return the changes between states C and D, returning:
+
Finally, the client will request the changes from "B-C-E", and the
+
server can return the changes between states B and C, returning:
+
Should the state on the server be modified in the middle of all this
+
(to "F"), the server still does the same, but now when the update to
+
state "E" is returned, it would indicate that it still has more
+
changes for the client to fetch.
+
Where multiple changes to a record are split across different
+
intermediate states, the server MUST NOT return a record as created
+
after a response that deems it as updated or destroyed, and it MUST
+
NOT return a record as destroyed before a response that deems it as
+
created or updated. The server may have to coalesce multiple changes
+
to a record to satisfy this requirement.
+
The following additional errors may be returned instead of the "Foo/
+
"cannotCalculateChanges": The server cannot calculate the changes
+
from the state string given by the client. Usually, this is due to
+
the client's state being too old or the server being unable to
+
produce an update to an intermediate state when there are too many
+
updates. The client MUST invalidate its Foo cache.
+
Maintaining state to allow calculation of "Foo/changes" can be
+
expensive for the server, but always returning
+
"cannotCalculateChanges" severely increases network traffic and
+
resource usage for the client. To allow efficient sync, servers
+
SHOULD be able to calculate changes from any state string that was
+
given to a client within the last 30 days (but of course may support
+
calculating updates from states older than this).
+
Jenkins & Newman Standards Track [Page 33]
+
RFC 8620 JMAP July 2019
+
Modifying the state of Foo objects on the server is done via the
+
"Foo/set" method. This encompasses creating, updating, and
+
destroying Foo records. This allows the server to sort out ordering
+
and dependencies that may exist if doing multiple operations at once
+
(for example, to ensure there is always a minimum number of a certain
+
The "Foo/set" method takes the following arguments:
+
The id of the account to use.
+
o ifInState: "String|null"
+
This is a state string as returned by the "Foo/get" method
+
(representing the state of all objects of this type in the
+
account). If supplied, the string must match the current state;
+
otherwise, the method will be aborted and a "stateMismatch" error
+
returned. If null, any changes will be applied to the current
+
o create: "Id[Foo]|null"
+
A map of a *creation id* (a temporary id set by the client) to Foo
+
objects, or null if no objects are to be created.
+
The Foo object type definition may define default values for
+
properties. Any such property may be omitted by the client.
+
The client MUST omit any properties that may only be set by the
+
server (for example, the "id" property on most object types).
+
o update: "Id[PatchObject]|null"
+
A map of an id to a Patch object to apply to the current Foo
+
object with that id, or null if no objects are to be updated.
+
A *PatchObject* is of type "String[*]" and represents an unordered
+
set of patches. The keys are a path in JSON Pointer format
+
[RFC6901], with an implicit leading "/" (i.e., prefix each key
+
with "/" before applying the JSON Pointer evaluation algorithm).
+
All paths MUST also conform to the following restrictions; if
+
there is any violation, the update MUST be rejected with an
+
Jenkins & Newman Standards Track [Page 34]
+
RFC 8620 JMAP July 2019
+
* The pointer MUST NOT reference inside an array (i.e., you MUST
+
NOT insert/delete from an array; the array MUST be replaced in
+
* All parts prior to the last (i.e., the value after the final
+
slash) MUST already exist on the object being patched.
+
* There MUST NOT be two patches in the PatchObject where the
+
pointer of one is the prefix of the pointer of the other, e.g.,
+
"alerts/1/offset" and "alerts".
+
The value associated with each pointer determines how to apply
+
* If null, set to the default value if specified for this
+
property; otherwise, remove the property from the patched
+
object. If the key is not present in the parent, this a no-op.
+
* Anything else: The value to set for this property (this may be
+
a replacement or addition to the object being patched).
+
Any server-set properties MAY be included in the patch if their
+
value is identical to the current server value (before applying
+
the patches to the object). Otherwise, the update MUST be
+
rejected with an "invalidProperties" SetError.
+
This patch definition is designed such that an entire Foo object
+
is also a valid PatchObject. The client may choose to optimise
+
network usage by just sending the diff or may send the whole
+
object; the server processes it the same either way.
+
A list of ids for Foo objects to permanently delete, or null if no
+
objects are to be destroyed.
+
Each creation, modification, or destruction of an object is
+
considered an atomic unit. It is permissible for the server to
+
commit changes to some objects but not others; however, it MUST NOT
+
only commit part of an update to a single record (e.g., update a
+
"name" property but not a "count" property, if both are supplied in
+
The final state MUST be valid after the "Foo/set" is finished;
+
however, the server may have to transition through invalid
+
intermediate states (not exposed to the client) while processing the
+
individual create/update/destroy requests. For example, suppose
+
there is a "name" property that must be unique. A single method call
+
Jenkins & Newman Standards Track [Page 35]
+
RFC 8620 JMAP July 2019
+
could rename an object A => B and simultaneously rename another
+
object B => A. If the final state is valid, this is allowed.
+
Otherwise, each creation, modification, or destruction of an object
+
should be processed sequentially and accepted/rejected based on the
+
If a create, update, or destroy is rejected, the appropriate error
+
MUST be added to the notCreated/notUpdated/notDestroyed property of
+
the response, and the server MUST continue to the next create/update/
+
destroy. It does not terminate the method.
+
If an id given cannot be found, the update or destroy MUST be
+
rejected with a "notFound" set error.
+
The server MAY skip an update (rejecting it with a "willDestroy"
+
SetError) if that object is destroyed in the same /set request.
+
Some records may hold references to other records (foreign keys).
+
That reference may be set (via create or update) in the same request
+
as the referenced record is created. To do this, the client refers
+
to the new record using its creation id prefixed with a "#". The
+
order of the method calls in the request by the client MUST be such
+
that the record being referenced is created in the same or an earlier
+
call. Thus, the server never has to look ahead. Instead, while
+
processing a request, the server MUST keep a simple map for the
+
duration of the request of creation id to record id for each newly
+
created record, so it can substitute in the correct value if
+
necessary in later method calls. In the case of records with
+
references to the same type, the server MUST order the creates and
+
updates within a single method call so that creates happen before
+
their creation ids are referenced by another create/update/destroy in
+
Creation ids are not scoped by type but are a single map for all
+
types. A client SHOULD NOT reuse a creation id anywhere in the same
+
API request. If a creation id is reused, the server MUST map the
+
creation id to the most recently created item with that id. To allow
+
easy proxying of API requests, an initial set of creation id to real
+
id values may be passed with a request (see "The Request Object",
+
Section 3.3) and the final state of the map passed out with the
+
response (see "The Response Object", Section 3.4).
+
The response has the following arguments:
+
The id of the account used for the call.
+
Jenkins & Newman Standards Track [Page 36]
+
RFC 8620 JMAP July 2019
+
o oldState: "String|null"
+
The state string that would have been returned by "Foo/get" before
+
making the requested changes, or null if the server doesn't know
+
what the previous state string was.
+
The state string that will now be returned by "Foo/get".
+
o created: "Id[Foo]|null"
+
A map of the creation id to an object containing any properties of
+
the created Foo object that were not sent by the client. This
+
includes all server-set properties (such as the "id" in most
+
object types) and any properties that were omitted by the client
+
and thus set to a default by the server.
+
This argument is null if no Foo objects were successfully created.
+
o updated: "Id[Foo|null]|null"
+
The keys in this map are the ids of all Foos that were
+
The value for each id is a Foo object containing any property that
+
changed in a way *not* explicitly requested by the PatchObject
+
sent to the server, or null if none. This lets the client know of
+
any changes to server-set or computed properties.
+
This argument is null if no Foo objects were successfully updated.
+
o destroyed: "Id[]|null"
+
A list of Foo ids for records that were successfully destroyed, or
+
o notCreated: "Id[SetError]|null"
+
A map of the creation id to a SetError object for each record that
+
failed to be created, or null if all successful.
+
o notUpdated: "Id[SetError]|null"
+
A map of the Foo id to a SetError object for each record that
+
failed to be updated, or null if all successful.
+
Jenkins & Newman Standards Track [Page 37]
+
RFC 8620 JMAP July 2019
+
o notDestroyed: "Id[SetError]|null"
+
A map of the Foo id to a SetError object for each record that
+
failed to be destroyed, or null if all successful.
+
A *SetError* object has the following properties:
+
o description: "String|null"
+
A description of the error to help with debugging that includes an
+
explanation of what the problem was. This is a non-localised
+
string and is not intended to be shown directly to end users.
+
The following SetError types are defined and may be returned for set
+
operations on any record type where appropriate:
+
o "forbidden": (create; update; destroy). The create/update/destroy
+
would violate an ACL or other permissions policy.
+
o "overQuota": (create; update). The create would exceed a server-
+
defined limit on the number or total size of objects of this type.
+
o "tooLarge": (create; update). The create/update would result in
+
an object that exceeds a server-defined limit for the maximum size
+
of a single object of this type.
+
o "rateLimit": (create). Too many objects of this type have been
+
created recently, and a server-defined rate limit has been
+
reached. It may work if tried again later.
+
o "notFound": (update; destroy). The id given to update/destroy
+
o "invalidPatch": (update). The PatchObject given to update the
+
record was not a valid patch (see the patch description).
+
o "willDestroy": (update). The client requested that an object be
+
both updated and destroyed in the same /set request, and the
+
server has decided to therefore ignore the update.
+
Jenkins & Newman Standards Track [Page 38]
+
RFC 8620 JMAP July 2019
+
o "invalidProperties": (create; update). The record given is
+
invalid in some way. For example:
+
* It contains properties that are invalid according to the type
+
specification of this record type.
+
* It contains a property that may only be set by the server
+
(e.g., "id") and is different to the current value. Note, to
+
allow clients to pass whole objects back, it is not an error to
+
include a server-set property in an update as long as the value
+
is identical to the current value on the server.
+
* There is a reference to another record (foreign key), and the
+
given id does not correspond to a valid record.
+
The SetError object SHOULD also have a property called
+
"properties" of type "String[]" that lists *all* the properties
+
Individual methods MAY specify more specific errors for certain
+
conditions that would otherwise result in an invalidProperties
+
error. If the condition of one of these is met, it MUST be
+
returned instead of the invalidProperties error.
+
o "singleton": (create; destroy). This is a singleton type, so you
+
cannot create another one or destroy the existing one.
+
Other possible SetError types MAY be given in specific method
+
descriptions. Other properties MAY also be present on the SetError
+
object, as described in the relevant methods.
+
The following additional errors may be returned instead of the "Foo/
+
"requestTooLarge": The total number of objects to create, update, or
+
destroy exceeds the maximum number the server is willing to process
+
in a single method call.
+
"stateMismatch": An "ifInState" argument was supplied, and it does
+
not match the current state.
+
Jenkins & Newman Standards Track [Page 39]
+
RFC 8620 JMAP July 2019
+
The only way to move Foo records *between* two different accounts is
+
to copy them using the "Foo/copy" method; once the copy has
+
succeeded, delete the original. The "onSuccessDestroyOriginal"
+
argument allows you to try to do this in one method call; however,
+
note that the two different actions are not atomic, so it is possible
+
for the copy to succeed but the original not to be destroyed for some
+
The copy is conceptually in three phases:
+
1. Reading the current values from the "from" account.
+
2. Writing the new copies to the other account.
+
3. Destroying the originals in the "from" account, if requested.
+
Data may change in between phases due to concurrent requests.
+
The "Foo/copy" method takes the following arguments:
+
The id of the account to copy records from.
+
o ifFromInState: "String|null"
+
This is a state string as returned by the "Foo/get" method. If
+
supplied, the string must match the current state of the account
+
referenced by the fromAccountId when reading the data to be
+
copied; otherwise, the method will be aborted and a
+
"stateMismatch" error returned. If null, the data will be read
+
from the current state.
+
The id of the account to copy records to. This MUST be different
+
to the "fromAccountId".
+
o ifInState: "String|null"
+
This is a state string as returned by the "Foo/get" method. If
+
supplied, the string must match the current state of the account
+
referenced by the accountId; otherwise, the method will be aborted
+
and a "stateMismatch" error returned. If null, any changes will
+
be applied to the current state.
+
Jenkins & Newman Standards Track [Page 40]
+
RFC 8620 JMAP July 2019
+
A map of the *creation id* to a Foo object. The Foo object MUST
+
contain an "id" property, which is the id (in the fromAccount) of
+
the record to be copied. When creating the copy, any other
+
properties included are used instead of the current value for that
+
property on the original.
+
o onSuccessDestroyOriginal: "Boolean" (default: false)
+
If true, an attempt will be made to destroy the original records
+
that were successfully copied: after emitting the "Foo/copy"
+
response, but before processing the next method, the server MUST
+
make a single call to "Foo/set" to destroy the original of each
+
successfully copied record; the output of this is added to the
+
responses as normal, to be returned to the client.
+
o destroyFromIfInState: "String|null"
+
This argument is passed on as the "ifInState" argument to the
+
implicit "Foo/set" call, if made at the end of this request to
+
destroy the originals that were successfully copied.
+
Each record copy is considered an atomic unit that may succeed or
+
The response has the following arguments:
+
The id of the account records were copied from.
+
The id of the account records were copied to.
+
o oldState: "String|null"
+
The state string that would have been returned by "Foo/get" on the
+
account records that were copied to before making the requested
+
changes, or null if the server doesn't know what the previous
+
The state string that will now be returned by "Foo/get" on the
+
account records were copied to.
+
Jenkins & Newman Standards Track [Page 41]
+
RFC 8620 JMAP July 2019
+
o created: "Id[Foo]|null"
+
A map of the creation id to an object containing any properties of
+
the copied Foo object that are set by the server (such as the "id"
+
in most object types; note, the id is likely to be different to
+
the id of the object in the account it was copied from).
+
This argument is null if no Foo objects were successfully copied.
+
o notCreated: "Id[SetError]|null"
+
A map of the creation id to a SetError object for each record that
+
failed to be copied, or null if none.
+
The SetError may be any of the standard set errors returned for a
+
create or update. In addition, the following SetError is defined:
+
"alreadyExists": The server forbids duplicates, and the record
+
already exists in the target account. An "existingId" property of
+
type "Id" MUST be included on the SetError object with the id of the
+
The following additional errors may be returned instead of the "Foo/
+
"fromAccountNotFound": The "fromAccountId" does not correspond to a
+
"fromAccountNotSupportedByMethod": The "fromAccountId" given
+
corresponds to a valid account, but the account does not support this
+
"stateMismatch": An "ifInState" argument was supplied and it does not
+
match the current state, or an "ifFromInState" argument was supplied
+
and it does not match the current state in the from account.
+
For data sets where the total amount of data is expected to be very
+
small, clients can just fetch the complete set of data and then do
+
any sorting/filtering locally. However, for large data sets (e.g.,
+
multi-gigabyte mailboxes), the client needs to be able to
+
search/sort/window the data type on the server.
+
A query on the set of Foos in an account is made by calling "Foo/
+
query". This takes a number of arguments to determine which records
+
to include, how they should be sorted, and which part of the result
+
Jenkins & Newman Standards Track [Page 42]
+
RFC 8620 JMAP July 2019
+
should be returned (the full list may be *very* long). The result is
+
returned as a list of Foo ids.
+
A call to "Foo/query" takes the following arguments:
+
The id of the account to use.
+
o filter: "FilterOperator|FilterCondition|null"
+
Determines the set of Foos returned in the results. If null, all
+
objects in the account of this type are included in the results.
+
A *FilterOperator* object has the following properties:
+
This MUST be one of the following strings:
+
+ "AND": All of the conditions must match for the filter to
+
+ "OR": At least one of the conditions must match for the
+
+ "NOT": None of the conditions must match for the filter to
+
* conditions: "(FilterOperator|FilterCondition)[]"
+
The conditions to evaluate against each record.
+
A *FilterCondition* is an "object" whose allowed properties and
+
semantics depend on the data type and is defined in the /query
+
method specification for that type. It MUST NOT have an
+
o sort: "Comparator[]|null"
+
Lists the names of properties to compare between two Foo records,
+
and how to compare them, to determine which comes first in the
+
sort. If two Foo records have an identical value for the first
+
comparator, the next comparator will be considered, and so on. If
+
all comparators are the same (this includes the case where an
+
empty array or null is given as the "sort" argument), the sort
+
order is server dependent, but it MUST be stable between calls to
+
"Foo/query". A *Comparator* has the following properties:
+
Jenkins & Newman Standards Track [Page 43]
+
RFC 8620 JMAP July 2019
+
The name of the property on the Foo objects to compare.
+
* isAscending: "Boolean" (optional; default: true)
+
If true, sort in ascending order. If false, reverse the
+
comparator's results to sort in descending order.
+
* collation: "String" (optional; default is server-dependent)
+
The identifier, as registered in the collation registry defined
+
in [RFC4790], for the algorithm to use when comparing the order
+
of strings. The algorithms the server supports are advertised
+
in the capabilities object returned with the Session object
+
If omitted, the default algorithm is server dependent, but:
+
1. It MUST be unicode-aware.
+
2. It MAY be selected based on an Accept-Language header in
+
the request (as defined in [RFC7231], Section 5.3.5) or
+
out-of-band information about the user's language/locale.
+
3. It SHOULD be case insensitive where such a concept makes
+
sense for a language/locale. Where the user's language is
+
unknown, it is RECOMMENDED to follow the advice in
+
Section 5.2.3 of [RFC8264].
+
The "i;unicode-casemap" collation [RFC5051] and the Unicode
+
Collation Algorithm (<http://www.unicode.org/reports/tr10/>)
+
are two examples that fulfil these criterion and provide
+
reasonable behaviour for a large number of languages.
+
When the property being compared is not a string, the
+
"collation" property is ignored, and the following comparison
+
rules apply based on the type. In ascending order:
+
+ "Boolean": false comes before true.
+
+ "Number": A lower number comes before a higher number.
+
+ "Date"/"UTCDate": The earlier date comes first.
+
The Comparator object may also have additional properties as
+
required for specific sort operations defined in a type's /query
+
Jenkins & Newman Standards Track [Page 44]
+
RFC 8620 JMAP July 2019
+
o position: "Int" (default: 0)
+
The zero-based index of the first id in the full list of results
+
If a negative value is given, it is an offset from the end of the
+
list. Specifically, the negative value MUST be added to the total
+
number of results given the filter, and if still negative, it's
+
clamped to "0". This is now the zero-based index of the first id
+
If the index is greater than or equal to the total number of
+
objects in the results list, then the "ids" array in the response
+
will be empty, but this is not an error.
+
A Foo id. If supplied, the "position" argument is ignored. The
+
index of this id in the results will be used in combination with
+
the "anchorOffset" argument to determine the index of the first
+
result to return (see below for more details).
+
o anchorOffset: "Int" (default: 0)
+
The index of the first result to return relative to the index of
+
the anchor, if an anchor is given. This MAY be negative. For
+
example, "-1" means the Foo immediately preceding the anchor is
+
the first result in the list returned (see below for more
+
o limit: "UnsignedInt|null"
+
The maximum number of results to return. If null, no limit
+
presumed. The server MAY choose to enforce a maximum "limit"
+
argument. In this case, if a greater value is given (or if it is
+
null), the limit is clamped to the maximum; the new limit is
+
returned with the response so the client is aware. If a negative
+
value is given, the call MUST be rejected with an
+
"invalidArguments" error.
+
o calculateTotal: "Boolean" (default: false)
+
Does the client wish to know the total number of results in the
+
query? This may be slow and expensive for servers to calculate,
+
particularly with complex filters, so clients should take care to
+
only request the total when needed.
+
Jenkins & Newman Standards Track [Page 45]
+
RFC 8620 JMAP July 2019
+
If an "anchor" argument is given, the anchor is looked for in the
+
results after filtering and sorting. If found, the "anchorOffset" is
+
then added to its index. If the resulting index is now negative, it
+
is clamped to 0. This index is now used exactly as though it were
+
supplied as the "position" argument. If the anchor is not found, the
+
call is rejected with an "anchorNotFound" error.
+
If an "anchor" is specified, any position argument supplied by the
+
client MUST be ignored. If no "anchor" is supplied, any
+
"anchorOffset" argument MUST be ignored.
+
A client can use "anchor" instead of "position" to find the index of
+
an id within a large set of results.
+
The response has the following arguments:
+
The id of the account used for the call.
+
A string encoding the current state of the query on the server.
+
This string MUST change if the results of the query (i.e., the
+
matching ids and their sort order) have changed. The queryState
+
string MAY change if something has changed on the server, which
+
means the results may have changed but the server doesn't know for
+
The queryState string only represents the ordered list of ids that
+
match the particular query (including its sort/filter). There is
+
no requirement for it to change if a property on an object
+
matching the query changes but the query results are unaffected
+
(indeed, it is more efficient if the queryState string does not
+
change in this case). The queryState string only has meaning when
+
compared to future responses to a query with the same type/sort/
+
filter or when used with /queryChanges to fetch changes.
+
Should a client receive back a response with a different
+
queryState string to a previous call, it MUST either throw away
+
the currently cached query and fetch it again (note, this does not
+
require fetching the records again, just the list of ids) or call
+
"Foo/queryChanges" to get the difference.
+
Jenkins & Newman Standards Track [Page 46]
+
RFC 8620 JMAP July 2019
+
o canCalculateChanges: "Boolean"
+
This is true if the server supports calling "Foo/queryChanges"
+
with these "filter"/"sort" parameters. Note, this does not
+
guarantee that the "Foo/queryChanges" call will succeed, as it may
+
only be possible for a limited time afterwards due to server
+
internal implementation details.
+
o position: "UnsignedInt"
+
The zero-based index of the first result in the "ids" array within
+
the complete list of query results.
+
The list of ids for each Foo in the query results, starting at the
+
index given by the "position" argument of this response and
+
continuing until it hits the end of the results or reaches the
+
"limit" number of ids. If "position" is >= "total", this MUST be
+
o total: "UnsignedInt" (only if requested)
+
The total number of Foos in the results (given the "filter").
+
This argument MUST be omitted if the "calculateTotal" request
+
o limit: "UnsignedInt" (if set by the server)
+
The limit enforced by the server on the maximum number of results
+
to return. This is only returned if the server set a limit or
+
used a different limit than that given in the request.
+
The following additional errors may be returned instead of the "Foo/
+
"anchorNotFound": An anchor argument was supplied, but it cannot be
+
found in the results of the query.
+
"unsupportedSort": The "sort" is syntactically valid, but it includes
+
a property the server does not support sorting on or a collation
+
method it does not recognise.
+
"unsupportedFilter": The "filter" is syntactically valid, but the
+
server cannot process it. If the filter was the result of a user's
+
search input, the client SHOULD suggest that the user simplify their
+
Jenkins & Newman Standards Track [Page 47]
+
RFC 8620 JMAP July 2019
+
The "Foo/queryChanges" method allows a client to efficiently update
+
the state of a cached query to match the new state on the server. It
+
takes the following arguments:
+
The id of the account to use.
+
o filter: "FilterOperator|FilterCondition|null"
+
The filter argument that was used with "Foo/query".
+
o sort: "Comparator[]|null"
+
The sort argument that was used with "Foo/query".
+
o sinceQueryState: "String"
+
The current state of the query in the client. This is the string
+
that was returned as the "queryState" argument in the "Foo/query"
+
response with the same sort/filter. The server will return the
+
changes made to the query since this state.
+
o maxChanges: "UnsignedInt|null"
+
The maximum number of changes to return in the response. See
+
error descriptions below for more details.
+
The last (highest-index) id the client currently has cached from
+
the query results. When there are a large number of results, in a
+
common case, the client may have only downloaded and cached a
+
small subset from the beginning of the results. If the sort and
+
filter are both only on immutable properties, this allows the
+
server to omit changes after this point in the results, which can
+
significantly increase efficiency. If they are not immutable,
+
this argument is ignored.
+
o calculateTotal: "Boolean" (default: false)
+
Does the client wish to know the total number of results now in
+
the query? This may be slow and expensive for servers to
+
calculate, particularly with complex filters, so clients should
+
take care to only request the total when needed.
+
Jenkins & Newman Standards Track [Page 48]
+
RFC 8620 JMAP July 2019
+
The response has the following arguments:
+
The id of the account used for the call.
+
o oldQueryState: "String"
+
This is the "sinceQueryState" argument echoed back; that is, the
+
state from which the server is returning changes.
+
o newQueryState: "String"
+
This is the state the query will be in after applying the set of
+
changes to the old state.
+
o total: "UnsignedInt" (only if requested)
+
The total number of Foos in the results (given the "filter").
+
This argument MUST be omitted if the "calculateTotal" request
+
The "id" for every Foo that was in the query results in the old
+
state and that is not in the results in the new state.
+
If the server cannot calculate this exactly, the server MAY return
+
the ids of extra Foos in addition that may have been in the old
+
results but are not in the new results.
+
If the sort and filter are both only on immutable properties and
+
an "upToId" is supplied and exists in the results, any ids that
+
were removed but have a higher index than "upToId" SHOULD be
+
If the "filter" or "sort" includes a mutable property, the server
+
MUST include all Foos in the current results for which this
+
property may have changed. The position of these may have moved
+
in the results, so they must be reinserted by the client to ensure
+
its query cache is correct.
+
Jenkins & Newman Standards Track [Page 49]
+
RFC 8620 JMAP July 2019
+
The id and index in the query results (in the new state) for every
+
Foo that has been added to the results since the old state AND
+
every Foo in the current results that was included in the
+
"removed" array (due to a filter or sort based upon a mutable
+
If the sort and filter are both only on immutable properties and
+
an "upToId" is supplied and exists in the results, any ids that
+
were added but have a higher index than "upToId" SHOULD be
+
The array MUST be sorted in order of index, with the lowest index
+
An *AddedItem* object has the following properties:
+
The result of this is that if the client has a cached sparse array of
+
Foo ids corresponding to the results in the old state, then:
+
fooIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ]
+
If it *splices out* all ids in the removed array that it has in its
+
removed = [ "id2", "id31", ... ];
+
fooIds => [ "id1", null, null, "id3", "id4", null, null, null ]
+
and *splices in* (one by one in order, starting with the lowest
+
index) all of the ids in the added array:
+
added = [{ id: "id5", index: 0, ... }];
+
fooIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ]
+
and *truncates* or *extends* to the new total length, then the
+
results will now be in the new state.
+
Note: splicing in adds the item at the given index, incrementing the
+
index of all items previously at that or a higher index. Splicing
+
out is the inverse, removing the item and decrementing the index of
+
every item after it in the array.
+
Jenkins & Newman Standards Track [Page 50]
+
RFC 8620 JMAP July 2019
+
The following additional errors may be returned instead of the "Foo/
+
queryChanges" response:
+
"tooManyChanges": There are more changes than the client's
+
"maxChanges" argument. Each item in the removed or added array is
+
considered to be one change. The client may retry with higher max
+
changes or invalidate its cache of the query results.
+
"cannotCalculateChanges": The server cannot calculate the changes
+
from the queryState string given by the client, usually due to the
+
client's state being too old. The client MUST invalidate its cache
+
Suppose we have a type *Todo* with the following properties:
+
o id: "Id" (immutable; server-set)
+
A brief summary of what is to be done.
+
o keywords: "String[Boolean]" (default: {})
+
A set of keywords that apply to the Todo. The set is represented
+
as an object, with the keys being the "keywords". The value for
+
each key in the object MUST be true. (This format allows you to
+
update an individual key using patch syntax rather than having to
+
update the whole set of keywords as one, which a "String[]"
+
representation would require.)
+
o neuralNetworkTimeEstimation: "Number" (server-set)
+
The title and keywords are fed into the server's state-of-the-art
+
neural network to get an estimation of how long this Todo will
+
o subTodoIds: "Id[]|null"
+
The ids of a list of other Todos to complete as part of this Todo.
+
Suppose also that all the standard methods are defined for this type
+
and the FilterCondition object supports a "hasKeyword" property to
+
match Todos with the given keyword.
+
Jenkins & Newman Standards Track [Page 51]
+
RFC 8620 JMAP July 2019
+
A client might want to display the list of Todos with either a
+
"music" keyword or a "video" keyword, so it makes the following
+
{ "hasKeyword": "music" },
+
{ "hasKeyword": "video" }
+
"sort": [{ "property": "title" }],
+
Jenkins & Newman Standards Track [Page 52]
+
RFC 8620 JMAP July 2019
+
This would query the server for the set of Todos with a keyword of
+
either "music" or "video", sorted by title, and limited to the first
+
10 results. It fetches the full object for each of these Todos using
+
back-references to reference the result of the query. The response
+
might look something like:
+
"queryState": "y13213",
+
"canCalculateChanges": true,
+
"ids": [ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j" ]
+
"title": "Practise Piano",
+
"neuralNetworkTimeEstimation": 3600
+
"title": "Watch Daft Punk music video",
+
"neuralNetworkTimeEstimation": 18000
+
Jenkins & Newman Standards Track [Page 53]
+
RFC 8620 JMAP July 2019
+
Now, suppose the user adds a keyword "chopin" and removes the keyword
+
"mozart" from the "Practise Piano" task. The client may send the
+
whole object to the server, as this is a valid PatchObject:
+
"title": "Practise Piano",
+
"neuralNetworkTimeEstimation": 360
+
or it may send a minimal patch:
+
"keywords/chopin": true,
+
"keywords/mozart": null
+
Jenkins & Newman Standards Track [Page 54]
+
RFC 8620 JMAP July 2019
+
The effect is exactly the same on the server in either case, and
+
presuming the server is still in state "10324", it will probably
+
"neuralNetworkTimeEstimation": 5400
+
The server changed the "neuralNetworkTimeEstimation" property on the
+
object as part of this change; as this changed in a way *not*
+
explicitly requested by the PatchObject sent to the server, it is
+
returned with the "updated" confirmation.
+
Let us now add a sub-Todo to our new "Practise Piano" Todo. In this
+
example, we can see the use of a reference to a creation id to allow
+
us to set a foreign key reference to a record created in the same
+
"title": "Warm up with scales"
+
"subTodoIds": [ "#k15" ]
+
Jenkins & Newman Standards Track [Page 55]
+
RFC 8620 JMAP July 2019
+
Now, suppose another user deleted the "Listen to Daft Punk" Todo.
+
The first user will receive a push notification (see Section 7) with
+
the changed state string for the "Todo" type. Since the new string
+
does not match its current state, it knows it needs to check for
+
updates. It may make a request like:
+
[ "Todo/queryChanges", {
+
{ "hasKeyword": "music" },
+
{ "hasKeyword": "video" }
+
"sort": [{ "property": "title" }],
+
"sinceQueryState": "y13213",
+
and receive in response:
+
"hasMoreChanges": false,
+
[ "Todo/queryChanges", {
+
"oldQueryState": "y13213",
+
"newQueryState": "y13218",
+
Jenkins & Newman Standards Track [Page 56]
+
RFC 8620 JMAP July 2019
+
Suppose the user has access to another account "y", for example, a
+
team account shared between multiple users. To move an existing Todo
+
from account "x", the client would call:
+
"onSuccessDestroyOriginal": true
+
The server successfully copies the Todo to a new account (where it
+
receives a new id) and deletes the original. Due to the implicit
+
call to "Todo/set", there are two responses to the single method
+
call, both with the same method call id:
+
"oldState": "c1d64ecb038c",
+
"newState": "33844835152b"
+
Jenkins & Newman Standards Track [Page 57]
+
RFC 8620 JMAP July 2019
+
5.8. Proxy Considerations
+
JMAP has been designed to allow an API endpoint to easily proxy
+
through to one or more JMAP servers. This may be useful for load
+
balancing, augmenting capabilities, or presenting a single endpoint
+
to accounts hosted on different JMAP servers (splitting the request
+
based on each method's "accountId" argument). The proxy need only
+
understand the general structure of a JMAP Request object; it does
+
not need to know anything specifically about the methods and
+
arguments it will pass through to other servers.
+
If splitting up the methods in a request to call them on different
+
backend servers, the proxy must do two things to ensure back-
+
references and creation-id references resolve the same as if the
+
entire request were processed on a single server:
+
1. It must pass a "createdIds" property with each subrequest. If
+
this is not given by the client, an empty object should be used
+
for the first subrequest. The "createdIds" property of each
+
subresponse should be passed on in the next subrequest.
+
2. It must resolve back-references to previous method results that
+
were processed on a different server. This is a relatively
+
simple syntactic substitution, described in Section 3.7.
+
When splitting a request based on accountId, proxy implementors do
+
need to be aware of "/copy" methods that copy between accounts. If
+
the accounts are on different servers, the proxy will have to
+
implement this functionality directly.
+
Binary data is referenced by a *blobId* in JMAP and uploaded/
+
downloaded separately to the core API. The blobId solely represents
+
the raw bytes of data, not any associated metadata such as a file
+
name or content type. Such metadata is stored alongside the blobId
+
in the object referencing it. The data represented by a blobId is
+
Any blobId that exists within an account may be used when creating/
+
updating another object in that account. For example, an Email type
+
may have a blobId that represents the object in Internet Message
+
Format [RFC5322]. A client could create a new Email object with an
+
attachment and use this blobId, in effect attaching the old message
+
to the new one. Similarly, it could attach any existing attachment
+
of an old message without having to download and upload it again.
+
Jenkins & Newman Standards Track [Page 58]
+
RFC 8620 JMAP July 2019
+
When the client uses a blobId in a create/update, the server MAY
+
assign a new blobId to refer to the same binary data within the new/
+
updated object. If it does so, it MUST return any properties that
+
contain a changed blobId in the created/updated response, so the
+
client gets the new ids.
+
A blob that is not referenced by a JMAP object (e.g., as a message
+
attachment) MAY be deleted by the server to free up resources.
+
Uploads (see below) are initially unreferenced blobs. To ensure
+
o The server SHOULD use a separate quota for unreferenced blobs to
+
the account's usual quota. In the case of shared accounts, this
+
quota SHOULD be separate per user.
+
o This quota SHOULD be at least the maximum total size that a single
+
object can reference on this server. For example, if supporting
+
JMAP Mail, this should be at least the maximum total attachments
+
o When an upload would take the user over quota, the server MUST
+
delete unreferenced blobs in date order, oldest first, until there
+
is room for the new blob.
+
o Except where quota restrictions force early deletion, an
+
unreferenced blob MUST NOT be deleted for at least 1 hour from the
+
time of upload; if reuploaded, the same blobId MAY be returned,
+
but this SHOULD reset the expiry time.
+
o A blob MUST NOT be deleted during the method call that removed the
+
last reference, so that a client can issue a create and a destroy
+
that both reference the blob within the same method call.
+
6.1. Uploading Binary Data
+
There is a single endpoint that handles all file uploads for an
+
account, regardless of what they are to be used for. The Session
+
object (see Section 2) has an "uploadUrl" property in URI Template
+
(level 1) format [RFC6570], which MUST contain a variable called
+
"accountId". The client may use this template in combination with an
+
"accountId" to get the URL of the file upload resource.
+
To upload a file, the client submits an authenticated POST request to
+
the file upload resource.
+
Jenkins & Newman Standards Track [Page 59]
+
RFC 8620 JMAP July 2019
+
A successful request MUST return a single JSON object with the
+
following properties as the response:
+
The id of the account used for the call.
+
The id representing the binary data uploaded. The data for this
+
id is immutable. The id *only* refers to the binary data, not any
+
The media type of the file (as specified in [RFC6838],
+
Section 4.2) as set in the Content-Type header of the upload HTTP
+
The size of the file in octets.
+
If identical binary content to an existing blob in the account is
+
uploaded, the existing blobId MAY be returned.
+
Clients should use the blobId returned in a timely manner. Under
+
rare circumstances, the server may have deleted the blob before the
+
client uses it; the client should keep a reference to the local file
+
so it can upload it again in such a situation.
+
When an HTTP error response is returned to the client, the server
+
SHOULD return a JSON "problem details" object as the response body,
+
As access controls are often determined by the object holding the
+
reference to a blob, unreferenced blobs MUST only be accessible to
+
the uploader, even in shared accounts.
+
6.2. Downloading Binary Data
+
The Session object (see Section 2) has a "downloadUrl" property,
+
which is in URI Template (level 1) format [RFC6570]. The URL MUST
+
contain variables called "accountId", "blobId", "type", and "name".
+
Jenkins & Newman Standards Track [Page 60]
+
RFC 8620 JMAP July 2019
+
To download a file, the client makes an authenticated GET request to
+
the download URL with the appropriate variables substituted in:
+
o "accountId": The id of the account to which the record with the
+
o "blobId": The blobId representing the data of the file to
+
o "type": The type for the server to set in the "Content-Type"
+
header of the response; the blobId only represents the binary data
+
and does not have a content-type innately associated with it.
+
o "name": The name for the file; the server MUST return this as the
+
filename if it sets a "Content-Disposition" header.
+
As the data for a particular blobId is immutable, and thus the
+
response in the generated download URL is too, implementors are
+
recommended to set long cache times and use the "immutable" Cache-
+
Control extension [RFC8246] for successful responses, for example,
+
"Cache-Control: private, immutable, max-age=31536000".
+
When an HTTP error response is returned to the client, the server
+
SHOULD return a JSON "problem details" object as the response body,
+
Binary data may be copied *between* two different accounts using the
+
"Blob/copy" method rather than having to download and then reupload
+
The "Blob/copy" method takes the following arguments:
+
The id of the account to copy blobs from.
+
The id of the account to copy blobs to.
+
A list of ids of blobs to copy to the other account.
+
Jenkins & Newman Standards Track [Page 61]
+
RFC 8620 JMAP July 2019
+
The response has the following arguments:
+
The id of the account blobs were copied from.
+
The id of the account blobs were copied to.
+
o copied: "Id[Id]|null"
+
A map of the blobId in the fromAccount to the id for the blob in
+
the account it was copied to, or null if none were successfully
+
o notCopied: "Id[SetError]|null"
+
A map of blobId to a SetError object for each blob that failed to
+
be copied, or null if none.
+
The SetError may be any of the standard set errors that may be
+
returned for a create, as defined in Section 5.3. In addition, the
+
"notFound" SetError error may be returned if the blobId to be copied
+
The following additional method-level error may be returned instead
+
of the "Blob/copy" response:
+
"fromAccountNotFound": The "fromAccountId" included with the request
+
does not correspond to a valid account.
+
Push notifications allow clients to efficiently update (almost)
+
instantly to stay in sync with data changes on the server. The
+
general model for push is simple and sends minimal data over the push
+
channel: just enough for the client to know whether it needs to
+
resync. The format allows multiple changes to be coalesced into a
+
single push update and the frequency of pushes to be rate limited by
+
the server. It doesn't matter if some push events are dropped before
+
they reach the client; the next time it gets/sets any records of a
+
changed type, it will discover the data has changed and still sync
+
Jenkins & Newman Standards Track [Page 62]
+
RFC 8620 JMAP July 2019
+
There are two different mechanisms by which a client can receive push
+
notifications, to allow for the different environments in which a
+
client may exist. An event source resource (see Section 7.3) allows
+
clients that can hold transport connections open to receive push
+
notifications directly from the JMAP server. This is simple and
+
avoids third parties, but it is often not feasible on constrained
+
platforms such as mobile devices. Alternatively, clients can make
+
use of any push service supported by their environment. A URL for
+
the push service is registered with the JMAP server (see
+
Section 7.2); the server then POSTs each notification to that URL.
+
The push service is then responsible for routing these to the client.
+
7.1. The StateChange Object
+
When something changes on the server, the server pushes a StateChange
+
object to the client. A *StateChange* object has the following
+
This MUST be the string "StateChange".
+
o changed: "Id[TypeState]"
+
A map of an "account id" to an object encoding the state of data
+
types that have changed for that account since the last
+
StateChange object was pushed, for each of the accounts to which
+
the user has access and for which something has changed.
+
A *TypeState* object is a map. The keys are the type name "Foo"
+
(e.g., "Mailbox" or "Email"), and the value is the "state"
+
property that would currently be returned by a call to "Foo/get".
+
The client can compare the new state strings with its current
+
values to see whether it has the current data for these types. If
+
not, the changes can then be efficiently fetched in a single
+
standard API request (using the /changes type methods).
+
Jenkins & Newman Standards Track [Page 63]
+
RFC 8620 JMAP July 2019
+
In this example, the server has amalgamated a few changes together
+
across two different accounts the user has access to, before pushing
+
the following StateChange object to the client:
+
"@type": "StateChange",
+
"Email": "d35ecb040aab",
+
"EmailDelivery": "428d565f2440",
+
"CalendarEvent": "87accfac587a"
+
"Mailbox": "0af7a512ce70",
+
"CalendarEvent": "7a4297cecd76"
+
The client can compare the state strings with its current state for
+
the Email, CalendarEvent, etc., object types in the appropriate
+
accounts to see if it needs to fetch changes.
+
If the client is itself making changes, it may receive a StateChange
+
object while the /set API call is in flight. It can wait until the
+
call completes and then compare if the new state string after the
+
/set is the same as was pushed in the StateChange object; if so, and
+
the old state of the /set response matches the client's previous
+
state, it does not need to waste a request asking for changes it
+
Clients may create a PushSubscription to register a URL with the JMAP
+
server. The JMAP server will then make an HTTP POST request to this
+
URL for each push notification it wishes to send to the client.
+
As a push subscription causes the JMAP server to make a number of
+
requests to a previously unknown endpoint, it can be used as a vector
+
for launching a denial-of-service attack. To prevent this, when a
+
subscription is created, the JMAP server immediately sends a
+
PushVerification object to that URL (see Section 7.2.2). The JMAP
+
server MUST NOT make any further requests to the URL until the client
+
receives the push and updates the subscription with the correct
+
Jenkins & Newman Standards Track [Page 64]
+
RFC 8620 JMAP July 2019
+
A *PushSubscription* object has the following properties:
+
o id: "Id" (immutable; server-set)
+
The id of the push subscription.
+
o deviceClientId: "String" (immutable)
+
An id that uniquely identifies the client + device it is running
+
on. The purpose of this is to allow clients to identify which
+
PushSubscription objects they created even if they lose their
+
local state, so they can revoke or update them. This string MUST
+
be different on different devices and be different from apps from
+
other vendors. It SHOULD be easy to regenerate and not depend on
+
persisted state. It is RECOMMENDED to use a secure hash of a
+
1. A unique identifier associated with the device where the JMAP
+
client is running, normally supplied by the device's operating
+
2. A custom vendor/app id, including a domain controlled by the
+
vendor of the JMAP client.
+
To protect the privacy of the user, the deviceClientId id MUST NOT
+
contain an unobfuscated device id.
+
o url: "String" (immutable)
+
An absolute URL where the JMAP server will POST the data for the
+
push message. This MUST begin with "https://".
+
o keys: "Object|null" (immutable)
+
Client-generated encryption keys. If supplied, the server MUST
+
use them as specified in [RFC8291] to encrypt all data sent to the
+
push subscription. The object MUST have the following properties:
+
The P-256 Elliptic Curve Diffie-Hellman (ECDH) public key as
+
described in [RFC8291], encoded in URL-safe base64
+
representation as defined in [RFC4648].
+
The authentication secret as described in [RFC8291], encoded in
+
URL-safe base64 representation as defined in [RFC4648].
+
Jenkins & Newman Standards Track [Page 65]
+
RFC 8620 JMAP July 2019
+
o verificationCode: "String|null"
+
This MUST be null (or omitted) when the subscription is created.
+
The JMAP server then generates a verification code and sends it in
+
a push message, and the client updates the PushSubscription object
+
with the code; see Section 7.2.2 for details.
+
o expires: "UTCDate|null"
+
The time this push subscription expires. If specified, the JMAP
+
server MUST NOT make further requests to this resource after this
+
time. It MAY automatically destroy the push subscription at or
+
The server MAY choose to set an expiry if none is given by the
+
client or modify the expiry time given by the client to a shorter
+
o types: "String[]|null"
+
A list of types the client is interested in (using the same names
+
as the keys in the TypeState object defined in the previous
+
section). A StateChange notification will only be sent if the
+
data for one of these types changes. Other types are omitted from
+
the TypeState object. If null, changes will be pushed for all
+
The POST request MUST have a content type of "application/json" and
+
contain the UTF-8 JSON-encoded object as the body. The request MUST
+
have a "TTL" header and MAY have "Urgency" and/or "Topic" headers, as
+
specified in Section 5 of [RFC8030]. The JMAP server is expected to
+
understand and handle HTTP status responses in a reasonable manner.
+
A "429" (Too Many Requests) response MUST cause the JMAP server to
+
reduce the frequency of pushes; the JMAP push structure allows
+
multiple changes to be coalesced into a single minimal StateChange
+
object. See the security considerations in Section 8.6 for a
+
discussion of the risks in connecting to unknown servers.
+
The JMAP server acts as an application server as defined in
+
[RFC8030]. A client MAY use the rest of [RFC8030] in combination
+
with its own push service to form a complete end-to-end solution, or
+
it MAY rely on alternative mechanisms to ensure the delivery of the
+
pushed data after it leaves the JMAP server.
+
The push subscription is tied to the credentials used to authenticate
+
the API request that created it. Should these credentials expire or
+
be revoked, the push subscription MUST be destroyed by the JMAP
+
Jenkins & Newman Standards Track [Page 66]
+
RFC 8620 JMAP July 2019
+
server. Only subscriptions created by these credentials are returned
+
when the client fetches existing subscriptions.
+
When these credentials have their own expiry (i.e., it is a session
+
with a timeout), the server SHOULD NOT set or bound the expiry time
+
for the push subscription given by the client but MUST expire it when
+
When these credentials are not time bounded (e.g., Basic
+
authentication [RFC7617]), the server SHOULD set an expiry time for
+
the push subscription if none is given and limit the expiry time if
+
set too far in the future. This maximum expiry time MUST be at least
+
48 hours in the future and SHOULD be at least 7 days in the future.
+
An app running on a mobile device may only be able to refresh the
+
push subscription lifetime when it is in the foreground, so this
+
gives a reasonable time frame to allow this to happen.
+
In the case of separate access and refresh credentials, as in Oauth
+
2.0 [RFC6749], the server SHOULD tie the push subscription to the
+
validity of the refresh token rather than the access token and behave
+
according to whether this is time-limited or not.
+
When a push subscription is destroyed, the server MUST securely erase
+
the URL and encryption keys from memory and storage as soon as
+
7.2.1. PushSubscription/get
+
Standard /get method as described in Section 5.1, except it does
+
*not* take or return an "accountId" argument, as push subscriptions
+
are not tied to specific accounts. It also does *not* return a
+
"state" argument. The "ids" argument may be null to fetch all at
+
The server MUST only return push subscriptions that were created
+
using the same authentication credentials as for this
+
"PushSubscription/get" request.
+
As the "url" and "keys" properties may contain data that is private
+
to a particular device, the values for these properties MUST NOT be
+
returned. If the "properties" argument is null or omitted, the
+
server MUST default to all properties excluding these two. If one of
+
them is explicitly requested, the method call MUST be rejected with a
+
Jenkins & Newman Standards Track [Page 67]
+
RFC 8620 JMAP July 2019
+
7.2.2. PushSubscription/set
+
Standard /set method as described in Section 5.3, except it does
+
*not* take or return an "accountId" argument, as push subscriptions
+
are not tied to specific accounts. It also does *not* take an
+
"ifInState" argument or return "oldState" or "newState" arguments.
+
The "url" and "keys" properties are immutable; if the client wishes
+
to change these, it must destroy the current push subscription and
+
When a PushSubscription is created, the server MUST immediately push
+
a *PushVerification* object to the URL. It has the following
+
This MUST be the string "PushVerification".
+
o pushSubscriptionId: "String"
+
The id of the push subscription that was created.
+
o verificationCode: "String"
+
The verification code to add to the push subscription. This MUST
+
contain sufficient entropy to avoid the client being able to guess
+
the code via brute force.
+
The client MUST update the push subscription with the correct
+
verification code before the server makes any further requests to the
+
subscription's URL. Attempts to update the subscription with an
+
invalid verification code MUST be rejected by the server with an
+
"invalidProperties" SetError.
+
The client may update the "expires" property to extend (or, less
+
commonly, shorten) the lifetime of a push subscription. The server
+
MAY modify the proposed new expiry time to enforce server-defined
+
limits. Extending the lifetime does not require the subscription to
+
Clients SHOULD NOT update or destroy a push subscription that they
+
did not create (i.e., has a "deviceClientId" that they do not
+
Jenkins & Newman Standards Track [Page 68]
+
RFC 8620 JMAP July 2019
+
At "2018-07-06T02:14:29Z", a client with deviceClientId "a889-ffea-
+
910" fetches the set of push subscriptions currently on the server,
+
making an API request with:
+
[[ "PushSubscription/get", {
+
[[ "PushSubscription/get", {
+
"id": "e50b2c1d-9553-41a3-b0a7-a7d26b599ee1",
+
"deviceClientId": "b37ff8001ca0",
+
"verificationCode": "b210ef734fe5f439c1ca386421359f7b",
+
"expires": "2018-07-31T00:13:21Z",
+
"id": "f2d0aab5-e976-4e8b-ad4b-b380a5b987e4",
+
"deviceClientId": "X8980fc",
+
"verificationCode": "f3d4618a9ae15c8b7f5582533786d531",
+
"expires": "2018-07-12T05:55:00Z",
+
"types": [ "Mailbox", "Email", "EmailDelivery" ]
+
Since neither of the returned push subscription objects have the
+
client's deviceClientId, it knows it does not have a current push
+
subscription active on the server. So it creates one, sending this
+
[[ "PushSubscription/set", {
+
"deviceClientId": "a889-ffea-910",
+
"url": "https://example.com/push/?device=X8980fc&client=12c6d086",
+
Jenkins & Newman Standards Track [Page 69]
+
RFC 8620 JMAP July 2019
+
The server creates the push subscription but limits the expiry time
+
to 7 days in the future, returning this response:
+
[[ "PushSubscription/set", {
+
"id": "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60",
+
"expires": "2018-07-13T02:14:29Z"
+
The server also immediately makes a POST request to
+
"https://example.com/push/?device=X8980fc&client=12c6d086" with the
+
"@type": "PushVerification",
+
"pushSubscriptionId": "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60",
+
"verificationCode": "da1f097b11ca17f06424e30bf02bfa67"
+
The client receives this and updates the subscription with the
+
verification code (note there is a potential race condition here; the
+
client MUST be able to handle receiving the push while the request
+
creating the subscription is still in progress):
+
[[ "PushSubscription/set", {
+
"P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": {
+
"verificationCode": "da1f097b11ca17f06424e30bf02bfa67"
+
The server confirms the update was successful and will now make
+
requests to the registered URL when the state changes.
+
Jenkins & Newman Standards Track [Page 70]
+
RFC 8620 JMAP July 2019
+
Two days later, the client updates the subscription to extend its
+
lifetime, sending this request:
+
[[ "PushSubscription/set", {
+
"P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": {
+
"expires": "2018-08-13T00:00:00Z"
+
The server extends the expiry time, but only again to its maximum
+
limit of 7 days in the future, returning this response:
+
[[ "PushSubscription/set", {
+
"P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": {
+
"expires": "2018-07-15T02:22:50Z"
+
Clients that can hold transport connections open can connect directly
+
to the JMAP server to receive push notifications via a "text/event-
+
stream" resource, as described in [EventSource]. This is a long
+
running HTTP request, where the server can push data to the client by
+
appending data without ending the response.
+
When a change occurs in the data on the server, it pushes an event
+
called "state" to any connected clients, with the StateChange object
+
The server SHOULD also send a new event id that encodes the entire
+
server state visible to the user immediately after sending a "state"
+
event. When a new connection is made to the event-source endpoint, a
+
client following the server-sent events specification will send a
+
Last-Event-ID HTTP header field with the last id it saw, which the
+
server can use to work out whether the client has missed some
+
changes. If so, it SHOULD send these changes immediately on
+
The Session object (see Section 2) has an "eventSourceUrl" property,
+
which is in URI Template (level 1) format [RFC6570]. The URL MUST
+
contain variables called "types", "closeafter", and "ping".
+
Jenkins & Newman Standards Track [Page 71]
+
RFC 8620 JMAP July 2019
+
To connect to the resource, the client makes an authenticated GET
+
request to the event-source URL with the appropriate variables
+
o "types": This MUST be either:
+
* A comma-separated list of type names, e.g.,
+
"Email,CalendarEvent". The server MUST only push changes for
+
the types in this list.
+
* The single character: "*". Changes to all types are pushed.
+
o "closeafter": This MUST be one of the following values:
+
* "state": The server MUST end the HTTP response after pushing a
+
state event. This can be used by clients in environments where
+
buffering proxies prevent the pushed data from arriving
+
immediately, or indeed at all, when operating in the usual
+
* "no": The connection is persisted by the server as a standard
+
o "ping": A positive integer value representing a length of time in
+
seconds, e.g., "300". If non-zero, the server MUST send an event
+
called "ping" whenever this time elapses since the previous event
+
was sent. This MUST NOT set a new event id. If the value is "0",
+
the server MUST NOT send ping events.
+
The server MAY modify a requested ping interval to be subject to a
+
minimum and/or maximum value. For interoperability, servers MUST
+
NOT have a minimum allowed value higher than 30 or a maximum
+
allowed value less than 300.
+
The data for the ping event MUST be a JSON object containing an
+
"interval" property, the value (type "UnsignedInt") being the
+
interval in seconds the server is using to send pings (this may be
+
different to the requested value if the server clamped it to be
+
within a min/max value).
+
Clients can monitor for the ping event to help determine when the
+
closeafter mode may be required.
+
A client MAY hold open multiple connections to the event-source
+
resource, although it SHOULD try to use a single connection for
+
Jenkins & Newman Standards Track [Page 72]
+
RFC 8620 JMAP July 2019
+
8. Security Considerations
+
8.1. Transport Confidentiality
+
To ensure the confidentiality and integrity of data sent and received
+
via JMAP, all requests MUST use TLS 1.2 [RFC5246] [RFC8446] or later,
+
following the recommendations in [RFC7525]. Servers SHOULD support
+
TLS 1.3 [RFC8446] or later.
+
Clients MUST validate TLS certificate chains to protect against
+
man-in-the-middle attacks [RFC5280].
+
8.2. Authentication Scheme
+
A number of HTTP authentication schemes have been standardised (see
+
<https://www.iana.org/assignments/http-authschemes/>). Servers
+
should take care to assess the security characteristics of different
+
schemes in relation to their needs when deciding what to implement.
+
Use of the Basic authentication scheme is NOT RECOMMENDED. Services
+
that choose to use it are strongly recommended to require generation
+
of a unique "app password" via some external mechanism for each
+
client they wish to connect. This allows connections from different
+
devices to be differentiated by the server and access to be
+
8.3. Service Autodiscovery
+
Unless secured by something like DNSSEC, autodiscovery of server
+
details using SRV DNS records is vulnerable to a DNS poisoning
+
attack, which can lead to the client talking to an attacker's server
+
instead of the real JMAP server. The attacker may then intercept
+
requests to execute man-in-the-middle attacks and, depending on the
+
authentication scheme, steal credentials to generate its own
+
Clients that do not support SRV lookups are likely to try just using
+
the "/.well-known/jmap" path directly against the domain of the
+
username over HTTPS. Servers SHOULD ensure this path resolves or
+
redirects to the correct JMAP Session resource to allow this to work.
+
If this is not feasible, servers MUST ensure this path cannot be
+
controlled by an attacker, as again it may be used to steal
+
Jenkins & Newman Standards Track [Page 73]
+
RFC 8620 JMAP July 2019
+
The Security Considerations of [RFC8259] apply to the use of JSON as
+
the data interchange format.
+
As for any serialization format, parsers need to thoroughly check the
+
syntax of the supplied data. JSON uses opening and closing tags for
+
several types and structures, and it is possible that the end of the
+
supplied data will be reached when scanning for a matching closing
+
tag; this is an error condition, and implementations need to stop
+
scanning at the end of the supplied data.
+
JSON also uses a string encoding with some escape sequences to encode
+
special characters within a string. Care is needed when processing
+
these escape sequences to ensure that they are fully formed before
+
the special processing is triggered, with special care taken when the
+
escape sequences appear adjacent to other (non-escaped) special
+
characters or adjacent to the end of data (as in the previous
+
If parsing JSON into a non-textual structured data format,
+
implementations may need to allocate storage to hold JSON string
+
elements. Since JSON does not use explicit string lengths, the risk
+
of denial of service due to resource exhaustion is small, but
+
implementations may still wish to place limits on the size of
+
allocations they are willing to make in any given context, to avoid
+
untrusted data causing excessive memory allocation.
+
A small request may result in a very large response and require
+
considerable work on the server if resource limits are not enforced.
+
JMAP provides mechanisms for advertising and enforcing a wide variety
+
of limits for mitigating this threat, including limits on the number
+
of objects fetched in a single method call, number of methods in a
+
single request, number of concurrent requests, etc.
+
JMAP servers MUST implement sensible limits to mitigate against
+
resource exhaustion attacks.
+
8.6. Connection to Unknown Push Server
+
When a push subscription is registered, the application server will
+
make POST requests to the given URL. There are a number of security
+
considerations that MUST be considered when implementing this.
+
Jenkins & Newman Standards Track [Page 74]
+
RFC 8620 JMAP July 2019
+
The server MUST ensure the URL is externally resolvable to avoid
+
server-side request forgery, where the server makes a request to a
+
resource on its internal network.
+
A malicious client may use the push subscription to attempt to flood
+
a third party server with requests, creating a denial-of-service
+
attack and masking the attacker's true identity. There is no
+
guarantee that the URL given to the JMAP server is actually a valid
+
push server. Upon creation of a push subscription, the JMAP server
+
sends a PushVerification object to the URL and MUST NOT send any
+
further requests until the client verifies it has received the
+
initial push. The verification code MUST contain sufficient entropy
+
to prevent the client from being able to verify the subscription via
+
The verification code does not guarantee the URL is a valid push
+
server, only that the client is able to access the data submitted to
+
it. While the verification step significantly reduces the set of
+
potential targets, there is still a risk that the server is unrelated
+
to the client and being targeted for a denial-of-service attack.
+
The server MUST limit the number of push subscriptions any one user
+
may have to ensure the user cannot cause the server to send a large
+
number of push notifications at once, which could again be used as
+
part of a denial-of-service attack. The rate of creation MUST also
+
be limited to minimise the ability to abuse the verification request
+
When data changes, a small object is pushed with the new state
+
strings for the types that have changed. While the data here is
+
minimal, a passive man-in-the-middle attacker may be able to gain
+
useful information. To ensure confidentiality and integrity, if the
+
push is sent via a third party outside of the control of the client
+
and JMAP server, the client MUST specify encryption keys when
+
establishing the PushSubscription and ignore any push notification
+
received that is not encrypted with those keys.
+
The privacy and security considerations of [RFC8030] and [RFC8291]
+
also apply to the use of the PushSubscription mechanism.
+
As there is no crypto algorithm agility in Web Push Encryption
+
[RFC8291], a new specification will be needed to provide this if new
+
algorithms are required in the future.
+
Jenkins & Newman Standards Track [Page 75]
+
RFC 8620 JMAP July 2019
+
While the data is encrypted, a passive observer with the ability to
+
monitor network traffic may be able to glean information from the
+
timing of API requests and push notifications. For example, suppose
+
an email or calendar invitation is sent from User A (hosted on Server
+
X) to User B (hosted on Server Y). If Server X hosts data for many
+
users, a passive observer can see that the two servers connected but
+
does not know who the data was for. However, if a push notification
+
is immediately sent to User B and the attacker can observe this as
+
well, they may reasonably conclude that someone on Server X is
+
9.1. Assignment of jmap Service Name
+
IANA has assigned the 'jmap' service name in the "Service Name and
+
Transport Protocol Port Number Registry" [RFC6335].
+
Transport Protocol(s): tcp
+
Description: JSON Meta Application Protocol
+
Assignment Notes: This service name was previously assigned under the
+
name "JSON Mail Access Protocol". This has been de-assigned and
+
re-assigned with the approval of the previous assignee.
+
9.2. Registration of Well-Known URI Suffix for JMAP
+
IANA has registered the following suffix in the "Well-Known URIs"
+
registry for JMAP, as described in [RFC8615]:
+
Change Controller: IETF
+
Specification Document: RFC 8620, Section 2.2.
+
Jenkins & Newman Standards Track [Page 76]
+
RFC 8620 JMAP July 2019
+
9.3. Registration of the jmap URN Sub-namespace
+
IANA has registered the following URN sub-namespace in the "IETF URN
+
Sub-namespace for Registered Protocol Parameter Identifiers" registry
+
within the "Uniform Resource Name (URN) Namespace for IETF Use"
+
registry as described in [RFC3553].
+
Registered Parameter Identifier: jmap
+
Reference: RFC 8620, Section 9.4
+
IANA Registry Reference: http://www.iana.org/assignments/jmap
+
9.4. Creation of "JMAP Capabilities" Registry
+
IANA has created the "JMAP Capabilities" registry as described in
+
Section 2. JMAP capabilities are advertised in the "capabilities"
+
property of the JMAP Session resource. They are used to extend the
+
functionality of a JMAP server. A capability is referenced by a URI.
+
The JMAP capability URI can be a URN starting with
+
"urn:ietf:params:jmap:" plus a unique suffix that is the index value
+
in the jmap URN sub-namespace. Registration of a JMAP capability
+
with another form of URI has no impact on the jmap URN sub-namespace.
+
This registry follows the expert review process unless the "intended
+
use" field is "common" or "placeholder", in which case registration
+
follows the specification required process.
+
A JMAP capability registration can have an intended use of "common",
+
"placeholder", "limited", or "obsolete". IANA will list common-use
+
registrations prominently and separately from those with other
+
The JMAP capability registration procedure is not a formal standards
+
process but rather an administrative procedure intended to allow
+
community comment and sanity checking without excessive time delay.
+
A "placeholder" registration reserves part of the jmap URN namespace
+
for another purpose but is typically not included in the
+
"capabilities" property of the JMAP Session resource.
+
9.4.1. Preliminary Community Review
+
Notice of a potential JMAP common-use registration SHOULD be sent to
+
the JMAP mailing list <jmap@ietf.org> for review. This mailing list
+
is appropriate to solicit community feedback on a proposed JMAP
+
Jenkins & Newman Standards Track [Page 77]
+
RFC 8620 JMAP July 2019
+
capability. Registrations that are not intended for common use MAY
+
be sent to the list for review as well; doing so is entirely
+
OPTIONAL, but is encouraged.
+
The intent of the public posting to this list is to solicit comments
+
and feedback on the choice of the capability name, the unambiguity of
+
the specification document, and a review of any interoperability or
+
security considerations. The submitter may submit a revised
+
registration proposal or abandon the registration completely at any
+
9.4.2. Submit Request to IANA
+
Registration requests can be sent to <iana@iana.org>.
+
9.4.3. Designated Expert Review
+
For a limited-use registration, the primary concern of the designated
+
expert (DE) is preventing name collisions and encouraging the
+
submitter to document security and privacy considerations; a
+
published specification is not required. For a common-use
+
registration, the DE is expected to confirm that suitable
+
documentation, as described in Section 4.6 of [RFC8126], is
+
available. The DE should also verify that the capability does not
+
conflict with work that is active or already published within the
+
Before a period of 30 days has passed, the DE will either approve or
+
deny the registration request and publish a notice of the decision to
+
the JMAP WG mailing list or its successor, as well as inform IANA. A
+
denial notice must be justified by an explanation, and, in the cases
+
where it is possible, concrete suggestions on how the request can be
+
modified so as to become acceptable should be provided.
+
If the DE does not respond within 30 days, the registrant may request
+
the IESG take action to process the request in a timely manner.
+
9.4.4. Change Procedures
+
Once a JMAP capability has been published by the IANA, the change
+
controller may request a change to its definition. The same
+
procedure that would be appropriate for the original registration
+
request is used to process a change request.
+
JMAP capability registrations may not be deleted; capabilities that
+
are no longer believed appropriate for use can be declared obsolete
+
by a change to their "intended use" field; such capabilities will be
+
clearly marked in the lists published by the IANA.
+
Jenkins & Newman Standards Track [Page 78]
+
RFC 8620 JMAP July 2019
+
Significant changes to a capability's definition should be requested
+
only when there are serious omissions or errors in the published
+
specification. When review is required, a change request may be
+
denied if it renders entities that were valid under the previous
+
definition invalid under the new definition.
+
The owner of a JMAP capability may pass responsibility to another
+
person or agency by informing the IANA; this can be done without
+
The IESG may reassign responsibility for a JMAP capability. The most
+
common case of this will be to enable changes to be made to
+
capabilities where the author of the registration has died, moved out
+
of contact, or is otherwise unable to make changes that are important
+
9.4.5. JMAP Capabilities Registry Template
+
Capability name: (see capability property in Section 2)
+
Specification document:
+
Intended use: (one of common, limited, placeholder, or obsolete)
+
Change controller: ("IETF" for Standards Track / BCP RFCs)
+
Security and privacy considerations:
+
9.4.6. Initial Registration for JMAP Core
+
Capability Name: "urn:ietf:params:jmap:core"
+
Specification document: RFC 8620, Section 2
+
Change Controller: IETF
+
Security and privacy considerations: RFC 8620, Section 8.
+
Jenkins & Newman Standards Track [Page 79]
+
RFC 8620 JMAP July 2019
+
9.4.7. Registration for JMAP Error Placeholder in JMAP Capabilities
+
Capability Name: "urn:ietf:params:jmap:error:"
+
Specification document: RFC 8620, Section 9.5
+
Intended use: placeholder
+
Change Controller: IETF
+
Security and privacy considerations: RFC 8620, Section 8.
+
9.5. Creation of "JMAP Error Codes" Registry
+
IANA has created the "JMAP Error Codes" registry. JMAP error codes
+
appear in the "type" member of a JSON problem details object (as
+
described in Section 3.6.1), the "type" member in a JMAP error object
+
(as described in Section 3.6.2), or the "type" member of a JMAP
+
method-specific error object (such as SetError in Section 5.3). When
+
used in a problem details object, the prefix
+
"urn:ietf:params:jmap:error:" is always included; when used in JMAP
+
objects, the prefix is always omitted.
+
This registry follows the expert review process. Preliminary
+
community review for this registry follows the same procedures as the
+
"JMAP Capabilities" registry, but it is optional. The change
+
procedures for this registry are the same as the change procedures
+
for the "JMAP Capabilities" registry.
+
The designated expert should review the following aspects of the
+
1. Verify the error code does not conflict with existing names.
+
2. Verify the error code follows the syntax limitations (does not
+
3. Encourage the submitter to follow the naming convention of
+
previously registered errors.
+
4. Encourage the submitter to describe client behaviours that are
+
recommended in response to the error code. These may distinguish
+
the error code from other error codes.
+
Jenkins & Newman Standards Track [Page 80]
+
RFC 8620 JMAP July 2019
+
5. Encourage the submitter to describe when the server should issue
+
the error as opposed to some other error code.
+
6. Encourage the submitter to note any security considerations
+
associated with the error, if any (e.g., an error code that might
+
disclose existence of data the authenticated user does not have
+
permission to know about).
+
Steps 3-6 are meant to promote a higher-quality registry. However,
+
the expert is encouraged to approve any registration that would not
+
actively harm JMAP interoperability to make this a relatively
+
9.5.2. JMAP Error Codes Registry Template
+
Intended use: (one of "common", "limited", "obsolete")
+
Change Controller: ("IETF" for Standards Track / BCP RFCs)
+
Reference: (Optional. Only required if defined in an RFC.)
+
9.5.3. Initial Contents for the JMAP Error Codes Registry
+
o JMAP Error Code: accountNotFound
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: The accountId does not correspond to a valid account.
+
o JMAP Error Code: accountNotSupportedByMethod
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: The accountId given corresponds to a valid account,
+
but the account does not support this method or data type.
+
o JMAP Error Code: accountReadOnly
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: This method modifies state, but the account is read-
+
only (as returned on the corresponding Account object in the JMAP
+
Jenkins & Newman Standards Track [Page 81]
+
RFC 8620 JMAP July 2019
+
o JMAP Error Code: anchorNotFound
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.5
+
Description: An anchor argument was supplied, but it cannot be
+
found in the results of the query.
+
o JMAP Error Code: alreadyExists
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.4
+
Description: The server forbids duplicates, and the record already
+
exists in the target account. An existingId property of type Id
+
MUST be included on the SetError object with the id of the
+
o JMAP Error Code: cannotCalculateChanges
+
Change Controller: IETF
+
Reference: RFC 8620, Sections 5.2 and 5.6
+
Description: The server cannot calculate the changes from the
+
state string given by the client.
+
o JMAP Error Code: forbidden
+
Change Controller: IETF
+
Reference: RFC 8620, Sections 3.6.2, 5.3, and 7.2.1
+
Description: The action would violate an ACL or other permissions
+
o JMAP Error Code: fromAccountNotFound
+
Change Controller: IETF
+
Reference: RFC 8620, Sections 5.4 and 6.3
+
Description: The fromAccountId does not correspond to a valid
+
o JMAP Error Code: fromAccountNotSupportedByMethod
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.4
+
Description: The fromAccountId given corresponds to a valid
+
account, but the account does not support this data type.
+
Jenkins & Newman Standards Track [Page 82]
+
RFC 8620 JMAP July 2019
+
o JMAP Error Code: invalidArguments
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: One of the arguments is of the wrong type or
+
otherwise invalid, or a required argument is missing.
+
o JMAP Error Code: invalidPatch
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: The PatchObject given to update the record was not a
+
o JMAP Error Code: invalidProperties
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: The record given is invalid.
+
o JMAP Error Code: notFound
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: The id given cannot be found.
+
o JMAP Error Code: notJSON
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.1
+
Description: The content type of the request was not application/
+
json, or the request did not parse as I-JSON.
+
o JMAP Error Code: notRequest
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.1
+
Description: The request parsed as JSON but did not match the type
+
signature of the Request object.
+
o JMAP Error Code: overQuota
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: The create would exceed a server-defined limit on the
+
number or total size of objects of this type.
+
Jenkins & Newman Standards Track [Page 83]
+
RFC 8620 JMAP July 2019
+
o JMAP Error Code: rateLimit
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: Too many objects of this type have been created
+
recently, and a server-defined rate limit has been reached. It
+
may work if tried again later.
+
o JMAP Error Code: requestTooLarge
+
Change Controller: IETF
+
Reference: RFC 8620, Sections 5.1 and 5.3
+
Description: The total number of actions exceeds the maximum
+
number the server is willing to process in a single method call.
+
o JMAP Error Code: invalidResultReference
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: The method used a result reference for one of its
+
arguments, but this failed to resolve.
+
o JMAP Error Code: serverFail
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: An unexpected or unknown error occurred during the
+
processing of the call. The method call made no changes to the
+
o JMAP Error Code: serverPartialFail
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: Some, but not all, expected changes described by the
+
method occurred. The client MUST resynchronise impacted data to
+
determine the server state. Use of this error is strongly
+
o JMAP Error Code: serverUnavailable
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: Some internal server resource was temporarily
+
unavailable. Attempting the same operation later (perhaps after a
+
backoff with a random factor) may succeed.
+
Jenkins & Newman Standards Track [Page 84]
+
RFC 8620 JMAP July 2019
+
o JMAP Error Code: singleton
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: This is a singleton type, so you cannot create
+
another one or destroy the existing one.
+
o JMAP Error Code: stateMismatch
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: An ifInState argument was supplied, and it does not
+
match the current state.
+
o JMAP Error Code: tooLarge
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: The action would result in an object that exceeds a
+
server-defined limit for the maximum size of a single object of
+
o JMAP Error Code: tooManyChanges
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.6
+
Description: There are more changes than the client's maxChanges
+
o JMAP Error Code: unknownCapability
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.1
+
Description: The client included a capability in the "using"
+
property of the request that the server does not support.
+
o JMAP Error Code: unknownMethod
+
Change Controller: IETF
+
Reference: RFC 8620, Section 3.6.2
+
Description: The server does not recognise this method name.
+
o JMAP Error Code: unsupportedFilter
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.5
+
Description: The filter is syntactically valid, but the server
+
Jenkins & Newman Standards Track [Page 85]
+
RFC 8620 JMAP July 2019
+
o JMAP Error Code: unsupportedSort
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.5
+
Description: The sort is syntactically valid but includes a
+
property the server does not support sorting on or a collation
+
method it does not recognise.
+
o JMAP Error Code: willDestroy
+
Change Controller: IETF
+
Reference: RFC 8620, Section 5.3
+
Description: The client requested an object be both updated and
+
destroyed in the same /set request, and the server has decided to
+
therefore ignore the update.
+
10.1. Normative References
+
Hickson, I., "Server-Sent Events", World Wide Web
+
Consortium Recommendation REC-eventsource-20150203,
+
February 2015, <https://www.w3.org/TR/eventsource/>.
+
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+
Requirement Levels", BCP 14, RFC 2119,
+
DOI 10.17487/RFC2119, March 1997,
+
<https://www.rfc-editor.org/info/rfc2119>.
+
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
+
specifying the location of services (DNS SRV)", RFC 2782,
+
DOI 10.17487/RFC2782, February 2000,
+
<https://www.rfc-editor.org/info/rfc2782>.
+
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
+
DOI 10.17487/RFC2818, May 2000,
+
<https://www.rfc-editor.org/info/rfc2818>.
+
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
+
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
+
<https://www.rfc-editor.org/info/rfc3339>.
+
[RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
+
IETF URN Sub-namespace for Registered Protocol
+
Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June
+
2003, <https://www.rfc-editor.org/info/rfc3553>.
+
Jenkins & Newman Standards Track [Page 86]
+
RFC 8620 JMAP July 2019
+
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+
10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
+
2003, <https://www.rfc-editor.org/info/rfc3629>.
+
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
+
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
+
<https://www.rfc-editor.org/info/rfc4648>.
+
[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
+
Application Protocol Collation Registry", RFC 4790,
+
DOI 10.17487/RFC4790, March 2007,
+
<https://www.rfc-editor.org/info/rfc4790>.
+
[RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation
+
Algorithm", RFC 5051, DOI 10.17487/RFC5051, October 2007,
+
<https://www.rfc-editor.org/info/rfc5051>.
+
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+
(TLS) Protocol Version 1.2", RFC 5246,
+
DOI 10.17487/RFC5246, August 2008,
+
<https://www.rfc-editor.org/info/rfc5246>.
+
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
+
Housley, R., and W. Polk, "Internet X.509 Public Key
+
Infrastructure Certificate and Certificate Revocation List
+
(CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008,
+
<https://www.rfc-editor.org/info/rfc5280>.
+
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
+
DOI 10.17487/RFC5322, October 2008,
+
<https://www.rfc-editor.org/info/rfc5322>.
+
[RFC6186] Daboo, C., "Use of SRV Records for Locating Email
+
Submission/Access Services", RFC 6186,
+
DOI 10.17487/RFC6186, March 2011,
+
<https://www.rfc-editor.org/info/rfc6186>.
+
[RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
+
Cheshire, "Internet Assigned Numbers Authority (IANA)
+
Procedures for the Management of the Service Name and
+
Transport Protocol Port Number Registry", BCP 165,
+
RFC 6335, DOI 10.17487/RFC6335, August 2011,
+
<https://www.rfc-editor.org/info/rfc6335>.
+
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
+
and D. Orchard, "URI Template", RFC 6570,
+
DOI 10.17487/RFC6570, March 2012,
+
<https://www.rfc-editor.org/info/rfc6570>.
+
Jenkins & Newman Standards Track [Page 87]
+
RFC 8620 JMAP July 2019
+
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
+
RFC 6749, DOI 10.17487/RFC6749, October 2012,
+
<https://www.rfc-editor.org/info/rfc6749>.
+
[RFC6764] Daboo, C., "Locating Services for Calendaring Extensions
+
to WebDAV (CalDAV) and vCard Extensions to WebDAV
+
(CardDAV)", RFC 6764, DOI 10.17487/RFC6764, February 2013,
+
<https://www.rfc-editor.org/info/rfc6764>.
+
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
+
Specifications and Registration Procedures", BCP 13,
+
RFC 6838, DOI 10.17487/RFC6838, January 2013,
+
<https://www.rfc-editor.org/info/rfc6838>.
+
[RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
+
"JavaScript Object Notation (JSON) Pointer", RFC 6901,
+
DOI 10.17487/RFC6901, April 2013,
+
<https://www.rfc-editor.org/info/rfc6901>.
+
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
+
Protocol (HTTP/1.1): Message Syntax and Routing",
+
RFC 7230, DOI 10.17487/RFC7230, June 2014,
+
<https://www.rfc-editor.org/info/rfc7230>.
+
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
+
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
+
DOI 10.17487/RFC7231, June 2014,
+
<https://www.rfc-editor.org/info/rfc7231>.
+
[RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
+
DOI 10.17487/RFC7493, March 2015,
+
<https://www.rfc-editor.org/info/rfc7493>.
+
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre,
+
"Recommendations for Secure Use of Transport Layer
+
Security (TLS) and Datagram Transport Layer Security
+
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May
+
2015, <https://www.rfc-editor.org/info/rfc7525>.
+
[RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme",
+
RFC 7617, DOI 10.17487/RFC7617, September 2015,
+
<https://www.rfc-editor.org/info/rfc7617>.
+
[RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP
+
APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
+
<https://www.rfc-editor.org/info/rfc7807>.
+
Jenkins & Newman Standards Track [Page 88]
+
RFC 8620 JMAP July 2019
+
[RFC8030] Thomson, M., Damaggio, E., and B. Raymor, Ed., "Generic
+
Event Delivery Using HTTP Push", RFC 8030,
+
DOI 10.17487/RFC8030, December 2016,
+
<https://www.rfc-editor.org/info/rfc8030>.
+
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
+
Writing an IANA Considerations Section in RFCs", BCP 26,
+
RFC 8126, DOI 10.17487/RFC8126, June 2017,
+
<https://www.rfc-editor.org/info/rfc8126>.
+
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
+
Interchange Format", STD 90, RFC 8259,
+
DOI 10.17487/RFC8259, December 2017,
+
<https://www.rfc-editor.org/info/rfc8259>.
+
[RFC8264] Saint-Andre, P. and M. Blanchet, "PRECIS Framework:
+
Preparation, Enforcement, and Comparison of
+
Internationalized Strings in Application Protocols",
+
RFC 8264, DOI 10.17487/RFC8264, October 2017,
+
<https://www.rfc-editor.org/info/rfc8264>.
+
[RFC8291] Thomson, M., "Message Encryption for Web Push", RFC 8291,
+
DOI 10.17487/RFC8291, November 2017,
+
<https://www.rfc-editor.org/info/rfc8291>.
+
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
+
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
+
<https://www.rfc-editor.org/info/rfc8446>.
+
[RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers
+
(URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
+
<https://www.rfc-editor.org/info/rfc8615>.
+
10.2. Informative References
+
[RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246,
+
DOI 10.17487/RFC8246, September 2017,
+
<https://www.rfc-editor.org/info/rfc8246>.
+
Jenkins & Newman Standards Track [Page 89]
+
RFC 8620 JMAP July 2019
+
PO Box 234, Collins St. West
+
Email: neilj@fastmailteam.com
+
URI: https://www.fastmail.com
+
440 E. Huntington Dr., Suite 400
+
United States of America
+
Email: chris.newman@oracle.com
+
Jenkins & Newman Standards Track [Page 90]
anil.recoil.org