JMAP for Migration and Data Portability

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 8 September 2023.¶

Copyright Notice

Copyright (c) 2023 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 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

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 meeting 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.¶

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 are likely to not want to implement the full feature set that JMAP Core currently defines. Currently, there is no clear guidance on which parts of the JMAP specification are essential to migration and data portablity use cases.¶

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. It also defines a simplified version of the JMAP Request that has even less requirements.¶

2. 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].¶

3. Session Resource

For a lot of basic portability use of 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).¶
• This implies that 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 static JSON file without the username property. The accountId is then the same as the username.¶

4. 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.¶

5. Standard Methods and Naming Convention

JMAP core defines 6 standard methods, which are then reused in most JMAP extensions. 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 /set .¶

/changes, /copy as well as /queryChanges are not required as all data can already be retrieved and set with above's three methods.¶

6. Binary Data

The advanced Blob/copy method call is not essential.¶

7. Simplified REST-like JMAP API

Structured data exchange over JMAP usually involves processing JMAP Request JSON payloads. This might impose unnecessary requirements for certain use cases of JMAP. Likely scenarios in which this is beneficiary are situations in which portability needs to be provided due to regulatory requirements or when migrating user data away from legacy platforms.¶

For rapid development of a JMAP API without support for batching, the essential properties of the Request object can instead be implemented as URI with query parameters.¶

• apiUrlSimple: String The URL to use for JMAP API requests. THE URL MUST contain accountId and methodCall. One MAY use ids.¶

{
  ...
  "capabilities": {
    ...,
    "urn:ietf:params:jmap:core-simple": {}
  },
  "apiUrlSimple": "https://jmap.me/api
    /?accountId=<account-id>&methodCall=<methodCall>&ids=<ids>"
}

8. Security considerations

All security considerations of JMAP [RFC8620] apply to this specification.¶

9. IANA considerations

10. Acknowledgements

Bron Gondwana, Neil Jenkins, Alexey Melnikov, Ken Murchison, Robert Stepanek and the JMAP working group at the IETF.¶

Appendix A. Required features for JMAP Portability

Not all features of JMAP Core are required for basic data portability use cases. Tables 1-4 list the required features for a minimal implementation of JMAP for Migration and Portability in more detail. It distinguishes between two common scenarios:¶

• Export use cases: Minimal implementation for exporting data from an application server¶
• Import use cases: Minimal implementation for importing data into an application server¶

The last column lists more advanced features of JMAP Core recommended for data portability use cases.¶

• 1: Can be modeled as a static JSON file for a lot of scenarios. Section 3 details for which use cases a static JSON file should be sufficient.¶
• 2: Some data types require using ids in /get .¶
• 3: maxObjectsInGet might not be sufficiently high in some products. Then /query and paging is required.¶
• 4: 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.¶

Appendix B. JMAP Debug extension

{
  "logs" : [
    {
      "file" : "Logger.php",
      "level" : "info",
      "line" : 32,
      "message" : "Array Logger has been successfully initialized",
      "timestamp" : "2022-01-18T10:26:56+01:00"
    },
    {
      "file" : "ErrorHandler.php",
      "level" : "warning",
      "line" : 52,
      "message" : "fopen(bridge.php):
        failed to open stream: No such file or directory",
      "timestamp" : "2022-01-18T10:26:56+01:00"
    },
    ...
  ],
  "methodResponses" : [
    [
      "Core/echo",
      ...

Appendix C. Backend Info

{
  "capabilities": {
    "urn:ietf:params:jmap:core:backendinfo": {
      "backend": "OpenXPort/Horde v1.0.0",
      "product": "Horde Webmailer v1.0.0",
      "environment": "PHP v5.5",
      "capabilityInfo": {
        "urn:ietf:params:jmap:sieve": {
          "backend": "Cyrus timsieved",
          "product": "Horde Ingo v1.0.0",
          "fileType": "SIEVE/HORDE"
        }
      }
    }
  },
    ...
  }
}

Appendix D. Turning JMAP Portability into a different version of JMAP Core

Because this document contradicts in parts what was stated in JMAP Core (e.g., leave out certain required properties), one might also realize this as a separate protocol that is basically just a subset of JMAP Core. Then we would need to advertise this as a new capability.¶

{
  "capabilities": {
    ...,
    "urn:ietf:params:jmap:core-essential-portability": {}
  },
  "apiUrl": "https://jmap.example.com/api/",
  "downloadUrl": "https://jmap.example.com
    /download/{accountId}/{blobId}/{name}?accept={type}",
  "uploadUrl": "https://jmap.example.com/upload/{accountId}/"
}

Authors' Addresses