JMAP Blob Extensions

Addition to the Capabilities Object The capabilities object is returned as part of the JMAP Session object; see , Section 2. This document defines an additional capability URI.

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 (); 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 which supports . This MAY be the same as the uploadUrl, and has the same keys. 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/upload with DataSourceObjects referencing these chunks, the server can optimise storage of 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 () 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". supportedPatchTypes: "String[]" The delta/patch media types supported for DeltaRecipe and PatchRecipe. Defined values are "application/x-rdiff-delta", "application/x-bsdiff", and "text/x-diff" (unified diff). An empty array means no delta/patch operations are supported. 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.

Capability Example

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

Additions to DataSourceObject When this capability is present, the DataSourceObject (as defined in , 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 ; 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 ). 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 ). 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.

Additions to Blob/upload When this capability is present, Blob/upload (, 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.

The "expires" response property When this capability is present, the following blob creation responses MAY include an additional property: the resumableUploadUrl response, the Blob/upload response (, Section 4), and the Blob/convert response defined below. 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 or absent, the server provides no hint about the blob's lifetime. Clients that need the blob to persist beyond the expires time should reference it from a persistent object (e.g., a FileNode or an Email) before it expires.

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 (, 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 delta: DeltaRecipe patch: PatchRecipe The response has the same structure as Blob/upload (, 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 (see "The expires response property" above). 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. 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 deferred generation later fails (e.g., the source blob has expired), the server SHOULD return an appropriate HTTP error when the blob is downloaded. If the exact size of the output is not yet known, the server MUST omit the size property from the response 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. 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.

ImageConvertRecipe An ImageConvertRecipe converts an image blob to a different format or size. It is an object with the following properties: blobId: "BlobId" The blobId of the source image. type: "String" Media type () of the image to create (e.g. "image/png"). MUST be one of the values in the server's supportedImageTypes capability. width: "UnsignedInt|null" Maximum width in pixels of the image to create. If null, the server preserves the source width (or scales proportionally if only height is given). height: "UnsignedInt|null" Maximum height in pixels of the image to create. If null, the server preserves the source height (or scales proportionally if only width is given). ignoreAspect: "Boolean|null" If true, resize to exactly the given width and height, even if the aspect ratio is changed. If null or false, the image is scaled to fit within the given dimensions while preserving the aspect ratio. 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 server selects a sensible default (typically white). 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 the target format supports it. autoOrient: "Boolean|null" If true, automatically rotate and flip the image according to its EXIF orientation tag, then reset the tag. If null or false, the image data is not reoriented. Errors: "notFound" — the referenced blobId does not exist. "invalidProperties" — the type is not in supportedImageTypes, or the source blob is not a supported image format. "tooLarge" — the source blob exceeds maxConvertSize, or the requested dimensions exceed maxImageDimension.

ArchiveRecipe An ArchiveRecipe creates an archive blob from a list of entries. It is an object with the following properties: type: "String" The MIME type of the archive to create. MUST be one of the values in the server's supportedArchiveTypes capability. Defined values are "application/zip", "application/x-tar", and "application/x-cpio". entries: "ArchiveEntry[]" An array of ArchiveEntry objects describing the contents of the archive. Errors: "notFound" — a referenced entry blobId does not exist. "invalidProperties" — the type is not in supportedArchiveTypes; an entry has an unsupported entryType for the archive format; or a required field (e.g. linkTarget for symlink entries) is missing. "tooLarge" — the number of entries exceeds maxArchiveEntries, or a referenced blob exceeds maxConvertSize.

ArchiveEntry An ArchiveEntry describes a single entry in an archive. It is used both as input (in ArchiveRecipe) and as output (in UnArchiveRecipe results). 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 "/". blobId: "BlobId|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. Violating these constraints is an "invalidProperties" error. 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). The server MUST reject entries with unsupported types for the chosen archive format with an "invalidProperties" error. modified: "UTCDate|null" The modification time of the entry as an RFC 3339 timestamp. If null, defaults to the current server time. 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.

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 mode, uid, gid, ownerName, groupName, devMajor, and devMinor properties are ignored.

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 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. The following example creates a .tar.gz containing three files in a single Blob/convert call, using a backreference from the archive creation to the compression step:

Considerations for application/x-cpio The cpio format supports all entry types except that ownerName and groupName are not supported. The comment and compressionMethod properties are ignored.

UnArchiveRecipe An UnArchiveRecipe extracts the entry listing from an existing archive blob. It is an object with the following properties: blobId: "BlobId" The blobId of the archive to extract. type: "String|null" The MIME type of the archive format. If null, the server SHOULD attempt to auto-detect the format from the blob content (e.g. by inspecting magic bytes). If auto-detection fails, the server MUST return an "unknownFormat" error. In addition to the standard creation response properties, a successful UnArchiveRecipe result includes: entries: "ArchiveEntry[]" An array of ArchiveEntry objects describing the contents of the archive. Each file entry will have a blobId that can be used to access the content of that entry. Errors: "notFound" — the referenced blobId does not exist. "unknownFormat" — the server could not determine or does not support the archive format. "invalidProperties" — the type is not in supportedArchiveTypes. "tooLarge" — the source blob exceeds maxConvertSize.

CompressRecipe A CompressRecipe compresses a blob using a specified compression algorithm. It is an object with the following properties: blobId: "BlobId" The blobId of the data to compress. type: "String" The MIME type of the compression format to use. MUST be one of the values in the server's supportedCompressionTypes capability. Defined values are "application/gzip", "application/x-bzip2", "application/x-xz", and "application/zstd". 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 behaviour. Errors: "notFound" — the referenced blobId does not exist. "invalidProperties" — the type is not in supportedCompressionTypes. "tooLarge" — the source blob exceeds maxConvertSize.

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.

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.

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.

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.

UnCompressRecipe An UnCompressRecipe decompresses a compressed blob. It is an object with the following properties: blobId: "BlobId" The blobId of the compressed data to decompress. type: "String|null" The MIME type of the compression format. If null, the server SHOULD attempt to auto-detect the format from magic bytes. If auto-detection fails, the server MUST return an "unknownFormat" error. Errors: "notFound" — the referenced blobId does not exist. "unknownFormat" — the server could not determine or does not support the compression format. "invalidProperties" — the type is not in supportedCompressionTypes. "tooLarge" — the source blob exceeds maxConvertSize.

DeltaRecipe A DeltaRecipe computes a delta between two blobs. It is an object with the following properties: blobId: "BlobId" The blobId of the original (base) blob. newBlobId: "BlobId" 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 supportedPatchTypes capability. The result blob is the computed delta, which can be applied to the base blob using PatchRecipe to reconstruct the new blob. Errors: "notFound" — a referenced blobId does not exist. "invalidProperties" — the type is not in supportedPatchTypes. "tooLarge" — a referenced blob exceeds maxConvertSize.

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.

Considerations for application/x-bsdiff The server produces a bsdiff-format patch. Both blobs must fit in memory; servers MAY reject very large blobs with a "tooLarge" error.

Considerations for text/x-diff The server produces a unified diff. Both blobs are interpreted as text. If either blob contains content that cannot be interpreted as text, the server MUST return an "unknownFormat" error.

PatchRecipe A PatchRecipe applies a delta to a base blob to produce a new blob. It is an object with the following properties: blobId: "BlobId" The blobId of the base blob to patch. deltaBlobId: "BlobId" 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. The result blob is the patched output. Errors: "notFound" — a referenced blobId does not exist. "invalidProperties" — the deltaType is not in supportedPatchTypes. "unknownFormat" — the delta blob is not valid for the specified format (e.g., corrupt or malformed delta data). "tooLarge" — a referenced blob exceeds maxConvertSize.