Internet-Draft JMAP Blob November 2026
Gondwana Expires 22 May 2027 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-ietf-jmap-blobext-05
Obsoletes:
9404 (if approved)
Updates:
8620 (if approved)
Published:
Intended Status:
Standards Track
Expires:
Author:
B. Gondwana
Fastmail

JMAP Blob Management

Abstract

The JSON Meta Application Protocol (JMAP) base protocol provides the ability to upload and download arbitrary binary data, called "blobs", via HTTP POST and GET on a defined endpoint.

This document defines JMAP methods to create and read blobs within a JMAP request, to find which objects reference a blob, to build large blobs from chunks, and to convert blobs on the server: converting images, creating and extracting archives, compressing and decompressing, and computing and applying deltas. It obsoletes RFC 9404 and updates RFC 8620.

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 May 2027.

▲

Table of Contents

1. Introduction

The JSON Meta Application Protocol (JMAP) [JMAP-CORE] provides an endpoint to upload and download blobs. Sometimes JMAP interactions require creating a blob and then referencing it. Embedding blobs directly into the JMAP method calls array can reduce round trips.

Likewise, when fetching an object, it can be useful to also fetch the raw content of that object without a separate round trip.

When JMAP is proxied through a system that applies additional access restrictions, it can be useful to know which objects reference any particular blob; this document defines a way to discover those references.

For large blobs, a client may wish to upload data in chunks and have the server assemble them efficiently, or retrieve information about how the server has stored a blob internally.

Many applications also benefit from server-side transformations (converting images, creating or unpacking archives, compressing or decompressing data, or computing and applying deltas) without needing to download and re-upload blob content.

This document obsoletes [JMAP-BLOB]. It keeps the urn:ietf:params:jmap:blob capability's Blob/get and Blob/lookup methods, in extended form, under a new capability, urn:ietf:params:jmap:blob2, and replaces Blob/upload with a standard Blob/set method. It adds digests, chunk information, and image metadata to Blob/get, and adds the Blob/convert method. As [JMAP-BLOB] did, it updates [JMAP-CORE], and it carries forward the "JMAP Data Types" registry that [JMAP-BLOB] created. The Blob/copy method of [JMAP-CORE] is unchanged.

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.

Type signatures, examples, and property descriptions in this document follow the conventions established in Section 1.1 of [JMAP-CORE]. Data types defined in the core specification are also used in this document.

1.2. Terminology

This document uses the same terminology as [JMAP-CORE].

A "blob" is a sequence of zero or more octets, identified by a blobId, as in Section 6 of [JMAP-CORE]. Blobs are immutable. A "recipe" is the object in a Blob/convert creation that says which conversion to perform (see Section 3.6).

2. Addition to the Capabilities Object

The capabilities object is returned as part of the JMAP Session object; see Section 2 of [JMAP-CORE].

This document defines one additional capability URI.

2.1. urn:ietf:params:jmap:blob2

The capability urn:ietf:params:jmap:blob2 being present in the "accountCapabilities" property of an account represents support for the blob methods defined in this document: Blob/set, Blob/get, Blob/lookup, and Blob/convert. Servers that include this capability in one or more "accountCapabilities" properties MUST also include it in the "capabilities" property.

A server MAY also advertise urn:ietf:params:jmap:blob (as defined in [JMAP-BLOB]) to support older clients, but a client MUST NOT include both urn:ietf:params:jmap:blob and urn:ietf:params:jmap:blob2 in the using array of the same request. A request that includes both is not valid, and the server SHOULD reject the whole request with a "urn:ietf:params:jmap:error:unknownCapability" error (Section 3.6.1 of [JMAP-CORE]), as it would a request whose using array names a capability that it does not support. The blob2 capability supersedes the blob capability and does not depend on it.

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:

  • maxSizeBlobSet: "UnsignedInt|null"

    The maximum size of a blob (in octets) that the server will allow to be created (including blobs created by concatenating multiple data sources together). A creation that would exceed it is rejected with a "tooLarge" SetError. If null, the server does not advertise a specific limit but MAY still reject blobs that are too large.

  • maxDataSources: "UnsignedInt"

    The maximum number of DataSourceObjects allowed in the data array of a single creation in Blob/set. Servers MUST support at least 64 DataSourceObjects per creation. A creation with more is rejected with a "tooLarge" SetError.

  • supportedTypeNames: "String[]"

    An array of data type names that the server supports for Blob/lookup. The values are the names listed in the IANA "JMAP Data Types" registry. If the array is empty, the server does not support Blob/lookup. Servers MAY include private type names not in the registry; clients MUST ignore names they do not recognize. Clients MUST also ignore names that they do recognize if the corresponding capability for that type name is not present in the 'capabilities' section of the session object, because that means that the name has been used as a private type rather than a capability that the client knows.

  • supportedDigestAlgorithms: "String[]"

    An array of digest algorithms supported for Blob/get and for checking digests in Blob/set, from the IANA "Hash Algorithms for HTTP Digest Fields" registry [DIGEST-FIELDS], expressed in lowercase (e.g., "sha-256", "sha").

    The server lists the algorithms in its order of preference, and SHOULD only list ones it can compute efficiently: a server that stores a digest of each blob, for example, can return that one without reading the blob. Clients SHOULD use the first algorithm in the list that they support. An algorithm the registry marks as deprecated, such as "sha" (SHA-1), which [JMAP-BLOB] servers and clients commonly use, MAY still be listed. SHA-1 is vulnerable to collision attacks: it detects accidental corruption, but a client relying on a digest to detect deliberate tampering SHOULD NOT use it.

  • uploadUrl: "String|null"

    A URI template (optionally containing {accountId}) for uploading blobs via HTTP POST for this account, in the same format as the session-level uploadUrl defined in Section 2 of [JMAP-CORE]. Servers MUST still provide the session-level uploadUrl; this per-account URL is an alternative that MAY point to a different server or be more efficient for this account. Uploads to this URL return a JSON object with the same properties as the session-level upload response, plus an expires property as defined in Section 3.1. If null, clients SHOULD use the session-level uploadUrl.

  • chunkSize: "UnsignedInt|null"

    A hint indicating the preferred chunk size in octets. If a client uploads blobs with exactly this size except for the final chunk, and uses Blob/set with DataSourceObjects referencing these chunks, the server can optimize storage of these chunks. Servers MUST allow other sizes for the individual data blocks in Blob/set though, and will then choose whether to store them as an array of blobs still, or to combine them.

  • supportedImageReadTypes: "String[]|null"

    The media types ([MEDIA-TYPES]) that the server can read as input to ImageConvertRecipe. If null, the server does not support image conversion.

  • supportedImageWriteTypes: "String[]|null"

    The media types ([MEDIA-TYPES]) that the server can produce as output from ImageConvertRecipe. If null, the server does not support image conversion.

  • supportedArchiveTypes: "String[]|null"

    The archive media types ([MEDIA-TYPES]) supported for creating archives via ArchiveRecipe. If null, the server does not support archive creation.

  • supportedExtractTypes: "String[]|null"

    The archive media types supported for extracting archives via ExtractRecipe. This MAY include types not in supportedArchiveTypes (e.g., "application/vnd.ms-tnef"). If null, the server does not support archive extraction.

  • supportedCompressTypes: "String[]|null"

    The compression media types ([MEDIA-TYPES]) supported for compressing via CompressRecipe. If null, the server does not support compression.

  • supportedDecompressTypes: "String[]|null"

    The compression media types supported for decompressing via DecompressRecipe. This MAY include types not in supportedCompressTypes. If null, the server does not support decompression.

  • supportedDeltaTypes: "String[]|null"

    The delta media types ([MEDIA-TYPES]) supported for computing deltas via DeltaRecipe. If null, the server does not support delta computation.

  • supportedPatchTypes: "String[]|null"

    The delta media types supported for applying patches via PatchRecipe. This MAY include types not in supportedDeltaTypes. If null, the server does not support patch application.

  • maxConvertSize: "UnsignedInt|null"

    If supplied, the maximum size in octets of any single input blob to a Blob/convert operation, and of the blob it produces. Requests referencing a blob larger than this value, or whose result would be larger, MUST be rejected with a "tooLarge" SetError. A server stops producing a result once it passes the limit, so a small input that expands without bound (such as a compressed "bomb") costs no more than this. 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, counted after expanding any entry that stands for many (such as a FileNode Directory with recurse in [JMAP-FILENODE]), and in an archive an ExtractRecipe reads. 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.

2.1.1. Capability Example

{
  "urn:ietf:params:jmap:blob2": {
    "maxSizeBlobSet": 52428800,
    "maxDataSources": 64,
    "supportedTypeNames": ["Email", "Thread", "Mailbox"],
    "supportedDigestAlgorithms": ["sha-256", "sha"],
    "uploadUrl": "https://up.example.com/jmap/upload/{accountId}/",
    "chunkSize": 5242880,
    "supportedImageReadTypes": [
      "image/png",
      "image/jpeg",
      "image/gif",
      "image/tiff"
    ],
    "supportedImageWriteTypes": [
      "image/png",
      "image/jpeg"
    ],
    "supportedArchiveTypes": [
      "application/zip",
      "application/x-tar"
    ],
    "supportedExtractTypes": [
      "application/zip",
      "application/x-tar",
      "application/vnd.ms-tnef"
    ],
    "supportedCompressTypes": [
      "application/gzip",
      "application/zstd"
    ],
    "supportedDecompressTypes": [
      "application/gzip",
      "application/x-bzip2",
      "application/zstd"
    ],
    "supportedDeltaTypes": [
      "application/x-rdiff-delta",
      "text/x-diff"
    ],
    "supportedPatchTypes": [
      "application/x-rdiff-delta",
      "text/x-diff"
    ],
    "maxConvertSize": 104857600,
    "maxArchiveEntries": 10000,
    "maxImageDimension": 8192
  }
}

3. Blobs

The methods in this section are defined under the urn:ietf:params:jmap:blob2 capability, and a request that calls any of them MUST include that capability in its using array.

As in [JMAP-BLOB], blobs have no state: there is no state string for blobs and no Blob/changes method.

3.1. BlobObject

A BlobObject describes a blob that Blob/set or Blob/convert created or updated. It has the following properties:

  • id: "Id"

    The blobId of the blob.

  • type: "String|null"

    The media type of the blob, or null if unknown.

  • size: "UnsignedInt|null"

    The size of the blob in octets, or null if the server has not yet generated a deferred Blob/convert result (see Section 3.6.2).

  • expires: "UTCDate|null"

    A hint from the server indicating the likely availability of the blob. The blob is likely to remain available until this time, and likely not to be available after it. This is not a guarantee in either direction: the server MAY garbage collect the blob before this time if it is unreferenced, and MAY retain it longer. If null, the server does not have a specific expiry time for the blob.

Clients that need a blob to persist beyond its expires time should reference it from a persistent object, such as a FileNode [JMAP-FILENODE] or an Email [JMAP-MAIL], before it expires.

3.2. DataSourceObject

A DataSourceObject describes a source of data for a blob created by Blob/set, or a chunk of a blob in a Blob/get response (see Section 3.4). In Blob/set it contains exactly one of data:asText or data:asBase64 (for inline data) or blobId (for a reference to an existing blob), and omits the other two.

  • data:asText: "String"

    The data represented as a UTF-8 string.

  • data:asBase64: "String"

    The data encoded as base64 ([BASE64]).

  • blobId: "Id"

    The blobId of an existing blob whose octets are to be copied into the new blob.

  • offset: "UnsignedInt|null"

    The offset (in octets) within the data source from which to start copying. If null, defaults to 0 (the start of the data source).

  • length: "UnsignedInt|null"

    The number of octets to copy from the data source. If null, copy from offset to the end of the data source.

  • size: "UnsignedInt|null"

    The full size of the data source in octets. In the chunks array of a Blob/get response this is the size of the underlying chunk blob.

  • position: "UnsignedInt|null"

    The byte offset of the start of this data source within the outer (containing) blob. This value is redundant with the sum of the length values of the preceding chunks, but it allows a client to locate the chunk covering a particular byte range without fetching or summing every earlier chunk, and when a DataSourceObject is reused in Blob/set it acts as a consistency check that the chunk is being placed where the client expects.

A DataSourceObject in the chunks array of a Blob/get response MAY also include digest:* properties (e.g. digest:sha-256) when those names are included in the dataSourceProperties request argument. Each digest value is computed over the octets that the chunk contributes to the blob (i.e. after applying offset and length).

A DataSourceObject used in Blob/set is invalid if it contains more than one of data:asText, data:asBase64, and blobId, whatever their values, or none of them; if data:asText is not valid UTF-8; if data:asBase64 is not valid base64; if the range given by offset and length begins or extends past the end of the data; or if any size, position, or digest:* value it contains does not match the actual data. The server MUST NOT guess the user's intent: it MUST reject the creation with an "invalidProperties" SetError whose properties is ["data"].

If a blobId does not exist, or the user cannot access it, the server MUST reject the creation with a "blobNotFound" SetError (Section 10.6.3 of [JMAP-MAIL]), with a notFound property listing each such blobId, as Email/set does (Section 4.6 of [JMAP-MAIL]). The "notFound" SetError is for the ids a /set updates or destroys, not for the blobs a creation refers to. A blobId that is a creation id backreference (using the # prefix) and does not resolve to a blob, for example because that creation failed, is a blobId that does not exist.

3.3. Blob/set

This is a standard "/set" method as described in Section 5.3 of [JMAP-CORE], which creates, touches, and destroys blobs, with the following differences:

  • There is no ifInState argument, and a non-null value is rejected with an "invalidArguments" error. The response has oldState and newState both null.

  • The create argument maps creation ids to BlobCreateObjects, described below. The objects in the created map of the response are BlobObjects (Section 3.1).

  • The only property an update can change is expires; any other property can only be set to its existing value. The purpose of an update is to "touch" the blob, refreshing its lifetime on the server. The server can apply the requested expires or a different lifetime; if it applies a different one, the entry in the updated map gives the expires it applied.

  • The server MUST reject the destruction of a blob that is still referenced by another object with a "blobHasReference" SetError.

A BlobCreateObject has the following properties:

  • data: "DataSourceObject[]"

    An array of zero or more DataSourceObjects. The new blob is formed by concatenating the data described by each DataSourceObject in the order given.

  • type: "String|null" (default: null)

    A media type hint ([MEDIA-TYPES]) for the blob. The server MAY use this when setting the Content-Type of a subsequent download of the blob, but is not required to. The server MAY infer the type itself and override the client's hint.

  • size: "UnsignedInt|null" (default: null)

    The size in octets of the blob being created: the total of the octets contributed by all the DataSourceObjects. If given, the server MUST reject the creation with an "invalidProperties" SetError if the resulting blob is a different size.

  • digest:<algorithm>: "String|null" (default: null)

    The base64-encoded digest of the whole blob being created, computed with the named algorithm, as returned by Blob/get. A client MAY give any number of these. The server MUST verify each one against the resulting blob, and if any does not match, MUST reject the creation with an "invalidProperties" SetError and MUST NOT create the blob. A server MUST reject a digest whose algorithm is not in its supportedDigestAlgorithms capability with an "invalidProperties" SetError, so that a client never believes an unchecked blob was verified.

    This lets a client that uploaded content in several pieces, or sent it inline, confirm in the same call that the server holds exactly the bytes it meant to send, without a further Blob/get.

  • 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. This allows servers to optimize pipelines where intermediate blobs are never needed after the request completes.

A blobId in a DataSourceObject can be a creation id backreference to another entry in the create map of the same call. 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.

Inline data (data:asText and data:asBase64) is part of the JMAP request, so it counts towards the server's maxSizeRequest limit (Section 2 of [JMAP-CORE]), and base64 makes it about a third larger than the octets it carries. Clients SHOULD consider using the upload endpoint (Section 6.1 of [JMAP-CORE]) for blobs larger than a megabyte, and referencing the uploaded blob by blobId.

3.4. Blob/get

This is a standard "/get" method as described in Section 5.1 of [JMAP-CORE], with the following differences:

  • The ids argument MUST NOT be null, since a server cannot list every blob in an account. The server rejects a null ids with an "invalidArguments" error.

  • The response has no state property.

  • There are additional arguments, properties, and response properties, described below.

Blob/get takes the following additional arguments:

  • offset: "UnsignedInt|null" (default: null)

    The starting byte position within the blob. If null, defaults to 0.

  • length: "UnsignedInt|null" (default: null)

    The number of bytes to return. If null, returns all bytes from offset to the end of the blob.

  • dataSourceProperties: "String[]" (default: ["blobId", "offset", "length"])

    The properties to return for each DataSourceObject in the chunks property. This argument has no effect unless chunks is included in properties. Available properties include blobId, size, offset, length, position, and digest:* values where * is an algorithm name from the supportedDigestAlgorithms capability (e.g. digest:sha-256).

The properties that can be requested in the properties argument are:

  • data:asText

    The data in the selected range as a UTF-8 string. If the selected bytes are not valid UTF-8 (including truncation in the middle of a multi-octet sequence), the value is null and isEncodingProblem is set to true. JSON parsers are not all consistent in handling data that is not UTF-8, so a server MUST NOT return such octets here.

  • data:asBase64

    The data in the selected range encoded as base64 ([BASE64]).

  • data

    Returns data:asText if the selected bytes are valid UTF-8, otherwise returns data:asBase64.

  • digest:<algorithm>

    The base64-encoded digest of the octets in the selected range, computed using the named algorithm: exactly the octets that a data property would return. If the range extends past the end of the blob, that is the octets from offset to the end, or no octets if offset is past the end.

  • size

    The total size of the blob in octets, regardless of the range selected. Servers SHOULD store the size of a blob in a form that is cheap to read, and clients SHOULD request only size when that is all they need, since fetching blob content can be much more expensive for the server.

  • imageData

    If the blob is an image or video type and the server can extract metadata, this is an ImageData object. Otherwise null. The server MAY need to read the blob content to compute this data, so clients SHOULD only request it when needed. Since blobs are immutable, the result for a given blobId will never change, and the server SHOULD cache it.

    An ImageData object has the following properties, all taken from metadata in the blob's content:

    • width: "UnsignedInt|null"

      Width of the image in pixels, if known.

    • height: "UnsignedInt|null"

      Height of the image in pixels, if known.

    • orientation: "UnsignedInt|null"

      EXIF orientation value (1-8) as defined in [EXIF]. If present, indicates how the image should be rotated or flipped for display.

    • date: "UTCDate|null"

      Date the image or video was captured (from EXIF DateTimeOriginal or equivalent), if present.

    • gps: "ImageGPS|null"

      GPS coordinates from EXIF, if present. An ImageGPS object has the following properties:

      • latitude: "Number"

        Latitude in decimal degrees.

      • longitude: "Number"

        Longitude in decimal degrees.

    • duration: "Number|null"

      Duration in seconds for video content, if known. This is a floating-point number to allow sub-second precision.

    • comment: "String|null"

      Embedded EXIF comment or description, if present.

  • chunks

    An array of one or more DataSourceObjects describing the internal chunk structure of the blob. The blob is reconstructed by concatenating the data from each DataSourceObject in the listed order. The client MUST use the offset and length of each to determine which octets to read from that chunk's underlying blob. The dataSourceProperties argument selects the properties returned for each DataSourceObject.

    A server that does not store the blob in chunks returns a single DataSourceObject covering the entire blob, with blobId set to the blob's own id, offset 0, length and size equal to the size of the blob, and position 0. This allows clients to process the chunks array the same way regardless of how the server stores blobs.

A digest:* name in properties or dataSourceProperties whose algorithm is not in the server's supportedDigestAlgorithms capability is rejected with an "invalidArguments" error.

If neither offset nor length is given (i.e., both are null), the default properties are data and size. Otherwise, the client MUST specify the properties to return.

Data returned inline counts towards the response as a whole, so a server MAY reject a Blob/get whose data, data:asText or data:asBase64 properties would return more than maxSizeRequest (Section 2 of [JMAP-CORE]) octets in total with a "requestTooLarge" error. A client that gets one asks for smaller ranges with offset and length, or downloads the blob. Digests and size are not data, and do not count.

Each object in the list of the response also has the following properties:

  • isEncodingProblem: "Boolean" (default: false)

    Set to true if data or data:asText was requested but the selected range is not valid UTF-8.

  • isTruncated: "Boolean" (default: false)

    Set to true if the selected range extends past the end of the blob. In this case, only the bytes from offset to the end of the blob (or an empty string if offset is past the end) are returned. A null length selects everything from offset to the end, so it sets isTruncated only if offset is past the end of the blob.

3.5. Blob/lookup

This method provides a reverse lookup: given a set of blobIds, it returns which objects of specified data types reference those blobs.

Since different data types have different semantics of "contains", the definition of "reference" is somewhat loose, but roughly means "you could discover this blobId by looking at this object or at other objects recursively contained within this object". For example, with a server that supports [JMAP-MAIL], if any Email in a Mailbox references a blob, then that Mailbox references the blob, and any Thread containing such an Email references it too. This does not work the other way: an Email that references a Mailbox in its mailboxIds does not thereby reference the blobs of other Emails in that Mailbox.

The method takes the following arguments:

  • accountId: "Id"

    The id of the account to use.

  • typeNames: "String[]"

    A list of data type names to search. Only type names listed in the server's supportedTypeNames capability, and whose "JMAP Data Types" registry entry has "Can Reference Blobs" set to "Yes" (or private types defined to reference blobs), are valid. If a type name is not known by the server or the associated capability has not been requested in using, the server MUST return an "unknownDataType" error.

  • ids: "Id[]"

    The blobIds to look up.

The response has the following properties:

  • accountId: "Id"

    The id of the account used for the operation.

  • list: "BlobInfo[]"

    A list of BlobInfo objects, one per blobId. A BlobInfo object has the following properties:

    • id: "Id"

      The blobId queried.

    • matchedIds: "String[Id[]]"

      An object mapping each requested type name to an array of object ids of that type that reference this blob. If no objects of that type reference this blob, the array is empty.

If a blob is not visible to the authenticated user or does not exist on the server at all, the server MUST still return an empty array for each type name. This ensures that the response does not reveal whether the blob exists but is inaccessible to the user. Likewise, the server MUST NOT return the id of an object that the user could not discover by querying. For example, if an Email that references the blob is in a Mailbox the user cannot see, that Email's id MUST NOT appear in matchedIds.

3.6. Blob/convert

Blob/convert performs server-side transformations on blobs. Like Blob/set, it takes an accountId and a create argument that maps creation ids to conversion request objects.

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

It MAY also include a noPersist property, with the same meaning as in a BlobCreateObject (Section 3.3).

The response has the accountId, created, and notCreated properties of a Blob/set response, and no others: a created map of creation id to a BlobObject (Section 3.1) for each successful conversion, and a notCreated map of creation id to a SetError object for each failed conversion.

If the conversion completed but encountered problems (e.g., a corrupt archive where some entries extracted successfully but others did not, or a truncated compressed stream that partially decompressed), the BlobObject for that creation also has the following properties:

  • isIncomplete: "Boolean" (default: false)

    If true, the conversion did not complete cleanly. The output blob may be partial or missing some content.

  • description: "String|null"

    A human-readable description of the problem, if any.

Creation id backreferences (using the # prefix) resolve to the id of the created blob 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 orders the conversions in the create map, and rejects a dependency cycle, as Blob/set does.

A recipe that reads a blob in some format determines that format from the blob's content, unless the recipe names the format of that input (the type of an ExtractRecipe or DecompressRecipe, or the deltaType of a PatchRecipe). Any media type held with the blob, such as the type given to Blob/set, the Content-Type of an upload, or one inferred from an archive entry's name, is at most a hint, and the server MUST NOT reject a source that its content shows is in a supported format because that media type says otherwise or is null. So an image extracted from an archive can be given straight to an ImageConvertRecipe.

When the request's using array also includes urn:ietf:params:jmap:conditional, Blob/convert accepts the "ifUnchangedBy" and "atomic" arguments of [JMAP-CONDITIONAL], which mean what they mean for Blob/set. If "atomic" is true, either every conversion in the create map succeeds, or the server creates no blob and rejects the method with an "atomicFailure" error, which MAY carry a notCreated map. A conversion whose result would be incomplete has failed for this purpose: the server does not return it with isIncomplete set, but treats it as it would a "conversionFailed" SetError. A server that cannot apply the method as a unit rejects it with a "cannotApplyAtomically" error.

3.6.1. Conversion Errors

A conversion that fails is rejected with one of the following SetErrors:

  • "blobNotFound": a blobId it refers to does not exist, or the user cannot access it. The SetError has a notFound property listing every such blobId, as for a DataSourceObject (Section 3.2).

  • "invalidProperties": the recipe is of a kind the server does not support, names a media type that is not in the corresponding capability, or is otherwise not valid. The properties of the SetError are there to help a person find the problem, so the server lists whatever it judges most useful.

  • "unknownFormat": the server could not determine the format of an input, the format it found is not one it supports for this recipe, or the input is not valid for the format the recipe names.

  • "tooLarge": an input or the result exceeds maxConvertSize, or the recipe exceeds maxArchiveEntries or maxImageDimension.

  • "conversionFailed": the conversion failed entirely and produced no usable output.

3.6.2. Deferred Results

A server MAY return a blobId for a conversion result without immediately generating the output data. In this case the server MUST generate the data when the blob is later accessed (e.g., via a download request or as input to another operation). This allows the server to respond quickly to Blob/convert requests while deferring expensive work such as image resizing or archive creation. The returned blobId MUST be usable in all contexts where a regular blobId is accepted. If the exact size of the output is not yet known, the server returns a null size for that creation. If a client later requests the size property via Blob/get for a deferred blob, the server MUST generate the blob at that point and return the actual size.

If the deferred generation later fails (e.g., the source blob has expired), the server treats the blob as not existing: a download returns 404 (Not Found), Blob/get reports it in notFound, and a creation in Blob/set or Blob/convert that references it fails with a "blobNotFound" SetError.

Only the Blob/convert response can report isIncomplete, so a server MUST NOT defer a kind of conversion whose result can be incomplete: once its creation has succeeded there is no response left to say so. If generating a deferred blob nonetheless gives an incomplete result, the generation has failed, as above.

A deferred blob MUST NOT become the content of an object that outlives it, such as a FileNode or an Email: before such an object references it, the server generates it, and fails the create or update that would reference it, with the SetError the generation gave, if it can't. Otherwise the object would point at content that may never exist. The data a deferred blob is generated from is what the inputs held when the server processed the Blob/convert, even if an input that can change (such as a FileNode named in an ArchiveEntry) has changed since.

3.6.3. ImageConvertRecipe

An ImageConvertRecipe converts an image blob to a different format or size. The server reads source images in the formats listed in supportedImageReadTypes. It is an object with the following properties:

  • blobId: "Id"

    The blobId of the source image.

  • type: "String"

    Media type ([MEDIA-TYPES]) of the image to create (e.g. "image/png"). MUST be one of the values in the server's supportedImageWriteTypes capability.

  • width: "UnsignedInt|null"

    Maximum width in pixels of the image to create, or null for no limit on the width.

  • height: "UnsignedInt|null"

    Maximum height in pixels of the image to create, or null for no limit on the height.

    If either width or height is given, the server scales the image, preserving its aspect ratio, to the largest size that fits within the limits given; a null one does not constrain it. So giving only width scales the height in proportion. An image that already fits is not enlarged. If both are null, the image keeps its size. Dimensions are those of the image as displayed, after its orientation is applied (see autoOrient).

  • ignoreAspect: "Boolean|null"

    If true, the image to create is exactly width by height pixels, stretched, squashed, or enlarged as needed; a null width or height is the source's own. If null or false, the aspect ratio is preserved as above.

  • quality: "UnsignedInt|null"

    Compression quality for lossy formats, as a value from 1 (lowest quality, smallest file) to 100 (highest quality, largest file). Only meaningful for formats that support lossy compression such as image/jpeg and image/webp. If null, the server selects a sensible default.

  • colorSpace: "String|null"

    The color space for the output image. Defined values are "sRGB" and "grayscale". If null, the server preserves the source image's color space where possible.

  • background: "String|null"

    A fill color to use when the source image has transparency but the target format does not support it (e.g. converting PNG to JPEG). The value is a CSS-style hex color string (e.g. "#ffffff" for white). If null, the fill color is white ("#ffffff"). Transparent areas are composited over the fill color, so partly transparent pixels blend into it.

  • stripMetadata: "Boolean|null"

    If true, strip image metadata such as EXIF, XMP, and IPTC data from the output. If null or false, the server preserves metadata where it can.

  • autoOrient: "Boolean|null" (default: false)

    If true, the server applies the source image's orientation (such as the EXIF Orientation tag) to the pixel data and gives the output no orientation of its own, so it displays the same in any viewer. If null or false, the server copies the orientation to the output and leaves the pixel data as it is. A server that cannot carry the orientation into the output, because the target format has nowhere to keep it, stripMetadata is true, or the server cannot write that metadata, MUST apply it as if autoOrient were true rather than lose it. Either way, the output displays as the source does.

3.6.4. ArchiveRecipe

An ArchiveRecipe creates an archive blob from a list of entries. It is an object with the following properties:

  • type: "String"

    The media type ([MEDIA-TYPES]) of the archive to create. MUST be one of the values in the server's supportedArchiveTypes capability.

  • entries: "ArchiveEntry[]"

    An array of ArchiveEntry objects (Section 3.6.5) describing the contents of the archive.

3.6.5. ArchiveEntry

An ArchiveEntry describes a single entry in an archive. It is used both as input (in ArchiveRecipe) and as output (in ExtractRecipe results). An ArchiveEntry in an ArchiveRecipe that breaks a constraint below, or has an entryType the archive format does not support, is an "invalidProperties" error. It is an object with the following properties:

  • name: "String"

    The path of the entry within the archive. Directory entries MUST have a name ending with "/". Servers SHOULD reject an ArchiveRecipe with an entry name that has a ".." path component (see Section 5.4).

  • blobId: "Id|null"

    The blobId of the content for this entry. MUST be non-null for file entries. MUST be null or absent for directory, symlink, hardlink, fifo, and device entries.

  • entryType: "String|null"

    The type of the entry. If null, defaults to "file". Defined values are "file" (a regular file, the default), "directory", "symlink" (a symbolic link), "hardlink" (a hard link), "fifo" (a named pipe), "blockDevice" (a block device node), and "charDevice" (a character device node).

  • modified: "UTCDate|null"

    The modification time of the entry. If null, defaults to the current server time.

  • created: "UTCDate|null"

    The creation time of the entry, or null if it has none. Formats that cannot record a creation time ignore it.

  • linkTarget: "String|null"

    The target path for symlink and hardlink entries. MUST be non-null when entryType is "symlink" or "hardlink". MUST be null for all other entry types.

  • mode: "String|null"

    Unix file permissions as an octal string (e.g. "0755", "0644"). If null, the server chooses a reasonable default. This is represented as a string rather than an integer to avoid ambiguity between octal and decimal interpretation.

  • uid: "UnsignedInt|null"

    The numeric user ID of the entry owner.

  • gid: "UnsignedInt|null"

    The numeric group ID of the entry owner.

  • ownerName: "String|null"

    The user name of the entry owner.

  • groupName: "String|null"

    The group name of the entry owner.

  • devMajor: "UnsignedInt|null"

    The major device number for "blockDevice" and "charDevice" entries.

  • devMinor: "UnsignedInt|null"

    The minor device number for "blockDevice" and "charDevice" entries.

  • comment: "String|null"

    A comment string for this entry.

  • compressionMethod: "String|null"

    The per-entry compression method. Defined values are "store" (no compression) and "deflate". If null, the server chooses a reasonable default.

3.6.5.1. Considerations for application/zip

The zip format only supports "file" and "directory" entry types. The comment and compressionMethod properties are only meaningful for zip archives. The created time is stored in an extra field. The mode, uid, gid, ownerName, groupName, devMajor, and devMinor properties are ignored.

3.6.5.2. Considerations for application/x-tar

The tar format supports all entry types. The mode, uid, gid, ownerName, groupName, devMajor, and devMinor properties are meaningful for tar archives. The created, comment, and compressionMethod properties are ignored.

Tar archives are not inherently compressed. To create a compressed tar archive (e.g. a .tar.gz file), first create the tar archive using ArchiveRecipe, then compress the result using CompressRecipe (see Section 4.5).

3.6.5.3. Considerations for application/x-cpio

The cpio format supports all entry types, but not the ownerName and groupName properties. The created, comment, and compressionMethod properties are ignored.

3.6.6. ExtractRecipe

An ExtractRecipe extracts the entry listing from an existing archive blob. It is an object with the following properties:

  • blobId: "Id"

    The blobId of the archive to extract.

  • type: "String|null"

    The media type of the archive format. MUST be one of the values in the server's supportedExtractTypes capability. If null, the server determines the format from the blob's content (e.g. by inspecting magic bytes).

An ExtractRecipe creates no blob. The id, type, and size in its result are those of the archive blob that was extracted, and a backreference to its creation id resolves to that blob. noPersist has no effect on an ExtractRecipe. A successful ExtractRecipe result also has the following property:

  • entries: "ArchiveEntry[]"

    An array of ArchiveEntry objects describing the contents of the archive. Each file entry has a blobId that can be used to access the content of that entry.

3.6.7. CompressRecipe

A CompressRecipe compresses a blob using a specified compression algorithm. It is an object with the following properties:

  • blobId: "Id"

    The blobId of the data to compress.

  • type: "String"

    The media type ([MEDIA-TYPES]) of the compression format to use. MUST be one of the values in the server's supportedCompressTypes capability.

  • level: "UnsignedInt|null"

    The compression level, where higher values produce smaller output at the cost of more CPU time. If null, the server uses the format's default level. The valid range depends on the format; if the requested level is outside the valid range, the server SHOULD use the nearest valid value.

  • checksum: "Boolean|null"

    If true, include an integrity checksum in the compressed output. If null, the server uses the format's default behavior.

3.6.7.1. Considerations for application/gzip

Compression level ranges from 1 (fastest) to 9 (best compression). The default is typically 6. Gzip always includes a CRC-32 checksum; the checksum property is ignored.

3.6.7.2. Considerations for application/x-bzip2

Compression level ranges from 1 (fastest, 100k block size) to 9 (best compression, 900k block size). The default is typically 9. Bzip2 always includes a CRC-32 checksum; the checksum property is ignored.

3.6.7.3. Considerations for application/x-xz

Compression level ranges from 0 (fastest) to 9 (best compression). The default is typically 6. Xz always includes an integrity check; if checksum is true the server SHOULD use SHA-256, otherwise CRC-64 is used by default.

3.6.7.4. Considerations for application/zstd

Compression level ranges from 1 (fastest) to 22 (best compression). The default is typically 3. If checksum is true, an xxHash-64 checksum is included in the frame; the default is false.

3.6.8. DecompressRecipe

A DecompressRecipe decompresses a compressed blob. It is an object with the following properties:

  • blobId: "Id"

    The blobId of the compressed data to decompress.

  • type: "String|null"

    The media type of the compression format. MUST be one of the values in the server's supportedDecompressTypes capability. If null, the server determines the format from the blob's content (e.g. by inspecting magic bytes).

3.6.9. DeltaRecipe

A DeltaRecipe computes a delta between two blobs. It is an object with the following properties:

  • blobId: "Id"

    The blobId of the original (base) blob.

  • newBlobId: "Id"

    The blobId of the new blob to compare against.

  • type: "String"

    The media type of the delta format to produce. MUST be one of the values in the server's supportedDeltaTypes capability.

The result blob is the computed delta, which can be applied to the base blob using PatchRecipe to reconstruct the new blob.

3.6.9.1. Considerations for application/x-rdiff-delta

The server computes an rdiff signature of the base blob and then generates a delta against the new blob. The resulting delta blob can only be applied to the exact base blob used to generate it.

3.6.9.2. Considerations for application/x-bsdiff

The server produces a bsdiff-format patch. Computing one needs both blobs in memory, so a server may set a lower size limit for this format, rejecting larger blobs with "tooLarge".

3.6.9.3. Considerations for text/x-diff

The server produces a unified diff. Both blobs are interpreted as text; if either cannot be, the conversion fails with "unknownFormat".

3.6.10. PatchRecipe

A PatchRecipe applies a delta to a base blob to produce a new blob. It is an object with the following properties:

  • blobId: "Id"

    The blobId of the base blob to patch.

  • deltaBlobId: "Id"

    The blobId of the delta to apply.

  • deltaType: "String"

    The media type of the delta format. MUST be one of the values in the server's supportedPatchTypes capability. It is not called type because in every recipe type describes the output, and the output of a patch is not a delta.

The result blob is the patched output.

3.6.10.1. Considerations for text/x-diff

A patch applies exactly or not at all: every line a hunk gives as context or as removed MUST match the base blob exactly, with no fuzz (no lines of context ignored), or the patch fails with "conversionFailed". The server MAY apply a hunk at a different line than the hunk gives (an offset), as common patch tools do, if its lines match there. A patch whose context does not match would otherwise give content nobody wrote.

4. Examples

4.1. Uploading a Blob Inline

This example creates a blob from inline text data:

[["Blob/set", {
  "accountId": "abc",
  "create": {
    "b1": {
      "data": [{"data:asText": "Hello, world!"}],
      "type": "text/plain"
    }
  }
}, "0"]]

The response:

[["Blob/set", {
  "accountId": "abc",
  "oldState": null,
  "newState": null,
  "created": {
    "b1": {
      "id": "Babc123",
      "type": "text/plain",
      "size": 13,
      "expires": "2026-03-08T12:00:00Z"
    }
  },
  "notCreated": null
}, "0"]]

4.2. Querying Blob Chunks

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

[["Blob/get", {
  "accountId": "abc",
  "ids": ["B1a2b3c"],
  "properties": ["size", "chunks"],
  "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.

4.3. Looking Up Blob References

This example finds which Mailbox and Email objects reference two blobs:

[["Blob/lookup", {
  "accountId": "abc",
  "typeNames": ["Mailbox", "Email"],
  "ids": ["Bfirst", "Bsecond"]
}, "0"]]

The response shows that the first blob is referenced by two emails in the same mailbox, and the second blob is not referenced by any objects of the requested types (or is not visible to the user):

[["Blob/lookup", {
  "accountId": "abc",
  "list": [
    {
      "id": "Bfirst",
      "matchedIds": {
        "Mailbox": ["M1"],
        "Email": ["E1", "E2"]
      }
    },
    {
      "id": "Bsecond",
      "matchedIds": {
        "Mailbox": [],
        "Email": []
      }
    }
  ]
}, "0"]]

4.4. 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,
      "expires": "2026-03-08T12:00:00Z"
    }
  },
  "notCreated": {}
}, "0"]]

4.5. 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,
      "expires": "2026-03-08T12:00:00Z"
    }
  },
  "notCreated": {}
}, "0"]]

4.6. 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,
      "decompress": {
        "blobId": "Bd81c7f",
        "type": "application/gzip"
      }
    },
    "u2": {
      "extract": {
        "blobId": "#u1",
        "type": "application/x-tar"
      }
    }
  }
}, "0"]]

The response for the ExtractRecipe gives the id, type, and size of the archive it extracted, which here is the decompressed tar created by "u1", and 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,
      "expires": "2026-03-08T12:00:00Z",
      "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.7. Computing and Applying a Delta

This example computes a unified diff between two versions of a text file:

[["Blob/convert", {
  "accountId": "abc",
  "create": {
    "d1": {
      "delta": {
        "blobId": "BoldVersion",
        "newBlobId": "BnewVersion",
        "type": "text/x-diff"
      }
    }
  }
}, "0"]]

The response contains the delta blob:

[["Blob/convert", {
  "accountId": "abc",
  "created": {
    "d1": {
      "id": "Bdelta789",
      "type": "text/x-diff",
      "size": 1234,
      "expires": "2026-03-08T12:00:00Z"
    }
  },
  "notCreated": {}
}, "0"]]

The delta can later be applied to the original blob to reconstruct the new version:

[["Blob/convert", {
  "accountId": "abc",
  "create": {
    "p1": {
      "patch": {
        "blobId": "BoldVersion",
        "deltaBlobId": "Bdelta789",
        "deltaType": "text/x-diff"
      }
    }
  }
}, "0"]]

The result is a blob identical to "BnewVersion":

[["Blob/convert", {
  "accountId": "abc",
  "created": {
    "p1": {
      "id": "Breconstructed",
      "type": "application/octet-stream",
      "size": 48576,
      "expires": "2026-03-08T12:00:00Z"
    }
  },
  "notCreated": {}
}, "0"]]

5. Security Considerations

All security considerations from [JMAP-CORE] apply to this document.

5.1. Access Control

Servers MUST NOT allow a client to access blob data that the authenticated user does not have permission to access, whether by Blob/get, by copying it into a new blob with Blob/set, or as the input to Blob/convert. A blob the user cannot access is treated as one that does not exist, so that the response does not reveal that it exists. Blob/lookup likewise reveals no object that the user could not discover otherwise (Section 3.5).

5.2. Untrusted Data

A server rejects a malformed DataSourceObject rather than guess what the client meant (Section 3.2), and never returns octets that are not valid UTF-8 in data:asText (Section 3.4), since JSON parsers are not all consistent in handling them.

The server MUST NOT trust that the data given to Blob/set is a well-formed instance of its stated media type. If the server parses a blob (to convert it, extract an archive, or read image metadata), it SHOULD only use hardened parsers designed to deal with arbitrary untrusted data. The server SHOULD NOT reject data on the grounds that it is not a valid specimen of the stated type.

5.3. 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" SetError.

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

Digest algorithms can be expensive to calculate over large blobs. Servers that share resources between users SHOULD track resource use by clients and rate-limit expensive operations, such as computing digests in Blob/get or verifying them in Blob/set, to avoid resource starvation.

Delta and patch 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 these 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. Deferring a conversion (Section 3.6.2) moves its cost to whoever first reads the result, which can be a later request or a different client.

5.4. 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 ExtractRecipe 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. A server likewise rejects such names in an ArchiveRecipe (Section 3.6.5), so that archives it creates do not carry them.

5.5. Content Smuggling

The ability to split content into multiple blobs, recombine them via Blob/set, and apply delta patches may be used to bypass security scanners that inspect blob content: carefully chosen data sources can recreate dangerous content on the far side of a scanner watching the upload endpoint. Servers that perform content scanning SHOULD provide a hook to scan the blob that results from concatenating the data sources in Blob/set, in the same way as blobs arriving through the upload endpoint, and SHOULD scan the output of Blob/convert operations as well as the inputs.

6. IANA Considerations

6.1. JMAP Capability Registration for urn:ietf:params:jmap:blob2

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

Capability Name: urn:ietf:params:jmap:blob2

Intended use: common

Change Controller: IETF

Specification document: this document

Security and privacy considerations: this document, Section 5

6.2. JMAP Capability Update for urn:ietf:params:jmap:blob

IANA is requested to update the "urn:ietf:params:jmap:blob" capability, registered by [JMAP-BLOB], as follows:

Capability Name: urn:ietf:params:jmap:blob

Specification document: [JMAP-BLOB], superseded by this document

Intended use: obsolete

Change Controller: IETF

Security and privacy considerations: Section 5 of [JMAP-BLOB]

6.3. JMAP Error Code Update for unknownDataType

IANA is requested to update the "unknownDataType" entry in the "JMAP Error Codes" registry, registered by [JMAP-BLOB], as follows:

JMAP Error Code: unknownDataType

Intended use: common

Change Controller: IETF

Description: The server does not recognize the data type specified in the typeNames array of a Blob/lookup request, or the capability required to use that data type has not been included in the using array of the request.

Reference: this document (replacing [JMAP-BLOB])

6.4. JMAP Error Code Registrations

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

6.4.1. unknownFormat

JMAP Error Code: unknownFormat

Intended use: common

Change Controller: IETF

Description: The server could not determine the format of an input to a blob conversion, the format is not one it supports for that conversion, or the input is not valid for the format the request names.

Reference: this document

6.4.2. blobHasReference

JMAP Error Code: blobHasReference

Intended use: common

Change Controller: IETF

Description: The blob cannot be destroyed because it is still referenced by one or more objects. The client can use Blob/lookup to discover which objects reference the blob.

Reference: this document

6.4.3. conversionFailed

JMAP Error Code: conversionFailed

Intended use: common

Change Controller: IETF

Description: The server was unable to perform the requested blob conversion.

Reference: this document

6.5. JMAP Data Types Registry

IANA is requested to update the reference for the "JMAP Data Types" registry to this document (replacing the reference to [JMAP-BLOB]). The registry's fields, registration policy, and instructions to the designated experts below are carried forward unchanged from [JMAP-BLOB], so that they remain defined in a current document. The existing entries are unchanged.

Each entry has the following fields:

Type Name: the name of the data type, as used in typeNames in Blob/lookup and as a key in a StateChange object (Section 7.1 of [JMAP-CORE]).

Can Reference Blobs: "Yes" if objects of this type can reference blobs (see Section 3.5), otherwise "No".

Can Use for State Change: "Yes" if the type name can appear in a StateChange object, otherwise "No".

Capability: the capability URI that a client includes in using to use this data type.

Reference: the document that defines the data type.

The registration policy for this registry is "Specification Required" [IANA-GUIDELINES]. Either an RFC or a similarly stable reference document defines a JMAP Data Type and associated capability.

IANA will appoint designated experts to review requests for additions to this registry, with guidance to allow any registration that provides a stable document describing the capability and control over the URI namespace to which the capability URI points.

7. Changes

EDITOR: please remove this section before publication.

The source of this document exists on github at: https://github.com/brong/draft-gondwana-jmap-blobext/

draft-ietf-jmap-blobext-05

draft-ietf-jmap-blobext-04

draft-ietf-jmap-blobext-03

draft-ietf-jmap-blobext-02

draft-ietf-jmap-blobext-01

draft-ietf-jmap-blobext-00

draft-gondwana-jmap-blobext-06

draft-gondwana-jmap-blobext-05

draft-gondwana-jmap-blobext-04

draft-gondwana-jmap-blobext-03

draft-gondwana-jmap-blobext-02

draft-gondwana-jmap-blobext-01

draft-gondwana-jmap-blobext-00

8. Acknowledgements

The authors would like to thank Mauro De Gennaro, Ben Bucksch, Ricardo Signes, Neil Jenkins, Ken Murchison, Arnt Gulbrandsen, Seph Gentle, Matthew Horsfall, Mark Atwood, and the members of the JMAP Working Group at the IETF for their contributions and feedback.

9. References

9.1. Normative References

[BASE64]
Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, , <https://www.rfc-editor.org/rfc/rfc4648>.
[DIGEST-FIELDS]
Polli, R. and L. Pardue, "Digest Fields", RFC 9530, DOI 10.17487/RFC9530, , <https://www.rfc-editor.org/rfc/rfc9530>.
[JMAP-CORE]
Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, , <https://www.rfc-editor.org/rfc/rfc8620>.
[JMAP-MAIL]
Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, , <https://www.rfc-editor.org/rfc/rfc8621>.
[MEDIA-TYPES]
Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, , <https://www.rfc-editor.org/rfc/rfc6838>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.

9.2. Informative References

[EXIF]
Camera & Imaging Products Association, "Exchangeable image file format for digital still cameras: Exif Version 3.0", CIPA DC-008-2023, .
[IANA-GUIDELINES]
Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/rfc/rfc8126>.
[JMAP-BLOB]
Gondwana, B., Ed., "JSON Meta Application Protocol (JMAP) Blob Management Extension", RFC 9404, DOI 10.17487/RFC9404, , <https://www.rfc-editor.org/rfc/rfc9404>.
[JMAP-CONDITIONAL]
Gondwana, B., "JMAP Conditional Set", Work in Progress, Internet-Draft, draft-ietf-jmap-conditional-03, , <https://datatracker.ietf.org/doc/html/draft-ietf-jmap-conditional-03>.
[JMAP-FILENODE]
Gondwana, B., "JMAP File Storage extension", Work in Progress, Internet-Draft, draft-ietf-jmap-filenode-21, , <https://datatracker.ietf.org/doc/html/draft-ietf-jmap-filenode-21>.

Author's Address

Bron Gondwana
Fastmail