JMAP Blob Management

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

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Sometimes JMAP ([JMAP-CORE]) 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.¶

2. Addition to the Capabilities Object

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

This document defines one additional capability URI.¶

{
  "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. DataSourceObject

A DataSourceObject describes a source of data for use in Blob/set. It MUST contain exactly one of either data:asText or data:asBase64 (for inline data) or blobId (for a reference to an existing blob). The data:asText and data:asBase64 properties MUST NOT both be present in the same DataSourceObject.¶

• data:asText: "String|null"¶

  The data represented as a UTF-8 string.¶

• data:asBase64: "String|null"¶

  The data encoded as base64 ([BASE64]).¶

• blobId: "BlobId"¶

  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. Only meaningful in the chunks array of a Blob/get response. 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).¶

When a server provides size, position, or digest:* values in a Blob/get response, it MUST calculate them correctly.¶

A DataSourceObject used in Blob/set is invalid 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 "notFound" SetError.¶

4. Blob/set

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

This method creates, touches, and destroys blobs. It is a standard Foo/set method ([JMAP-CORE], Section 5.3) with the following blob-specific behaviours:¶

• Blobs have no state, as in [JMAP-BLOB]: Blob/get returns no state string, and there is no Blob/changes method. Blob/set does not take an ifInState argument, and a non-null value is rejected with an "invalidArguments" error. Unlike other Foo/set methods, the response has oldState and newState both null.¶

• create: "Id[BlobCreateObject]|null"¶

  A map of a creation id to a BlobCreateObject describing the blob to create, or null if no blobs are to be created.¶

• update: A map of blobId to a patch object. The only property a client can request to change is expires; all other properties can only be set to their existing values. The server can honour the requested expires (by not returning an expires in the updated BlobObject) or return a different expires value if it applied a different lifetime. The purpose of update is to "touch" the blob, refreshing its lifetime on the server. If the blobId does not exist, it MUST be reported in a notUpdated map with a "notFound" SetError.¶

• destroy: The server MUST reject any 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 optimise pipelines where intermediate blobs are never needed after the request completes.¶

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

Apart from oldState and newState, the response is a standard Foo/set response. The objects in the created and updated maps are BlobObjects. If an update set a new expires, the server returns a BlobObject with the actual expires that was applied; if the server accepted the requested value it need not return an expires in the BlobObject.¶

A BlobObject has the following properties:¶

• id: "BlobId"¶

  The id 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 Blob/convert result (see "Blob/convert").¶

• expires: "UTCDate|null"¶

  See "The expires Response Property" below.¶

5. Blob/get

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

This method retrieves blob data. It is a standard Foo/get method ([JMAP-CORE], Section 5.1) with the following additional parameters and a custom response.¶

In addition to the standard accountId, ids, and properties arguments, Blob/get accepts:¶

• 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"])¶

  If supplied, only the properties listed in the array are returned for each DataSourceObject in the chunks array. 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 requestable properties in the properties array 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 response value is null and isEncodingProblem is set to true.¶

• 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. Only returned if explicitly requested in properties. 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:¶

  • 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/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. This is read-only — it reflects the metadata stored in the blob content and is not a user-editable property.¶

• chunks¶

  An array of DataSourceObjects describing the internal chunk structure of the blob (see below). Only returned if explicitly requested in properties. The properties returned for each DataSourceObject are controlled by the dataSourceProperties argument.¶

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 are specified (i.e., both null), the default properties are data and size. Otherwise, the client MUST specify the properties to return.¶

The response contains a list of objects, one per blobId. Each object contains the requested properties plus:¶

• id: "BlobId"¶

  The blobId of the blob.¶

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

• chunks: "DataSourceObject[]"¶

  Present only if chunks was requested in properties. An array of one or more data source objects describing the internal chunk structure of the blob. The blob is reconstructed by concatenating the data from each data source object in the listed order. The client MUST use the offset and length of each DataSourceObject to determine which octets to read from each chunk's underlying blob.¶

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

The response also contains:¶

• accountId: "Id"¶

  The id of the account used for the operation.¶

• notFound: "Id[]"¶

  An array of blobIds that were not found.¶

6. Blob/lookup

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

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: "BlobId[]"¶

  The blobIds to look up.¶

The response contains:¶

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

Access control: 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.¶

7. The "expires" Response Property

The Blob/set response and the Blob/convert response include the following property on each BlobObject:¶

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

8. Blob/convert

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

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

• extract: ExtractRecipe¶

• compress: CompressRecipe¶

• decompress: DecompressRecipe¶

• delta: DeltaRecipe¶

• patch: PatchRecipe¶

The response has the same structure as Blob/set: a created map of creation id to a BlobObject 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 response also includes an expires property on each BlobObject (see "The expires Response Property" above).¶

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 response for that creation also includes:¶

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

If the conversion failed entirely and no usable output could be produced, the server MUST return a conversionFailed SetError in the notCreated map.¶

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

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 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 "notFound" SetError. 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.¶

9. Examples

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

[["Blob/set", {
  "accountId": "abc",
  "created": {
    "b1": {
      "id": "Babc123",
      "type": "text/plain",
      "size": 13
    }
  },
  "notCreated": null
}, "0"]]

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

[["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"]]

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

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

[["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"]]

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

[["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"]]

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

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

[["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"]]

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

[["Blob/convert", {
  "accountId": "abc",
  "created": {
    "d1": {
      "id": "Bdelta789",
      "type": "text/x-diff",
      "size": 1234
    }
  },
  "notCreated": {}
}, "0"]]

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

[["Blob/convert", {
  "accountId": "abc",
  "created": {
    "p1": {
      "id": "Breconstructed",
      "type": "application/octet-stream",
      "size": 48576
    }
  },
  "notCreated": {}
}, "0"]]

10. Security Considerations

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

11. IANA Considerations

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

• Added created to ArchiveEntry.¶

• Carried over from RFC9404 what this document had lost: Blob/lookup does not return ids of objects the user cannot discover, the meaning of "reference" and the "Can Reference Blobs" restriction, the server's handling of untrusted blob data, scanning of concatenated blobs, the cost of digests, the request size limit for inline data, and the hints about fetching size.¶

• Digest algorithm names come from the "Hash Algorithms for HTTP Digest Fields" registry of RFC9530 (which replaces the RFC3230 registry RFC9404 used), not the "Hash Function Textual Names" registry, where SHA-1 is "sha-1". Servers list algorithms in their order of preference, only ones they can compute efficiently, and clients use the first they support; "sha" (deprecated there) remains allowed.¶

• A Blob/get digest is over exactly the octets returned for the range, including when the range runs past the end of the blob.¶

• Added optional size and digest:<algorithm> properties to the BlobCreateObject, checked against the whole blob being created, so a client can verify an assembled or inline upload in the same call. (RFC9404 defined neither; per-source values were already checked on each DataSourceObject.)¶

• Restated the registration policy and designated expert guidance for the "JMAP Data Types" registry, so they are not left only in the obsoleted RFC9404.¶

• Blobs have no state, as in RFC9404: Blob/set takes no ifInState and returns null oldState and newState. (Thanks to Mark Atwood.)¶

• The dataSourceProperties default is ["blobId", "offset", "length"], so chunks fed back into Blob/set keep their ranges. (Thanks to Mark Atwood.)¶

• Named the SetErrors for Blob/set: "invalidProperties" for an invalid DataSourceObject, "tooLarge" for exceeding maxDataSources or maxSizeBlobSet, and "notFound" for an unknown blobId. An unsupported digest:* name in Blob/get is "invalidArguments". (Thanks to Mark Atwood.)¶

• BlobObject size is null until a deferred Blob/convert result is generated, and a deferred result whose generation fails is treated as not existing everywhere. (Thanks to Mark Atwood.)¶

• The id, type, and size of an ExtractRecipe result are those of the archive it extracted. (Thanks to Mark Atwood.)¶

• IANA: the "urn:ietf:params:jmap:blob" capability is marked obsolete, "unknownDataType" is updated rather than registered again, and the "JMAP Data Types" registry's fields are defined here. RFC9404 is now an informative reference. (Thanks to Mark Atwood.)¶

• Editorial: removed a duplicate .tar.gz example, used "media type" throughout, added a reference for EXIF, and removed a stray back matter marker from the text. (Thanks to Mark Atwood.)¶

draft-ietf-jmap-blobext-02¶

• Listed chunks as a requestable Blob/get property and fixed the chunks example to request it.¶

• Explained the purpose of the DataSourceObject position property.¶

• Servers that do not store blobs in chunks return a single chunk covering the whole blob.¶

• Added a Blob/lookup example.¶

• Extended acknowledgements.¶

draft-ietf-jmap-blobext-01¶

• Added per-account uploadUrl capability property, allowing servers to direct uploads for individual accounts to a different endpoint. Uploads to this URL return an expires property in addition to the standard upload response fields.¶

• Blob/set is now a standard Foo/set method with state strings (ifInState/oldState/newState). Renamed UploadObject to BlobCreateObject. The expires property can be set via update.¶

• Removed hardcoded type value lists from normative text (supportedArchiveTypes, supportedCompressTypes, supportedDeltaTypes, ArchiveRecipe, CompressRecipe). Values are now described as media types per [MEDIA-TYPES]. Format-specific considerations subsections remain as informative examples.¶

• Obsoletes RFC9404: incorporated all content from RFC9404 into this document, making it self-contained.¶

• Renamed Blob/upload to Blob/set, making it a standard Foo/set operation with create, update, and destroy at the top level.¶

• Added urn:ietf:params:jmap:blob capability definition (previously defined only in RFC9404).¶

• Added Blob/lookup method (previously defined only in RFC9404).¶

• Added full DataSourceObject definition (merging RFC9404 base definition with blobext extensions).¶

• Added full Blob/get definition (merging RFC9404 base definition with blobext extensions).¶

• Added inline blob creation example.¶

• Updated IANA section to include blob capability, unknownDataType error code, and JMAP Data Types registry.¶

draft-ietf-jmap-blobext-00¶

• No changes, just uploading with the new name¶

draft-gondwana-jmap-blobext-06¶

• Removed resumableUploadUrl capability property.¶

• Added isIncomplete and description response properties for partial conversion results.¶

• Added conversionFailed error code for total conversion failure.¶

• Made expires always present (null if indeterminate) rather than optional.¶

• Split supportedImageTypes into supportedImageReadTypes and supportedImageWriteTypes.¶

• Made all supported type lists nullable (null = not supported).¶

• Changed imageData duration from UnsignedInt to Number for sub-second precision.¶

• Clarified imageData comment as read-only.¶

• Added EXIF orientation reference and digest algorithm registry reference.¶

• Fixed grammar and consistent error ordering across recipes.¶

• Structural reorder: DataSourceObject before Blob/get, ArchiveEntry promoted to peer section.¶

draft-gondwana-jmap-blobext-05¶

• Added imageData property to Blob/get for image/video metadata extraction (dimensions, orientation, date, GPS, duration).¶

• Renamed UnArchiveRecipe to ExtractRecipe and UnCompressRecipe to DecompressRecipe.¶

• Split capability lists into separate create/extract pairs: supportedArchiveTypes/supportedExtractTypes, supportedCompressTypes/supportedDecompressTypes, supportedDeltaTypes/supportedPatchTypes.¶

draft-gondwana-jmap-blobext-04¶

• Moved noPersist from top-level Blob/upload property to per-item in the create map, for consistency with Blob/convert.¶

draft-gondwana-jmap-blobext-03¶

• Added update (touch) and destroy operations to Blob/upload.¶

draft-gondwana-jmap-blobext-02¶

• Replaced RdiffRecipe with generic DeltaRecipe and PatchRecipe using media types (rdiff, bsdiff, unified diff).¶

• Replaced supportsRdiff with supportedPatchTypes capability.¶

• Clarified chunkSize as a hint, not a definitive statement.¶

• Added lazy generation text for Blob/convert (deferred output).¶

• Defined "expires" response property for blob creation responses.¶

draft-gondwana-jmap-blobext-01¶

• Added Blob/convert method with recipes for image conversion, archiving, compression, and rdiff.¶

• Added noPersist option to Blob/upload and Blob/convert for ephemeral intermediate blobs in pipelines.¶

• Removed rdiffSignature and rdiffPatch from Blob/get and DataSourceObject.¶

• Fleshed out capability object with supported type lists.¶

• Added capability and method examples.¶

• Expanded Security Considerations.¶

• Updated IANA registrations with error codes and corrected capability URI.¶

• Added limit capability properties: maxConvertSize, maxArchiveEntries, maxImageDimension, and supportsRdiff.¶

• Added dependency resolution requirement for Blob/convert create map with cycle detection.¶

• Now updates both RFC 8620 and RFC 9404.¶

draft-gondwana-jmap-blobext-00¶

• initial proposal¶

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

14. References

Author's Address