JMAP Guide for Migration and Data Portability

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¶

{
  "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.¶
• 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:¶

• 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.¶
• /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.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".¶

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