JMAP J.M. Baum, Ed. Internet-Draft H.J. Happel, Ed. Intended status: Informational audriga Expires: 2 February 2025 1 August 2024 JMAP Essential Profile draft-ietf-jmap-essential-01 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 2 February 2025. 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 2 February 2025 [Page 1] Internet-Draft JMAP Essential August 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.1.1. JMAP Bare Minimum . . . . . . . . . . . . . . . . . . 3 2.1.2. JMAP Essential Export . . . . . . . . . . . . . . . . 4 2.1.3. JMAP Essential Import . . . . . . . . . . . . . . . . 4 2.2. Session Resource . . . . . . . . . . . . . . . . . . . . 4 2.3. Structured Data exchange . . . . . . . . . . . . . . . . 4 2.4. Standard Methods and Naming Convention . . . . . . . . . 5 2.5. Binary Data . . . . . . . . . . . . . . . . . . . . . . . 5 3. Implementation Details . . . . . . . . . . . . . . . . . . . 5 3.1. Overview Tables . . . . . . . . . . . . . . . . . . . . . 5 3.2. Implementation considerations . . . . . . . . . . . . . . 12 3.2.1. All use cases . . . . . . . . . . . . . . . . . . . . 12 3.2.2. Listing . . . . . . . . . . . . . . . . . . . . . . . 16 3.2.3. Paging . . . . . . . . . . . . . . . . . . . . . . . 17 3.2.4. Dynamic Session Resource . . . . . . . . . . . . . . 17 3.2.5. Attachments . . . . . . . . . . . . . . . . . . . . . 18 3.3. Recommended functionality . . . . . . . . . . . . . . . . 18 4. Security considerations . . . . . . . . . . . . . . . . . . . 19 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 7. Normative References . . . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 1. Introduction JMAP [RFC8620] is designed to be a generic, efficient, mobile friendly and scalable protocol. Achieving these design goals comes with high complexity, which can be a barrier to its adoption in new application domains. 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 the full JMAP spec can be complicated, which makes it difficult to explore new application domains in practice. Baum & Happel Expires 2 February 2025 [Page 2] Internet-Draft JMAP Essential August 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 aiming to support JMAP for their services to meet data portability requirements likely do not want to implement the full feature set defined by JMAP. 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. It focuses on the minimal implementation required for basic data portability. For the sole purpose of providing very basic data portability, there is no need to implement all parts of the JMAP protocol. It should be noted that this essential profile will result in an inefficient protocol compared to the full JMAP specification. In a second iteration, developers could then extend this basic version of JMAP by adding advanced features, such as those for additional performance improvements. 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 use cases for which efficiency is not a crucial requirement. This document focuses on two main scenarios: JMAP Essential Export and JMAP Essential Import. 2.1.1. JMAP Bare Minimum JMAP Bare Minimum defines the absolute minimal set of features required to implement JMAP. It serves as a foundational blueprint, ensuring that developers understand the essential components of JMAP. Although this implementation is unlikely to meet practical needs on its own, it establishes the groundwork for more complex use cases. Baum & Happel Expires 2 February 2025 [Page 3] Internet-Draft JMAP Essential August 2024 2.1.2. JMAP Essential Export JMAP Essential Export use cases require that data can be exported from an application server. This scenario is common in data portability contexts where data needs to be transferred out of a server, such as when a user wants to move their data from one service provider to another. The emphasis here is on the necessary methods for extracting data, ensuring that the exported data is in a usable format for subsequent import or analysis. 2.1.3. JMAP Essential Import JMAP Essential Import use cases, on the other hand require that data can be imported into an application server. This is crucial for scenarios where data is being migrated into a new system from an external source. The primary focus is on the methods needed for receiving and integrating data, such as uploading binary data and processing incoming data formats. This use case ensures that the server can seamlessly incorporate external data into its existing structure. 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). * 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 can be left out as it is not essential, in particular for basic portability use cases. Baum & Happel Expires 2 February 2025 [Page 4] Internet-Draft JMAP Essential August 2024 2.4. Standard Methods and Naming Convention JMAP core defines 6 standard methods. Not all JMAP Methods are required to provide essential functionality. 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 encoded 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 Essential Profile 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: * *-* : 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 Bare Minimum Baum & Happel Expires 2 February 2025 [Page 5] Internet-Draft JMAP Essential August 2024 +===================+===========+================+================+ | JMAP Core Feature | JMAP Bare | JMAP Essential | JMAP Essential | | | Minimum | Export | Import | +===================+===========+================+================+ | Session Object | constant | "" | "" | | | values^1 | | | +-------------------+-----------+----------------+----------------+ | Service | - | "" | "" | | Autodiscovery | | | | +-------------------+-----------+----------------+----------------+ Table 1: Session Object features essential for basic use cases Baum & Happel Expires 2 February 2025 [Page 6] Internet-Draft JMAP Essential August 2024 +===================+===========+================+================+ | JMAP Core Feature | JMAP Bare | JMAP Essential | JMAP Essential | | | Minimum | Export | Import | +===================+===========+================+================+ | 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 basic use cases +=======================+==========+====================+===========+ | JMAP Core Feature | JMAP | JMAP Essential | JMAP | | | Bare | Export | Essential | | | Minimum | | Import | +=======================+==========+====================+===========+ | Core/echo | required | "" | "" | +-----------------------+----------+--------------------+-----------+ | /get method Request | error | required | "" | | | response | | | +-----------------------+----------+--------------------+-----------+ Baum & Happel Expires 2 February 2025 [Page 7] Internet-Draft JMAP Essential August 2024 | /get method Request | - | constant value^1 | "" | | (accountId) | | | | +-----------------------+----------+--------------------+-----------+ | /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 value^1 | "" | | (accountId) | | | | +-----------------------+----------+--------------------+-----------+ | /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 | | | | | ids) | | | | +-----------------------+----------+--------------------+-----------+ | /set method Request | - | "" | error | | (update) | | | response | +-----------------------+----------+--------------------+-----------+ Baum & Happel Expires 2 February 2025 [Page 8] Internet-Draft JMAP Essential August 2024 | /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 | | | | | /paging^(1,2) | | +-----------------------+----------+--------------------+-----------+ | /query method Request | - | error response | "" | | (filter) | | for listing | | | | | /paging^2 | | +-----------------------+----------+--------------------+-----------+ Baum & Happel Expires 2 February 2025 [Page 9] Internet-Draft JMAP Essential August 2024 | /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 | "" | | Response (position) | | paging | | +-----------------------+----------+--------------------+-----------+ | /query method | - | required for | "" | | Response (ids) | | listing/paging^2 | | +-----------------------+----------+--------------------+-----------+ | /query method | - | required for | "" | | Response (total) | | paging | | Baum & Happel Expires 2 February 2025 [Page 10] Internet-Draft JMAP Essential August 2024 +-----------------------+----------+--------------------+-----------+ | /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 basic use cases +=============+===========+================+========================+ | JMAP Core | JMAP Bare | JMAP Essential | JMAP Essential | | Feature | Minimum | Export | Import | +=============+===========+================+========================+ | 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 basic use cases * 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. Baum & Happel Expires 2 February 2025 [Page 11] Internet-Draft JMAP Essential August 2024 * 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 2 February 2025 [Page 12] Internet-Draft JMAP Essential August 2024 { "capabilities": { "urn:ietf:params:jmap:core": { "maxSizeUpload": 0, "maxConcurrentUpload": 0, "maxSizeRequest": , "maxConcurrentRequests": , "maxCallsInRequest": 1, "maxObjectsInGet": 0, "maxObjectsInSet": 0, "collationAlgorithms": [] }, "urn:ietf:params:jmap:": {}, ... }, "accounts": { "self": { "name": "", "isPersonal": true, "isReadOnly": true, "accountCapabilities": { "urn:ietf:params:jmap:": { "": , ... }, ... } } }, "primaryAccounts": { "urn:ietf:params:jmap:": "self" }, "username": "", "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 2 February 2025 [Page 13] Internet-Draft JMAP Essential August 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 2 February 2025 [Page 14] Internet-Draft JMAP Essential August 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 2 February 2025 [Page 15] Internet-Draft JMAP Essential August 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 2 February 2025 [Page 16] Internet-Draft JMAP Essential August 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 2 February 2025 [Page 17] Internet-Draft JMAP Essential August 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 2 February 2025 [Page 18] Internet-Draft JMAP Essential August 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, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, . 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 2 February 2025 [Page 19] Internet-Draft JMAP Essential August 2024 Email: hans-joerg@audriga.com URI: https://www.audriga.com Baum & Happel Expires 2 February 2025 [Page 20]