idnits 2.17.1 draft-ietf-jmap-core-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 18, 2019) is 1866 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC5246' is mentioned on line 3032, but not defined ** Obsolete undefined reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'EventSource' == Outdated reference: A later version (-17) exists of draft-ietf-jmap-core-16 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Obsolete normative reference: RFC 7807 (Obsoleted by RFC 9457) Summary: 8 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JMAP N. Jenkins 3 Internet-Draft FastMail 4 Intended status: Standards Track C. Newman 5 Expires: September 19, 2019 Oracle 6 March 18, 2019 8 JSON Meta Application Protocol 9 draft-ietf-jmap-core-17 11 Abstract 13 This document specifies a protocol for clients to efficiently query, 14 fetch and modify JSON-based data objects, with support for push 15 notification of changes and fast resynchronisation, and out-of-band 16 binary data upload/download. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on September 19, 2019. 35 Copyright Notice 37 Copyright (c) 2019 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Notational conventions . . . . . . . . . . . . . . . . . 4 54 1.2. The Id data type . . . . . . . . . . . . . . . . . . . . 5 55 1.3. The Int and UnsignedInt data types . . . . . . . . . . . 6 56 1.4. The Date and UTCDate data types . . . . . . . . . . . . . 6 57 1.5. JSON as the data encoding format . . . . . . . . . . . . 6 58 1.6. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 59 1.6.1. User . . . . . . . . . . . . . . . . . . . . . . . . 7 60 1.6.2. Accounts . . . . . . . . . . . . . . . . . . . . . . 7 61 1.6.3. Data types and records . . . . . . . . . . . . . . . 7 62 1.7. The JMAP API model . . . . . . . . . . . . . . . . . . . 8 63 1.8. Vendor-specific extensions . . . . . . . . . . . . . . . 8 64 2. The JMAP Session resource . . . . . . . . . . . . . . . . . . 9 65 2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 2.2. Service autodiscovery . . . . . . . . . . . . . . . . . . 14 67 3. Structured data exchange . . . . . . . . . . . . . . . . . . 14 68 3.1. Making an API request . . . . . . . . . . . . . . . . . . 14 69 3.1.1. The Invocation data type . . . . . . . . . . . . . . 15 70 3.2. The Request object . . . . . . . . . . . . . . . . . . . 15 71 3.2.1. Example request . . . . . . . . . . . . . . . . . . . 16 72 3.3. The Response object . . . . . . . . . . . . . . . . . . . 16 73 3.3.1. Example response: . . . . . . . . . . . . . . . . . . 17 74 3.4. Omitting arguments . . . . . . . . . . . . . . . . . . . 17 75 3.5. Errors . . . . . . . . . . . . . . . . . . . . . . . . . 18 76 3.5.1. Request-level errors . . . . . . . . . . . . . . . . 18 77 3.5.2. Method-level errors . . . . . . . . . . . . . . . . . 19 78 3.6. References to previous method results . . . . . . . . . . 21 79 3.7. Localisation of user-visible strings . . . . . . . . . . 25 80 3.8. Security . . . . . . . . . . . . . . . . . . . . . . . . 26 81 3.9. Concurrency . . . . . . . . . . . . . . . . . . . . . . . 26 82 4. The Core/echo method . . . . . . . . . . . . . . . . . . . . 26 83 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 26 84 5. Standard methods and naming convention . . . . . . . . . . . 26 85 5.1. /get . . . . . . . . . . . . . . . . . . . . . . . . . . 27 86 5.2. /changes . . . . . . . . . . . . . . . . . . . . . . . . 28 87 5.3. /set . . . . . . . . . . . . . . . . . . . . . . . . . . 31 88 5.4. /copy . . . . . . . . . . . . . . . . . . . . . . . . . . 36 89 5.5. /query . . . . . . . . . . . . . . . . . . . . . . . . . 38 90 5.6. /queryChanges . . . . . . . . . . . . . . . . . . . . . . 43 91 5.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . 46 92 5.8. Proxy considerations . . . . . . . . . . . . . . . . . . 52 93 6. Binary data . . . . . . . . . . . . . . . . . . . . . . . . . 53 94 6.1. Uploading binary data . . . . . . . . . . . . . . . . . . 54 95 6.2. Downloading binary data . . . . . . . . . . . . . . . . . 55 96 6.3. Blob/copy . . . . . . . . . . . . . . . . . . . . . . . . 55 97 7. Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 98 7.1. The StateChange object . . . . . . . . . . . . . . . . . 57 99 7.1.1. Example . . . . . . . . . . . . . . . . . . . . . . . 57 100 7.2. PushSubscription . . . . . . . . . . . . . . . . . . . . 58 101 7.2.1. PushSubscription/get . . . . . . . . . . . . . . . . 60 102 7.2.2. PushSubscription/set . . . . . . . . . . . . . . . . 61 103 7.2.3. Example . . . . . . . . . . . . . . . . . . . . . . . 62 104 7.3. Event Source . . . . . . . . . . . . . . . . . . . . . . 64 105 8. Security considerations . . . . . . . . . . . . . . . . . . . 65 106 8.1. Transport confidentiality . . . . . . . . . . . . . . . . 65 107 8.2. Authentication scheme . . . . . . . . . . . . . . . . . . 66 108 8.3. Service autodiscovery . . . . . . . . . . . . . . . . . . 66 109 8.4. JSON parsing . . . . . . . . . . . . . . . . . . . . . . 66 110 8.5. Denial of service . . . . . . . . . . . . . . . . . . . . 67 111 8.6. Connection to unknown push server . . . . . . . . . . . . 67 112 8.7. Push encryption . . . . . . . . . . . . . . . . . . . . . 68 113 8.8. Traffic analysis . . . . . . . . . . . . . . . . . . . . 68 114 9. IANA considerations . . . . . . . . . . . . . . . . . . . . . 69 115 9.1. Assignment of jmap service name . . . . . . . . . . . . . 69 116 9.2. Registration of well-known URI suffix for JMAP . . . . . 69 117 9.3. Registration of the jmap URN sub-namespace . . . . . . . 69 118 9.4. Creation of "JMAP Capabilities" registry . . . . . . . . 70 119 9.4.1. Preliminary community review . . . . . . . . . . . . 70 120 9.4.2. Submit request to IANA . . . . . . . . . . . . . . . 71 121 9.4.3. Designated expert review . . . . . . . . . . . . . . 71 122 9.4.4. Change procedures . . . . . . . . . . . . . . . . . . 71 123 9.4.5. JMAP Capabilities registry template: . . . . . . . . 72 124 9.4.6. Initial registration for JMAP core . . . . . . . . . 72 125 9.4.7. Registration for JMAP error placeholder in JMAP 126 capabilities registry . . . . . . . . . . . . . . . . 72 127 9.5. Creation of "JMAP Error Codes" registry . . . . . . . . . 72 128 9.5.1. Designated expert review . . . . . . . . . . . . . . 73 129 9.5.2. JMAP Error Codes registry template: . . . . . . . . . 73 130 9.5.3. Initial JMAP Error Codes registry . . . . . . . . . . 74 131 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 132 10.1. Normative References . . . . . . . . . . . . . . . . . . 81 133 10.2. Informative References . . . . . . . . . . . . . . . . . 85 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 85 136 1. Introduction 138 JMAP is a protocol for synchronising data, such as mail, calendars or 139 contacts, between a client and a server. It is optimised for mobile 140 and web environments, and aims to provide a consistent interface to 141 different data types. 143 This specification is for the generic mechanism of data 144 synchronisation. Further specifications define the data models for 145 different data types that may be synchronised via JMAP. 147 JMAP is designed to make efficient use of limited network resources. 148 Multiple API calls may be batched in a single request to the server, 149 reducing round trips and improving battery life on mobile devices. 150 Push connections remove the need for polling, and an efficient delta 151 update mechanism ensures a minimum of data is transferred. 153 JMAP is designed to be horizontally scalable to a very large number 154 of users. This is facilitated by separate end points for users after 155 login, the separation of binary and structured data, and a data model 156 for sharing that does not allow data dependencies between accounts. 158 1.1. Notational conventions 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 162 "OPTIONAL" in this document are to be interpreted as described in BCP 163 14 [RFC2119] [RFC8174] when, and only when, they appear in all 164 capitals, as shown here. 166 The underlying format used for this specification is JSON. 167 Consequently, the terms "object" and "array" as well as the four 168 primitive types (strings, numbers, booleans, and null) are to be 169 interpreted as described in section 1 of [RFC8259]. Unless otherwise 170 noted, all the property names and values are case sensitive. 172 Some examples in this document contain "partial" JSON documents used 173 for illustrative purposes. In these examples, three periods "..." 174 are used to indicate a portion of the document that has been removed 175 for compactness. 177 For compatibility with publishing requirements, line breaks have been 178 inserted inside long JSON strings, with the following continuation 179 lines indented. To form the valid JSON example, any line breaks 180 inside a string must be replaced with a space, and any other white- 181 space after the line break removed. 183 Unless otherwise specified, examples of API exchanges only show the 184 _methodCalls_ array of the Request object or the _methodResponses_ 185 array of the Response object. For compactness, the rest of the 186 Request/Response object is omitted. 188 Type signatures are given for all JSON values in this document. The 189 following conventions are used: 191 o "*" - The type is undefined (the value could be any type, although 192 permitted values may be constrained by the context of this value). 194 o "String" - The JSON string type. 196 o "Number" - The JSON number type. 198 o "Boolean" - The JSON boolean type. 200 o "A[B]" - A JSON object where the keys are all of type "A", and the 201 values are all of type "B". 203 o "A[]" - An array of values of type "A". 205 o "A|B" - The value is either of type "A" or of type "B". 207 Other types may also be given, with their representation defined 208 elsewhere in this document. 210 Object properties may also have a set of attributes defined along 211 with the type signature. These have the following meanings: 213 o *server-set*: Only the server can set the value for this property. 214 The client MUST NOT send this property when creating a new object 215 of this type. 217 o *immutable*: The value MUST NOT change after the object is 218 created. 220 o *default*: (This is followed by a JSON value). The value that 221 will be used for this property if it is omitted in an argument, or 222 when creating a new object of this type. 224 1.2. The Id data type 226 All record ids are assigned by the server, and are immutable. 228 Where "Id" is given as a datatype, it means a "String" of at least 1 229 and maximum 255 octets in size, and MUST only contain characters from 230 the "URL and Filename safe" Base 64 Alphabet, as defined in section 5 231 of [RFC4648], excluding the pad character ("="). This means the 232 allowed characters are the ASCII alphanumeric characters ("A-Za- 233 z0-9"), hyphen ("-"), and underscore ("_"). 235 These characters are safe to use in almost any context (e.g., 236 filesystems, URIs, IMAP atoms). For maximum safety, servers SHOULD 237 also follow defensive allocation strategies to avoid creating risks 238 where glob completion or data type detection may be present (e.g., on 239 filesystems or in spreadsheets). In particular, it is wise to avoid: 241 o Ids starting with a dash 243 o Ids starting with digits 244 o Ids that contain only digits 246 o Ids that differ only by ASCII case (for example, A vs. a) 248 o the specific sequence of three characters "NIL" (because this 249 sequence can be confused with the IMAP protocol expression of the 250 null value) 252 A good solution to these issues is to prefix every id with a single 253 alphabetical character. 255 1.3. The Int and UnsignedInt data types 257 Where "Int" is given as a data type, it means an integer in the range 258 -2^53+1 <= value <= 2^53-1, the safe range for integers stored in a 259 floating-point double, represented as a JSON "Number". 261 Where "UnsignedInt" is given as a data type, it means an "Int" where 262 the value MUST be in the range 0 <= value <= 2^53-1. 264 1.4. The Date and UTCDate data types 266 Where "Date" is given as a type, it means a string in [RFC3339] 267 _date-time_ format. To ensure a normalised form, the _time-secfrac_ 268 MUST always be omitted if zero, and any letters in the string (e.g. 269 "T" and "Z") MUST be upper-case. For example, 270 ""2014-10-30T14:12:00+08:00"". 272 Where "UTCDate" is given as a type, it means a "Date" where the 273 _time-offset_ component MUST be "Z" (i.e. it must be in UTC time). 274 For example, ""2014-10-30T06:12:00Z"". 276 1.5. JSON as the data encoding format 278 JSON is a text-based data interchange format as specified in 279 [RFC8259]. The I-JSON format defined in [RFC7493] is a strict subset 280 of this, adding restrictions to avoid potentially confusing scenarios 281 (for example, it mandates that an object MUST NOT have two members 282 with the same name). 284 All data sent from the client to the server or from the server to the 285 client (except binary file upload/download) MUST be valid I-JSON 286 according to the RFC, and is therefore case-sensitive and encoded in 287 UTF-8 ([RFC3629]). 289 1.6. Terminology 291 1.6.1. User 293 A user is a person accessing data via JMAP. A user has a set of 294 permissions determining the data that they can see. 296 1.6.2. Accounts 298 An account is a collection of data. A single account may contain an 299 arbitrary set of data types, for example a collection of mail, 300 contacts and calendars. Most JMAP methods take a mandatory 301 _accountId_ argument that specifies on which account the operations 302 are to take place. 304 An account is not the same as a user, although it is common for a 305 primary account to directly belong to the user. For example, you may 306 have an account that contains data for a group or business, to which 307 multiple users have access. 309 A single set of credentials may provide access to multiple accounts, 310 for example if another user is sharing their work calendar with the 311 authenticated user, or if there is a group mailbox for a support-desk 312 inbox. 314 In the event of a severe internal error, a server may have to 315 reallocate ids or do something else that violates standard JMAP data 316 constraints for an account. In this situation, the data on the 317 server is no longer compatible with cached data the client may have 318 from before. The server MUST treat this as though the account has 319 been deleted and then recreated with a new account id. Clients will 320 then be forced to throw away any data with the old account id and 321 refetch all data from scratch. 323 1.6.3. Data types and records 325 JMAP provides a uniform interface for creating, retrieving, updating 326 and deleting various types of objects. A *data type* is a collection 327 of named, typed properties, just like the schema for a database 328 table. Each instance of a data type is called a *record*. 330 The id of a record is immutable, and assigned by the server. The id 331 MUST be unique among all records of the *same type* within the *same 332 account*. Ids may clash across accounts, or for two records of 333 different types within the same account. 335 1.7. The JMAP API model 337 JMAP uses HTTP [RFC7230] to expose API, Push, Upload and Download 338 resources. All HTTP requests MUST use the "https://" scheme 339 ([RFC2818] HTTP over TLS). All HTTP requests MUST be authenticated. 341 An authenticated client can fetch the user's JMAP Session object with 342 details about the data and capabilities the server can provide as 343 shown in section 2. The client may then exchange data with the 344 server in the following ways: 346 1. The client may make an API request to the server to get or set 347 structured data. This request consists of an ordered series of 348 method calls. These are processed by the server, which then 349 returns an ordered series of responses. This is described in 350 sections 3 to 5. 352 2. The client may download or upload binary files from/to the 353 server. This is detailed in section 6. 355 3. The client may connect to a push channel on the server, to be 356 notified when data has changed. This is explained in section 7. 358 1.8. Vendor-specific extensions 360 Individual services will have custom features they wish to expose 361 over JMAP. This may take the form of extra data types and/or methods 362 not in the spec, or extra arguments to JMAP methods, or extra 363 properties on existing data types (which may also appear in arguments 364 to methods that take property names). 366 The server can advertise custom extensions it supports by including 367 the identifiers in the capabilities object. Identifiers for vendor 368 extensions MUST be a URL belonging to a domain owned by the vendor, 369 to avoid conflict. The URL SHOULD resolve to documentation for the 370 changes the extension makes. 372 To ensure compatibility with clients that don't know about a specific 373 custom extension, and for compatibility with future versions of JMAP, 374 to use an extension the client MUST opt in by passing the appropriate 375 capability identifier in the _using_ array of the Request object, as 376 described in section 3.2. The server MUST only follow the 377 specifications that are opted-into and behave as though it does not 378 implement anything else when processing a request. 380 2. The JMAP Session resource 382 You need two things to connect to a JMAP server: 384 1. The URL for the JMAP Session resource. This may be requested 385 directly from the user, or discovered automatically based on a 386 username domain (see section 2.2 below). 388 2. Credentials to authenticate with. How to obtain credentials is 389 out of scope for this document. 391 An authenticated GET request to the JMAP Session resource MUST return 392 the details about the data and capabilities the server can provide to 393 the client given those credentials. 395 The response to a successful request is a JSON-encoded *JMAP Session* 396 object. It has the following properties: 398 o *capabilities*: "String[Object]" An object specifying the 399 capabilities of this server. Each key is a URI for a capability 400 supported by the server. The value for each of these keys is an 401 object with further information about the server's capabilities in 402 relation to that capability. 404 The client MUST ignore any properties it does not understand. 406 The capabilities object MUST include a property called 407 "urn:ietf:params:jmap:core". The value of this property is an 408 object which MUST contain the following information on server 409 capabilities (suggested minimum values for limits are supplied 410 that allow clients to make efficient use of the network): 412 * *maxSizeUpload*: "UnsignedInt" The maximum file size, in 413 octets, that the server will accept for a single file upload 414 (for any purpose). Suggested minimum: 50,000,000. 416 * *maxConcurrentUpload*: "UnsignedInt" The maximum number of 417 concurrent requests the server will accept to the upload 418 endpoint. Suggested minimum: 4. 420 * *maxSizeRequest*: "UnsignedInt" The maximum size, in octets, 421 that the server will accept for a single request to the API 422 endpoint. Suggested minimum: 10,000,000. 424 * *maxConcurrentRequests*: "UnsignedInt" The maximum number of 425 concurrent requests the server will accept to the API endpoint. 426 Suggested minimum: 4. 428 * *maxCallsInRequest*: "UnsignedInt" The maximum number of method 429 calls the server will accept in a single request to the API 430 endpoint. Suggested minimum: 16. 432 * *maxObjectsInGet*: "UnsignedInt" The maximum number of objects 433 that the client may request in a single "/get" type method 434 call. Suggested minimum: 500 436 * *maxObjectsInSet*: "UnsignedInt" The maximum number of objects 437 the client may send to create, update or destroy in a single 438 "/set" type method call. This is the combined total, e.g. if 439 the maximum is 10 you could not create 7 objects and destroy 6, 440 as this would be 13 actions, which exceeds the limit. 441 Suggested minimum: 500. 443 * *collationAlgorithms*: "String[]" A list of identifiers for 444 algorithms registered in the collation registry defined in 445 [RFC4790] that the server supports for sorting when querying 446 records. 448 Specifications for future capabilities will define their own 449 properties on the capabilities object. 451 Servers MAY advertise vendor-specific JMAP extensions, as 452 described in section 1.8. To avoid conflict, an identifier for a 453 vendor-specific extension MUST be a URL with a domain owned by the 454 vendor. Clients MUST opt in to any capability it wishes to use 455 (see section 3.2). 457 o *accounts*: "Id[Account]" A map of *account id* to Account object 458 for each account (see section 1.5.2) the user has access to. An 459 *Account* object has the following properties: 461 * *name*: "String" A user-friendly string to show when presenting 462 content from this account, e.g. the email address representing 463 the owner of the account. 465 * *isPersonal*: "Boolean" This is "true" if the account belongs 466 to the authenticated user, rather than a group account or a 467 personal account of another user that has been shared with 468 them. 470 * *isReadOnly*: "Boolean" This is "true" if the entire account is 471 read-only. 473 * *accountCapabilities*: "String[Object]" The set of capability 474 URIs for the methods supported in this account. Each key is a 475 URI for a capability that has methods you can use with this 476 account. The value for each of these keys is an object with 477 further information about the account's permissions and 478 restrictions with respect to this capability, as defined in the 479 capability's specification. 481 The client MUST ignore any properties it does not understand. 483 The server advertises the full list of capabilities it supports 484 in the capabilities object, as defined above. If the 485 capability defines new methods, the server MUST include it in 486 the _accountCapabilities_ object if the user may use those 487 methods with this account. It MUST NOT include it in the 488 _accountCapabilities_ object if the user cannot use those 489 methods with this account. 491 For example, you may have access to your own account with mail, 492 calendars and contacts data, and also a shared account that 493 only has contacts data (a business address book for example). 494 In this case the _accountCapabilities_ property on the first 495 account would include something like 496 "urn:ietf:params:jmap:mail", "urn:ietf:params:jmap:calendars", 497 "urn:ietf:params:jmap:contacts", while the second account would 498 just have the last of these. 500 Attempts to use the methods defined in a capability with one of 501 the accounts that does not support that capability are rejected 502 with an _accountNotSupportedByMethod_ error (see section 3.5.2: 503 method-level errors). 505 o *primaryAccounts*: "String[Id]" A map of capability URIs (as found 506 in _accountCapabilities_) to the account id to be considered the 507 user's main or default account for data pertaining to that 508 capability. If no account being returned belongs to the user, or 509 in any other way there is no appropriate way to determine a 510 default account, there MAY be no entry for a particular URI, even 511 though that capability is supported by the server (and in the 512 capabilities object). "urn:ietf:params:jmap:core" SHOULD NOT be 513 present. 515 o *username*: "String" The username associated with the given 516 credentials, or the empty string if none. 518 o *apiUrl*: "String" The URL to use for JMAP API requests. 520 o *downloadUrl*: "String" The URL endpoint to use when downloading 521 files, in [RFC6570] URI Template (level 1) format. The URL MUST 522 contain variables called "accountId", "blobId", "type" and "name". 523 The use of these variables is described in section 6.2. Due to 524 potential encoding issues with slashes in content types, it is 525 RECOMMENDED to put the "type" variable in the query section of the 526 URL. 528 o *uploadUrl*: "String" The URL endpoint to use when uploading 529 files, in [RFC6570] URI Template (level 1) format. The URL MUST 530 contain a variable called "accountId". The use of this variable 531 is described in section 6.1. 533 o *eventSourceUrl*: "String" The URL to connect to for push events, 534 as described in section 7.3, in [RFC6570] URI Template (level 1) 535 format. The URL MUST contain variables called "types", 536 "closeafter" and "ping". The use of these variables is described 537 in section 7.3. 539 o *state*: "String" A (preferably short) string representing the 540 state of this object on the server. If the value of any other 541 property on the session object changes, this string will change. 542 The current value is also returned on the API Response object (see 543 section 3.3), allowing clients to quickly determine if the session 544 information has changed (e.g. an account has been added or 545 removed) and so they need to refetch the object. 547 To ensure future compatibility, other properties MAY be included on 548 the JMAP Session object. Clients MUST ignore any properties they are 549 not expecting. 551 Implementors must take care to avoid inappropriate caching of the 552 session object at the HTTP layer. Since the client should only 553 refetch when it detects there is a change (via the sessionState 554 property of an API response), it is RECOMMENDED to disable HTTP 555 caching altogether, for example by setting "Cache-Control: no-cache, 556 no-store, must-revalidate" on the response. 558 2.1. Example 560 In the following example JMAP Session object, the user has access to 561 their own mail and contacts via JMAP, as well as read-only access to 562 shared mail from another user. The server is advertising a custom 563 "https://example.com/apis/foobar" capability. 565 { 566 "capabilities": { 567 "urn:ietf:params:jmap:core": { 568 "maxSizeUpload": 50000000, 569 "maxConcurrentUpload": 8, 570 "maxSizeRequest": 10000000, 571 "maxConcurrentRequest": 8, 572 "maxCallsInRequest": 32, 573 "maxObjectsInGet": 256, 574 "maxObjectsInSet": 128, 575 "collationAlgorithms": [ 576 "i;ascii-numeric", 577 "i;ascii-casemap", 578 "i;unicode-casemap" 579 ] 580 }, 581 "urn:ietf:params:jmap:mail": {} 582 "urn:ietf:params:jmap:contacts": {}, 583 "https://example.com/apis/foobar": { 584 "maxFoosFinangled": 42 585 } 586 }, 587 "accounts": { 588 "A13824": { 589 "name": "john@example.com", 590 "isPersonal": true, 591 "isReadOnly": false, 592 "accountCapabilities": { 593 "urn:ietf:params:jmap:mail": { 594 "maxMailboxesPerEmail": null, 595 "maxMailboxDepth": 10, 596 ... 597 }, 598 "urn:ietf:params:jmap:contacts": { 599 ... 600 } 601 } 602 }, 603 "A97813": { 604 "name": "jane@example.com", 605 "isPersonal": false, 606 "isReadOnly": true, 607 "accountCapabilities": { 608 "urn:ietf:params:jmap:mail": { 609 "maxMailboxesPerEmail": 1, 610 "maxMailboxDepth": 10, 611 ... 612 } 613 } 614 } 615 }, 616 "primaryAccounts": { 617 "urn:ietf:params:jmap:mail": "A13824", 618 "urn:ietf:params:jmap:contacts": "A13824" 619 }, 620 "username": "john@example.com", 621 "apiUrl": "https://jmap.example.com/api/", 622 "downloadUrl": "https://jmap.example.com 623 /download/{accountId}/{blobId}/{name}?accept={type}", 624 "uploadUrl": "https://jmap.example.com/upload/{accountId}/", 625 "eventSourceUrl": "https://jmap.example.com 626 /eventsource/?types={types}&closeafter={closeafter}&ping={ping}", 627 "state": "75128aab4b1b" 628 } 630 2.2. Service autodiscovery 632 There are two standardised autodiscovery methods in use for internet 633 protocols: 635 o *DNS SRV* ([RFC2782], [RFC6186] and [RFC6764]) 637 o *.well-known/servicename* ([RFC5785]) 639 A JMAP-supporting host for the domain "example.com" SHOULD publish a 640 SRV record "_jmap._tcp.example.com" which gives a _hostname_ and 641 _port_ (usually port "443"). The JMAP Session resource is then 642 "https://${hostname}[:${port}]/.well-known/jmap" (following any 643 redirects). 645 If the client has a username in the form of an email address, it MAY 646 use the domain portion of this to attempt autodiscovery of the JMAP 647 server. 649 3. Structured data exchange 651 The client may make an API request to the server to get or set 652 structured data. This request consists of an ordered series of 653 method calls. These are processed by the server, which then returns 654 an ordered series of responses. 656 3.1. Making an API request 658 To make an API request, the client makes an authenticated POST 659 request to the API resource, which is defined by the _apiUrl_ 660 property in the JMAP Session object. 662 The request MUST be of type "application/json" and consist of a 663 single JSON *Request* object, as defined in section 3.2. If 664 successful, the response MUST also be of type "application/json" and 665 consist of a single *Response* object, as defined in section 3.3. 667 3.1.1. The Invocation data type 669 Method calls and responses are represented by the *Invocation* data 670 type. This is a tuple, represented as a JSON array containing three 671 elements: 673 1. A "String" *name* of the method to call or of the response. 675 2. A "String[*]" object containing _named_ *arguments* for that 676 method or response. 678 3. A "String" *method call id*: an arbitrary string from the client 679 to be echoed back with the responses emitted by that method call 680 (a method may return 1 or more responses, as it may make implicit 681 calls to other methods; all responses initiated by this method 682 call get the same method call id in the response). 684 3.2. The Request object 686 A *Request* object has the following properties: 688 o *using*: "String[]" The set of capabilities the client wishes to 689 use. The client MAY include capability identifiers even if the 690 method calls it makes do not utilise those capabilities. The 691 server advertises the set of specifications it supports in the 692 JMAP Session object, as keys on the _capabilities_ property. 694 o *methodCalls*: "Invocation[]" An array of method calls to process 695 on the server. The method calls MUST be processed sequentially, 696 in order. 698 o *createdIds*: "Id[Id]" (optional) A map of (client-specified) 699 creation id to the id the server assigned when a record was 700 successfully created. 702 As described later in this specification, some records may have a 703 property that contains the id of another record. To allow more 704 efficient network usage, you can set this property to reference a 705 record created earlier in the same API request. Since the real id 706 is unknown when the request is created, the client can instead 707 specify the creation id it assigned, prefixed with a "#" (see 708 section 5.3 for more details). 710 As the server processes API requests, any time it successfully 711 creates a new record it adds to this map the creation id (see the 712 _create_ argument to "/set" in section 5.3), with the server- 713 assigned real id as the value. If it comes across a reference to 714 a creation id in a create/update, it looks it up in the map and 715 replaces the reference with the real id, if found. 717 The client can pass an initial value for this map as the 718 _createdIds_ property of the Request. This may be an empty 719 object. If given in the request, the response will also include a 720 createdIds property. This allows proxy servers to easily split a 721 JMAP request into multiple JMAP requests to send to different 722 servers. For example it could send the first two method calls to 723 server A, then the third to server B, before sending the fourth to 724 server A again. By passing the createdIds of the previous 725 response to the next request, it can ensure all of these still 726 resolve. See section 5.8 for further discussion of proxy 727 considerations. 729 Future specifications MAY add further properties to the Request 730 object to extend the semantics. To ensure forwards compatibility, a 731 server MUST ignore any other properties it does not understand on the 732 JMAP request object. 734 3.2.1. Example request 736 { 737 "using": [ "urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail" ], 738 "methodCalls": [ 739 [ "method1", { 740 "arg1": "arg1data", 741 "arg2": "arg2data" 742 }, "c1" ], 743 [ "method2", { 744 "arg1": "arg1data" 745 }, "c2" ], 746 [ "method3", {}, "c3" ] 747 ] 748 } 750 3.3. The Response object 752 A *Response* object has the following properties: 754 o *methodResponses*: "Invocation[]" An array of responses, in the 755 same format as the _methodCalls_ on the request object. The 756 output of the methods MUST be added to the _methodResponses_ array 757 in the same order as the methods are processed. 759 o *createdIds*: "Id[Id]" (optional; only returned if given in 760 request) A map of (client-specified) creation id to the id the 761 server assigned when a record was successfully created. This MUST 762 include all creation ids passed in the original createdIds 763 parameter of the Request object, as well as any additional ones 764 added for newly created records. 766 o *sessionState*: "String" The current value of the "state" string 767 on the JMAP Session object, as described in section 2. Clients 768 may use this to detect if this object has changed and needs to be 769 refetched. 771 Unless otherwise specified, if the method call completed successfully 772 its response name is the same as the method name in the request. 774 3.3.1. Example response: 776 { 777 "methodResponses": [ 778 [ "method1", { 779 "arg1": 3, 780 "arg2": "foo" 781 }, "c1" ], 782 [ "method2", { 783 "isBlah": true 784 }, "c2" ], 785 [ "anotherResponseFromMethod2", { 786 "data": 10, 787 "yetmoredata": "Hello" 788 }, "c2"], 789 [ "error", { 790 "type":"unknownMethod" 791 }, "c3" ] 792 ], 793 "sessionState": "75128aab4b1b" 794 } 796 3.4. Omitting arguments 798 An argument to a method may be specified to have a default value. If 799 omitted by the client, the server MUST treat the method call the same 800 as if the default value had been specified. Similarly, the server 801 MAY omit any argument in a response which has the default value. 803 Unless otherwise specified in a method description, "null" is the 804 default value for any argument in a request or response where this is 805 allowed by the type signature. Other arguments may only be omitted 806 if an explicit default value is defined in the method description. 808 3.5. Errors 810 There are three different levels of granularity at which an error may 811 be returned in JMAP. 813 When an API request is made, the request as a whole may be rejected 814 due to rate limiting, malformed JSON, request for an unknown 815 capability etc. In this case the entire request is rejected with an 816 appropriate HTTP error response code, and an additional JSON body 817 with more detail for the client. 819 Provided the request itself is syntactically valid (the JSON is 820 valid, and when decoded matches the type signature of a Request 821 object), the methods within it are executed sequentially by the 822 server. Each method may individually fail, for example if invalid 823 arguments are given, or an unknown method name is called. 825 Finally, methods that make changes to the server state often act upon 826 a number of different records within a single call. Each record 827 change may be separately rejected with a SetError, as described in 828 section 5.3. 830 3.5.1. Request-level errors 832 When an HTTP error response is returned to the client, the server 833 SHOULD return a JSON "problem details" object as the response body, 834 as per [RFC7807]. 836 The following problem types are defined: 838 o "urn:ietf:params:jmap:error:unknownCapability" The client included 839 a capability in the "using" property of the request that the 840 server does not support. 842 o "urn:ietf:params:jmap:error:notJSON" The content type of the 843 request was not "application/json" or the request did not parse as 844 I-JSON. 846 o "urn:ietf:params:jmap:error:notRequest" The request parsed as JSON 847 but did not match the type signature of the Request object. 849 o "urn:ietf:params:jmap:error:limit" The request was not processed 850 as it would have exceeded one of the *request* limits defined on 851 the capability object, such as maxSizeRequest, maxCallsInRequest 852 or maxConcurrentRequests. A "limit" property MUST also be present 853 on the "problem details" object, containing the name of the limit 854 being applied. 856 3.5.1.1. Example 858 { 859 "type": "urn:ietf:params:jmap:error:unknownCapability", 860 "status": 400, 861 "detail": "The request object used capability 862 'https://example.com/apis/foobar', which is not supported 863 by this server." 864 } 866 Another example: 868 { 869 "type": "urn:ietf:params:jmap:error:limit", 870 "limit": "maxSizeRequest", 871 "status": 400, 872 "detail": "The request is larger than the server is willing to process." 873 } 875 3.5.2. Method-level errors 877 If a method encounters an error, the appropriate "error" response 878 MUST be inserted at the current point in the _methodResponses_ array 879 and, unless otherwise specified, further processing MUST NOT happen 880 within that method call. 882 Any further method calls in the request MUST then be processed as 883 normal. Errors at the method level MUST NOT generate an HTTP-level 884 error. 886 An "error" response looks like this: 888 [ "error", { 889 "type": "unknownMethod" 890 }, "call-id" ] 892 The response name is "error", and it MUST have a type property. 893 Other properties may be present with further information; these are 894 detailed in the error type descriptions where appropriate. 896 With the exception of when the "serverPartialFail" error is returned, 897 the externally-visible state of the server MUST NOT have changed if 898 an error is returned at the method level. 900 The following error types are defined which may be returned for any 901 method call where appropriate: 903 "serverUnavailable": Some internal server resource was temporarily 904 unavailable. Attempting the same operation later (perhaps after a 905 backoff with a random factor) may succeed. 907 "serverFail": An unexpected or unknown error occurred during the 908 processing of the call. A _description_ property should provide more 909 details about the error. The method call made no changes to the 910 server's state. Attempting the same operation again is expected to 911 fail again. Contacting the service administrator is likely necessary 912 to resolve this problem if it is persistent. 914 "serverPartialFail": Some, but not all expected changes described by 915 the method occurred. The client MUST re-synchronise impacted data to 916 determine server state. Use of this error is strongly discouraged. 918 "unknownMethod": The server does not recognise this method name. 920 "invalidArguments": One of the arguments is of the wrong type or 921 otherwise invalid, or a required argument is missing. A 922 "description" property MAY be present to help debug with an 923 explanation of what the problem was. This is a non-localised string, 924 and is not intended to be shown directly to end users. 926 "invalidResultReference": The method used a result reference for one 927 of its arguments (see section 3.6), but this failed to resolve. 929 "forbidden": The method and arguments are valid, but executing the 930 method would violate an ACL or other permissions policy. 932 "accountNotFound": The _accountId_ does not correspond to a valid 933 account. 935 "accountNotSupportedByMethod": The _accountId_ given corresponds to a 936 valid account, but the account does not support this method or data 937 type. 939 "accountReadOnly": This method call would modify state in an account 940 that is read-only (as returned on the corresponding Account object in 941 the JMAP Session resource). 943 Further possible errors for a particular method are specified in the 944 method descriptions. 946 Further general errors MAY be defined in future RFCs. Should a 947 client receive an error type it does not understand, it MUST treat it 948 the same as the "serverFail" type. 950 3.6. References to previous method results 952 To allow clients to make more efficient use of the network and avoid 953 round trips, an argument to one method can be taken from the result 954 of a previous method call in the same request. 956 To do this, the client prefixes the argument name with "#" (an 957 octothorpe). The value is a _ResultReference_ object as described 958 below. When processing a method call, the server MUST first check 959 the arguments object for any names beginning with "#". If found, the 960 result reference should be resolved and the value used as the "real" 961 argument. The method is then processed as normal. If any result 962 reference fails to resolve, the whole method MUST be rejected with an 963 "invalidResultReference" error. If an argument object contains the 964 same argument name in normal and referenced form (e.g. "foo" and 965 "#foo"), the method MUST return an "invalidArguments" error. 967 A *ResultReference* object has the following properties: 969 o *resultOf*: "String" The method call id of the method call to get 970 the result from (the string given as the third item in the array 971 for a method call). 973 o *name*: "String" The expected name of the response. 975 o *path*: "String" A pointer into the arguments. This is an 976 [RFC6901] JSON Pointer, except it also allows the use of "*" to 977 map through an array (see description below). 979 To resolve: 981 1. Find the first response with a method call id identical to the 982 _resultOf_ property of the _ResultReference_ in the 983 _methodResponses_ array from previously processed method calls in 984 the same request. If none, evaluation fails. 986 2. If the response name is not identical to the _name_ property of 987 the _ResultReference_, evaluation fails. 989 3. Apply the _path_ to the arguments object of the response (the 990 second item in the response array) following the [RFC6901] JSON 991 Pointer algorithm, except with the following addition in section 992 4 (Evaluation): 994 If the currently referenced value is a JSON array, the reference 995 token may be exactly the single character "*", making the new 996 referenced value the result of applying the rest of the JSON 997 pointer tokens to every item in the array and returning the 998 results in the same order in a new array. If the result of 999 applying the rest of the pointer tokens to a value was itself an 1000 array, its items should be included individually in the output 1001 rather than including the array itself (i.e. the result is 1002 flattened from an array of arrays to a single array). 1004 As a simple example, suppose we have the following API request 1005 _methodCalls_: 1007 [[ "Foo/changes", { 1008 "accountId": "A1", 1009 "sinceState": "abcdef" 1010 }, "t0" ], 1011 [ "Foo/get", { 1012 "accountId": "A1", 1013 "#ids": { 1014 "resultOf": "t0", 1015 "name": "Foo/changes", 1016 "path": "/created" 1017 } 1018 }, "t1" ]] 1020 After executing the first method call the _methodResponses_ array is: 1022 [[ "Foo/changes", { 1023 "accountId": "A1", 1024 "oldState": "abcdef", 1025 "newState": "123456", 1026 "hasMoreChanges": false, 1027 "created": [ "f1", "f4" ], 1028 "updated": [], 1029 "destroyed": [] 1030 }, "t0" ]] 1032 To execute the Foo/get call, we look through the arguments and find 1033 there is one with a "#" prefix. To resolve this, we apply the 1034 algorithm above: 1036 1. Find the first response with method call id "t0". The Foo/ 1037 changes response fulfils this criterion. 1039 2. Check the response name is the same as in the result reference. 1040 It is, so this is fine. 1042 3. Apply the _path_ as a JSON pointer to the arguments object. This 1043 simply selects the "created" property, so the result of 1044 evaluating is: "[ "f1", "f4" ]" 1046 The JMAP server now continues to process the Foo/get call as though 1047 the arguments were: 1049 { 1050 "accountId": "A1", 1051 "ids": [ "f1", "f4" ] 1052 } 1054 Now a more complicated example using the JMAP Mail data model: fetch 1055 the "from"/"date"/"subject" for every email in the first 10 threads 1056 in the Inbox (sorted newest first): 1058 [[ "Email/query", { 1059 "accountId": "A1", 1060 "filter": { "inMailbox": "id_of_inbox" }, 1061 "sort": [{ "property": "receivedAt", "isAscending": false }], 1062 "collapseThreads": true, 1063 "position": 0, 1064 "limit": 10, 1065 "calculateTotal": true 1066 }, "t0" ], 1067 [ "Email/get", { 1068 "accountId": "A1", 1069 "#ids": { 1070 "resultOf": "t0", 1071 "name": "Email/query", 1072 "path": "/ids" 1073 }, 1074 "properties": [ "threadId" ] 1075 }, "t1" ], 1076 [ "Thread/get", { 1077 "accountId": "A1", 1078 "#ids": { 1079 "resultOf": "t1", 1080 "name": "Email/get", 1081 "path": "/list/*/threadId" 1082 } 1083 }, "t2" ], 1084 [ "Email/get", { 1085 "accountId": "A1", 1086 "#ids": { 1087 "resultOf": "t2", 1088 "name": "Thread/get", 1089 "path": "/list/*/emailIds" 1090 }, 1091 "properties": [ "from", "receivedAt", "subject" ] 1092 }, "t3" ]] 1094 After executing the first 3 method calls the _methodResponses_ array 1095 might be: 1097 [[ "Email/query", { 1098 "accountId": "A1", 1099 "queryState": "abcdefg", 1100 "canCalculateChanges": true, 1101 "position": 0, 1102 "total": 101, 1103 "ids": [ "msg1023", "msg223", "msg110", "msg93", "msg91", 1104 "msg38", "msg36", "msg33", "msg11", "msg1" ] 1105 }, "t0" ], 1106 [ "Email/get", { 1107 "accountId": "A1", 1108 "state": "123456", 1109 "list": [{ 1110 "id": "msg1023", 1111 "threadId": "trd194" 1112 }, { 1113 "id": "msg223", 1114 "threadId": "trd114" 1115 }, 1116 ... 1117 ], 1118 "notFound": [] 1119 }, "t1" ], 1120 [ "Thread/get", { 1121 "accountId": "A1", 1122 "state": "123456", 1123 "list": [{ 1124 "id": "trd194", 1125 "emailIds": [ "msg1020", "msg1021", "msg1023" ] 1126 }, { 1127 "id": "trd114", 1128 "emailIds": [ "msg201", "msg223" ] 1129 }, 1130 ... 1131 ], 1132 "notFound": [] 1133 }, "t2" ]] 1135 So to execute the final Email/get call, we look through the arguments 1136 and find there is one with a "#" prefix. To resolve this, we apply 1137 the algorithm: 1139 1. Find the first response with method call id "t2". The "Thread/ 1140 get" response fulfils this criterion. 1142 2. "Thread/get" is the name specified in the result reference, so 1143 this is fine. 1145 3. Apply the _path_ as a JSON pointer to the arguments object. 1146 Token-by-token: 1148 1. "list": get the array of thread objects 1150 2. "*": for each of the items in the array: 1152 1. "emailIds": get the array of email ids 1154 2. Concatenate these into a single array of all the ids in 1155 the result. 1157 The JMAP server now continues to process the Email/get call as though 1158 the arguments were: 1160 { 1161 "accountId": "A1", 1162 "ids": [ "msg1020", "msg1021", "msg1023", "msg201", "msg223", ... ], 1163 "properties": [ "from", "receivedAt", "subject" ] 1164 } 1166 The ResultReference performs a similar role to that of the creation 1167 id, in that it allows a chained method call to refer to information 1168 not available when the request is generated. However, they are 1169 different things and not interchangable; the only commonality is the 1170 octothorpe used to indicate them. 1172 3.7. Localisation of user-visible strings 1174 If returning a custom string to be displayed to the user, for example 1175 an error message, the server SHOULD use information from the Accept- 1176 Language header of the request (as defined in [RFC7231] section 1177 5.3.5) to help determine the choice of localisation if multiple are 1178 available. The Content-Language header of the response (see 1179 section 3.1.3.2 of [RFC7231]) SHOULD indicate the language being used 1180 for user-visible strings. 1182 For example, suppose a request was made with the following header: 1184 Accept-Language: fr-CH, fr;q=0.9, de;q=0.8, en;q=0.7, *;q=0.5 1186 and a method generated an error to display to the user. The server 1187 has translations of the error message in English and German. Looking 1188 at the Accept-Language header, the user's preferred language is 1189 French. Since we don't have a translation for this, we look at the 1190 next most preferred which is German. We have a German translation so 1191 the server returns this, and indicates the language chosen in a 1192 Content-Language header like so: 1194 Content-Language: de 1196 3.8. Security 1198 As always, the server must be strict about data received from the 1199 client. Arguments need to be checked for validity; a malicious user 1200 could attempt to find an exploit through the API. In case of invalid 1201 arguments (unknown/insufficient/wrong type for data etc.) the method 1202 MUST return an "invalidArguments" error and terminate. 1204 3.9. Concurrency 1206 Method calls within a single request MUST be executed in order. 1207 However, method calls from different concurrent API requests may be 1208 interleaved. This means that the data on the server may change 1209 between two method calls within a single API request. 1211 4. The Core/echo method 1213 The _Core/echo_ method returns exactly the same arguments as it is 1214 given. It is useful for testing you have a valid authenticated 1215 connection to a JMAP API endpoint. 1217 4.1. Example 1219 Request: 1221 [[ "Core/echo", { 1222 "hello": true, 1223 "high": 5 1224 }, "b3ff" ]] 1226 Response: 1228 [[ "Core/echo", { 1229 "hello": true, 1230 "high": 5 1231 }, "b3ff" ]] 1233 5. Standard methods and naming convention 1235 JMAP provides a uniform interface for creating, retrieving, updating 1236 and deleting objects of a particular type. For a "Foo" data type, 1237 records of that type would be fetched via a "Foo/get" call and 1238 modified via a "Foo/set" call. Delta updates may be fetched via a 1239 "Foo/changes" call. These methods all follow a standard format as 1240 described below. 1242 Some types may not have all these methods. Specifications defining 1243 types MUST specify which methods are available for the type. 1245 5.1. /get 1247 Objects of type *Foo* are fetched via a call to _Foo/get_. 1249 It takes the following arguments: 1251 o *accountId*: "Id" The id of the account to use. 1253 o *ids*: "Id[]|null" The ids of the Foo objects to return. If 1254 "null" then *all* records of the data type are returned, if this 1255 is supported for that data type and the number of records does not 1256 exceed the _maxObjectsInGet_ limit. 1258 o *properties*: "String[]|null" If supplied, only the properties 1259 listed in the array are returned for each Foo object. If "null", 1260 all properties of the object are returned. The id property of the 1261 object is *always* returned, even if not explicitly requested. If 1262 an invalid property is requested, the call MUST be rejected with 1263 an "invalidArguments" error. 1265 The response has the following arguments: 1267 o *accountId*: "Id" The id of the account used for the call. 1269 o *state*: "String" A (preferably short) string representing the 1270 state on the server for *all* the data of this type in the account 1271 (not just the objects returned in this call). If the data 1272 changes, this string MUST change. If the Foo data is unchanged, 1273 servers SHOULD return the same state string on subsequent requests 1274 for this data type. When a client receives a response with a 1275 different state string to a previous call, it MUST either throw 1276 away all currently cached objects for the type, or call _Foo/ 1277 changes_ to get the exact changes. 1279 o *list*: "Foo[]" An array of the Foo objects requested. This is 1280 the *empty array* if no objects were found, or if the _ids_ 1281 argument passed in was also the empty array. The results MAY be 1282 in a different order to the _ids_ in the request arguments. If an 1283 identical id is included more than once in the request, the server 1284 MUST only include it once in either the _list_ or _notFound_ 1285 argument of the response. 1287 o *notFound*: "Id[]" This array contains the ids passed to the 1288 method for records that do not exist. The array is empty if all 1289 requested ids were found, or if the _ids_ argument passed in was 1290 either "null" or the empty array. 1292 The following additional error may be returned instead of the _Foo/ 1293 get_ response: 1295 "requestTooLarge": The number of _ids_ requested by the client 1296 exceeds the maximum number the server is willing to process in a 1297 single method call. 1299 5.2. /changes 1301 When the state of the set of Foo records in an account changes on the 1302 server (whether due to creation, updates or deletion), the _state_ 1303 property of the _Foo/get_ response will change. The _Foo/changes_ 1304 method allows a client to efficiently update the state of its Foo 1305 cache to match the new state on the server. It takes the following 1306 arguments: 1308 o *accountId*: "Id" The id of the account to use. 1310 o *sinceState*: "String" The current state of the client. This is 1311 the string that was returned as the _state_ argument in the _Foo/ 1312 get_ response. The server will return the changes that have 1313 occurred since this state. 1315 o *maxChanges*: "UnsignedInt|null" The maximum number of ids to 1316 return in the response. The server MAY choose to return fewer 1317 than this value, but MUST NOT return more. If not given by the 1318 client, the server may choose how many to return. If supplied by 1319 the client, the value MUST be a positive integer greater than 0. 1320 If a value outside of this range is given, the server MUST reject 1321 the call with an "invalidArguments" error. 1323 The response has the following arguments: 1325 o *accountId*: "Id" The id of the account used for the call. 1327 o *oldState*: "String" This is the _sinceState_ argument echoed 1328 back; the state from which the server is returning changes. 1330 o *newState*: "String" This is the state the client will be in after 1331 applying the set of changes to the old state. 1333 o *hasMoreChanges*: "Boolean" If "true", the client may call _Foo/ 1334 changes_ again with the _newState_ returned to get further 1335 updates. If "false", _newState_ is the current server state. 1337 o *created*: "Id[]" An array of ids for records which have been 1338 created since the old state. 1340 o *updated*: "Id[]" An array of ids for records which have been 1341 updated since the old state. 1343 o *destroyed*: "Id[]" An array of ids for records which have been 1344 destroyed since the old state. 1346 If a record has been created AND updated since the old state, the 1347 server SHOULD just return the id in the _created_ list, but MAY 1348 return it in the _updated_ list as well. 1350 If a record has been updated AND destroyed since the old state, the 1351 server SHOULD just return the id in the _destroyed_ list, but MAY 1352 return it in the _updated_ list as well. 1354 If a record has been created AND destroyed since the old state, the 1355 server SHOULD remove the id from the response entirely, but MAY 1356 include it in the _destroyed_ list, and if so MAY also include it in 1357 the _created_ list. 1359 If a _maxChanges_ is supplied, or set automatically by the server, 1360 the server MUST ensure the number of ids returned across _created_, 1361 _updated_ and _destroyed_ does not exceed this limit. If there are 1362 more changes than this between the client's state and the current 1363 server state, the server SHOULD generate an update to take the client 1364 to an intermediate state, from which the client can continue to call 1365 _Foo/changes_ until it is fully up to date. If it is unable to 1366 calculate an intermediate state, it MUST return a 1367 "cannotCalculateChanges" error response instead. 1369 When generating intermediate states, the server may choose how to 1370 divide up the changes. For many types it will provide a better user 1371 experience to return the more recent changes first, as this is more 1372 likely to be what the user is most interested in. The client can 1373 then continue to page in the older changes while the user is viewing 1374 the newer data. For example, suppose a server went through the 1375 following states: 1377 A -> B -> C -> D -> E 1379 And a client asks for changes from state "B". The server might first 1380 get the ids of records created, updated or destroyed between states D 1381 and E, returning them with: 1383 state: "B-D-E" 1384 hasMoreChanges: true 1386 The client will then ask for the change from state "B-D-E", and the 1387 server can return the changes between states C and D, returning: 1389 state: "B-C-E" 1390 hasMoreChanges: true 1392 Finally the client will request the changes from "B-C-E" and the 1393 server can return the changes between states B and C, returning: 1395 state: "E" 1396 hasMoreChanges: false 1398 Should the state on the server be modified in the middle of all this 1399 (to "F"), the server still does the same but now when the update to 1400 state "E" is returned, it would indicate that it still has more 1401 changes for the client to fetch. 1403 Where multiple changes to a record are split across different 1404 intermediate states, the server MUST NOT return a record as created 1405 in a later response than one which gives it as updated or destroyed, 1406 and MUST NOT return a record as destroyed before a response that 1407 gives it as created or updated. The server may have to coalesce 1408 multiple changes to a record to satisfy this requirement. 1410 The following additional errors may be returned instead of the _Foo/ 1411 changes_ response: 1413 "cannotCalculateChanges": The server cannot calculate the changes 1414 from the state string given by the client. Usually due to the 1415 client's state being too old, or the server being unable to produce 1416 an update to an intermediate state when there are too many updates. 1417 The client MUST invalidate its Foo cache. 1419 Maintaining state to allow calculation of _Foo/changes_ can be 1420 expensive for the server, but always returning 1421 _cannotCalculateChanges_ severely increases network traffic and 1422 resource usage for the client. To allow efficient sync, servers 1423 SHOULD be able to calculate changes from any state string that was 1424 given to a client within the last 30 days (but of course may support 1425 calculating updates from states older than this). 1427 5.3. /set 1429 Modifying the state of Foo objects on the server is done via the 1430 _Foo/set_ method. This encompasses creating, updating and destroying 1431 Foo records. This allows the server to sort out ordering and 1432 dependencies that may exist if doing multiple operations at once (for 1433 example to ensure there is always a minimum number of a certain 1434 record type). 1436 The _Foo/set_ method takes the following arguments: 1438 o *accountId*: "Id" The id of the account to use. 1440 o *ifInState*: "String|null" This is a state string as returned by 1441 the _Foo/get_ method (representing the state of all objects of 1442 this type in the account). If supplied, the string must match the 1443 current state, otherwise the method will be aborted and a 1444 "stateMismatch" error returned. If "null", any changes will be 1445 applied to the current state. 1447 o *create*: "Id[Foo]|null" A map of _creation id_ (a temporary id 1448 set by the client) to Foo objects, or "null" if no objects are to 1449 be created. 1451 The Foo object type definition may define default values for 1452 properties. Any such property may be omitted by the client. 1454 The client MUST omit any properties that may only be set by the 1455 server (for example, the _id_ property on most object types). 1457 o *update*: "Id[PatchObject]|null" A map of id to a Patch object to 1458 apply to the current Foo object with that id, or "null" if no 1459 objects are to be updated. 1461 A _PatchObject_ is of type "String[*]", and represents an 1462 unordered set of patches. The keys are a path in [RFC6901] JSON 1463 pointer format, with an implicit leading "/" (i.e. prefix each key 1464 with "/" before applying the JSON pointer evaluation algorithm). 1466 All paths MUST also conform to the following restrictions; if 1467 there is any violation, the update MUST be rejected with an 1468 "invalidPatch" error: 1470 * The pointer MUST NOT reference inside an array (i.e. you MUST 1471 NOT insert/delete from an array; the array MUST be replaced in 1472 its entirety instead). 1474 * All parts prior to the last (i.e. the value after the final 1475 slash) MUST already exist on the object being patched. 1477 * There MUST NOT be two patches in the PatchObject where the 1478 pointer of one is the prefix of the pointer of the other, e.g. 1479 "alerts/1/offset" and "alerts". 1481 The value associated with each pointer determines how to apply 1482 that patch: 1484 * If "null", set to the default value if specified for this 1485 property, otherwise remove the property from the patched 1486 object. If the key is not present in the parent, this a no-op. 1488 * Anything else: The value to set for this property (this may be 1489 a replacement or addition to the object being patched). 1491 Any server-set properties MAY be included in the patch if their 1492 value is identical to the current server value (before applying 1493 the patches to the object). Otherwise, the update MUST be 1494 rejected with an _invalidProperties_ SetError. 1496 This patch definition is designed such that an entire Foo object 1497 is also a valid PatchObject. The client MAY choose to optimise 1498 network usage by just sending the diff, or MAY just send the whole 1499 object; the server processes it the same either way. 1501 o *destroy*: "Id[]|null" A list of ids for Foo objects to 1502 permanently delete, or "null" if no objects are to be destroyed. 1504 Each creation, modification or destruction of an object is considered 1505 an atomic unit. It is permissible for the server to commit changes 1506 to some objects but not others, however it MUST NOT only commit part 1507 of an update to a single record (e.g. update a _name_ property but 1508 not a _count_ property, if both are supplied in the update object). 1510 The final state MUST be valid after the Foo/set is finished, however 1511 the server may have to transition through invalid intermediate states 1512 (not exposed to the client) while processing the individual 1513 create/update/destroy requests. For example, suppose there is a 1514 "name" property that must be unique. A single method call could 1515 rename an object A => B, and simultaneously rename another object B 1516 => A. If the final state is valid, this is allowed. Otherwise, each 1517 creation, modification or destruction of an object should be 1518 processed sequentially and accepted/rejected based on the current 1519 server state. 1521 If a create, update or destroy is rejected, the appropriate error 1522 MUST be added to the notCreated/notUpdated/notDestroyed property of 1523 the response and the server MUST continue to the next create/update/ 1524 destroy. It does not terminate the method. 1526 If an id given cannot be found, the update or destroy MUST be 1527 rejected with a "notFound" set error. 1529 The server MAY skip an update (rejecting it with a "willDestroy" 1530 SetError) if that object is destroyed in the same /set request. 1532 Some records may hold references to other records (foreign keys). 1533 That reference may be set (via create or update) in the same request 1534 as the referenced record is created. To do this, the client refers 1535 to the new record using its creation id prefixed with a "#". The 1536 order of the method calls in the request by the client MUST be such 1537 that the record being referenced is created in the same or an earlier 1538 call. The server thus never has to look ahead. Instead, while 1539 processing a request the server MUST keep a simple map for the 1540 duration of the request of creation id to record id for each newly 1541 created record, so it can substitute in the correct value if 1542 necessary in later method calls. In the case of records with 1543 references to the same type, the server MUST order the creates and 1544 updates within a single method call so that creates happen before 1545 their creation ids are referenced by another create/update/destroy in 1546 the same call. 1548 Creation ids are not scoped by type but are a single map for all 1549 types. A client SHOULD NOT reuse a creation id anywhere in the same 1550 API request. If a creation id is reused, the server MUST map the 1551 creation id to the most recently created item with that id. To allow 1552 easy proxying of API requests, an initial set of creation id to real 1553 id values may be passed with a request (see The Request object in 1554 section 3.2) and the final state of the map passed out with the 1555 response (see section 3.3). 1557 The response has the following arguments: 1559 o *accountId*: "Id" The id of the account used for the call. 1561 o *oldState*: "String|null" The state string that would have been 1562 returned by _Foo/get_ before making the requested changes, or 1563 "null" if the server doesn't know what the previous state string 1564 was. 1566 o *newState*: "String" The state string that will now be returned by 1567 _Foo/get_. 1569 o *created*: "Id[Foo]|null" A map of the creation id to an object 1570 containing any properties of the created Foo object that were not 1571 sent by the client. This includes all server-set properties (such 1572 as the _id_ in most object types) and any properties that were 1573 omitted by the client and so set to a default by the server. 1575 This argument is "null" if no Foo objects were successfully 1576 created. 1578 o *updated*: "Id[Foo|null]|null" The _keys_ in this map are the ids 1579 of all Foos that were successfully updated. 1581 The _value_ for each id is a Foo object containing any property 1582 that changed in a way _not_ explicitly requested by the 1583 _PatchObject_ sent to the server, or "null" if none. This lets 1584 the client know of any changes to server-set or computed 1585 properties. 1587 This argument is "null" if no Foo objects were successfully 1588 updated. 1590 o *destroyed*: "Id[]|null" A list of Foo ids for records that were 1591 successfully destroyed, or "null" if none. 1593 o *notCreated*: "Id[SetError]|null" A map of creation id to a 1594 SetError object for each record that failed to be created, or 1595 "null" if all successful. 1597 o *notUpdated*: "Id[SetError]|null" A map of Foo id to a SetError 1598 object for each record that failed to be updated, or "null" if all 1599 successful. 1601 o *notDestroyed*: "Id[SetError]|null" A map of Foo id to a SetError 1602 object for each record that failed to be destroyed, or "null" if 1603 all successful. 1605 A *SetError* object has the following properties: 1607 o *type*: "String" The type of error. 1609 o *description*: "String|null" A description of the error to help 1610 debug with an explanation of what the problem was. This is a non- 1611 localised string, and is not intended to be shown directly to end 1612 users. 1614 The following SetError types are defined and may be returned for set 1615 operations on any record type where appropriate: 1617 o "forbidden": (create; update; destroy) The create/update/destroy 1618 would violate an ACL or other permissions policy. 1620 o "overQuota": (create; update) The create would exceed a server- 1621 defined limit on the number or total size of objects of this type. 1623 o "tooLarge": (create; update) The create/update would result in an 1624 object that exceeds a server-defined limit for the maximum size of 1625 a single object of this type. 1627 o "rateLimit": (create) Too many objects of this type have been 1628 created recently, and a server-defined rate limit has been 1629 reached. It may work if tried again later. 1631 o "notFound": (update; destroy) The id given to update/destroy 1632 cannot be found. 1634 o "invalidPatch": (update) The PatchObject given to update the 1635 record was not a valid patch (see the patch description). 1637 o "willDestroy" (update) The client requested an object be both 1638 updated and destroyed in the same /set request, and the server has 1639 decided to therefore ignore the update. 1641 o "invalidProperties": (create; update) The record given is invalid 1642 in some way. For example: 1644 * It contains properties which are invalid according to the type 1645 specification of this record type. 1647 * It contains a property that may only be set by the server (e.g. 1648 "id") and is different to the current value. Note, to allow 1649 clients to pass whole objects back, it is not an error to 1650 include a server-set property in an update so long as the value 1651 is identical to the current value on the server. 1653 * There is a reference to another record (foreign key) and the 1654 given id does not correspond to a valid record. 1656 The SetError object SHOULD also have a property called 1657 _properties_ of type "String[]" that lists *all* the properties 1658 that were invalid. 1660 Individual methods MAY specify more specific errors for certain 1661 conditions that would otherwise result in an invalidProperties 1662 error. If the condition of one of these is met, it MUST be 1663 returned instead of the invalidProperties error. 1665 o "singleton": (create; destroy) This is a singleton type, so you 1666 cannot create another one or destroy the existing one. 1668 Other possible SetError types MAY be given in specific method 1669 descriptions. Other properties MAY also be present on the _SetError_ 1670 object, as described in the relevant methods. 1672 The following additional errors may be returned instead of the _Foo/ 1673 set_ response: 1675 "requestTooLarge": The total number of objects to create, update or 1676 destroy exceeds the maximum number the server is willing to process 1677 in a single method call. 1679 "stateMismatch": An "ifInState" argument was supplied and it does not 1680 match the current state. 1682 5.4. /copy 1684 The only way to move Foo records *between* two different accounts is 1685 to copy them using the _Foo/copy_ method, then once the copy has 1686 succeeded, delete the original. The _onSuccessDestroyOriginal_ 1687 argument allows you to try to do this in one method call, however 1688 note that the two different actions are not atomic, and so it is 1689 possible for the copy to succeed but the original not to be destroyed 1690 for some reason. 1692 The copy is conceptually in three phases: 1694 1. Reading the current values from the "from" account. 1696 2. Writing the new copies to the other account. 1698 3. Destroying the originals in the "from" account, if requested. 1700 Data may change in between phases due to concurrent requests. 1702 The _Foo/copy_ method takes the following arguments: 1704 o *fromAccountId*: "Id" The id of the account to copy records from. 1706 o *ifFromInState*: "String|null" This is a state string as returned 1707 by the _Foo/get_ method. If supplied, the string must match the 1708 current state of the account referenced by the fromAccountId when 1709 reading the data to be copied, otherwise the method will be 1710 aborted and a "stateMismatch" error returned. If "null", the data 1711 will be read from the current state. 1713 o *accountId*: "Id" The id of the account to copy records to. This 1714 MUST be different to the "fromAccountId". 1716 o *ifInState*: "String|null" This is a state string as returned by 1717 the _Foo/get_ method. If supplied, the string must match the 1718 current state of the account referenced by the accountId, 1719 otherwise the method will be aborted and a "stateMismatch" error 1720 returned. If "null", any changes will be applied to the current 1721 state. 1723 o *create*: "Id[Foo]" A map of _creation id_ to a Foo object. The 1724 object MUST contain an id property: the id (in the fromAccount) of 1725 the record to be copied. Any other properties included are used 1726 instead of the current value for that property on the original 1727 when creating the copy. 1729 o *onSuccessDestroyOriginal*: "Boolean" (default: false) If "true", 1730 an attempt will be made to destroy the original records that were 1731 successfully copied: after emitting the _Foo/copy_ response, but 1732 before processing the next method, the server MUST make a single 1733 call to _Foo/set_ to destroy the original of each successfully 1734 copied record; the output of this is added to the responses as 1735 normal to be returned to the client. 1737 o *destroyFromIfInState*: "String|null" This argument is passed on 1738 as the "ifInState" argument to the implicit _Foo/set_ call, if 1739 made at the end of this request to destroy the originals that were 1740 successfully copied. 1742 Each record copy is considered an atomic unit which may succeed or 1743 fail individually. 1745 The response has the following arguments: 1747 o *fromAccountId*: "Id" The id of the account records were copied 1748 from. 1750 o *accountId*: "Id" The id of the account records were copied to. 1752 o *oldState*: "String|null" The state string that would have been 1753 returned by _Foo/get_ on the account records were copied to before 1754 making the requested changes, or "null" if the server doesn't know 1755 what the previous state string was. 1757 o *newState*: "String" The state string that will now be returned by 1758 _Foo/get_ on the account records were copied to. 1760 o *created*: "Id[Foo]|null" A map of the creation id to an object 1761 containing any properties of the copied Foo object that are set by 1762 the server (such as the _id_ in most object types; note, the id is 1763 likely to be different to the id of the object in the account it 1764 was copied from). 1766 This argument is "null" if no Foo objects were successfully 1767 copied. 1769 o *notCreated*: "Id[SetError]|null" A map of creation id to a 1770 SetError object for each record that failed to be copied, "null" 1771 if none. 1773 The *SetError* may be any of the standard set errors that may be 1774 returned for a _create_ or _update_. In addition, the following 1775 SetError is defined: 1777 "alreadyExists": The server forbids duplicates and the record already 1778 exists in the target account. An _existingId_ property of type "Id" 1779 MUST be included on the error object with the id of the existing 1780 record. 1782 The following additional errors may be returned instead of the _Foo/ 1783 copy_ response: 1785 "fromAccountNotFound": The _fromAccountId_ does not correspond to a 1786 valid account. 1788 "fromAccountNotSupportedByMethod": The _fromAccountId_ given 1789 corresponds to a valid account, but the account does not support this 1790 data type. 1792 "stateMismatch": An "ifInState" argument was supplied and it does not 1793 match the current state, or an "ifFromInState" argument was supplied 1794 and it does not match the current state in the from account. 1796 5.5. /query 1798 For data sets where the total amount of data is expected to be very 1799 small, clients can just fetch the complete set of data and then do 1800 any sorting/filtering locally. However, for large data sets (e.g. 1801 multi-gigabyte mailboxes), the client needs to be able to 1802 search/sort/window the data type on the server. 1804 A query on the set of Foos in an account is made by calling _Foo/ 1805 query_. This takes a number of arguments to determine which records 1806 to include, how they should be sorted, and which part of the result 1807 should be returned (the full list may be _very_ long). The result is 1808 returned as a list of Foo ids. 1810 A call to _Foo/query_ takes the following arguments: 1812 o *accountId*: "Id" The id of the account to use. 1814 o *filter*: "FilterOperator|FilterCondition|null" Determines the set 1815 of Foos returned in the results. If "null", all objects in the 1816 account of this type are included in the results. A 1817 *FilterOperator* object has the following properties: 1819 * *operator*: "String" This MUST be one of the following strings: 1820 "AND" / "OR" / "NOT": 1822 + *AND*: all of the conditions must match for the filter to 1823 match. 1825 + *OR*: at least one of the conditions must match for the 1826 filter to match. 1828 + *NOT*: none of the conditions must match for the filter to 1829 match. 1831 * *conditions*: "(FilterOperator|FilterCondition)[]" The 1832 conditions to evaluate against each record. 1834 A *FilterCondition* is an "object" whose allowed properties and 1835 semantics depend on the data type and is defined in the _/query_ 1836 method specification for that type. It MUST NOT have an 1837 _operator_ property. 1839 o *sort*: "Comparator[]|null" Lists the names of properties to 1840 compare between two Foo records, and how to compare them, to 1841 determine which comes first in the sort. If two Foo records have 1842 an identical value for the first comparator, the next comparator 1843 will be considered and so on. If all comparators are the same 1844 (this includes the case where an empty array or "null" is given as 1845 the _sort_ argument), the sort order is server-dependent, but MUST 1846 be stable between calls to Foo/query. A *Comparator* has the 1847 following properties: 1849 * *property*: "String" The name of the property on the Foo 1850 objects to compare. 1852 * *isAscending*: "Boolean" (optional; default: true) If "true", 1853 sort in ascending order. If "false", reverse the comparator's 1854 results to sort in descending order. 1856 * *collation*: "String" (optional; default is server-dependent) 1857 The identifier, as registered in the collation registry defined 1858 in [RFC4790], for the algorithm to use when comparing the order 1859 of strings. The algorithms the server supports are advertised 1860 in the capabilities object returned with the JMAP Session 1861 object. 1863 If omitted, the default algorithm is server-dependent, but: 1865 1. It MUST be unicode-aware. 1867 2. It MAY be selected based on an Accept-Language header in 1868 the request (as defined in [RFC7231] section 5.3.5), or 1869 out-of-band information about the user's language/locale. 1871 3. It SHOULD be case-insensitive where such a concept makes 1872 sense for a language/locale. Where the user's language is 1873 unknown, it is RECOMMENDED to follow the advice in section 1874 5.2.3 of [RFC8264]. 1876 The "i;unicode-casemap" collation ([RFC5051]) and the Unicode 1877 Collation Algorithm () 1878 are two examples that fulfil these criterion and provide 1879 reasonable behaviour for a large number of languages. 1881 When the property being compared is not a string, the 1882 _collation_ property is ignored and the following comparison 1883 rules apply based on the type. In ascending order: 1885 + "Boolean": "false" comes before "true". 1887 + "Number": A lower number comes before a higher number. 1889 + "Date"/"UTCDate": The earlier date comes first. 1891 The Comparator object may also have additional properties as 1892 required for specific sort operations defined in a type's /query 1893 method. 1895 o *position*: "Int" (default: 0) The 0-based index of the first id 1896 in the full list of results to return. 1898 If a negative value is given, it is an offset from the end of the 1899 list. Specifically, the negative value MUST be added to the total 1900 number of results given the filter, and if still negative clamped 1901 to "0". This is now the 0-based index of the first id to return. 1903 If the index is greater than or equal to the total number of 1904 objects in the results list then the _ids_ array in the response 1905 will be empty, but this is not an error. 1907 o *anchor*: "Id|null" A Foo id. If supplied the _position_ argument 1908 is ignored. The index of this id in the results will be used in 1909 combination with the "anchorOffset" argument to determine the 1910 index of the first result to return (see below for more details). 1912 o *anchorOffset*: "Int" (default: 0) The index of the first result 1913 to return relative to the index of the anchor, if an anchor is 1914 given. This MAY be negative. For example, "-1" means the Foo 1915 immediately preceding the anchor is the first result in the list 1916 returned (see below for more details). 1918 o *limit*: "UnsignedInt|null" The maximum number of results to 1919 return. If "null", no limit presumed. The server MAY choose to 1920 enforce a maximum "limit" argument. In this case, if a greater 1921 value is given (or if it is "null"), the limit is clamped to the 1922 maximum; the new limit is returned with the response so the client 1923 is aware. If a negative value is given, the call MUST be rejected 1924 with an "invalidArguments" error. 1926 o *calculateTotal*: "Boolean" (default: false) Does the client wish 1927 to know the total number of results in the query? This may be 1928 slow and expensive for servers to calculate, particularly with 1929 complex filters, so clients should take care to only request the 1930 total when needed. 1932 If an *anchor* argument is given, then after filtering and sorting 1933 the anchor is looked for in the results. If found, the *anchor 1934 offset* is then added to its index. If the resulting index is now 1935 negative, it is clamped to 0. This index is now used exactly as 1936 though it were supplied as the "position" argument. If the anchor is 1937 not found, the call is rejected with an "anchorNotFound" error. 1939 If an _anchor_ is specified, any position argument supplied by the 1940 client MUST be ignored. If no _anchor_ is supplied, any anchor 1941 offset argument MUST be ignored. 1943 A client can use _anchor_ instead of _position_ to find the index of 1944 an id within a large set of results. 1946 The response has the following arguments: 1948 o *accountId*: "Id" The id of the account used for the call. 1950 o *queryState*: "String" A string encoding the current state of the 1951 query on the server. This string MUST change if the results of 1952 the query (i.e. the matching ids and their sort order) have 1953 changed. The queryState string MAY change if something has 1954 changed on the server which means the results may have changed but 1955 the server doesn't know for sure. 1957 The queryState string only represents the ordered list of ids that 1958 match the particular query (including its sort/filter). There is 1959 no requirement for it to change if a property on an object 1960 matching the query changes but the query results are unaffected 1961 (indeed, it is more efficient if the queryState string does not 1962 change in this case). The queryState string only has meaning when 1963 compared to future responses to a query with the same type/sort/ 1964 filter, or when used with /queryChanges to fetch changes. 1966 Should a client receive back a response with a different 1967 queryState string to a previous call it MUST either throw away the 1968 currently cached query and fetch it again (note, this does not 1969 require fetching the records again, just the list of ids) or call 1970 _Foo/queryChanges_ to get the difference. 1972 o *canCalculateChanges*: "Boolean" This is "true" if the server 1973 supports calling _Foo/queryChanges_ with these "filter"/"sort" 1974 parameters. Note, this does not guarantee that the _Foo/ 1975 queryChanges_ call will succeed, as it may only be possible for a 1976 limited time afterwards due to server internal implementation 1977 details. 1979 o *position*: "UnsignedInt" The 0-based index of the first result in 1980 the "ids" array within the complete list of query results. 1982 o *ids*: "Id[]" The list of ids for each foo in the query results, 1983 starting at the index given by the _position_ argument of this 1984 response, and continuing until it hits the end of the results or 1985 reaches the "limit" number of ids. If _position_ is >= _total_, 1986 this MUST be the empty list. 1988 o *total*: "UnsignedInt" (only if requested) The total number of 1989 foos in the results (given the _filter_). This argument MUST be 1990 omitted if the _calculateTotal_ request argument is not "true". 1992 o *limit*: "UnsignedInt" (if set by the server) The limit enforced 1993 by the server on the maximum number of results to return. This is 1994 only returned if the server set a limit, or used a different limit 1995 to that given in the request. 1997 The following additional errors may be returned instead of the _Foo/ 1998 query_ response: 2000 "anchorNotFound": An anchor argument was supplied, but it cannot be 2001 found in the results of the query. 2003 "unsupportedSort": The _sort_ is syntactically valid, but includes a 2004 property the server does not support sorting on, or a collation 2005 method it does not recognise. 2007 "unsupportedFilter": The _filter_ is syntactically valid, but the 2008 server cannot process it. If the filter was the result of a user's 2009 search input, the client SHOULD suggest the user simplify their 2010 search. 2012 5.6. /queryChanges 2014 The "Foo/queryChanges" method allows a client to efficiently update 2015 the state of a cached query to match the new state on the server. It 2016 takes the following arguments: 2018 o *accountId*: "Id" The id of the account to use. 2020 o *filter*: "FilterOperator|FilterCondition|null" The filter 2021 argument that was used with _Foo/query_. 2023 o *sort*: "Comparator[]|null" The sort argument that was used with 2024 _Foo/query_. 2026 o *sinceQueryState*: "String" The current state of the query in the 2027 client. This is the string that was returned as the _queryState_ 2028 argument in the _Foo/query_ response with the same sort/filter. 2029 The server will return the changes made to the query since this 2030 state. 2032 o *maxChanges*: "UnsignedInt|null" The maximum number of changes to 2033 return in the response. See error descriptions below for more 2034 details. 2036 o *upToId*: "Id|null" The last (highest-index) id the client 2037 currently has cached from the query results. When there are a 2038 large number of results, in a common case the client may have only 2039 downloaded and cached a small subset from the beginning of the 2040 results. If the sort and filter are both only on immutable 2041 properties, this allows the server to omit changes after this 2042 point in the results, which can significantly increase efficiency. 2043 If they are not immutable, this argument is ignored. 2045 o *calculateTotal*: "Boolean" (default: false) Does the client wish 2046 to know the total number of results now in the query? This may be 2047 slow and expensive for servers to calculate, particularly with 2048 complex filters, so clients should take care to only request the 2049 total when needed. 2051 The response has the following arguments: 2053 o *accountId*: "Id" The id of the account used for the call. 2055 o *oldQueryState*: "String" This is the "sinceQueryState" argument 2056 echoed back; the state from which the server is returning changes. 2058 o *newQueryState*: "String" This is the state the query will be in 2059 after applying the set of changes to the old state. 2061 o *total*: "UnsignedInt" (only if requested) The total number of 2062 foos in the results (given the _filter_). This argument MUST be 2063 omitted if the _calculateTotal_ request argument is not "true". 2065 o *removed*: "Id[]" The _id_ for every foo that was in the query 2066 results in the old state and is not in the results in the new 2067 state. 2069 If the server cannot calculate this exactly, the server MAY return 2070 extra foos in addition that may have been in the old results but 2071 are not in the new results. 2073 If the sort and filter are both only on immutable properties and 2074 an _upToId_ is supplied and exists in the results, any ids that 2075 were removed but have a higher index than _upToId_ SHOULD be 2076 omitted. 2078 If the _filter_ or _sort_ includes a mutable property, the server 2079 MUST include all foos in the current results for which this 2080 property may have changed. The position of these may have moved 2081 in the results so must be reinserted by the client to ensure its 2082 query cache is correct. 2084 o *added*: "AddedItem[]" The id and index in the query results (in 2085 the new state) for every foo that has been added to the results 2086 since the old state AND every foo in the current results that was 2087 included in the _removed_ array (due to a filter or sort based 2088 upon a mutable property). 2090 If the sort and filter are both only on immutable properties and 2091 an _upToId_ is supplied and exists in the results, any ids that 2092 were added but have a higher index than _upToId_ SHOULD be 2093 omitted. 2095 The array MUST be sorted in order of index, lowest index first. 2097 An *AddedItem* object has the following properties: 2099 * *id*: "Id" 2101 * *index*: "UnsignedInt" 2103 The result of this is that if the client has a cached sparse array of 2104 foo ids corresponding to the results in the old state: 2106 fooIds = [ "id1", "id2", null, null, "id3", "id4", null, null, null ] 2108 then if it *splices out* all ids in the removed array that it has in 2109 its cached results: 2111 removed = [ "id2", "id31", ... ]; 2112 fooIds => [ "id1", null, null, "id3", "id4", null, null, null ] 2114 and *splices in* (one-by-one in order, starting with the lowest 2115 index) all of the ids in the added array: 2117 added = [{ id: "id5", index: 0, ... }]; 2118 fooIds => [ "id5", "id1", null, null, "id3", "id4", null, null, null ] 2120 and *truncates* or *extends* to the new total length, then the 2121 results will now be in the new state. 2123 Note: splicing in adds the item at the given index, incrementing the 2124 index of all items previously at that or a higher index. Splicing 2125 out is the inverse, removing the item and decrementing the index of 2126 every item after it in the array. 2128 The following additional errors may be returned instead of the _Foo/ 2129 queryChanges_ response: 2131 "tooManyChanges": There are more changes than the client's 2132 _maxChanges_ argument. Each item in the removed or added array is 2133 considered as one change. The client may retry with a higher max 2134 changes or invalidate its cache of the query results. 2136 "cannotCalculateChanges": The server cannot calculate the changes 2137 from the queryState string given by the client. Usually due to the 2138 client's state being too old. The client MUST invalidate its cache 2139 of the query results. 2141 5.7. Examples 2143 Suppose we have a type _Todo_ with the following properties: 2145 o *id*: "Id" (immutable; server-set) The id of the object. 2147 o *title*: "String" A brief summary of what is to be done. 2149 o *keywords*: "String[Boolean]" (default: {}) A set of keywords that 2150 apply to the todo. The set is represented as an object, with the 2151 keys being the _keywords_. The value for each key in the object 2152 MUST be "true". (This format allows you to update an individual 2153 key using patch syntax rather than having to update the whole set 2154 of keywords as one, which an "String[]" representation would 2155 require.) 2157 o *neuralNetworkTimeEstimation*: "Number" (server-set) The title and 2158 keywords are fed into the server's state-of-the-art neural network 2159 to get an estimation of how long this todo will take, in seconds. 2161 o *subTodoIds*: "Id[]|null" The ids of a list of subtodos to 2162 complete as part of this todo. 2164 Suppose also that all the standard methods are defined for this type, 2165 and the FilterCondition object supports a "hasKeyword" property to 2166 match todos with the given keyword. 2168 A client might want to display the list of todos with either a 2169 "music" keyword or a "video" keyword, so it makes the following 2170 method call: 2172 [[ "Todo/query", { 2173 "accountId": "x", 2174 "filter": { 2175 "operator": "OR", 2176 "conditions": [ 2177 { "hasKeyword": "music" }, 2178 { "hasKeyword": "video" } 2179 ] 2180 }, 2181 "sort": [{ "property": "title" }], 2182 "position": 0, 2183 "limit": 10 2184 }, "0" ], 2185 [ "Todo/get", { 2186 "accountId": "x", 2187 "#ids": { 2188 "resultOf": "0", 2189 "name": "Todo/query", 2190 "path": "/ids" 2191 } 2192 }, "1" ]] 2194 This would query the server for the set of todos with a keyword of 2195 either "music" or "video", sorted by title, and limited to the first 2196 10 results. It fetches the full object for each of these Todos using 2197 back-references to reference the result of the query. The response 2198 might look something like: 2200 [[ "Todo/query", { 2201 "accountId": "x", 2202 "queryState": "y13213", 2203 "canCalculateChanges": true, 2204 "position": 0, 2205 "ids": [ "a", "b", "c", "d", "e", "f", "g", "h", "i", "j" ] 2206 }, "0" ], 2207 [ "Todo/get", { 2208 "accountId": "x", 2209 "state": "10324", 2210 "list": [{ 2211 "id": "a", 2212 "title": "Practise Piano", 2213 "keywords": { 2214 "music": true, 2215 "beethoven": true, 2216 "mozart": true, 2217 "liszt": true, 2218 "rachmaninov": true 2219 }, 2220 "neuralNetworkTimeEstimation": 3600 2221 }, { 2222 "id": "b", 2223 "title": "Watch Daft Punk music video", 2224 "keywords": { 2225 "music": true, 2226 "video": true, 2227 "trance": true 2228 }, 2229 "neuralNetworkTimeEstimation": 18000 2230 }, 2231 ... 2232 ] 2233 }, "1" ]] 2235 Now suppose the user adds a keyword "chopin" and removes the keyword 2236 "mozart" from the "Practise Piano" task. The client may send the 2237 whole object to the server, as this is a valid PatchObject: 2239 [[ "Todo/set", { 2240 "accountId": "x", 2241 "ifInState": "10324", 2242 "update": { 2243 "a": { 2244 "id": "a", 2245 "title": "Practise Piano", 2246 "keywords": { 2247 "music": true, 2248 "beethoven": true, 2249 "chopin": true, 2250 "liszt": true, 2251 "rachmaninov": true 2252 }, 2253 "neuralNetworkTimeEstimation": 360 2254 } 2255 } 2256 }, "0" ]] 2258 or it may send a minimal patch: 2260 [[ "Todo/set", { 2261 "accountId": "x", 2262 "ifInState": "10324", 2263 "update": { 2264 "a": { 2265 "keywords/chopin": true, 2266 "keywords/mozart": null 2267 } 2268 } 2269 }, "0" ]] 2271 The effect is exactly the same on the server in either case, and 2272 presuming the server is still in state "10324" it will probably 2273 return success: 2275 [[ "Todo/set", { 2276 "accountId": "x", 2277 "oldState": "10324", 2278 "newState": "10329", 2279 "updated": { 2280 "a": { 2281 "neuralNetworkTimeEstimation": 5400 2282 } 2283 } 2284 }, "0" ]] 2286 The server changed the "neuralNetworkTimeEstimation" property on the 2287 object as part of this change; as this changed in a way _not_ 2288 explicitly requested by the PatchObject sent to the server, it is 2289 returned with the "updated" confirmation. 2291 Let us now add a subtodo to our new "Practice Piano" todo. In this 2292 example we can see the use of a reference to a creation id to allow 2293 us to set a foreign key reference to a record created in the same 2294 request: 2296 [[ "Todo/set", { 2297 "accountId": "x", 2298 "create": { 2299 "k15": { 2300 "title": "Warm up with scales" 2301 } 2302 }, 2303 "update": { 2304 "a": { 2305 "subTodoIds": [ "#k15" ] 2306 } 2307 } 2308 }, "0" ]] 2310 Now, suppose another user deleted the "Listen to Daft Punk" todo. 2311 The first user will receive a push notification (see section 7) with 2312 the changed state string for the "Todo" type. Since the new string 2313 does not match its current state, it knows it needs to check for 2314 updates. It may make a request like: 2316 [[ "Todo/changes", { 2317 "accountId": "x", 2318 "sinceState": "10324", 2319 "maxChanges": 50 2320 }, "0" ], 2321 [ "Todo/queryChanges", { 2322 "accountId": "x", 2323 "filter": { 2324 "operator": "OR", 2325 "conditions": [ 2326 { "hasKeyword": "music" }, 2327 { "hasKeyword": "video" } 2328 ] 2329 }, 2330 "sort": [{ "property": "title" }], 2331 "sinceQueryState": "y13213", 2332 "maxChanges": 50 2333 }, "1" ]] 2335 and receive in response: 2337 [[ "Todo/changes", { 2338 "accountId": "x", 2339 "oldState": "10324", 2340 "newState": "871903", 2341 "hasMoreChanges": false, 2342 "created": [], 2343 "updated": [], 2344 "destroyed": ["b"] 2345 }, "0" ], 2346 [ "Todo/queryChanges", { 2347 "accountId": "x", 2348 "oldQueryState": "y13213", 2349 "newQueryState": "y13218", 2350 "removed": ["b"], 2351 "added": null 2352 }, "1" ]] 2354 Suppose the user has access to another account "y", for example a 2355 team account shared between multiple users. To move an existing Todo 2356 from account "x", the client would call: 2358 [[ "Todo/copy", { 2359 "fromAccountId": "x", 2360 "accountId": "y", 2361 "create": { 2362 "k5122": { 2363 "id": "a" 2364 } 2365 }, 2366 "onSuccessDestroyOriginal": true 2367 }, "0" ]] 2369 The server successfully copies the Todo to a new account (where it 2370 receives a new id) and deletes the original. Due to the implicit 2371 call to "Todo/set", there are two responses to the single method 2372 call, both with the same method call id: 2374 [[ "Todo/copy", { 2375 "fromAccountId": "x", 2376 "accountId": "y", 2377 "created": { 2378 "k5122": { 2379 "id": "DAf97" 2380 } 2381 }, 2382 "oldState": "c1d64ecb038c", 2383 "newState": "33844835152b" 2384 }, "0" ], 2385 [ "Todo/set", { 2386 "accountId": "x", 2387 "oldState": "871903", 2388 "newState": "871909", 2389 "destroyed": [ "a" ], 2390 ... 2391 }, "0" ]] 2393 5.8. Proxy considerations 2395 JMAP has been designed to allow an API endpoint to easily proxy 2396 through to one or more JMAP servers. This may be useful for load 2397 balancing, augmenting capabilities, or presenting a single endpoint 2398 to accounts hosted on different JMAP servers (splitting the request 2399 based on each method's "accountId" argument). The proxy need only 2400 understand the general structure of a JMAP Request object, it does 2401 not need to know anything specifically about the methods and 2402 arguments it will pass through to other servers. 2404 If splitting up the methods in a request to call them on different 2405 backend servers, the proxy must do two things to ensure back- 2406 references and creation id references resolve the same as if the 2407 entire request were processed on a single server: 2409 1. It must pass a "createdIds" property with each subrequest. If 2410 this is not given by the client, an empty object should be used 2411 for the first subrequest. The "createdIds" property of each 2412 subresponse should be passed on in the next subrequest. 2414 2. It must resolve back-references to previous method results that 2415 were processed on a different server. This is a relatively 2416 simple syntactic substitution, described in section 3.6. 2418 When splitting a request based on accountId, proxy implementors do 2419 need to be aware of "/copy" methods, that copy between accounts. If 2420 the accounts are on different servers, the proxy will have to 2421 implement this functionality directly. 2423 6. Binary data 2425 Binary data is referenced by a _blobId_ in JMAP, and uploaded/ 2426 downloaded separately to the core API. The blobId solely represents 2427 the raw bytes of data, not any associated metadata such as a file 2428 name or content type. Such metadata is stored alongside the blobId 2429 in the object referencing it. The data represented by a blobId is 2430 immutable. 2432 Any blobId that exists within an account may be used when creating/ 2433 updating another object in that account. For example, an Email type 2434 may have a blobId that represents the [RFC5322] representation of the 2435 message. A client could create a new Email object with an attachment 2436 and use this blobId, in effect attaching the old message to the new 2437 one. Similarly it could attach any existing attachment of an old 2438 message without having to download and upload it again. 2440 When the client uses a blobId in a create/update, the server MAY 2441 assign a new blobId to refer to the same binary data within the new/ 2442 updated object. If it does so, it MUST return any properties that 2443 contain a changed blobId in the created/updated response so the 2444 client gets the new ids. 2446 A blob that is not referenced by a JMAP object (e.g. as a message 2447 attachment) MAY be deleted by the server to free up resources. 2448 Uploads (see below) are initially unreferenced blobs. To ensure 2449 interoperability: 2451 o The server SHOULD use a separate quota for unreferenced blobs to 2452 the accounts's usual quota. This quota SHOULD be separate per 2453 user in the case of shared accounts. 2455 o This quota SHOULD be at least the maximum total size that a single 2456 object can reference on this server. For example, if supporting 2457 JMAP Mail, this should be at least the maximum total attachments 2458 size for a message. 2460 o When an upload would take the user over quota, the server MUST 2461 delete unreferenced blobs in date order, oldest first, until there 2462 is room for the new blob. 2464 o Except where quota restrictions force early deletion, an 2465 unreferenced blob MUST NOT be deleted for at least 1 hour from the 2466 time of upload; if reuploaded, the same blobId MAY be returned, 2467 but this SHOULD reset the expiry time. 2469 o A blob MUST NOT be deleted during the method call which removed 2470 the last reference, so that a client can issue a create and a 2471 destroy that both reference the blob within the same method call. 2473 6.1. Uploading binary data 2475 There is a single endpoint which handles all file uploads for an 2476 account, regardless of what they are to be used for. The JMAP 2477 Session object has an _uploadUrl_ property in [RFC6570] URI Template 2478 (level 1) format, which MUST contain a variable called "accountId". 2479 The client may use this template in combination with an _accountId_ 2480 to get the URL of the file upload resource. 2482 To upload a file, the client submits an authenticated POST request to 2483 the file upload resource. 2485 A successful request MUST return a single JSON object with the 2486 following properties as the response: 2488 o *accountId*: "Id" The id of the account used for the call. 2490 o *blobId*: "Id", The id representing the binary data uploaded. The 2491 data for this id is immutable. The id _only_ refers to the binary 2492 data, not any metadata. 2494 o *type*: "String" The media type of the file (as specified in 2495 [RFC6838], section 4.2) as set in the Content-Type header of the 2496 upload HTTP request. 2498 o *size*: "UnsignedInt" The size of the file in octets. 2500 If identical binary content to an existing blob in the account is 2501 uploaded, the existing blobId MAY be returned. 2503 Clients should use the blobId returned in a timely manner. Under 2504 rare circumstances the server may have deleted the blob before the 2505 client uses it; the client should keep a reference to the local file 2506 so it can upload it again in such a situation. 2508 When an HTTP error response is returned to the client, the server 2509 SHOULD return a JSON "problem details" object as the response body, 2510 as per [RFC7807]. 2512 As access controls are often determined by the object holding the 2513 reference to a blob, unreferenced blobs MUST only be accessible to 2514 the uploader, even in shared accounts. 2516 6.2. Downloading binary data 2518 The JMAP Session object has a _downloadUrl_ property, which is in 2519 [RFC6570] URI Template (level 1) format. The URL MUST contain 2520 variables called "accountId", "blobId", "type" and "name". 2522 To download a file, the client makes an authenticated GET request to 2523 the download URL with the appropriate variables substituted in: 2525 o "accountId": The id of the account to which the record with the 2526 blobId belongs. 2528 o "blobId": The blobId representing the data of the file to 2529 download. 2531 o "type": The type for the server to set in the "Content-Type" 2532 header of the response; the blobId only represents the binary data 2533 and does not have a content-type innately associated with it. 2535 o "name": The name for the file; the server MUST return this as the 2536 filename if it sets a "Content-Disposition" header. 2538 As the data for a particular blobId is immutable, and thus the 2539 response in the generated download URL is too, implementors are 2540 recommended to set long cache times and use the "immutable" Cache- 2541 Control extension ([RFC8246]) for a successful responses, for example 2542 "Cache-Control: private, immutable, max-age=31536000". 2544 When an HTTP error response is returned to the client, the server 2545 SHOULD return a JSON "problem details" object as the response body, 2546 as per [RFC7807]. 2548 6.3. Blob/copy 2550 Binary data may be copied *between* two different accounts using the 2551 _Blob/copy_ method, rather than having to download then re-upload on 2552 the client. 2554 The _Blob/copy_ method takes the following arguments: 2556 o *fromAccountId*: "Id" The id of the account to copy blobs from. 2558 o *accountId*: "Id" The id of the account to copy blobs to. 2560 o *blobIds*: "Id[]" A list of ids of blobs to copy to the other 2561 account. 2563 The response has the following arguments: 2565 o *fromAccountId*: "Id" The id of the account blobs were copied 2566 from. 2568 o *accountId*: "Id" The id of the account blobs were copied to. 2570 o *copied*: "Id[Id]|null" A map of the blobId in the _fromAccount_ 2571 to the id for the blob in the account it was copied to, or "null" 2572 if none were successfully copied. 2574 o *notCopied*: "Id[SetError]|null" A map of blobId to a SetError 2575 object for each blob that failed to be copied, "null" if none. 2577 The *SetError* may be any of the standard set errors that may be 2578 returned for a _create_, as defined in section 5.3. In addition, the 2579 "notFound" SetError error may be returned if the blobId to be copied 2580 cannot be found. 2582 The following additional method-level error may be returned instead 2583 of the _Blob/copy_ response: 2585 "fromAccountNotFound": The _fromAccountId_ included with the request 2586 does not correspond to a valid account. 2588 7. Push 2590 Push notifications allow clients to efficiently update (almost) 2591 instantly to stay in sync with data changes on the server. The 2592 general model for push is simple and sends minimal data over the push 2593 channel: just enough for the client to know whether it needs to 2594 resync. The format allows multiple changes to be coalesced into a 2595 single push update, and the frequency of pushes to be rate limited by 2596 the server. It doesn't matter if some push events are dropped before 2597 they reach the client; the next time it gets/sets any records of a 2598 changed type it will discover the data has changed and still sync all 2599 changes. 2601 There are two different mechanisms by which a client can receive push 2602 notifications, to allow for the different environments in which a 2603 client may exist. An event source resource (see section 7.3) allows 2604 clients that can hold transport connections open to receive push 2605 notifications directly from the JMAP server. This is simple and 2606 avoids 3rd parties, but is often not feasible on constrained 2607 platforms such as mobile devices. Alternatively, clients can make 2608 use of any push service supported by their environment. A URL for 2609 the push service is registered with the JMAP server (see section 2610 7.2), then the server then POSTs each notification to that URL. The 2611 push service is then responsible for routing these to the client. 2613 7.1. The StateChange object 2615 When something changes on the server, the server pushes a 2616 *StateChange* object to the client. A *StateChange* object has the 2617 following properties: 2619 o *@type*: "String" This MUST be the string "StateChange". 2621 o *changed*: "Id[TypeState]" A map of _account id_ to an object 2622 encoding the state of data types that have changed for that 2623 account since the last StateChange object was pushed, for each of 2624 the accounts to which the user has access and for which something 2625 has changed. 2627 A *TypeState* object is a map. The keys are the type name "Foo" 2628 (e.g. "Mailbox" or "Email"), and the value is the _state_ 2629 property that would currently be returned by a call to _Foo/get_. 2631 The client can compare the new state strings with its current 2632 values to see whether it has the current data for these types. If 2633 not, the changes can then be efficiently fetched in a single 2634 standard API request (using the _/changes_ type methods). 2636 7.1.1. Example 2638 In this example, the server has amalgamated a few changes together 2639 across two different accounts the user has access to, before pushing 2640 the following StateChange object to the client: 2642 { 2643 "@type": "StateChange", 2644 "changed": { 2645 "a3123": { 2646 "Email": "d35ecb040aab", 2647 "EmailDelivery": "428d565f2440", 2648 "CalendarEvent": "87accfac587a" 2649 }, 2650 "a43461d": { 2651 "Mailbox": "0af7a512ce70", 2652 "CalendarEvent": "7a4297cecd76" 2653 } 2654 } 2655 } 2657 The client can compare the state strings with its current state for 2658 the Email, CalendarEvent etc. object types in the appropriate 2659 accounts to see if it needs to fetch changes. 2661 If the client is itself making changes, it may receive a StateChange 2662 object while the /set API call is in flight. It can wait until the 2663 call completes and then compare if the new state string after the 2664 /set is the same as was pushed in the StateChange object; if so, and 2665 the old state of the /set response matches the client's previous 2666 state, it does not need to waste a request asking for changes it 2667 already knows. 2669 7.2. PushSubscription 2671 Clients may create a _PushSubscription_ to register a URL with the 2672 JMAP server. The JMAP server will then make an HTTP POST request to 2673 this URL for each push notification it wishes to send to the client. 2675 As a push subscription causes the JMAP server to make a number of 2676 requests to a previously unknown endpoint, it can be used as a vector 2677 for launching a denial of service attack. To prevent this, when a 2678 subscription is created the JMAP server immediately sends a 2679 PushVerification object to that URL (see section 7.2.2). The JMAP 2680 server MUST NOT make any further requests to the URL until the client 2681 receives the push and updates the subscription with the correct 2682 verification code. 2684 A *PushSubscription* object has the following properties: 2686 o *id*: "Id" (immutable; server-set) The id of the push 2687 subscription. 2689 o *deviceClientId*: "String" (immutable) An id that uniquely 2690 identifies the client + device it is running on. The purpose of 2691 this is to allow clients to identify which PushSubscription 2692 objects they created even if they lose their local state, so they 2693 can revoke or update them. This string MUST be different on 2694 different devices, and be different from apps from other vendors. 2695 It SHOULD be easy to re-generate, not depend on persisted state. 2696 It is RECOMMENDED to use a secure hash of a string that contains: 2698 1. A unique identifier associated with the device where the JMAP 2699 client is running, normally supplied by the device's operating 2700 system. 2702 2. A custom vendor/app id, including a domain controlled by the 2703 vendor of the JMAP client. 2705 To protect the privacy of the user, the deviceClientId id MUST NOT 2706 contain an unobfuscated device id. 2708 o *url*: "String" (immutable) An absolute URL where the JMAP server 2709 will POST the data for the push message. This MUST begin with 2710 "https://". 2712 o *keys*: "Object|null" (immutable) Client-generated encryption 2713 keys. If supplied the server MUST use them as specified in 2714 [RFC8291] to encrypt all data sent to the push subscription. The 2715 object MUST have the following properties: 2717 * *p256dh*: the P-256 ECDH Diffie-Hellman public key as described 2718 in [RFC8291], encoded in URL-safe Base64 representation as 2719 defined in [RFC4648]. 2721 * *auth*: the authentication secret as described in [RFC8291], 2722 encoded in URL-safe Base64 representation as defined in 2723 [RFC4648]. 2725 o *verificationCode*: "String|null" This MUST be "null" (or omitted) 2726 when the subscription is created. The JMAP server then generates 2727 a verification code and sends it in a push message, and the client 2728 updates the PushSubscription object with the code; see section 2729 7.2.2 for details. 2731 o *expires*: "UTCDate|null" The time this push subscription expires. 2732 If specified, the JMAP server MUST NOT make further requests to 2733 this resource after this time. It MAY automatically destroy the 2734 push subscription at or after this time. 2736 The server MAY choose to set an expiry if none is given by the 2737 client, or modify the expiry time given by the client to a shorter 2738 duration. 2740 o *types*: "String[]|null" A list of types the client is interested 2741 in (using the same names as the keys in the _TypeState_ object 2742 defined in the previous section). A StateChange notification will 2743 only be sent if the data for one of these types changes. Other 2744 types are omitted from the TypeState object. If "null", changes 2745 will be pushed for all types. 2747 The POST request MUST have a content type of "application/json" and 2748 contain the UTF-8 JSON encoded object as the body. The request MUST 2749 have a "TTL" header, and MAY have "Urgency" and/or "Topic" headers, 2750 as specified in section 5 of [RFC8030]. The JMAP server is expected 2751 to understand and handle HTTP status responses in a reasonable 2752 manner. A "429" (Too Many Requests) response MUST cause the JMAP 2753 server to reduce the frequency of pushes; the JMAP push structure 2754 allows multiple changes to be coalesced into a single minimal 2755 StateChange object. See the security considerations in section 8.6 2756 for a discussion of the risks in connecting to unknown servers. 2758 The JMAP server acts as an Application Server as defined in 2759 [RFC8030]. A client MAY use the rest of [RFC8030] in combination 2760 with its own Push Service to form a complete end-to-end solution, or 2761 MAY rely on alternative mechanisms to ensure the delivery of the 2762 pushed data after it leaves the JMAP server. 2764 The push subscription is tied to the credentials used to authenticate 2765 the API request that created it. Should these credentials expire or 2766 be revoked, the push subscription MUST be destroyed by the JMAP 2767 server. Only subscriptions created by these credentials are returned 2768 when the client fetches existing subscriptions. 2770 When these credentials have their own expiry (i.e. it is a session 2771 with a timeout), the server SHOULD NOT set or bound the expiry time 2772 for the push subscription given by the client, but MUST expire it 2773 when the session expires. 2775 When these credentials are not time bounded (e.g. [RFC7617] Basic 2776 Authentication), the server SHOULD set an expiry time for the push 2777 subscription if none given, and limit the expiry time if set too far 2778 in the future. This maximum expiry time MUST be at least 48 hours in 2779 the future and SHOULD be at least 7 days in the future. An app 2780 running on a mobile device may only be able to refresh the push 2781 subscription lifetime when it is in the foreground, and so this gives 2782 a reasonable timeframe to allow this to happen. 2784 In the case of separate access and refresh credentials, as in 2785 [RFC6749] Oauth 2.0, the server SHOULD tie the push subscription to 2786 the validity of the refresh token rather than the access token, and 2787 behave according to whether this is time-limited or not. 2789 When a push subscription is destroyed, the server MUST securely erase 2790 the URL and encryption keys from memory and storage as soon as 2791 possible. 2793 7.2.1. PushSubscription/get 2795 Standard _/get_ method as described in section 5.1, except it does 2796 *not* take or return an _accountId_ argument, as push subscriptions 2797 are not tied to specific accounts. It also does *not* return a 2798 _state_ argument. The _ids_ argument may be "null" to fetch all at 2799 once. 2801 The server MUST only return push subscriptions that were created 2802 using the same authentication credentials as for this 2803 PushSubscription/get request. 2805 As the _url_ and _keys_ properties may contain data that is private 2806 to a particular device, the values for these properties MUST NOT be 2807 returned. If the _properties_ argument is "null" or omitted, the 2808 server MUST default to all properties excluding these two. If one of 2809 them is explicitly requested, the method call MUST be rejected with a 2810 "forbidden" error. 2812 7.2.2. PushSubscription/set 2814 Standard _/set_ method as described in section 5.3, except it does 2815 *not* take or return an _accountId_ argument, as push subscriptions 2816 are not tied to specific accounts. It also does *not* take an 2817 _ifInState_ argument or return _oldState_ or _newState_ arguments. 2819 The _url_ and _keys_ properties are immutable; if the client wishes 2820 to change these, it must destroy the current push subscription and 2821 create a new one. 2823 When a PushSubscription is created, the server MUST immediately push 2824 a *PushVerification* object to the URL. It has the following 2825 properties: 2827 o *@type*: "String" This MUST be the string "PushVerification". 2829 o *pushSubscriptionId*: "String" The id of the push subscription 2830 that was created. 2832 o *verificationCode*: "String" The verification code to add to the 2833 push subscription. This MUST contain sufficient entropy to avoid 2834 the client being able to brute force guess the code. 2836 The client MUST update the push subscription with the correct 2837 verification code before the server makes any further requests to the 2838 subscription's URL. Attempts to update the subscription with an 2839 invalid verification code MUST be rejected by the server with an 2840 "invalidProperties" SetError. 2842 The client may update the _expires_ property to extend (or, less 2843 commonly, shorten) the lifetime of a push subscription. The server 2844 MAY modify the proposed new expiry time to enforce server-defined 2845 limits. Extending the lifetime does not require the subscription to 2846 be verified again. 2848 Clients SHOULD NOT update or destroy a push subscription that they 2849 did not create (i.e. has a _deviceClientId_ that they do not 2850 recognise). 2852 7.2.3. Example 2854 At "2018-07-06T02:14:29Z", a client with deviceClientId "a889-ffea- 2855 910" fetches the set of push subscriptions currently on the server, 2856 making an API request with: 2858 [[ "PushSubscription/get", { 2859 "ids": null 2860 }, "0" ]] 2862 Which returns: 2864 [[ "PushSubscription/get", { 2865 "list": [{ 2866 "id": "e50b2c1d-9553-41a3-b0a7-a7d26b599ee1", 2867 "deviceClientId": "b37ff8001ca0", 2868 "verificationCode": "b210ef734fe5f439c1ca386421359f7b", 2869 "expires": "2018-07-31T00:13:21Z", 2870 "types": [ "Todo" ] 2871 }, { 2872 "id": "f2d0aab5-e976-4e8b-ad4b-b380a5b987e4", 2873 "deviceClientId": "X8980fc", 2874 "verificationCode": "f3d4618a9ae15c8b7f5582533786d531", 2875 "expires": "2018-07-12T05:55:00Z", 2876 "types": [ "Mailbox", "Email", "EmailDelivery" ] 2877 }], 2878 "notFound": [] 2879 }, "0" ]] 2881 Since neither of the returned push subscription objects have the 2882 client's deviceClientId, it knows it does not have a current push 2883 subscription active on the server. So it creates one, sending this 2884 request: 2886 [[ "PushSubscription/set", { 2887 "create": { 2888 "4f29": { 2889 "deviceClientId": "a889-ffea-910", 2890 "url": "https://example.com/push/?device=X8980fc&client=12c6d086", 2891 "types": null 2892 } 2893 } 2894 }, "0" ]] 2895 The server creates the push subscription but limits the expiry time 2896 to 7 days in the future, returning this response: 2898 [[ "PushSubscription/set", { 2899 "created": { 2900 "4f29": { 2901 "id": "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60", 2902 "keys": null, 2903 "expires": "2018-07-13T02:14:29Z" 2904 } 2905 } 2906 }, "0" ]] 2908 The server also immediately makes a POST request to 2909 "https://example.com/push/?device=X8980fc&client=12c6d086" with the 2910 data: 2912 { 2913 "@type": "PushVerification", 2914 "pushSubscriptionId": "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60", 2915 "verificationCode": "da1f097b11ca17f06424e30bf02bfa67" 2916 } 2918 The client receives this and updates the subscription with the 2919 verification code (note there is a potential race condition here; the 2920 client MUST be able to handle receiving the push while the request 2921 creating the subscription is still in progress): 2923 [[ "PushSubscription/set", { 2924 "update": { 2925 "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": { 2926 "verificationCode": "da1f097b11ca17f06424e30bf02bfa67" 2927 } 2928 } 2929 }, "0" ]] 2931 The server confirms the update was successful and will now make 2932 requests to the registered URL when the state changes. 2934 Two days later, the client updates the subscription to extend its 2935 lifetime, sending this request: 2937 [[ "PushSubscription/set", { 2938 "update": { 2939 "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": { 2940 "expires": "2018-08-13T00:00:00Z" 2941 } 2942 } 2943 }, "0" ]] 2945 The server extends the expiry time, but only again to its maximum 2946 limit of 7 days in the future, returning this response: 2948 [[ "PushSubscription/set", { 2949 "updated": { 2950 "P43dcfa4-1dd4-41ef-9156-2c89b3b19c60": { 2951 "expires": "2018-07-15T02:22:50Z" 2952 } 2953 } 2954 }, "0" ]] 2956 7.3. Event Source 2958 Clients that can hold transport connections open can connect directly 2959 to the JMAP server to receive push notifications via a "text/event- 2960 stream" resource, as described in [EventSource]. This is a long 2961 running HTTP request down which the server can push data. 2963 When a change occurs in the data on the server, it pushes an event 2964 called "state" to any connected clients, with the _StateChange_ 2965 object as the data. 2967 The server SHOULD also send a new event id that encodes the entire 2968 server state visible to the user immediately after sending a _state_ 2969 event. When a new connection is made to the event-source endpoint, a 2970 client following the server-sent events specification will send a 2971 Last-Event-ID HTTP header field with the last id it saw, which the 2972 server can use to work out whether the client has missed some 2973 changes. If so, it SHOULD send these changes immediately on 2974 connection. 2976 The JMAP Session object has an _eventSourceUrl_ property, which is in 2977 [RFC6570] URI Template (level 1) format. The URL MUST contain 2978 variables called "types", "closeafter" and "ping". 2980 To connect to the resource, the client makes an authenticated GET 2981 request to the event-source URL with the appropriate variables 2982 substituted in: 2984 o "types": This MUST be either: 2986 * A comma-separated list of type names, e.g. 2987 "Email,CalendarEvent". The server MUST only push changes for 2988 the types in this list. 2990 * The single character: "*". Changes to all types are pushed. 2992 o "closeafter": This MUST be one of the following values: 2994 * "state": The server MUST end the HTTP response after pushing a 2995 state event. This can be used by clients in environments where 2996 buffering proxies prevent the pushed data from arriving 2997 immediately, or indeed at all, when operating in the usual 2998 mode. 3000 * "no": The connection is persisted by the server as a standard 3001 event-source resource. 3003 o "ping": A positive integer value representing a length of time in 3004 seconds, e.g. "300". If non-zero, the server MUST send an event 3005 called "ping" whenever this time elapses since the previous event 3006 was sent. This MUST NOT set a new event id. If the value is "0" 3007 the server MUST NOT send ping events. 3009 The server MAY modify a requested ping interval to be subject to a 3010 minimum and/or maximum value. For interoperability, servers MUST 3011 NOT have a minimum allowed value higher than 30 or a maximum 3012 allowed value less than 300. 3014 The data for the ping event MUST be a JSON object containing an 3015 _interval_ property, the value (type "UnsignedInt") being the 3016 interval in seconds the server is using to send pings (this may be 3017 different to the requested value if the server clamped it to be 3018 within a min/max value). 3020 Clients can monitor for the ping event to help determine when the 3021 closeafter mode may be required. 3023 A client MAY hold open multiple connections to the event-source 3024 resource, although it SHOULD try to use a single connection for 3025 efficiency. 3027 8. Security considerations 3029 8.1. Transport confidentiality 3031 To ensure the confidentiality and integrity of data sent and received 3032 via JMAP, all requests MUST use TLS 1.2 ([RFC5246]) or later, 3033 following the recommendations in [RFC7525]. Servers SHOULD support 3034 TLS 1.3 ([RFC8446]) or later. 3036 Clients MUST validate TLS certificate chains to protect against man- 3037 in-the-middle attacks. 3039 8.2. Authentication scheme 3041 A number of HTTP authentication schemes have been standardised 3042 (). Servers should take care to assess the security 3044 characteristics of different schemes in relation to their needs when 3045 deciding what to implement. 3047 Use of the Basic authentication scheme is NOT RECOMMENDED. Services 3048 that choose to use it are strongly recommended to require generation 3049 of a unique "app password" via some external mechanism for each 3050 client they wish to connect. This allows connections from different 3051 devices to be differentiated by the server, and access to be 3052 individually revoked. 3054 8.3. Service autodiscovery 3056 Unless secured by something like DNSSEC, DNS SRV-based autodiscovery 3057 of server details is vulnerable to a DNS poisoning attack leading to 3058 the client talking to an attacker's server instead of the real JMAP 3059 server. The attacker may then man-in-the-middle requests and 3060 depending on the authentication scheme, steal credentials to generate 3061 its own requests. 3063 Clients that do not support SRV lookups are likely to try just using 3064 the "/.well-known/jmap" path directly against the domain of the 3065 username over HTTPS. Servers SHOULD ensure this path resolves or 3066 redirects to the correct JMAP Session resource to allow this to work. 3067 If this is not feasible, servers MUST ensure this path cannot be 3068 controlled by an attacker, as again it may be used to steal 3069 credentials. 3071 8.4. JSON parsing 3073 The security considerations of [RFC8259] apply to the use of JSON as 3074 the data interchange format. 3076 As for any serialization format, parsers need to thoroughly check the 3077 syntax of the supplied data. JSON uses opening and closing tags for 3078 several types and structures, and it is possible that the end of 3079 supplied data will be reached when scanning for a matching closing 3080 tag; this is an error condition and implementations need to stop 3081 scanning at the end of the supplied data. 3083 JSON also uses a string encoding with some escape sequences to encode 3084 special characters within a string. Care is needed when processing 3085 these escape sequences to ensure that an escape sequence is fully 3086 formed before the special processing is triggered, with special care 3087 taken when the escape sequences appear adjacent to other (non- 3088 escaped) special characters or the end of data (as in the previous 3089 paragraph). 3091 If parsing JSON into a non-textual structured data format, 3092 implementations may need to allocate storage to hold JSON string 3093 elements. Since JSON does not use explicit string lengths, the risk 3094 of denial of service due to resource exhaustion is small, but 3095 implementations may still wish to place limits on the size of 3096 allocations they are willing to make in any given context, to avoid 3097 untrusted data causing excessive memory allocation. 3099 8.5. Denial of service 3101 A small request may result in a very large response, and require 3102 considerable work on the server if resource limits are not enforced. 3103 JMAP provides mechanisms for advertising and enforcing a wide variety 3104 of limits for mitigating this threat, including limits on number of 3105 objects fetched in a single method call, number of methods in a 3106 single request, number of concurrent requests, etc. 3108 JMAP servers MUST implement sensible limits to mitigate against 3109 resource exhaustion attacks. 3111 8.6. Connection to unknown push server 3113 When a push subscription is registered, the application server will 3114 make POST requests to the given URL. There are a number of security 3115 considerations that MUST be considered when implementing this. 3117 The server MUST ensure the URL is externally resolvable to avoid 3118 server-side request forgery, where the server makes a request to a 3119 resource on its internal network. 3121 A malicious client may use the push subscription to attempt to flood 3122 a 3rd party server with requests, creating a denial of service attack 3123 and masking the attacker's true identity. There is no guarantee the 3124 URL that was given to the JMAP server is actually a valid push 3125 server. Upon creation of a push subscription the JMAP server sends a 3126 PushVerification object to the URL and MUST NOT send any further 3127 requests until the client verifies it has received the initial push. 3129 The verification code MUST contain sufficient entropy to prevent the 3130 client from being able to verify the subscription via brute force. 3132 The verification code does not guarantee the URL is a valid push 3133 server, only that the client is able to access the data submitted to 3134 it. While the verification step significantly reduces the set of 3135 potential targets, there is still a risk that the server is unrelated 3136 to the client and being targeted for a denial of service attack. 3138 The server MUST limit the number of push subscriptions any one user 3139 may have to ensure the user cannot cause the server to send a large 3140 number of push notifications at once, which could again be used as 3141 part of a denial-of-service attack. The rate of creation MUST also 3142 be limited to minimise the ability to abuse the verification request 3143 as an attack vector. 3145 8.7. Push encryption 3147 When data changes, a small object is pushed with the new state 3148 strings for the types that have changed. While the data here is 3149 minimal, a passive man-in-the-middle attacker may be able to gain 3150 useful information. To ensure confidentiality and integrity, if the 3151 push is sent via a third party outside of the control of the client 3152 and JMAP server the client MUST specify encryption keys when 3153 establishing the PushSubscription and ignore any push notification 3154 received that is not encrypted with those keys. 3156 The privacy and security considerations of [RFC8030] and [RFC8291] 3157 also all apply to the use of the PushSubscription mechanism. 3159 As there is no crypto algorithm agility in [RFC8291] Web Push 3160 Encryption, if new algorithms are required in the future a new 3161 specification will be needed to provide this. 3163 8.8. Traffic analysis 3165 While the data is encrypted, a passive observer with the ability to 3166 monitor network traffic may be able to glean information from the 3167 timing of API requests and push notifications. For example, suppose 3168 an email or calendar invitation is sent from User A (hosted on Server 3169 X) to User B (hosted on Server Y). If Server X hosts data for many 3170 users, a passive observer can see that the two servers connected but 3171 does not know who the data was for. However, if a push notification 3172 is immediately sent to User B and the attacker can observe this as 3173 well, they may reasonably conclude that someone on Server X is 3174 connecting to User B. 3176 9. IANA considerations 3178 9.1. Assignment of jmap service name 3180 IANA will assign the 'jmap' service name in the 'Service Name and 3181 Transport Protocol Port Number Registry' [RFC6335]. 3183 Service Name: jmap 3185 Transport Protocol(s): tcp 3187 Assignee: IESG 3189 Contact: IETF Chair 3191 Description: JSON Meta Application Protocol 3193 Reference: [I-D.ietf-jmap-core] 3195 Assignment Notes: this service name was previously assigned under the 3196 name _JSON Mail Access Protocol_. This will be de-assigned and re- 3197 assigned with the approval of the previous assignee. 3199 9.2. Registration of well-known URI suffix for JMAP 3201 IANA will register the following well-known URI suffix for JMAP as 3202 described in [RFC5785]: 3204 URI Suffix: jmap 3206 Change Controller: IETF 3208 Specification Document: [I-D.ietf-jmap-core], section 2.2. 3210 9.3. Registration of the jmap URN sub-namespace 3212 IANA will register the following URN sub-namespace in the "IETF URN 3213 Sub-namespace for Registered Protocol Parameter Identifiers" registry 3214 as described in [RFC3553]. 3216 Registered Parameter Identifier: jmap 3218 Reference: [I-D.ietf-jmap-core], next section 3220 IANA Registry Reference: {insert IANA registry URL for registry in 3221 next section, upon approval} 3223 9.4. Creation of "JMAP Capabilities" registry 3225 IANA will create a registry for JMAP capabilities as described in 3226 section 2. JMAP capabilities are advertised in the _capabilities_ 3227 property of the JMAP Session resource. They are used to extend the 3228 functionality of a JMAP server. A capability is referenced by a URI. 3229 The JMAP capability URI can be a URN starting with 3230 "urn:ietf:params:jmap:" plus a unique suffix which is the index value 3231 in the jmap URN sub-namespace. Registration of a JMAP capability 3232 with another form of URI has no impact on the jmap URN sub-namespace. 3234 This registry follows the expert review process unless the "intended 3235 use" field is _common_ or _placeholder_ in which case registration 3236 follows the specification required process. 3238 A JMAP capability registration can have an intended use of _common_, 3239 _placeholder_, _limited_, or _obsolete_. IANA will list common use 3240 registrations prominently and separately from those with other 3241 intended use values. 3243 The JMAP capability registration procedure is not a formal standards 3244 process, but rather an administrative procedure intended to allow 3245 community comment and sanity checking without excessive time delay. 3247 A _placeholder_ registration reserves part of the jmap urn namespace 3248 for another purpose but is typically not included in the 3249 _capabilities_ property of the JMAP Session resource. 3251 9.4.1. Preliminary community review 3253 Notice of a potential JMAP common use registration SHOULD be sent to 3254 the jmap@ietf.org mailing list for review. This mailing list is 3255 appropriate to solicit community feedback on a proposed JMAP 3256 capability. Registrations that are not intended for common use MAY 3257 be sent to the list for review as well; doing so is entirely 3258 OPTIONAL, but is encouraged. 3260 The intent of the public posting to this list is to solicit comments 3261 and feedback on the choice of capability name, the unambiguity of the 3262 specification document, and a review of any interoperability or 3263 security considerations. The submitter may submit a revised 3264 registration proposal or abandon the registration completely and at 3265 any time. 3267 9.4.2. Submit request to IANA 3269 Registration requests can be sent to iana@iana.org. 3271 9.4.3. Designated expert review 3273 For a limited use registration, the designated expert's (DE) primary 3274 concern is preventing name collisions and encouraging the submitter 3275 to document security and privacy considerations; a published 3276 specification is not required. For a common use registration, the DE 3277 is expected to confirm that suitable documentation as described in 3278 [RFC8126], section 4.6, is available. The DE should also verify the 3279 capability does not conflict with work that is active or already 3280 published within the IETF. 3282 Before a period of 30 days has passed, the DE will either approve or 3283 deny the registration request and publish a notice of the decision to 3284 the JMAP WG mailing list or its successor, as well as informing IANA. 3285 A denial notice must be justified by an explanation, and in the cases 3286 where it is possible, concrete suggestions on how the request can be 3287 modified so as to become acceptable should be provided. 3289 If the DE does not respond within 30 days, the registrant may request 3290 the IESG take action to process the request in a timely manner. 3292 9.4.4. Change procedures 3294 Once a JMAP capability has been published by the IANA, the change 3295 controller may request a change to its definition. The same 3296 procedure that would be appropriate for the original registration 3297 request is used to process a change request. 3299 JMAP capability registrations may not be deleted; capabilities that 3300 are no longer believed appropriate for use can be declared obsolete 3301 by a change to their "intended use" field; such capabilities will be 3302 clearly marked in the lists published by the IANA. 3304 Significant changes to a capability's definition should be requested 3305 only when there are serious omissions or errors in the published 3306 specification. When review is required, a change request may be 3307 denied if it renders entities that were valid under the previous 3308 definition invalid under the new definition. 3310 The owner of a JMAP capability may pass responsibility to another 3311 person or agency by informing the IANA; this can be done without 3312 discussion or review. 3314 The IESG may reassign responsibility for a JMAP capability. The most 3315 common case of this will be to enable changes to be made to 3316 capabilities where the author of the registration has died, moved out 3317 of contact, or is otherwise unable to make changes that are important 3318 to the community. 3320 9.4.5. JMAP Capabilities registry template: 3322 Capability name: (see capability property in section 2) 3324 Specification document: 3326 Intended use: (one of common, limited, placeholder, or obsolete) 3328 Change controller: (_IETF_ for standards-track/BCP RFCs) 3330 Security and privacy considerations: 3332 9.4.6. Initial registration for JMAP core 3334 Capability Name: "urn:ietf:params:jmap:core" 3336 Specification document: [I-D.ietf-jmap-core], section 2 3338 Intended use: common 3340 Change Controller: IETF 3342 Security and privacy considerations: [I-D.ietf-jmap-core], section 8. 3344 9.4.7. Registration for JMAP error placeholder in JMAP capabilities 3345 registry 3347 Capability Name: "urn:ietf:params:jmap:error:" 3349 Specification document: [I-D.ietf-jmap-core], section 9.5 3351 Intended use: placeholder 3353 Change Controller: IETF 3355 Security and privacy considerations: [I-D.ietf-jmap-core], section 8. 3357 9.5. Creation of "JMAP Error Codes" registry 3359 IANA will create a registry for JMAP error codes. JMAP error codes 3360 appear in the "type" member of a JSON problem details object (as 3361 described in section 3.5.1), in the "type" member in a JMAP error 3362 object (as described in section 3.5.2), or the "type" member of a 3363 JMAP method-specific error object (such as SetError in section 5.3). 3364 When used in a problem details object, the prefix 3365 'urn:ietf:params:jmap:error:' is always included, and when used in 3366 JMAP objects, the prefix is always omitted. 3368 This registry follows the expert review process. Preliminary 3369 community review for this registry follows the same procedures as the 3370 JMAP capabilities registry but is optional. The change procedures 3371 for this registry are the same as the change procedures for the JMAP 3372 capabilities registry. 3374 9.5.1. Designated expert review 3376 The designated expert should review the following aspects of the 3377 registration: 3379 1. Verify the error code does not conflict with existing names. 3381 2. Verify the error code follows the syntax limitations (does not 3382 require URI encoding). 3384 3. Encourage the error code to follow the naming convention of 3385 previously registered errors. 3387 4. Encourage description of client behaviors that are recommended in 3388 response to the error code. These may distinguish the error code 3389 from other error codes. 3391 5. Encourage description of when the server should issue the error 3392 as opposed to some other error code. 3394 6. Encourage the submitter to note any security considerations 3395 associated with the error, if any. For example, an error code 3396 that might disclose existence of data the authenticated user does 3397 not have permission to know about. 3399 Steps 3-6 are meant to promote a higher-quality registry. However, 3400 the expert is encouraged to approve any registration that would not 3401 actively harm JMAP interoperability to make this a relatively 3402 lightweight process. 3404 9.5.2. JMAP Error Codes registry template: 3406 JMAP Error Code: 3408 Intended use: (one of _common_, _limited_, _obsolete_) 3409 Change Controller: (_IETF_ for standards-track/BCP RFCs) 3411 Reference: (optional, only if defined in an RFC.) 3413 Description: 3415 9.5.3. Initial JMAP Error Codes registry 3417 +--------------------+-------+---------+---------------+------------+ 3418 | JMAP Error Code | Inten | Change | Reference | Descriptio | 3419 | | ded | Control | | n | 3420 | | Use | ler | | | 3421 +--------------------+-------+---------+---------------+------------+ 3422 | accountNotFound | commo | IETF | [I-D.ietf-jma | The | 3423 | | n | | p-core] | accountId | 3424 | | | | section 3.5.2 | does not | 3425 | | | | | correspond | 3426 | | | | | to a valid | 3427 | | | | | account. | 3428 | accountNotSupporte | commo | IETF | [I-D.ietf-jma | The | 3429 | dByMethod | n | | p-core] | accountId | 3430 | | | | section 3.5.2 | given corr | 3431 | | | | | esponds to | 3432 | | | | | a valid | 3433 | | | | | account, | 3434 | | | | | but the | 3435 | | | | | account | 3436 | | | | | does not | 3437 | | | | | support | 3438 | | | | | this | 3439 | | | | | method or | 3440 | | | | | data type. | 3441 | accountReadOnly | commo | IETF | [I-D.ietf-jma | This | 3442 | | n | | p-core] | method | 3443 | | | | section 3.5.2 | call would | 3444 | | | | | modify | 3445 | | | | | state in | 3446 | | | | | an account | 3447 | | | | | that is | 3448 | | | | | read-only | 3449 | | | | | (as | 3450 | | | | | returned | 3451 | | | | | on the cor | 3452 | | | | | responding | 3453 | | | | | Account | 3454 | | | | | object in | 3455 | | | | | the JMAP | 3456 | | | | | Session | 3457 | | | | | resource). | 3458 | anchorNotFound | commo | IETF | [I-D.ietf-jma | An anchor | 3459 | | n | | p-core] | argument | 3460 | | | | section 5.5 | was | 3461 | | | | | supplied, | 3462 | | | | | but it | 3463 | | | | | cannot be | 3464 | | | | | found in | 3465 | | | | | the | 3466 | | | | | results of | 3467 | | | | | the query. | 3468 | alreadyExists | commo | IETF | [I-D.ietf-jma | The server | 3469 | | n | | p-core] | forbids | 3470 | | | | section 5.4 | duplicates | 3471 | | | | | and the | 3472 | | | | | record | 3473 | | | | | already | 3474 | | | | | exists in | 3475 | | | | | the target | 3476 | | | | | account. | 3477 | | | | | An | 3478 | | | | | existingId | 3479 | | | | | property | 3480 | | | | | of type Id | 3481 | | | | | MUST be | 3482 | | | | | included | 3483 | | | | | on the | 3484 | | | | | error | 3485 | | | | | object | 3486 | | | | | with the | 3487 | | | | | id of the | 3488 | | | | | existing | 3489 | | | | | record. | 3490 | cannotCalculateCha | commo | IETF | [I-D.ietf-jma | The server | 3491 | nges | n | | p-core] | cannot | 3492 | | | | sections 5.2 | calculate | 3493 | | | | and 5.6 | the | 3494 | | | | | changes | 3495 | | | | | from the | 3496 | | | | | state | 3497 | | | | | string | 3498 | | | | | given by | 3499 | | | | | the | 3500 | | | | | client. | 3501 | forbidden | commo | IETF | [I-D.ietf-jma | The action | 3502 | | n | | p-core] | would | 3503 | | | | sections | violate an | 3504 | | | | 3.5.2, 5.3, | ACL or | 3505 | | | | and 7.2.1 | other perm | 3506 | | | | | issions | 3507 | | | | | policy. | 3508 | fromAccountNotFoun | commo | IETF | [I-D.ietf-jma | The fromAc | 3509 | d | n | | p-core] | countId | 3510 | | | | sections 5.4 | does not | 3511 | | | | and 6.3 | correspond | 3512 | | | | | to a valid | 3513 | | | | | account. | 3514 | fromAccountNotSupp | commo | IETF | [I-D.ietf-jma | The fromAc | 3515 | ortedByMethod | n | | p-core] | countId | 3516 | | | | section 5.4 | given corr | 3517 | | | | | esponds to | 3518 | | | | | a valid | 3519 | | | | | account, | 3520 | | | | | but the | 3521 | | | | | account | 3522 | | | | | does not | 3523 | | | | | support | 3524 | | | | | this data | 3525 | | | | | type. | 3526 | invalidArguments | commo | IETF | [I-D.ietf-jma | One of the | 3527 | | n | | p-core] | arguments | 3528 | | | | section 3.5.2 | is of the | 3529 | | | | | wrong type | 3530 | | | | | or | 3531 | | | | | otherwise | 3532 | | | | | invalid, | 3533 | | | | | or a | 3534 | | | | | required | 3535 | | | | | argument | 3536 | | | | | is | 3537 | | | | | missing. | 3538 | invalidPatch | commo | IETF | [I-D.ietf-jma | The PatchO | 3539 | | n | | p-core] | bject | 3540 | | | | section 5.3 | given to | 3541 | | | | | update the | 3542 | | | | | record was | 3543 | | | | | not a | 3544 | | | | | valid | 3545 | | | | | patch. | 3546 | invalidProperties | commo | IETF | [I-D.ietf-jma | The record | 3547 | | n | | p-core] | given is | 3548 | | | | section 5.3 | invalid. | 3549 | notFound | commo | IETF | [I-D.ietf-jma | The id | 3550 | | n | | p-core] | given | 3551 | | | | section 5.3 | cannot be | 3552 | | | | | found. | 3553 | notJSON | commo | IETF | [I-D.ietf-jma | The | 3554 | | n | | p-core] | content | 3555 | | | | section 3.5.1 | type of | 3556 | | | | | the | 3557 | | | | | request | 3558 | | | | | was not ap | 3559 | | | | | plication/ | 3560 | | | | | json or | 3561 | | | | | the | 3562 | | | | | request | 3563 | | | | | did not | 3564 | | | | | parse as | 3565 | | | | | I-JSON. | 3566 | notRequest | commo | IETF | [I-D.ietf-jma | The | 3567 | | n | | p-core] | request | 3568 | | | | section 3.5.1 | parsed as | 3569 | | | | | JSON but | 3570 | | | | | did not | 3571 | | | | | match the | 3572 | | | | | type | 3573 | | | | | signature | 3574 | | | | | of the | 3575 | | | | | Request | 3576 | | | | | object. | 3577 | overQuota | commo | IETF | [I-D.ietf-jma | The create | 3578 | | n | | p-core] | would | 3579 | | | | section 5.3 | exceed a | 3580 | | | | | server- | 3581 | | | | | defined | 3582 | | | | | limit on | 3583 | | | | | the number | 3584 | | | | | or total | 3585 | | | | | size of | 3586 | | | | | objects of | 3587 | | | | | this type. | 3588 | rateLimit | commo | IETF | [I-D.ietf-jma | Too many | 3589 | | n | | p-core] | objects of | 3590 | | | | section 5.3 | this type | 3591 | | | | | have been | 3592 | | | | | created | 3593 | | | | | recently, | 3594 | | | | | and a | 3595 | | | | | server- | 3596 | | | | | defined | 3597 | | | | | rate limit | 3598 | | | | | has been | 3599 | | | | | reached. | 3600 | | | | | It may | 3601 | | | | | work if | 3602 | | | | | tried | 3603 | | | | | again | 3604 | | | | | later. | 3605 | requestTooLarge | commo | IETF | [I-D.ietf-jma | The total | 3606 | | n | | p-core] | number of | 3607 | | | | sections 5.1 | actions | 3608 | | | | and 5.3 | exceeds | 3609 | | | | | the | 3610 | | | | | maximum | 3611 | | | | | number the | 3612 | | | | | server is | 3613 | | | | | willing to | 3614 | | | | | process in | 3615 | | | | | a single | 3616 | | | | | method | 3617 | | | | | call. | 3618 | invalidResultRefer | commo | IETF | [I-D.ietf-jma | The method | 3619 | ence | n | | p-core] | used a | 3620 | | | | section 3.5.2 | result | 3621 | | | | | reference | 3622 | | | | | for one of | 3623 | | | | | its | 3624 | | | | | arguments, | 3625 | | | | | but this | 3626 | | | | | failed to | 3627 | | | | | resolve. | 3628 | serverFail | commo | IETF | [I-D.ietf-jma | An | 3629 | | n | | p-core] | unexpected | 3630 | | | | section 3.5.2 | or unknown | 3631 | | | | | error | 3632 | | | | | occurred | 3633 | | | | | during the | 3634 | | | | | processing | 3635 | | | | | of the | 3636 | | | | | call. The | 3637 | | | | | method | 3638 | | | | | call made | 3639 | | | | | no changes | 3640 | | | | | to the | 3641 | | | | | server's | 3642 | | | | | state. | 3643 | serverPartialFail | limit | IETF | [I-D.ietf-jma | Some, but | 3644 | | ed | | p-core] | not all | 3645 | | | | section 3.5.2 | expected | 3646 | | | | | changes | 3647 | | | | | described | 3648 | | | | | by the | 3649 | | | | | method | 3650 | | | | | occurred. | 3651 | | | | | The client | 3652 | | | | | MUST re-sy | 3653 | | | | | nchronise | 3654 | | | | | impacted | 3655 | | | | | data to | 3656 | | | | | determine | 3657 | | | | | server | 3658 | | | | | state. Use | 3659 | | | | | of this | 3660 | | | | | error is | 3661 | | | | | strongly d | 3662 | | | | | iscouraged | 3663 | | | | | . | 3664 | serverUnavailable | commo | IETF | [I-D.ietf-jma | Some | 3665 | | n | | p-core] | internal | 3666 | | | | section 3.5.2 | server | 3667 | | | | | resource | 3668 | | | | | was tempor | 3669 | | | | | arily unav | 3670 | | | | | ailable. | 3671 | | | | | Attempting | 3672 | | | | | the same | 3673 | | | | | operation | 3674 | | | | | later | 3675 | | | | | (perhaps | 3676 | | | | | after a | 3677 | | | | | backoff | 3678 | | | | | with a | 3679 | | | | | random | 3680 | | | | | factor) | 3681 | | | | | may | 3682 | | | | | succeed. | 3683 | singleton | commo | IETF | [I-D.ietf-jma | This is a | 3684 | | n | | p-core] | singleton | 3685 | | | | section 5.3 | type, so | 3686 | | | | | you cannot | 3687 | | | | | create | 3688 | | | | | another | 3689 | | | | | one or | 3690 | | | | | destroy | 3691 | | | | | the | 3692 | | | | | existing | 3693 | | | | | one. | 3694 | stateMismatch | commo | IETF | [I-D.ietf-jma | An | 3695 | | n | | p-core] | ifInState | 3696 | | | | section 5.3 | argument | 3697 | | | | | was | 3698 | | | | | supplied | 3699 | | | | | and it | 3700 | | | | | does not | 3701 | | | | | match the | 3702 | | | | | current | 3703 | | | | | state. | 3704 | tooLarge | commo | IETF | [I-D.ietf-jma | The action | 3705 | | n | | p-core] | would | 3706 | | | | section 5.3 | result in | 3707 | | | | | an object | 3708 | | | | | that | 3709 | | | | | exceeds a | 3710 | | | | | server- | 3711 | | | | | defined | 3712 | | | | | limit for | 3713 | | | | | the | 3714 | | | | | maximum | 3715 | | | | | size of a | 3716 | | | | | single | 3717 | | | | | object of | 3718 | | | | | this type. | 3719 | tooManyChanges | commo | IETF | [I-D.ietf-jma | There are | 3720 | | n | | p-core] | more | 3721 | | | | section 5.6 | changes | 3722 | | | | | than the | 3723 | | | | | client's | 3724 | | | | | maxChanges | 3725 | | | | | argument. | 3726 | unknownCapability | commo | IETF | [I-D.ietf-jma | The client | 3727 | | n | | p-core] | included a | 3728 | | | | section 3.5.1 | capability | 3729 | | | | | in the | 3730 | | | | | "using" | 3731 | | | | | property | 3732 | | | | | of the | 3733 | | | | | request | 3734 | | | | | that the | 3735 | | | | | server | 3736 | | | | | does not | 3737 | | | | | support. | 3738 | unknownMethod | commo | IETF | [I-D.ietf-jma | The server | 3739 | | n | | p-core] | does not | 3740 | | | | section 3.5.2 | recognise | 3741 | | | | | this | 3742 | | | | | method | 3743 | | | | | name. | 3744 | unsupportedFilter | commo | IETF | [I-D.ietf-jma | The filter | 3745 | | n | | p-core] | is syntact | 3746 | | | | section 5.5 | ically | 3747 | | | | | valid, but | 3748 | | | | | the server | 3749 | | | | | cannot | 3750 | | | | | process | 3751 | | | | | it. | 3752 | unsupportedSort | commo | IETF | [I-D.ietf-jma | The sort | 3753 | | n | | p-core] | is syntact | 3754 | | | | section 5.5 | ically | 3755 | | | | | valid, but | 3756 | | | | | includes a | 3757 | | | | | property | 3758 | | | | | the server | 3759 | | | | | does not | 3760 | | | | | support | 3761 | | | | | sorting | 3762 | | | | | on, or a | 3763 | | | | | collation | 3764 | | | | | method it | 3765 | | | | | does not | 3766 | | | | | recognise. | 3767 | willDestroy | commo | IETF | [I-D.ietf-jma | The client | 3768 | | n | | p-core] | requested | 3769 | | | | section 5.3 | an object | 3770 | | | | | be both | 3771 | | | | | updated | 3772 | | | | | and | 3773 | | | | | destroyed | 3774 | | | | | in the | 3775 | | | | | same /set | 3776 | | | | | request, | 3777 | | | | | and the | 3778 | | | | | server has | 3779 | | | | | decided to | 3780 | | | | | therefore | 3781 | | | | | ignore the | 3782 | | | | | update. | 3783 +--------------------+-------+---------+---------------+------------+ 3785 10. References 3787 10.1. Normative References 3789 [EventSource] 3790 Hickson, I., "Server-Sent Events", 2015, 3791 . 3793 [I-D.ietf-jmap-core] 3794 Jenkins, N. and C. Newman, "JSON Meta Application 3795 Protocol", draft-ietf-jmap-core-16 (work in progress), 3796 March 2019. 3798 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3799 Requirement Levels", BCP 14, RFC 2119, 3800 DOI 10.17487/RFC2119, March 1997, 3801 . 3803 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 3804 specifying the location of services (DNS SRV)", RFC 2782, 3805 DOI 10.17487/RFC2782, February 2000, 3806 . 3808 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 3809 DOI 10.17487/RFC2818, May 2000, 3810 . 3812 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 3813 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 3814 . 3816 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 3817 IETF URN Sub-namespace for Registered Protocol 3818 Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June 3819 2003, . 3821 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 3822 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 3823 2003, . 3825 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 3826 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 3827 . 3829 [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet 3830 Application Protocol Collation Registry", RFC 4790, 3831 DOI 10.17487/RFC4790, March 2007, 3832 . 3834 [RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation 3835 Algorithm", RFC 5051, DOI 10.17487/RFC5051, October 2007, 3836 . 3838 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 3839 DOI 10.17487/RFC5322, October 2008, 3840 . 3842 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3843 Uniform Resource Identifiers (URIs)", RFC 5785, 3844 DOI 10.17487/RFC5785, April 2010, 3845 . 3847 [RFC6186] Daboo, C., "Use of SRV Records for Locating Email 3848 Submission/Access Services", RFC 6186, 3849 DOI 10.17487/RFC6186, March 2011, 3850 . 3852 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 3853 Cheshire, "Internet Assigned Numbers Authority (IANA) 3854 Procedures for the Management of the Service Name and 3855 Transport Protocol Port Number Registry", BCP 165, 3856 RFC 6335, DOI 10.17487/RFC6335, August 2011, 3857 . 3859 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 3860 and D. Orchard, "URI Template", RFC 6570, 3861 DOI 10.17487/RFC6570, March 2012, 3862 . 3864 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 3865 RFC 6749, DOI 10.17487/RFC6749, October 2012, 3866 . 3868 [RFC6764] Daboo, C., "Locating Services for Calendaring Extensions 3869 to WebDAV (CalDAV) and vCard Extensions to WebDAV 3870 (CardDAV)", RFC 6764, DOI 10.17487/RFC6764, February 2013, 3871 . 3873 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 3874 Specifications and Registration Procedures", BCP 13, 3875 RFC 6838, DOI 10.17487/RFC6838, January 2013, 3876 . 3878 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 3879 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 3880 DOI 10.17487/RFC6901, April 2013, 3881 . 3883 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3884 Protocol (HTTP/1.1): Message Syntax and Routing", 3885 RFC 7230, DOI 10.17487/RFC7230, June 2014, 3886 . 3888 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 3889 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 3890 DOI 10.17487/RFC7231, June 2014, 3891 . 3893 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493, 3894 DOI 10.17487/RFC7493, March 2015, 3895 . 3897 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3898 "Recommendations for Secure Use of Transport Layer 3899 Security (TLS) and Datagram Transport Layer Security 3900 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3901 2015, . 3903 [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", 3904 RFC 7617, DOI 10.17487/RFC7617, September 2015, 3905 . 3907 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 3908 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 3909 . 3911 [RFC8030] Thomson, M., Damaggio, E., and B. Raymor, Ed., "Generic 3912 Event Delivery Using HTTP Push", RFC 8030, 3913 DOI 10.17487/RFC8030, December 2016, 3914 . 3916 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3917 Writing an IANA Considerations Section in RFCs", BCP 26, 3918 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3919 . 3921 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3922 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3923 May 2017, . 3925 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 3926 Interchange Format", STD 90, RFC 8259, 3927 DOI 10.17487/RFC8259, December 2017, 3928 . 3930 [RFC8264] Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 3931 Preparation, Enforcement, and Comparison of 3932 Internationalized Strings in Application Protocols", 3933 RFC 8264, DOI 10.17487/RFC8264, October 2017, 3934 . 3936 [RFC8291] Thomson, M., "Message Encryption for Web Push", RFC 8291, 3937 DOI 10.17487/RFC8291, November 2017, 3938 . 3940 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 3941 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 3942 . 3944 10.2. Informative References 3946 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 3947 DOI 10.17487/RFC8246, September 2017, 3948 . 3950 Authors' Addresses 3952 Neil Jenkins 3953 FastMail 3954 PO Box 234, Collins St West 3955 Melbourne VIC 8007 3956 Australia 3958 Email: neilj@fastmailteam.com 3959 URI: https://www.fastmail.com 3961 Chris Newman 3962 Oracle 3963 440 E. Huntington Dr., Suite 400 3964 Arcadia CA 91006 3965 United States of America 3967 Email: chris.newman@oracle.com