Internet DRAFT - draft-ietf-jmap-portability-guide
draft-ietf-jmap-portability-guide
JMAP J.M. Baum, Ed.
Internet-Draft H.J. Happel, Ed.
Intended status: Informational audriga
Expires: 22 August 2024 19 February 2024
JMAP Guide for Migration and Data Portability
draft-ietf-jmap-portability-guide-00
Abstract
JMAP (RFC8620) is a generic, efficient, mobile friendly and scalable
protocol that can be used for data of any type. This makes it a good
fit for migrations or data portability use cases that are focusing on
data import and export. However, due to its large set of features,
it is also quite complex, which makes it difficult to explore new
application domains in practice. The goal of this document is to
provide guidelines on implementing essential parts of JMAP for a much
lower entry barrier and more efficient implementation of the
protocol.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 22 August 2024.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
Baum & Happel Expires 22 August 2024 [Page 1]
Internet-Draft JMAP Portability Guide February 2024
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Conventions Used In This Document . . . . . . . . . . . . 3
2. Outline on RFC8620 Features . . . . . . . . . . . . . . . . . 3
2.1. Use cases . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Session Resource . . . . . . . . . . . . . . . . . . . . 3
2.3. Structured Data exchange . . . . . . . . . . . . . . . . 4
2.4. Standard Methods and Naming Convention . . . . . . . . . 4
2.5. Binary Data . . . . . . . . . . . . . . . . . . . . . . . 4
3. Implementation Details . . . . . . . . . . . . . . . . . . . 4
3.1. Overview Tables . . . . . . . . . . . . . . . . . . . . . 4
3.2. Implementation considerations . . . . . . . . . . . . . . 11
3.2.1. All use cases . . . . . . . . . . . . . . . . . . . . 11
3.2.2. Listing . . . . . . . . . . . . . . . . . . . . . . . 15
3.2.3. Paging . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.4. Dynamic Session Resource . . . . . . . . . . . . . . 16
3.2.5. Attachments . . . . . . . . . . . . . . . . . . . . . 17
3.3. Recommended functionality . . . . . . . . . . . . . . . . 17
4. Security considerations . . . . . . . . . . . . . . . . . . . 18
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 18
7. Normative References . . . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction
JMAP [RFC8620] is designed to be a generic, efficient, mobile
friendly and scalable protocol. This comes with the cost of high
complexity, even though this is necessary to meet JMAP's design
goals.
Migration and data portability is about moving arbitrary user data
between services. JMAP is a particularly good fit for satisfying
basic data portability requirements. It can be used as an open
protocol in front of an application service, exposing data of any
kind. However, implementing JMAP correctly can be complicated, which
makes it difficult to explore new application domains in practice.
Baum & Happel Expires 22 August 2024 [Page 2]
Internet-Draft JMAP Portability Guide February 2024
For basic data portability requirements, users need to be able to
export their data from a product or import it into a product in real
time. Providers that want to support JMAP for their service to meet
data portability requirements likely do not want to implement the
full feature set that JMAP currently defines. Currently, there is no
guidance on how to implement only parts of RFC8620's features.
This specification aims to provide guidance to identify essential
parts of the JMAP spec for more rapid development. For the sole
purpose of providing very basic data portability, there is no need to
implement all parts of the JMAP protocol. In a second iteration
developers could then extend upon this basic version of JMAP.
1.1. Conventions Used In This Document
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 definitions of JSON keys and datatypes in the document follow the
conventions described in the core JMAP specification [RFC8620].
2. Outline on RFC8620 Features
2.1. Use cases
Not all features of [RFC8620] are required for basic data portability
use cases. This document focuses on three scenarios:
* JMAP Minimum: Minimal JMAP implementation possible to show what
needs to be implemented at the very least. In practice,
applications will choose to implement more than this bare minimum
as this alone most likely does not satisfy any use case for JMAP.
* Export use cases: Minimal implementation for exporting data from
an application server. A common scenario for data portability.
* Import use cases: Minimal implementation for importing data into
an application server. A common scenario for data portability.
2.2. Session Resource
For a lot of basic portability use cases for existing application
services the following constraints are typically acceptable:
* A single user login is tied to a single user account (this is then
also the primary account).
Baum & Happel Expires 22 August 2024 [Page 3]
Internet-Draft JMAP Portability Guide February 2024
* Shared data shall not be exposed over the API. The API will only
provide access to data owned by the current user.
* Each user has the same set of capabilities and restrictions (e.g.
maxMailboxesPerEmail).
* apiUrl, downloadUrl, uploadUrl and eventSourceUrl are the same for
ever user.
For use cases adhering to those restrictions, the session resource
can be modeled as a simple JSON file that only contains constant
values. This JSON then specifies a single accountId which is then
assigned the value "self".
2.3. Structured Data exchange
While batching improves performance considerably, it imposes
additional implementation effort on developers. It is not essential
for portability and can be left out.
2.4. Standard Methods and Naming Convention
JMAP core defines 6 standard methods. Not all JMAP Methods are
required to provide essential portability. For some use-cases where
the data is expected to be small, */set* and */get* should be enough.
In case a large amount of data shall be supported, paging can be
achieved via the */query* method. Note that some specifications
require specific IDs for /get .
*/changes*, */copy* as well as */queryChanges* are not required as
all data can already be imported and exported with above's three
methods.
2.5. Binary Data
The advanced Blob/copy method call is not essential. Not all
applications support attachments for their specific kind of data.
Additionally, some data types allow having attachments as base64
enconded strings inside a JMAP object. In those cases, it is not
required to implement a download or upload endpoint.
3. Implementation Details
3.1. Overview Tables
Tables 1-4 list the required features for a minimal implementation of
JMAP for Migration and Portability in more detail. The next section
provides more implementation considerations. It references the three
use cases defined in Section 2.1. The value for each table cell
details what is required at minimum for an implementation:
Baum & Happel Expires 22 August 2024 [Page 4]
Internet-Draft JMAP Portability Guide February 2024
* *-* : Not required
* *constant value(s)*: RFC 8620 requires that at least a constant
value will be returned by an application
* *error response*: RFC 8620 requires that a minimal implementation
emits an error response signalling that a feature is not supported
* *""*: Same as JMAP Minimum
+===============+==========+==================+==================+
| JMAP Core | JMAP | JMAP Portability | JMAP Portability |
| Feature | Minium | export use cases | import use cases |
+===============+==========+==================+==================+
| Session | constant | "" | "" |
| Object | values^1 | | |
+---------------+----------+------------------+------------------+
| Service | - | "" | "" |
| Autodiscovery | | | |
+---------------+----------+------------------+------------------+
Table 1: Session Object features essential for Migration and
Portability use cases
Baum & Happel Expires 22 August 2024 [Page 5]
Internet-Draft JMAP Portability Guide February 2024
+===================+==========+==================+=============+
| JMAP Core Feature | JMAP | JMAP Portability | JMAP |
| | Minimum | export use cases | Portability |
| | | | import use |
| | | | cases |
+===================+==========+==================+=============+
| Invocation (all | required | "" | "" |
| properties) | | | |
+-------------------+----------+------------------+-------------+
| Request (using) | required | "" | "" |
+-------------------+----------+------------------+-------------+
| Request | required | "" | "" |
| (methodCalls) | | | |
+-------------------+----------+------------------+-------------+
| Request | - | "" | "" |
| (createdIds) | | | |
+-------------------+----------+------------------+-------------+
| Response | required | "" | "" |
| (methodResponses) | | | |
+-------------------+----------+------------------+-------------+
| Response | - | "" | "" |
| (createdIds) | | | |
+-------------------+----------+------------------+-------------+
| Response | constant | "" | "" |
| (sessionState) | value | | |
+-------------------+----------+------------------+-------------+
| Errors | required | "" | "" |
+-------------------+----------+------------------+-------------+
| References to | - | "" | "" |
| Previous Method | | | |
| Results | | | |
+-------------------+----------+------------------+-------------+
| Localisation of | - | "" | "" |
| User-Visible | | | |
| String | | | |
+-------------------+----------+------------------+-------------+
Table 2: Structured Data Exchange features essential for
Migration and Portability use cases
+=======================+==========+==================+=============+
| JMAP Core Feature | JMAP | JMAP | JMAP |
| | Minimum | Portability | Portability |
| | | export use | import use |
| | | cases | cases |
+=======================+==========+==================+=============+
| Core/echo | required | "" | "" |
+-----------------------+----------+------------------+-------------+
Baum & Happel Expires 22 August 2024 [Page 6]
Internet-Draft JMAP Portability Guide February 2024
| /get method Request | error | required | "" |
| | response | | |
+-----------------------+----------+------------------+-------------+
| /get method Request | - | constant | "" |
| (accountId) | | value^1 | |
+-----------------------+----------+------------------+-------------+
| /get method Request | - | error response, | "" |
| (ids) | | required for | |
| | | listing/ | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /get method Request | - | error response | "" |
| (properties) | | | |
+-----------------------+----------+------------------+-------------+
| /get method Response | - | required | "" |
+-----------------------+----------+------------------+-------------+
| /get method Response | - | constant | "" |
| (accountId) | | value^1 | |
+-----------------------+----------+------------------+-------------+
| /get method Response | - | constant value | "" |
| (state) | | | |
+-----------------------+----------+------------------+-------------+
| /get method Response | - | required | "" |
| (list) | | | |
+-----------------------+----------+------------------+-------------+
| /get method Response | - | constant value, | "" |
| (notFound) | | required for | |
| | | listing/ | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /changes method | error | "" | "" |
| (full) | response | | |
+-----------------------+----------+------------------+-------------+
| /set method Request | error | "" | required |
| | response | | |
+-----------------------+----------+------------------+-------------+
| /set method Request | - | "" | constant |
| (accountId) | | | value^1 |
+-----------------------+----------+------------------+-------------+
| /set method Request | - | "" | constant |
| (ifInState) | | | value |
+-----------------------+----------+------------------+-------------+
| /set method Request | - | "" | required |
| (create, only single | | | |
| id) | | | |
+-----------------------+----------+------------------+-------------+
| /set method Request | - | "" | "" |
| (create, multiple | | | |
Baum & Happel Expires 22 August 2024 [Page 7]
Internet-Draft JMAP Portability Guide February 2024
| ids) | | | |
+-----------------------+----------+------------------+-------------+
| /set method Request | - | "" | error |
| (update) | | | response |
+-----------------------+----------+------------------+-------------+
| /set method Request | - | "" | error |
| (destroy) | | | response |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | required |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | constant |
| (accountId) | | | value^1 |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | constant |
| (oldState) | | | value |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | constant |
| (newState) | | | value |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | required |
| (created) | | | |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | constant |
| (updated) | | | value |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | constant |
| (destroyed) | | | value |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | required |
| (notCreated) | | | |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | error |
| (notUpdated) | | | response |
+-----------------------+----------+------------------+-------------+
| /set method Response | - | "" | error |
| (notDestroyed) | | | response |
+-----------------------+----------+------------------+-------------+
| /set method SetError | - | "" | required |
+-----------------------+----------+------------------+-------------+
| /copy method (full) | error | "" | "" |
| | response | | |
+-----------------------+----------+------------------+-------------+
| /query method Request | error | required for | "" |
| | response | listing/ | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | constant value | "" |
| (accountId) | | for listing | |
Baum & Happel Expires 22 August 2024 [Page 8]
Internet-Draft JMAP Portability Guide February 2024
| | | /paging^(1,2) | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | error response | "" |
| (filter) | | for listing | |
| | | /paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | error response | "" |
| (sort) | | for listing | |
| | | /paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | error response | "" |
| (position) | | for listing, | |
| | | required for | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | error response | "" |
| (anchor) | | for listing | |
| | | /paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | "" | "" |
| (anchorOffset) | | | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | error response | "" |
| (limit) | | for listing | |
| | | /paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method Request | - | error response | "" |
| (calculateTotal) | | for listing, | |
| | | required for | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method | - | required for | "" |
| Response | | listing | |
| | | /paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method | - | constant value | "" |
| Response (accountId) | | for listing | |
| | | /paging^(1,2) | |
+-----------------------+----------+------------------+-------------+
| /query method | - | required for | "" |
| Response (queryState) | | listing/ | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method | - | constant value | "" |
| Response | | | |
| (canCalculateChanges) | | | |
+-----------------------+----------+------------------+-------------+
| /query method | - | required for | "" |
Baum & Happel Expires 22 August 2024 [Page 9]
Internet-Draft JMAP Portability Guide February 2024
| Response (position) | | paging | |
+-----------------------+----------+------------------+-------------+
| /query method | - | required for | "" |
| Response (ids) | | listing/ | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method | - | required for | "" |
| Response (total) | | paging | |
+-----------------------+----------+------------------+-------------+
| /query method | - | required for | "" |
| Response (limit) | | listing/ | |
| | | paging^2 | |
+-----------------------+----------+------------------+-------------+
| /query method | - | "" | "" |
| FilterCondition | | | |
+-----------------------+----------+------------------+-------------+
| /query method | - | "" | "" |
| FilterOperator | | | |
+-----------------------+----------+------------------+-------------+
| /query method | - | "" | "" |
| Comparator | | | |
+-----------------------+----------+------------------+-------------+
| /queryChanges method | error | "" | "" |
| (full) | response | | |
+-----------------------+----------+------------------+-------------+
Table 3: Method features essential for Migration and Portability
+=============+=========+==================+========================+
| JMAP Core | JMAP | JMAP Portability | JMAP Portability |
| Feature | Minimum | export use cases | import use cases |
+=============+=========+==================+========================+
| Uploading | - | "" | required for |
| Binary Data | | | importing |
| | | | attachments^3 |
+-------------+---------+------------------+------------------------+
| Downloading | - | required for | "" |
| Binary Data | | exporting | |
| | | attachments^3 | |
+-------------+---------+------------------+------------------------+
| Blob/copy | - | "" | "" |
| (full) | | | |
+-------------+---------+------------------+------------------------+
| Push | - | "" | "" |
+-------------+---------+------------------+------------------------+
Table 4: Blob and Push features essential for Migration and
Portability
Baum & Happel Expires 22 August 2024 [Page 10]
Internet-Draft JMAP Portability Guide February 2024
* 1: Can be modeled as a JSON file with only constant values for a
lot of scenarios. Section 2.2 details for which use cases such a
JSON file should be sufficient.
* 2: maxObjectsInGet might not be sufficiently high in some
products. In this case, /query is required. Similarly, paging
might be required in case a query might exceed the limit for the
maximum amount of results for /query.
* 3: Some data types allow having attachments as base64 enconded
strings inside a JMAP object. In those cases it is not necessary
to implement a download or upload endpoint.
3.2. Implementation considerations
3.2.1. All use cases
3.2.1.1. Bare Minimum
For a bare minimum Session object, choose the following to return a
static JSON, which is the same for every user:
* maxSizeRequest
* maxConcurrentRequests
* apiUrl
* additional capabilities and their configuration
Baum & Happel Expires 22 August 2024 [Page 11]
Internet-Draft JMAP Portability Guide February 2024
{
"capabilities": {
"urn:ietf:params:jmap:core": {
"maxSizeUpload": 0,
"maxConcurrentUpload": 0,
"maxSizeRequest": <maxSizeRequest>,
"maxConcurrentRequests": <maxConcurrentRequests>,
"maxCallsInRequest": 1,
"maxObjectsInGet": 0,
"maxObjectsInSet": 0,
"collationAlgorithms": []
},
"urn:ietf:params:jmap:<other-capability>": {},
...
},
"accounts": {
"self": {
"name": "",
"isPersonal": true,
"isReadOnly": true,
"accountCapabilities": {
"urn:ietf:params:jmap:<other-capability>": {
"<key>": <value>,
...
},
...
}
}
},
"primaryAccounts": {
"urn:ietf:params:jmap:<other-capability>": "self"
},
"username": "",
"apiUrl": "<apiUrl>",
"downloadUrl": "",
"uploadUrl": "",
"eventSourceUrl": "",
"state": ""
}
Implement the following for Structured Data Exchange:
* Invocation (all properties) - *required*
* Request (using) - *required*; Make sure to keep capabilities
simple to keep implementation complexity low.
* Request (methodCalls) - *required*; No logic for batching, because
maxCallsInRequest is set to 1.
Baum & Happel Expires 22 August 2024 [Page 12]
Internet-Draft JMAP Portability Guide February 2024
* Request (createdIds) - not required; Only required in conjunction
with batching.
* Response (methodResponses) - *required*
* Response (createdIds) - not required; See createIds.
* Response (sessionState) - _constant value_; Set to "".
* Errors - *required*; Implement serverFail as the most basic of all
error types. Make sure to implement its description property to
clarify the error context. Additional error types are very useful
for debugging.
* References to Previous Method Results - not required; This is,
because batching is not advertised.
* Localisation of User-Visible String - not required
For Methods:
* Core/echo method (full) - *required*; Core/echo is useful for
basic connection testing and requires very low implementation
effort.
* /get method (full) - _error response_; always reply with
requestTooLarge error.
* /set method (full) - _error response_; always reply with
accountReadOnly error.
* /changes method (full) - _error response_; always reply with
cannotCalculateChanges error.
* /copy method (full) - _error response_; always reply with
serverFail error. Its description should explain that the method
is merely not supported.
* /query method (full) - _error response_; same as /copy.
* /queryChanges method (full) - _error response_; always reply with
cannotCalculateChanges error.
Note that there are some caveats when implementing the bare minimum
of JMAP. Setting downloadUrl and uploadUrl to an empty string might
be incompatible with some existing JMAP implementations as they are
defined as "MUST contain variables", which an empty string does not
contain. Also, some errors recommended in this document, like
serverFail or invalidArgument, typically signal to clients that
something unexpected has happened, when in fact servers can expect
clients to call any standard JMAP method or property. Due to this
the description property is used to clarify the context of errors
like serverFail and invalidArgument. However, its value is a free-
text string and therefore not machine-processable in an interoperable
way.
3.2.1.2. Exporting data
The Session Object now additional requires:
Baum & Happel Expires 22 August 2024 [Page 13]
Internet-Draft JMAP Portability Guide February 2024
* maxObjectsInGet
For Methods:
* /get method Request - *required*
* /get method Request (accountId) - _constant value_; Is always
"self". Can therefore be ignored on the server side.
* /get method Request (ids) - _error response_; Always respond with
invalidArguments. Its description property MUST explain that the
ids property is merely not supported. The ids property is
formally required by RFC8920, but in practice applications will
not use the ids fields without retrieving ids via /query or /set
first.
* /get method Request (properties) - _error response_; Always
respond with invalidArguments. Its description property MUST
explain that the properties property is merely not supported.
* /get method Response
* /get method Response (accountId) - _constant value_; Always set to
"self".
* /get method Response (state) - _constant value_; Always set to
empty string.
* /get method Response (list) - *required*
* /get method Response (notFound) - _constant value_; Always set to
empty array, see ids.
3.2.1.3. Importing data
The Session Object now additional requires:
* isReadOnly = false
* maxObjectsInSet
For methods:
* /set method Request - *required*
* /set method Request (accountId) - _constant value_; Is always
"self". Can therefore be ignored on the server side.
* /set method Request (ifInState) - _constant value_; State is
always empty string, so a simple check if this is empty string
should suffice.
* /set method Request (create, only single id) - *required*
* /set method Request (create, multiple ids) - not required; Only
required if maxObjectsInSet > 1.
* /set method Request (update) - _error response_; Always place in
notUpdated and reply with forbidden SetError. Its description
property MUST explain that the update property is merely not
supported.
Baum & Happel Expires 22 August 2024 [Page 14]
Internet-Draft JMAP Portability Guide February 2024
* /set method Request (destroy) - _error response_; Always place in
notDestroyed and reply with forbidden SetError. Its description
property MUST explain that the update property is merely not
supported.
* /set method Response - *required*
* /set method Response (accountId) - _constant value_; Is always
"self". Can therefore be ignored on the server side.
* /set method Response (oldState) - _constant value_; Is always
empty string.
* /set method Response (newState) - _constant value_; Is always
empty string.
* /set method Response (created) - *required*
* /set method Response (updated) - _constant value_; Is always an
empty array.
* /set method Response (destroyed) - _constant value_; Is always
empty array.
* /set method Response (notCreated) - *required*
* /set method Response (notUpdated) - _error response_; In case
update was not empty.
* /set method Response (notDestroyed) - _error response_; In case
destroy was not empty.
* /set method SetError - *required*; Implement forbidden to signal
update and destroy are not supported.
3.2.2. Listing
Methods:
* /get method Request (ids) - *required*
* /get method Response (notFound) - *required*
* /query method Request - *required*
* /query method Request (accountId) - _constant value_; Is always
"self". Can therefore be ignored on the server side.
* /query method Request (filter) - _error response_; Always return
unsupportedFilter.
* /query method Request (sort) - _error response_; Always return
unsupportedSort.
* /query method Request (position) - _error response_; always return
invalidArgument. Its description property MUST explain that the
position property is merely not supported.
* /query method Request (anchor) - _error response_; always return
invalidArgument. Its description property MUST explain that the
anchor property is merely not supported.
* /query method Request (anchorOffset) - not required; This is
because anchor is not supported.
* /query method Request (limit) - _error response_; Always return
invalidArgument. Its description property MUST explain that the
limit property is merely not supported.
Baum & Happel Expires 22 August 2024 [Page 15]
Internet-Draft JMAP Portability Guide February 2024
* /query method Request (calculateTotal) - _error response_; Always
return invalidArgument. Its description property MUST explain
that the calculateTotal property is merely not supported.
* /query method Response - *required*
* /query method Response (accountId) - _constant value_; Is always
"self". Can therefore be ignored on the server side.
* /query method Response (queryState) - *required*
* /query method Response (canCalculateChanges) - _constant value_;
Is always false.
* /query method Response (position) - not required; position not
supported
* /query method Response (ids) - *required*
* /query method Response (total) - not required
* /query method Response (limit) - *required*
* /query method FilterCondition - not required
* /query method FilterOperator - not required
* /query method Comparator - not required
3.2.3. Paging
Regarding methods, all requirements of Section 3.2.2, as well as:
* /query method Request (position) - *required*
* /query method Request (calculateTotal) - *required*
* /query method Response (position) - *required*
* /query method Response (total) - *required*
3.2.4. Dynamic Session Resource
3.2.4.1. Multi-Account Scenario
A user might have access to more than one account. In this case, the
constraints defined in Section 2.2 no longer apply.
For the Session Object:
* choose how to determine accountId (e.g. base64-encode the
username)
* make sure that accounts returns more than a single account if a
user has more
Methods:
* method Request (accountId) - *required*; Can no loner be a
constant value or ignored on the server side as a user might have
multiple accounts.
* method Response (accountId) - *required*; Can no longer be the
constant value "self".
Baum & Happel Expires 22 August 2024 [Page 16]
Internet-Draft JMAP Portability Guide February 2024
3.2.4.2. Varying Capabilities or Server configuration between users
Each user might have different restrictions regarding account
capabilities. In this case, accounts will may differ from one user
to another, and the constraints defined in Section 2.2 no longer
apply.
Other properties like uploadUrl, apiUrl etc. might change
dynamically. It may no longer be possible to choose static values
for them.
3.2.5. Attachments
3.2.5.1. Exporting attachments
For exporting data, choose for the Session Object:
* downloadUrl
Implement:
* actual download endpoint
3.2.5.2. Importing attachments
For importing data, choose for the Session Object:
* uploadUrl
* maxSizeUpload
* maxConcurrentUpload
Implement:
* actual upload endpoint
3.3. Recommended functionality
Autodiscovery is useful, so clients can use the endpoint more easily.
Destroying objects via /set is very valuable functionality for
testing. Without it, JMAP cannot be used to remove data. It
requires the following method implementation:
* /set method Request (destroy) - *required*
* /set method Response (destroyed) - *required*
* /set method Response (notDestroyed) - *required*
Baum & Happel Expires 22 August 2024 [Page 17]
Internet-Draft JMAP Portability Guide February 2024
The filter functionality of /query may be relevant for your use case.
Filters allow listing objects of a specific kind.
4. Security considerations
All security considerations of JMAP [RFC8620] apply to this
specification.
5. IANA Considerations
This document has no IANA actions.
6. Acknowledgements
Bron Gondwana, Neil Jenkins, Alexey Melnikov, Ken Murchison, Robert
Stepanek and the JMAP working group at the IETF.
7. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
2019, <https://www.rfc-editor.org/info/rfc8620>.
Authors' Addresses
Joris Baum (editor)
audriga
Alter Schlachthof 57
76137 Karlsruhe
Germany
Email: joris@audriga.com
URI: https://www.audriga.com
Hans-Joerg (editor)
audriga
Alter Schlachthof 57
76137 Karlsruhe
Germany
Baum & Happel Expires 22 August 2024 [Page 18]
Internet-Draft JMAP Portability Guide February 2024
Email: hans-joerg@audriga.com
URI: https://www.audriga.com
Baum & Happel Expires 22 August 2024 [Page 19]
