JMAP Blob Extensions

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

2.1. urn:ietf:params:jmap:blobext

The capability urn:ietf:params:jmap:blobext being present in the "accountCapabilities" property of an account represents support for these extended properties on that account. This capability depends on urn:ietf:params:jmap:blob ([JMAP-BLOB]); both MUST be present in the account's "accountCapabilities" and in the request's using array. If this capability is present in one or more "accountCapabilities" properties then the server MUST also include the key in the "capabilities" property.¶

The value of this property in the JMAP session "capabilities" property MUST be an empty object.¶

The value of this property in an account's "accountCapabilities" property is an object that MUST contain the following information on server capabilities and permissions for that account:¶

• resumableUploadUrl: "String|null"¶

  If present, a [URI-TEMPLATE] which supports [HTTP-RESUMABLE-UPLOADS]. This MAY be the same as the uploadUrl, and has the same keys.¶

• chunkSize: "UnsignedInt|null"¶

  The size in octets which the server uses to split large files into chunks. If a client uploads blobs with exactly this size except for the final chunk, and uses Blob/upload with DataSourceObjects referencing these chunks, it is expected that the server can optimise these chunks. Servers MUST allow other sizes for the individual data blocks in Blob/upload though, and will then choose whether to store them as an array of blobs still, or to combine them.¶

• supportedImageTypes: "String[]"¶

  The media types ([MEDIA-TYPES]) supported for ImageConvertRecipe.¶

• supportedArchiveTypes: "String[]"¶

  The archive MIME types supported for ArchiveRecipe and UnArchiveRecipe. Defined values are "application/zip", "application/x-tar", and "application/x-cpio".¶

• supportedCompressionTypes: "String[]"¶

  The compression MIME types supported for CompressRecipe and UnCompressRecipe. Defined values are "application/gzip", "application/x-bzip2", "application/x-xz", and "application/zstd".¶

• supportsRdiff: "Boolean"¶

  Whether the server supports RdiffRecipe operations. If false, the server will reject RdiffRecipe requests with an "invalidProperties" SetError.¶

• maxConvertSize: "UnsignedInt|null"¶

  If supplied, the maximum size in octets of any single input blob to a Blob/convert operation. Requests referencing a blob larger than this value MUST be rejected with a "tooLarge" SetError. If null, the server does not advertise a specific limit but MAY still reject blobs that are too large.¶

• maxArchiveEntries: "UnsignedInt|null"¶

  If supplied, the maximum number of entries allowed in an ArchiveRecipe. Requests exceeding this limit MUST be rejected with a "tooLarge" SetError. If null, the server does not advertise a specific limit but MAY still reject requests with too many entries.¶

• maxImageDimension: "UnsignedInt|null"¶

  If supplied, the maximum value accepted for width or height in an ImageConvertRecipe, in pixels. Requests exceeding this limit MUST be rejected with a "tooLarge" SetError. If null, the server does not advertise a specific limit but MAY still reject requests with dimensions that are too large.¶

{
  "urn:ietf:params:jmap:blobext": {
    "resumableUploadUrl": null,
    "chunkSize": 5242880,
    "supportedImageTypes": [
      "image/png",
      "image/jpeg",
      "image/gif"
    ],
    "supportedArchiveTypes": [
      "application/zip",
      "application/x-tar"
    ],
    "supportedCompressionTypes": [
      "application/gzip",
      "application/x-bzip2",
      "application/zstd"
    ],
    "supportsRdiff": true,
    "maxConvertSize": 104857600,
    "maxArchiveEntries": 10000,
    "maxImageDimension": 8192
  }
}

2.2. Additions to Blob/get

When this capability is present, Blob/get accepts an additional request argument:¶

• dataSourceProperties: "String[]" (default: ["blobId", "size"]) If supplied, only the properties listed in the array are returned for each DataSourceObject in the chunks array. If omitted, the default of ["blobId", "size"] is used. Available properties include blobId, size, offset, length, position, and digest:* values (e.g. digest:sha-256).¶

Blob/get also returns an additional response property (returned by default when this capability is included in using):¶

• chunks: "DataSourceObject[]"¶

  An array of one or more data source objects (as defined in [JMAP-BLOB], Section 4.2). The blob is reconstructed by concatenating the data from each data source object in the listed order. While it is expected that each data source object will reference the entire underlying chunk blob, the server MAY return offset and length values that select only a portion of a chunk's blob. The client MUST use the offset and length to determine which octets to read from each chunk.¶

2.3. Additions to DataSourceObject

When this capability is present, the DataSourceObject (as defined in [JMAP-BLOB], Section 4.2) is extended with the following additional properties. These apply both to the chunks returned by Blob/get and to DataSourceObjects used in Blob/upload. The offset and length properties are already defined in [JMAP-BLOB]; they are listed here to document their use in the chunks response context, where they describe the range of each chunk's underlying data source that contributes to the containing blob.¶

• offset: "UnsignedInt|null" The offset within the data source from which to start copying octets (see [JMAP-BLOB]). MUST fit within the data source (i.e. offset MUST be less than or equal to the data source size). If null, defaults to 0 (the start of the data source).¶

• length: "UnsignedInt|null" The number of octets to copy from the data source (see [JMAP-BLOB]). MUST fit within the data source (i.e. offset + length MUST be less than or equal to the data source size). If null, copy from offset to the end of the data source.¶

• size: "UnsignedInt|null" The full size of the chunk's underlying data source in octets.¶

• position: "UnsignedInt|null" The byte offset of the start of this chunk within the outer (containing) blob.¶

If a digest:* property (e.g. digest:sha, digest:sha-256) is included in dataSourceProperties, each DataSourceObject in the chunks array will include the corresponding digest value computed over the octets that this chunk contributes (i.e. after applying offset and length).¶

When a server provides size, position, or digest:* values in a Blob/get response, it MUST calculate them correctly. When a DataSourceObject containing size, position, or digest:* values is used in Blob/upload, the server MUST reject the object if any provided value does not match the actual data.¶

2.4. Additions to Blob/upload

When this capability is present, Blob/upload ([JMAP-BLOB], Section 4) gains the following additional request property:¶

• noPersist: "Boolean" (default: false) If true, blobs created by this call are ephemeral: they may be referenced via creation id backreferences within the same JMAP request, but the server is not required to persist them beyond the lifetime of the request. The server MAY omit ephemeral blobs from the created map of the response and from the createdIds of the final Response object if it did not create a referenceable blob. This allows servers to optimise pipelines where intermediate blobs are never needed after the request completes.¶

2.5. New method Blob/convert

Blob/convert is defined under the urn:ietf:params:jmap:blobext capability and requires that capability in the request's using array.¶

Blob/convert performs server-side transformations on blobs. Like Blob/upload ([JMAP-BLOB], Section 4), it takes an accountId and a create argument that maps creation ids to conversion request objects.¶

Each conversion request object MAY also include the following property:¶

• noPersist: "Boolean" (default: false) If true, the resulting blob is ephemeral: it may be referenced via creation id backreferences within the same JMAP request, but the server is not required to persist it beyond the lifetime of the request. The server MAY omit ephemeral blobs from the created map of the response and from the createdIds of the final Response object if it did not create a referenceable blob.¶

Each conversion request object MUST contain exactly one of the following properties, which determines the type of conversion:¶

• imageConvert: ImageConvertRecipe¶

• archive: ArchiveRecipe¶

• unArchive: UnArchiveRecipe¶

• compress: CompressRecipe¶

• unCompress: UnCompressRecipe¶

• rdiff: RdiffRecipe¶

The response has the same structure as Blob/upload ([JMAP-BLOB], Section 4): a created map of creation id to an object containing id, type, and size for each successful conversion, and a notCreated map of creation id to a SetError object for each failed conversion. The id is the blobId of the created blob. The server MAY also return an expires property as described in [JMAP-CORE], Section 6.1. Creation id backreferences (using the # prefix) resolve to this id and may be used in subsequent conversions within the same Blob/convert call or in later method calls within the same JMAP request.¶

The server MUST resolve the order of dependencies between entries in the create map and process them in an order such that all backreferences are satisfied. If a dependency cycle is detected, all members of the cycle MUST be rejected with an "invalidProperties" error.¶

[["Blob/convert", {
  "accountId": "abc",
  "create": {
    "t1": {
      "archive": {
        "type": "application/x-tar",
        "entries": [
          {
            "name": "site/index.html",
            "blobId": "Baaaa",
            "modified": "2026-03-01T12:00:00Z",
            "mode": "0644"
          },
          {
            "name": "site/logo.png",
            "blobId": "Bbbbb",
            "modified": "2026-02-15T09:30:00Z",
            "mode": "0644"
          },
          {
            "name": "site/style.css",
            "blobId": "Bcccc",
            "modified": "2026-03-01T12:00:00Z",
            "mode": "0644"
          }
        ]
      }
    },
    "t2": {
      "compress": {
        "blobId": "#t1",
        "type": "application/gzip"
      }
    }
  }
}, "0"]]

3.1. Querying Blob Chunks

This example fetches a blob's chunk structure with offsets, sizes, and SHA-256 digests:¶

[["Blob/get", {
  "accountId": "abc",
  "ids": ["B1a2b3c"],
  "dataSourceProperties": [
    "blobId", "size", "offset", "length", "position",
    "digest:sha-256"
  ]
}, "0"]]

The response shows the blob is stored as two chunks:¶

[["Blob/get", {
  "accountId": "abc",
  "list": [{
    "id": "B1a2b3c",
    "size": 10485760,
    "chunks": [
      {
        "blobId": "Bchunk1",
        "size": 5242880,
        "offset": 0,
        "length": 5242880,
        "position": 0,
        "digest:sha-256": "a1b2c3..."
      },
      {
        "blobId": "Bchunk2",
        "size": 5242880,
        "offset": 0,
        "length": 5242880,
        "position": 5242880,
        "digest:sha-256": "d4e5f6..."
      }
    ]
  }],
  "notFound": []
}, "0"]]

The position values show where each chunk fits in the assembled blob, and the digest:sha-256 values can be used to verify chunk integrity.¶

3.2. Creating a Zip Archive

This example creates a zip file containing an HTML document, a CSS file, and a JPEG image:¶

[["Blob/convert", {
  "accountId": "abc",
  "create": {
    "z1": {
      "archive": {
        "type": "application/zip",
        "entries": [
          {
            "name": "site/index.html",
            "blobId": "Baaaa"
          },
          {
            "name": "site/style.css",
            "blobId": "Bbbbb"
          },
          {
            "name": "site/photo.jpg",
            "blobId": "Bcccc"
          }
        ]
      }
    }
  }
}, "0"]]

The response includes the blobId, type, and size of the created archive:¶

[["Blob/convert", {
  "accountId": "abc",
  "created": {
    "z1": {
      "id": "B9f2a4e",
      "type": "application/zip",
      "size": 104857
    }
  },
  "notCreated": {}
}, "0"]]

3.3. Creating a Compressed Tar Archive

This example creates a .tar.gz file from the same three files. The intermediate tar blob uses noPersist since only the final compressed result is needed:¶

[["Blob/convert", {
  "accountId": "abc",
  "create": {
    "t1": {
      "noPersist": true,
      "archive": {
        "type": "application/x-tar",
        "entries": [
          {
            "name": "site/index.html",
            "blobId": "Baaaa",
            "modified": "2026-03-01T12:00:00Z",
            "mode": "0644"
          },
          {
            "name": "site/style.css",
            "blobId": "Bbbbb",
            "modified": "2026-03-01T12:00:00Z",
            "mode": "0644"
          },
          {
            "name": "site/photo.jpg",
            "blobId": "Bcccc",
            "modified": "2026-02-15T09:30:00Z",
            "mode": "0644"
          }
        ]
      }
    },
    "t2": {
      "compress": {
        "blobId": "#t1",
        "type": "application/gzip"
      }
    }
  }
}, "0"]]

Because "t1" was created with noPersist, the server may omit it from the response:¶

[["Blob/convert", {
  "accountId": "abc",
  "created": {
    "t2": {
      "id": "Bd81c7f",
      "type": "application/gzip",
      "size": 98304
    }
  },
  "notCreated": {}
}, "0"]]

3.4. Extracting a Compressed Tar Archive

This example decompresses and extracts a .tar.gz file to discover its contents. The intermediate decompressed tar blob uses noPersist:¶

[["Blob/convert", {
  "accountId": "abc",
  "create": {
    "u1": {
      "noPersist": true,
      "unCompress": {
        "blobId": "Bd81c7f",
        "type": "application/gzip"
      }
    },
    "u2": {
      "unArchive": {
        "blobId": "#u1",
        "type": "application/x-tar"
      }
    }
  }
}, "0"]]

The response for the UnArchiveRecipe includes the standard creation response properties plus an entries array listing the archive contents, with a blobId for each file entry:¶

[["Blob/convert", {
  "accountId": "abc",
  "created": {
    "u2": {
      "id": "Be3a901",
      "type": "application/x-tar",
      "size": 102400,
      "entries": [
        {
          "name": "site/index.html",
          "blobId": "Bdd001",
          "entryType": "file",
          "modified": "2026-03-01T12:00:00Z",
          "mode": "0644"
        },
        {
          "name": "site/style.css",
          "blobId": "Bdd002",
          "entryType": "file",
          "modified": "2026-03-01T12:00:00Z",
          "mode": "0644"
        },
        {
          "name": "site/photo.jpg",
          "blobId": "Bdd003",
          "entryType": "file",
          "modified": "2026-02-15T09:30:00Z",
          "mode": "0644"
        }
      ]
    }
  },
  "notCreated": {}
}, "0"]]

The returned blobIds ("Bdd001", "Bdd002", "Bdd003") can be used to download individual files or as inputs to further Blob/convert operations.¶

4.1. Resource Consumption

Several operations defined in this document can consume significant server resources.¶

Archive and compression operations may require substantial CPU and memory. Servers SHOULD impose reasonable limits on archive size, number of entries, nesting depth of archives within archives, compression ratios (to mitigate zip bomb attacks), and total processing time. Servers SHOULD reject requests that would exceed these limits with a "tooLarge" or "serverFail" error as appropriate.¶

Image conversion can also consume significant resources, especially for very large images or high output dimensions.¶

The rdiff operations can also be resource-intensive, particularly for large blobs. Servers SHOULD impose limits on the size of blobs that can be used as inputs to rdiff operations.¶

Servers SHOULD advertise their limits via the maxConvertSize, maxArchiveEntries, and maxImageDimension capability properties so that clients can avoid making requests that will be rejected. Even when these properties are not advertised, servers SHOULD set sensible internal limits and reject requests that exceed them.¶

4.2. Archive Path Traversal

Archive formats allow entry names containing path separators and relative path components such as "../". Malicious archives may use names like "../../etc/passwd" to attempt directory traversal. While UnArchiveRecipe only returns entry metadata and blob references (not files on the server filesystem), clients that extract archive contents to a filesystem MUST validate entry names and reject or sanitize paths containing ".." components or absolute paths. Servers SHOULD reject ArchiveRecipe requests containing entry names with ".." path components.¶

4.3. Content Smuggling

The ability to split content into multiple blobs, recombine them via Blob/upload, and apply rdiff patches may be used to bypass security scanners that inspect blob content. Servers that perform content scanning SHOULD scan the output of Blob/convert operations as well as the inputs.¶

5.1. JMAP Capability Registration for urn:ietf:params:jmap:blobext

IANA is requested to register the "Blob Extended" Capability as follows:¶

Capability Name: urn:ietf:params:jmap:blobext¶

Intended use: common¶

Change Controller: IETF¶

Specification document: this document¶

Security and privacy considerations: this document, Security Considerations¶

5.2. JMAP Error Code Registrations

IANA is requested to register the following entries in the "JMAP Error Codes" registry:¶