Tech-invite   3GPPspecs   Glossaries   IETFRFCs   Groups   SIP   ABNFs   Ti+   Search in Tech-invite

in Index   Prev   Next
in Index   None   Next  Group: JMAP

RFC 8620

The JSON Meta Application Protocol (JMAP)

Pages: 90
Proposed STD
Errata
Part 1 of 5 – Pages 1 to 15
None   None   Next

Top   ToC   RFC8620 - Page 1
Internet Engineering Task Force (IETF)                        N. Jenkins
Request for Comments: 8620                                      Fastmail
Category: Standards Track                                      C. Newman
ISSN: 2070-1721                                                   Oracle
                                                               July 2019


               The JSON Meta Application Protocol (JMAP)

Abstract

   This document specifies a protocol for clients to efficiently query,
   fetch, and modify JSON-based data objects, with support for push
   notification of changes and fast resynchronisation and for out-of-
   band binary data upload/download.

Status of This Memo

   This is an Internet Standards Track document.

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

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

Copyright Notice

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

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

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   4
     1.2.  The Id Data Type  . . . . . . . . . . . . . . . . . . . .   6
     1.3.  The Int and UnsignedInt Data Types  . . . . . . . . . . .   6
     1.4.  The Date and UTCDate Data Types . . . . . . . . . . . . .   7
     1.5.  JSON as the Data Encoding Format  . . . . . . . . . . . .   7
     1.6.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   7
       1.6.1.  User  . . . . . . . . . . . . . . . . . . . . . . . .   7
       1.6.2.  Accounts  . . . . . . . . . . . . . . . . . . . . . .   7
       1.6.3.  Data Types and Records  . . . . . . . . . . . . . . .   8
     1.7.  The JMAP API Model  . . . . . . . . . . . . . . . . . . .   8
     1.8.  Vendor-Specific Extensions  . . . . . . . . . . . . . . .   9
   2.  The JMAP Session Resource . . . . . . . . . . . . . . . . . .   9
     2.1.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  14
     2.2.  Service Autodiscovery . . . . . . . . . . . . . . . . . .  15
   3.  Structured Data Exchange  . . . . . . . . . . . . . . . . . .  16
     3.1.  Making an API Request . . . . . . . . . . . . . . . . . .  16
     3.2.  The Invocation Data Type  . . . . . . . . . . . . . . . .  16
     3.3.  The Request Object  . . . . . . . . . . . . . . . . . . .  16
       3.3.1.  Example Request . . . . . . . . . . . . . . . . . . .  18
     3.4.  The Response Object . . . . . . . . . . . . . . . . . . .  18
       3.4.1.  Example Response  . . . . . . . . . . . . . . . . . .  19
     3.5.  Omitting Arguments  . . . . . . . . . . . . . . . . . . .  19
     3.6.  Errors  . . . . . . . . . . . . . . . . . . . . . . . . .  19
       3.6.1.  Request-Level Errors  . . . . . . . . . . . . . . . .  20
       3.6.2.  Method-Level Errors . . . . . . . . . . . . . . . . .  21
     3.7.  References to Previous Method Results . . . . . . . . . .  22
     3.8.  Localisation of User-Visible Strings  . . . . . . . . . .  27
     3.9.  Security  . . . . . . . . . . . . . . . . . . . . . . . .  28
     3.10. Concurrency . . . . . . . . . . . . . . . . . . . . . . .  28
   4.  The Core/echo Method  . . . . . . . . . . . . . . . . . . . .  28
     4.1.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  28
   5.  Standard Methods and Naming Convention  . . . . . . . . . . .  29
     5.1.  /get  . . . . . . . . . . . . . . . . . . . . . . . . . .  29
     5.2.  /changes  . . . . . . . . . . . . . . . . . . . . . . . .  30
     5.3.  /set  . . . . . . . . . . . . . . . . . . . . . . . . . .  34
     5.4.  /copy . . . . . . . . . . . . . . . . . . . . . . . . . .  40
     5.5.  /query  . . . . . . . . . . . . . . . . . . . . . . . . .  42
     5.6.  /queryChanges . . . . . . . . . . . . . . . . . . . . . .  48
     5.7.  Examples  . . . . . . . . . . . . . . . . . . . . . . . .  51
     5.8.  Proxy Considerations  . . . . . . . . . . . . . . . . . .  58
   6.  Binary Data . . . . . . . . . . . . . . . . . . . . . . . . .  58
     6.1.  Uploading Binary Data . . . . . . . . . . . . . . . . . .  59
     6.2.  Downloading Binary Data . . . . . . . . . . . . . . . . .  60
     6.3.  Blob/copy . . . . . . . . . . . . . . . . . . . . . . . .  61
Top   ToC   RFC8620 - Page 3
   7.  Push  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  62
     7.1.  The StateChange Object  . . . . . . . . . . . . . . . . .  63
       7.1.1.  Example . . . . . . . . . . . . . . . . . . . . . . .  64
     7.2.  PushSubscription  . . . . . . . . . . . . . . . . . . . .  64
       7.2.1.  PushSubscription/get  . . . . . . . . . . . . . . . .  67
       7.2.2.  PushSubscription/set  . . . . . . . . . . . . . . . .  68
       7.2.3.  Example . . . . . . . . . . . . . . . . . . . . . . .  69
     7.3.  Event Source  . . . . . . . . . . . . . . . . . . . . . .  71
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  73
     8.1.  Transport Confidentiality . . . . . . . . . . . . . . . .  73
     8.2.  Authentication Scheme . . . . . . . . . . . . . . . . . .  73
     8.3.  Service Autodiscovery . . . . . . . . . . . . . . . . . .  73
     8.4.  JSON Parsing  . . . . . . . . . . . . . . . . . . . . . .  74
     8.5.  Denial of Service . . . . . . . . . . . . . . . . . . . .  74
     8.6.  Connection to Unknown Push Server . . . . . . . . . . . .  74
     8.7.  Push Encryption . . . . . . . . . . . . . . . . . . . . .  75
     8.8.  Traffic Analysis  . . . . . . . . . . . . . . . . . . . .  76
   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  76
     9.1.  Assignment of jmap Service Name . . . . . . . . . . . . .  76
     9.2.  Registration of Well-Known URI Suffix for JMAP  . . . . .  76
     9.3.  Registration of the jmap URN Sub-namespace  . . . . . . .  77
     9.4.  Creation of "JMAP Capabilities" Registry  . . . . . . . .  77
       9.4.1.  Preliminary Community Review  . . . . . . . . . . . .  77
       9.4.2.  Submit Request to IANA  . . . . . . . . . . . . . . .  78
       9.4.3.  Designated Expert Review  . . . . . . . . . . . . . .  78
       9.4.4.  Change Procedures . . . . . . . . . . . . . . . . . .  78
       9.4.5.  JMAP Capabilities Registry Template . . . . . . . . .  79
       9.4.6.  Initial Registration for JMAP Core  . . . . . . . . .  79
       9.4.7.  Registration for JMAP Error Placeholder in JMAP
               Capabilities Registry . . . . . . . . . . . . . . . .  80
     9.5.  Creation of "JMAP Error Codes" Registry . . . . . . . . .  80
       9.5.1.  Expert Review . . . . . . . . . . . . . . . . . . . .  80
       9.5.2.  JMAP Error Codes Registry Template  . . . . . . . . .  81
       9.5.3.  Initial Contents for the JMAP Error Codes Registry  .  81
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  86
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  86
     10.2.  Informative References . . . . . . . . . . . . . . . . .  89
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  90
Top   ToC   RFC8620 - Page 4
1.  Introduction

   The JSON Meta Application Protocol (JMAP) is used for synchronising
   data, such as mail, calendars, or contacts, between a client and a
   server.  It is optimised for mobile and web environments and aims to
   provide a consistent interface to different data types.

   This specification is for the generic mechanism of data
   synchronisation.  Further specifications define the data models for
   different data types that may be synchronised via JMAP.

   JMAP is designed to make efficient use of limited network resources.
   Multiple API calls may be batched in a single request to the server,
   reducing round trips and improving battery life on mobile devices.
   Push connections remove the need for polling, and an efficient delta
   update mechanism ensures a minimum amount of data is transferred.

   JMAP is designed to be horizontally scalable to a very large number
   of users.  This is facilitated by separate endpoints for users after
   login, the separation of binary and structured data, and a data model
   for sharing that does not allow data dependencies between accounts.

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   The underlying format used for this specification is JSON.
   Consequently, the terms "object" and "array" as well as the four
   primitive types (strings, numbers, booleans, and null) are to be
   interpreted as described in Section 1 of [RFC8259].  Unless otherwise
   noted, all the property names and values are case sensitive.

   Some examples in this document contain "partial" JSON documents used
   for illustrative purposes.  In these examples, three periods "..."
   are used to indicate a portion of the document that has been removed
   for compactness.

   For compatibility with publishing requirements, line breaks have been
   inserted inside long JSON strings, with the following continuation
   lines indented.  To form the valid JSON example, any line breaks
   inside a string must be replaced with a space and any other white
   space after the line break removed.
Top   ToC   RFC8620 - Page 5
   Unless otherwise specified, examples of API exchanges only show the
   methodCalls array of the Request object or the methodResponses array
   of the Response object.  For compactness, the rest of the Request/
   Response object is omitted.

   Type signatures are given for all JSON values in this document.  The
   following conventions are used:

   o  "*" - The type is undefined (the value could be any type, although
      permitted values may be constrained by the context of this value).

   o  "String" - The JSON string type.

   o  "Number" - The JSON number type.

   o  "Boolean" - The JSON boolean type.

   o  "A[B]" - A JSON object where the keys are all of type "A", and the
      values are all of type "B".

   o  "A[]" - An array of values of type "A".

   o  "A|B" - The value is either of type "A" or of type "B".

   Other types may also be given, with their representation defined
   elsewhere in this document.

   Object properties may also have a set of attributes defined along
   with the type signature.  These have the following meanings:

   o  "server-set" -- Only the server can set the value for this
      property.  The client MUST NOT send this property when creating a
      new object of this type.

   o  "immutable" -- The value MUST NOT change after the object is
      created.

   o  "default" -- (This is followed by a JSON value).  The value that
      will be used for this property if it is omitted in an argument or
      when creating a new object of this type.
Top   ToC   RFC8620 - Page 6
1.2.  The Id Data Type

   All record ids are assigned by the server and are immutable.

   Where "Id" is given as a data type, it means a "String" of at least 1
   and a maximum of 255 octets in size, and it MUST only contain
   characters from the "URL and Filename Safe" base64 alphabet, as
   defined in Section 5 of [RFC4648], excluding the pad character ("=").
   This means the allowed characters are the ASCII alphanumeric
   characters ("A-Za-z0-9"), hyphen ("-"), and underscore ("_").

   These characters are safe to use in almost any context (e.g.,
   filesystems, URIs, and IMAP atoms).  For maximum safety, servers
   SHOULD also follow defensive allocation strategies to avoid creating
   risks where glob completion or data type detection may be present
   (e.g., on filesystems or in spreadsheets).  In particular, it is wise
   to avoid:

   o  Ids starting with a dash

   o  Ids starting with digits

   o  Ids that contain only digits

   o  Ids that differ only by ASCII case (for example, A vs. a)

   o  the specific sequence of three characters "NIL" (because this
      sequence can be confused with the IMAP protocol expression of the
      null value)

   A good solution to these issues is to prefix every id with a single
   alphabetical character.

1.3.  The Int and UnsignedInt Data Types

   Where "Int" is given as a data type, it means an integer in the range
   -2^53+1 <= value <= 2^53-1, the safe range for integers stored in a
   floating-point double, represented as a JSON "Number".

   Where "UnsignedInt" is given as a data type, it means an "Int" where
   the value MUST be in the range 0 <= value <= 2^53-1.
Top   ToC   RFC8620 - Page 7
1.4.  The Date and UTCDate Data Types

   Where "Date" is given as a type, it means a string in "date-time"
   format [RFC3339].  To ensure a normalised form, the "time-secfrac"
   MUST always be omitted if zero, and any letters in the string (e.g.,
   "T" and "Z") MUST be uppercase.  For example,
   "2014-10-30T14:12:00+08:00".

   Where "UTCDate" is given as a type, it means a "Date" where the
   "time-offset" component MUST be "Z" (i.e., it must be in UTC time).
   For example, "2014-10-30T06:12:00Z".

1.5.  JSON as the Data Encoding Format

   JSON is a text-based data interchange format as specified in
   [RFC8259].  The Internet JSON (I-JSON) format defined in [RFC7493] is
   a strict subset of this, adding restrictions to avoid potentially
   confusing scenarios (for example, it mandates that an object MUST NOT
   have two members with the same name).

   All data sent from the client to the server or from the server to the
   client (except binary file upload/download) MUST be valid I-JSON
   according to the RFC and is therefore case sensitive and encoded in
   UTF-8 [RFC3629].

1.6.  Terminology

1.6.1.  User

   A user is a person accessing data via JMAP.  A user has a set of
   permissions determining the data that they can see.

1.6.2.  Accounts

   An account is a collection of data.  A single account may contain an
   arbitrary set of data types, for example, a collection of mail,
   contacts, and calendars.  Most JMAP methods take a mandatory
   "accountId" argument that specifies on which account the operations
   are to take place.

   An account is not the same as a user, although it is common for a
   primary account to directly belong to the user.  For example, you may
   have an account that contains data for a group or business, to which
   multiple users have access.
Top   ToC   RFC8620 - Page 8
   A single set of credentials may provide access to multiple accounts,
   for example, if another user is sharing their work calendar with the
   authenticated user or if there is a group mailbox for a support-desk
   inbox.

   In the event of a severe internal error, a server may have to
   reallocate ids or do something else that violates standard JMAP data
   constraints for an account.  In this situation, the data on the
   server is no longer compatible with cached data the client may have
   from before.  The server MUST treat this as though the account has
   been deleted and then recreated with a new account id.  Clients will
   then be forced to throw away any data with the old account id and
   refetch all data from scratch.

1.6.3.  Data Types and Records

   JMAP provides a uniform interface for creating, retrieving, updating,
   and deleting various types of objects.  A "data type" is a collection
   of named, typed properties, just like the schema for a database
   table.  Each instance of a data type is called a "record".

   The id of a record is immutable and assigned by the server.  The id
   MUST be unique among all records of the *same type* within the *same
   account*.  Ids may clash across accounts or for two records of
   different types within the same account.

1.7.  The JMAP API Model

   JMAP uses HTTP [RFC7230] to expose API, push, upload, and download
   resources.  All HTTP requests MUST use the "https://" scheme (HTTP
   over TLS [RFC2818]).  All HTTP requests MUST be authenticated.

   An authenticated client can fetch the user's Session object with
   details about the data and capabilities the server can provide as
   shown in Section 2.  The client may then exchange data with the
   server in the following ways:

   1.  The client may make an API request to the server to get or set
       structured data.  This request consists of an ordered series of
       method calls.  These are processed by the server, which then
       returns an ordered series of responses.  This is described in
       Sections 3, 4, and 5.

   2.  The client may download or upload binary files from/to the
       server.  This is detailed in Section 6.

   3.  The client may connect to a push channel on the server, to be
       notified when data has changed.  This is explained in Section 7.
Top   ToC   RFC8620 - Page 9
1.8.  Vendor-Specific Extensions

   Individual services will have custom features they wish to expose
   over JMAP.  This may take the form of extra data types and/or methods
   not in the spec, extra arguments to JMAP methods, or extra properties
   on existing data types (which may also appear in arguments to methods
   that take property names).

   The server can advertise custom extensions it supports by including
   the identifiers in the capabilities object.  Identifiers for vendor
   extensions MUST be a URL belonging to a domain owned by the vendor,
   to avoid conflict.  The URL SHOULD resolve to documentation for the
   changes the extension makes.

   The client MUST opt in to use an extension by passing the appropriate
   capability identifier in the "using" array of the Request object, as
   described in Section 3.3.  The server MUST only follow the
   specifications that are opted into and behave as though it does not
   implement anything else when processing a request.  This is to ensure
   compatibility with clients that don't know about a specific custom
   extension and for compatibility with future versions of JMAP.

2.  The JMAP Session Resource

   You need two things to connect to a JMAP server:

   1.  The URL for the JMAP Session resource.  This may be requested
       directly from the user or discovered automatically based on a
       username domain (see Section 2.2 below).

   2.  Credentials to authenticate with.  How to obtain credentials is
       out of scope for this document.

   A successful authenticated GET request to the JMAP Session resource
   MUST return a JSON-encoded *Session* object, giving details about the
   data and capabilities the server can provide to the client given
   those credentials.  It has the following properties:

   o  capabilities: "String[Object]"

      An object specifying the capabilities of this server.  Each key is
      a URI for a capability supported by the server.  The value for
      each of these keys is an object with further information about the
      server's capabilities in relation to that capability.

      The client MUST ignore any properties it does not understand.
Top   ToC   RFC8620 - Page 10
      The capabilities object MUST include a property called
      "urn:ietf:params:jmap:core".  The value of this property is an
      object that MUST contain the following information on server
      capabilities (suggested minimum values for limits are supplied
      that allow clients to make efficient use of the network):

      *  maxSizeUpload: "UnsignedInt"

         The maximum file size, in octets, that the server will accept
         for a single file upload (for any purpose).  Suggested minimum:
         50,000,000.

      *  maxConcurrentUpload: "UnsignedInt"

         The maximum number of concurrent requests the server will
         accept to the upload endpoint.  Suggested minimum: 4.

      *  maxSizeRequest: "UnsignedInt"

         The maximum size, in octets, that the server will accept for a
         single request to the API endpoint.  Suggested minimum:
         10,000,000.

      *  maxConcurrentRequests: "UnsignedInt"

         The maximum number of concurrent requests the server will
         accept to the API endpoint.  Suggested minimum: 4.

      *  maxCallsInRequest: "UnsignedInt"

         The maximum number of method calls the server will accept in a
         single request to the API endpoint.  Suggested minimum: 16.

      *  maxObjectsInGet: "UnsignedInt"

         The maximum number of objects that the client may request in a
         single /get type method call.  Suggested minimum: 500.

      *  maxObjectsInSet: "UnsignedInt"

         The maximum number of objects the client may send to create,
         update, or destroy in a single /set type method call.  This is
         the combined total, e.g., if the maximum is 10, you could not
         create 7 objects and destroy 6, as this would be 13 actions,
         which exceeds the limit.  Suggested minimum: 500.
Top   ToC   RFC8620 - Page 11
      *  collationAlgorithms: "String[]"

         A list of identifiers for algorithms registered in the
         collation registry, as defined in [RFC4790], that the server
         supports for sorting when querying records.

      Specifications for future capabilities will define their own
      properties on the capabilities object.

      Servers MAY advertise vendor-specific JMAP extensions, as
      described in Section 1.8.  To avoid conflict, an identifier for a
      vendor-specific extension MUST be a URL with a domain owned by the
      vendor.  Clients MUST opt in to any capability it wishes to use
      (see Section 3.3).

   o  accounts: "Id[Account]"

      A map of an account id to an Account object for each account (see
      Section 1.6.2) the user has access to.  An *Account* object has
      the following properties:

      *  name: "String"

         A user-friendly string to show when presenting content from
         this account, e.g., the email address representing the owner of
         the account.

      *  isPersonal: "Boolean"

         This is true if the account belongs to the authenticated user
         rather than a group account or a personal account of another
         user that has been shared with them.

      *  isReadOnly: "Boolean"

         This is true if the entire account is read-only.

      *  accountCapabilities: "String[Object]"

         The set of capability URIs for the methods supported in this
         account.  Each key is a URI for a capability that has methods
         you can use with this account.  The value for each of these
         keys is an object with further information about the account's
         permissions and restrictions with respect to this capability,
         as defined in the capability's specification.

         The client MUST ignore any properties it does not understand.
Top   ToC   RFC8620 - Page 12
         The server advertises the full list of capabilities it supports
         in the capabilities object, as defined above.  If the
         capability defines new methods, the server MUST include it in
         the accountCapabilities object if the user may use those
         methods with this account.  It MUST NOT include it in the
         accountCapabilities object if the user cannot use those methods
         with this account.

         For example, you may have access to your own account with mail,
         calendars, and contacts data and also a shared account that
         only has contacts data (a business address book, for example).
         In this case, the accountCapabilities property on the first
         account would include something like
         "urn:ietf:params:jmap:mail", "urn:ietf:params:jmap:calendars",
         and "urn:ietf:params:jmap:contacts", while the second account
         would just have the last of these.

         Attempts to use the methods defined in a capability with one of
         the accounts that does not support that capability are rejected
         with an "accountNotSupportedByMethod" error (see "Method-Level
         Errors", Section 3.6.2).

   o  primaryAccounts: "String[Id]"

      A map of capability URIs (as found in accountCapabilities) to the
      account id that is considered to be the user's main or default
      account for data pertaining to that capability.  If no account
      being returned belongs to the user, or in any other way there is
      no appropriate way to determine a default account, there MAY be no
      entry for a particular URI, even though that capability is
      supported by the server (and in the capabilities object).
      "urn:ietf:params:jmap:core" SHOULD NOT be present.

   o  username: "String"

      The username associated with the given credentials, or the empty
      string if none.

   o  apiUrl: "String"

      The URL to use for JMAP API requests.
Top   ToC   RFC8620 - Page 13
   o  downloadUrl: "String"

      The URL endpoint to use when downloading files, in URI Template
      (level 1) format [RFC6570].  The URL MUST contain variables called
      "accountId", "blobId", "type", and "name".  The use of these
      variables is described in Section 6.2.  Due to potential encoding
      issues with slashes in content types, it is RECOMMENDED to put the
      "type" variable in the query section of the URL.

   o  uploadUrl: "String"

      The URL endpoint to use when uploading files, in URI Template
      (level 1) format [RFC6570].  The URL MUST contain a variable
      called "accountId".  The use of this variable is described in
      Section 6.1.

   o  eventSourceUrl: "String"

      The URL to connect to for push events, as described in
      Section 7.3, in URI Template (level 1) format [RFC6570].  The URL
      MUST contain variables called "types", "closeafter", and "ping".
      The use of these variables is described in Section 7.3.

   o  state: "String"

      A (preferably short) string representing the state of this object
      on the server.  If the value of any other property on the Session
      object changes, this string will change.  The current value is
      also returned on the API Response object (see Section 3.4),
      allowing clients to quickly determine if the session information
      has changed (e.g., an account has been added or removed), so they
      need to refetch the object.

   To ensure future compatibility, other properties MAY be included on
   the Session object.  Clients MUST ignore any properties they are not
   expecting.

   Implementors must take care to avoid inappropriate caching of the
   Session object at the HTTP layer.  Since the client should only
   refetch when it detects there is a change (via the sessionState
   property of an API response), it is RECOMMENDED to disable HTTP
   caching altogether, for example, by setting "Cache-Control: no-cache,
   no-store, must-revalidate" on the response.
Top   ToC   RFC8620 - Page 14
2.1.  Example

   In the following example Session object, the user has access to their
   own mail and contacts via JMAP, as well as read-only access to shared
   mail from another user.  The server is advertising a custom
   "https://example.com/apis/foobar" capability.

   {
     "capabilities": {
       "urn:ietf:params:jmap:core": {
         "maxSizeUpload": 50000000,
         "maxConcurrentUpload": 8,
         "maxSizeRequest": 10000000,
         "maxConcurrentRequest": 8,
         "maxCallsInRequest": 32,
         "maxObjectsInGet": 256,
         "maxObjectsInSet": 128,
         "collationAlgorithms": [
           "i;ascii-numeric",
           "i;ascii-casemap",
           "i;unicode-casemap"
         ]
       },
       "urn:ietf:params:jmap:mail": {}
       "urn:ietf:params:jmap:contacts": {},
       "https://example.com/apis/foobar": {
         "maxFoosFinangled": 42
       }
     },
     "accounts": {
       "A13824": {
         "name": "john@example.com",
         "isPersonal": true,
         "isReadOnly": false,
         "accountCapabilities": {
           "urn:ietf:params:jmap:mail": {
             "maxMailboxesPerEmail": null,
             "maxMailboxDepth": 10,
             ...
           },
           "urn:ietf:params:jmap:contacts": {
             ...
           }
         }
       },
Top   ToC   RFC8620 - Page 15
       "A97813": {
         "name": "jane@example.com",
         "isPersonal": false,
         "isReadOnly": true,
         "accountCapabilities": {
           "urn:ietf:params:jmap:mail": {
             "maxMailboxesPerEmail": 1,
             "maxMailboxDepth": 10,
             ...
           }
         }
       }
     },
     "primaryAccounts": {
       "urn:ietf:params:jmap:mail": "A13824",
       "urn:ietf:params:jmap:contacts": "A13824"
     },
     "username": "john@example.com",
     "apiUrl": "https://jmap.example.com/api/",
     "downloadUrl": "https://jmap.example.com
       /download/{accountId}/{blobId}/{name}?accept={type}",
     "uploadUrl": "https://jmap.example.com/upload/{accountId}/",
     "eventSourceUrl": "https://jmap.example.com
       /eventsource/?types={types}&closeafter={closeafter}&ping={ping}",
     "state": "75128aab4b1b"
   }

2.2.  Service Autodiscovery

   There are two standardised autodiscovery methods in use for Internet
   protocols:

   o  DNS SRV (see [RFC2782], [RFC6186], and [RFC6764])

   o  .well-known/servicename (see [RFC8615])

   A JMAP-supporting host for the domain "example.com" SHOULD publish a
   SRV record "_jmap._tcp.example.com" that gives a hostname and port
   (usually port "443").  The JMAP Session resource is then
   "https://${hostname}[:${port}]/.well-known/jmap" (following any
   redirects).

   If the client has a username in the form of an email address, it MAY
   use the domain portion of this to attempt autodiscovery of the JMAP
   server.


Next Section