JMAP File Storage extension

1.1. Conventions Used in This Document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

2.1. urn:ietf:params:jmap:filenode

The capability urn:ietf:params:jmap:filenode being present in the "accountCapabilities" property of an account represents support for the FileNode datatype. Servers that include the capability in one or more "accountCapabilities" properties MUST also include the property 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:¶

• maxFileNodeDepth: "UnsignedInt|null"¶

  The maximum depth of the FileNode hierarchy (that is, one more than the maximum number of ancestors a FileNode may have), or null for no limit.¶

• maxSizeFileNodeName: "UnsignedInt"¶

  The maximum length, in (UTF-8) octets, allowed for the name of a FileNode. This MUST be at least 100, although it is recommended servers allow more.¶

• forbiddenNameChars: "String|null"¶

  A string where each character is forbidden in FileNode names. If null, the server does not restrict name characters beyond the requirement that names be non-empty Net-Unicode strings. The server MUST reject names containing any of these characters with an "invalidProperties" error.¶

• forbiddenNodeNames: "String[]|null"¶

  An array of complete names that the server will not accept as FileNode names, compared case-insensitively. For example, [".", "..", "CON", "PRN", "AUX", "NUL"] would forbid common path-traversal names and Windows reserved device names. If null, the server does not forbid any specific names.¶

• supportedNodeTypes: "String[]"¶

  The @type values that the server allows clients to create in this account (see "FileNode objects" below). This MUST include "Directory" and "File". It MAY include "SymLink" and any other value registered in the "JMAP FileNode Types" registry. Clients MUST ignore values they do not recognise.¶

• fileNodeQuerySortOptions: "String[]"¶

  A list of all the values the server supports for the "property" field of the Comparator object in a "FileNode/query" sort (see "FileNode/query" below). This MAY include properties the client does not recognise (for example, custom properties specified in a vendor extension). Clients MUST ignore any unknown properties in the list.¶

• mayCreateTopLevelFileNode: "Boolean"¶

  If true, the user may create a FileNode (see "FileNode/set" below) in this account with a null parentId. (Permission for creating a child of an existing FileNode is given by the "myRights" property on that FileNode.)¶

• webTrashUrl: "String|null"¶

  The URL at which the folder with the "trash" role can be viewed on the web. If null, there is no web URL available.¶

• caseInsensitiveNames: "Boolean"¶

  If true, the server treats file names as case-insensitive for all name collision checks, including the sibling uniqueness constraint and onExists handling. The server preserves the original case as provided by the client.¶

• webUrlTemplate: "String|null"¶

  A template by which any node can be viewed on the web, in URI Template (level 1) format [URI-TEMPLATE]. The available variable is {id}, which is the FileNode id. If null, there is no web URL available.¶

• webWriteUrlTemplate: "String|null"¶

  A URI Template (level 1) [URI-TEMPLATE] for writing content to a FileNode with @type "File". The available variable is {id}, which is the FileNode id. If null, direct HTTP writes are not supported and clients must use FileNode/set to update content. See "Direct HTTP Write" below for the HTTP semantics.¶

{
  "urn:ietf:params:jmap:filenode": {
    "maxFileNodeDepth": 50,
    "maxSizeFileNodeName": 255,
    "fileNodeQuerySortOptions": [
      "name", "mediaType", "size", "created", "modified",
      "nodeType", "tree"
    ],
    "supportedNodeTypes": ["Directory", "File", "SymLink"],
    "forbiddenNameChars": "/<>:\"\\|?*",
    "forbiddenNodeNames": [".", "..", "CON", "PRN", "AUX",
      "NUL", "COM0", "COM1", "COM2", "COM3", "COM4", "COM5",
      "COM6", "COM7", "COM8", "COM9", "LPT0", "LPT1", "LPT2",
      "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9"
    ],
    "caseInsensitiveNames": false,
    "mayCreateTopLevelFileNode": false,
    "webTrashUrl": "https://files.example.com/trash",
    "webUrlTemplate": "https://files.example.com/view/{id}",
    "webWriteUrlTemplate": "https://files.example.com/write/{id}"
  }
}

3.1. FileNode objects

Every FileNode has a type, given by its @type property. This document defines three types: "File", "Directory", and "SymLink". Each type has its own set of properties in addition to the properties common to all FileNodes.¶

Properties that this document defines for one type MUST NOT appear on a FileNode of another type; they are omitted rather than set to null. An attempt to create or update a FileNode that sets a property not defined for its @type to a non-null value is an "invalidProperties" error. The server MUST ignore a null value for such a property, both on create and on update. This lets a client send the same set of properties for nodes of any type.¶

FileNode/get has additional rules for these properties (see "FileNode/get" below).¶

[
  {
    "@type": "Directory",
    "id": "n1",
    "parentId": null,
    "name": "Documents",
    "role": "documents"
  },
  {
    "@type": "File",
    "id": "n3",
    "parentId": "n1",
    "name": "report.pdf",
    "blobId": "Bfa61c0",
    "size": 48576,
    "mediaType": "application/pdf",
    "executable": false
  },
  {
    "@type": "SymLink",
    "id": "n7",
    "parentId": null,
    "name": "latest-report",
    "target": ["Documents", "report.pdf"]
  }
]

3.2. FileNode Methods

4.1. PUT

A PUT request replaces the entire content of the node. The request body is the new content. The Content-Type header sets the mediaType of the node. If the request has no Content-Type header, the server sets mediaType to "application/octet-stream".¶

On success, the server MUST update the node's blobId, size, and mediaType properties, and return an HTTP 200 response with a JSON body:¶

{
  "blobId": "Bnewblob123",
  "size": 48576,
  "mediaType": "text/plain"
}

4.2. PATCH

A PATCH request applies a partial modification to the node's current content. The Content-Type of the request indicates the patch format. The supported patch formats are those listed in the supportedPatchTypes capability of [JMAP-BLOBEXT] (for example, application/x-rdiff-delta, application/x-bsdiff, text/x-diff). The server applies the delta to the node's current blob to produce the new content.¶

On success, the server MUST update the node's blobId and size properties. The server MUST NOT change the node's mediaType. A client that needs to change it uses PUT, or updates mediaType with FileNode/set. The response is an HTTP 200 with the same JSON body as PUT:¶

{
  "blobId": "Bpatched456",
  "size": 49152,
  "mediaType": "text/plain"
}

Servers that do not support a given patch format MUST respond with HTTP 415 (Unsupported Media Type).¶

7.1. Examples

To archive an entire directory tree rooted at FileNode "dirabc" into a zip file:¶

json [["Blob/convert", { "accountId": "account1", "create": { "myarchive": { "archive": { "type": "application/zip", "entries": [{ "nodeId": "dirabc", "name": "/", "recurse": true }] } } } }, "R1"]] ¶

To archive specific files from different locations along with a full subdirectory:¶

json [["Blob/convert", { "accountId": "account1", "create": { "selective": { "archive": { "type": "application/zip", "entries": [ { "nodeId": "filenode1", "name": "README.txt" }, { "nodeId": "dirnode2", "name": "docs/", "recurse": true } ] } } } }, "R1"]] ¶

7.2. Extracting Archives into FileNodes

When both capabilities are present, the ExtractRecipe (defined in [JMAP-BLOBEXT]) is extended with the following additional properties:¶

• parentNodeId: "Id|null" The id of a FileNode with @type "Directory". When present, the server extracts the archive contents into this directory, creating FileNode objects for each entry. Subdirectories in the archive are created as FileNodes with @type "Directory". File entries become FileNodes with @type "File" and their blobId set to the extracted content. The created and modified timestamps are taken from the archive entry metadata. If the archive entry includes a mode field, the server SHOULD use it to set the executable property on the created FileNode.¶

  Symlink entries become FileNodes with @type "SymLink" if "SymLink" is in the supportedNodeTypes capability. The server splits the entry's linkTarget on "/" to produce the target path elements. A linkTarget that starts with "/" produces an empty string as the first element, which marks an absolute path. The server drops any other empty elements.¶

  An entry is unsupported if the server cannot create a FileNode for it. These are symlink entries when "SymLink" is not in supportedNodeTypes, and entries of any type that has no FileNode equivalent ("hardlink", "fifo", "blockDevice", and "charDevice"). The onUnsupportedEntry property controls how the server handles them.¶

• onUnsupportedEntry: "String" (default: "error") If "error", the server rejects the Blob/convert creation with an "unsupportedEntry" SetError, and creates no FileNodes. If "skip", the server does not create a FileNode for an unsupported entry, and extracts the other entries as usual. A skipped entry still appears in the response entries array, with a null nodeId. Any other value is an "invalidProperties" error.¶

• onExists: "String|null" (default: null) Controls the behaviour when an extracted entry would collide with an existing FileNode name under the same parent. The values and semantics are the same as for FileNode/set (see above): null rejects with an alreadyExists SetError, "replace" destroys the existing node, "rename" gives the new node a server-chosen name, and "newest" replaces the existing node only if the archive entry has a strictly later modified timestamp.¶

When parentNodeId is set, each ArchiveEntry in the response entries array includes an additional nodeId property containing the id of the FileNode that was created for that entry, or null if the server skipped the entry.¶

If parentNodeId references a FileNode that does not exist, is not a Directory, or for which the user does not have mayAddChildren permission, the server MUST reject the Blob/convert creation with an appropriate SetError (notFound, invalidProperties, or forbidden).¶

7.3. The unsupportedEntry Error

An "unsupportedEntry" SetError means that an archive or extraction with onUnsupportedEntry set to "error" found one or more entries that it could not handle. The SetError object MUST include an entryNames property: a "String[]" that lists the name of each such entry. For an archive, this is the name that the entry would have had in the archive.¶

8.1. The "xattr" namespace

This document defines the "xattr" namespace for the "metadata" and "privateMetadata" properties. Its value is an object mapping an attribute name to an XattrValue object. The attribute name is the platform-native name of the attribute or stream, stored verbatim (for example "user.comment", "com.apple.metadata:_kMDItemUserTags", or "Zone.Identifier"). Servers and clients MUST NOT normalise attribute names across platforms. The server keeps an attribute that one platform writes, even where another platform has no equivalent for it.¶

An XattrValue object has the following properties:¶

• data: "String|null"¶

  The attribute value as a UTF-8 string. Used for small textual attributes.¶

• blobId: "Id|null"¶

  The blobId of a blob holding the attribute value. Used for large or binary attributes (for example a resource fork, or a multi-kilobyte stream). A blob referenced by an XattrValue MUST NOT be expired or garbage collected by the server while the FileNode references it, in the same way as the content blob of a File.¶

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

  An optional media type ([MEDIATYPE]) for the attribute value.¶

An XattrValue MUST contain exactly one of "data" or "blobId"; providing both, or neither, is an "invalidProperties" error. Binary attributes small enough to carry inline are still referenced by "blobId" rather than base64-encoded in "data".¶

The value nests one object level below the namespace value (attribute name to XattrValue). A server that supports the "xattr" namespace MUST advertise a "maxDepth" for FileNode of at least 1, or null (no limit).¶

Attributes shared with every reader of the node (for example a quarantine flag) are stored under "metadata". Attributes private to the current user (for example that user's own tags) are stored under "privateMetadata" where the server supports it.¶

Example — a small textual attribute and a large binary one:¶

{
  "metadata": {
    "xattr": {
      "user.comment": { "data": "draft copy" },
      "com.apple.ResourceFork": {
        "blobId": "G_fork_9c2",
        "type": "application/octet-stream"
      }
    }
  }
}

To set or remove a single attribute without disturbing the others, a client patches the path directly. RFC 6901 escaping applies to any "/" or "~" in the attribute name ("/" as "~1", "~" as "~0"):¶

[["FileNode/set", {
  "accountId": "u1",
  "update": {
    "f42": {
      "metadata/xattr/Zone.Identifier": { "data": "ZoneId=3" }
    }
  }
}, "0"]]

Setting an attribute's path to null removes it, following the "metadata" patch semantics of [JMAP-METADATA].¶

9.1. Modification Timestamps

Clients SHOULD provide an updated modified value when modifying a node. This gives clients control over the timestamp, for example when preserving original modification times during file synchronization. Clients that do not care about preserving timestamps can set modified to null to have the server use the current time.¶

Clients may also choose to update the modified timestamp on a parent directory when moving a child node in or out, to reflect that the directory's contents have changed.¶

9.2. Timestamp Precision

The UTCDate type (RFC 3339) supports fractional seconds. Servers SHOULD include sub-second precision in created, modified, accessed, and changed timestamps where their storage backend supports it. Clients MUST preserve fractional seconds when they send timestamps back to the server.¶

9.3. Filename Character Restrictions

Servers should set forbiddenNameChars and forbiddenNodeNames to include characters and names that are problematic for their storage backend and for the broadest set of clients.¶

The following characters are problematic on common platforms:¶

• Windows: <, >, :, ", \, |, ?, *, and control characters (U+0000-U+001F). Windows also forbids trailing dots and spaces in names.¶

• macOS: : (HFS+ legacy; displayed as / in Finder).¶

• Linux: the null byte (U+0000).¶

The following names are problematic:¶

• All platforms: . and .. (path traversal).¶

• Windows: reserved device names CON, PRN, AUX, NUL, COM0-COM9, and LPT0-LPT9. These are reserved regardless of file extension (for example, "CON.txt" is also forbidden).¶

A server targeting broad client compatibility should include at least /<>:"\|?* in forbiddenNameChars and at least ., .., and the Windows reserved names in forbiddenNodeNames.¶

9.4. Case Sensitivity

Windows and macOS filesystems are typically case-insensitive (treating "Foo" and "foo" as the same name), while Linux filesystems are typically case-sensitive. Clients syncing to case-insensitive platforms should use compareCaseInsensitively on FileNode/set requests to prevent creating sibling nodes whose names differ only in case, as these cannot coexist on the target platform.¶

9.5. Access Time Updates

Updating accessed on every file read generates significant API traffic for little value. Clients are encouraged to use a "relatime" strategy similar to modern POSIX filesystems: only update accessed if the current value is older than modified, or if more than 24 hours have elapsed since the last accessed update. Clients should batch access time updates with their next JMAP request rather than making a dedicated call.¶

10.1. Path Traversal

Clients that reconstruct filesystem paths from FileNode hierarchies MUST validate the resulting paths and reject any that would escape the intended directory tree. Servers SHOULD include / in forbiddenNameChars and . and .. in forbiddenNodeNames to prevent path traversal attacks via node names.¶

10.2. Symlink Targets

Symlink targets are not validated by the server to point to existing nodes. Clients that resolve symlinks MUST guard against symlink loops (a symlink pointing to an ancestor of itself) and MUST NOT follow symlinks outside the FileNode tree. Servers SHOULD impose a limit on the length of target values and MAY reject targets containing ".." path components.¶

10.3. Denial of Service

Deep nesting of FileNodes or very large numbers of children under a single parent can consume significant server resources. Servers SHOULD enforce reasonable limits via maxFileNodeDepth and MAY impose additional limits on the number of children per node. Recursive operations such as destroying a subtree with onDestroyRemoveChildren can be expensive; servers SHOULD impose limits on the size of subtrees that can be destroyed in a single operation.¶

10.4. Access Control

The discoverability rules defined in this document mean that ancestor nodes of shared content are visible (with mayRead false) to users who have access to descendants. While these ancestor nodes do not expose file content, their names and structure may reveal information about the file hierarchy. Server administrators and users sharing content should be aware of this.¶

Changes to the shareWith property on a node affect all descendants. Removing sharing from a parent node will make all descendants undiscoverable to the affected users, which may be surprising if those users had been actively working with the shared files.¶

10.5. Content Security

Servers that perform content scanning or malware detection SHOULD scan blobs referenced by FileNode objects. The mediaType property is client-asserted and MUST NOT be trusted for security decisions; servers SHOULD independently verify content types where this matters.¶

11.1. JMAP Capability registration for "filenode"

IANA is requested to register the "filenode" JMAP Capability as follows:¶

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

Specification document: this document¶

Intended use: common¶

Change Controller: IETF¶

Security and privacy considerations: this document, Security Considerations¶

11.2. JMAP Error Codes registration for "nodeHasChildren"

IANA is requested to register the "nodeHasChildren" JMAP Error Code as follows:¶

JMAP Error Code: nodeHasChildren¶

Intended use: common¶

Change Controller: IETF¶

Description: The node being destroyed is still referenced by other nodes which have not been destroyed.¶

Reference: this document¶

11.3. JMAP Error Codes registration for "unsupportedEntry"

IANA is requested to register the "unsupportedEntry" JMAP Error Code as follows:¶

JMAP Error Code: unsupportedEntry¶

Intended use: common¶

Change Controller: IETF¶

Description: An archive or extraction found entries that the archive format or the server cannot represent, and the client asked for an error rather than for the entries to be skipped.¶

Reference: this document¶

11.4. JMAP Data Types registration for "FileNode"

IANA is requested to register the "FileNode" JMAP Data Type as follows:¶

Type Name: FileNode¶

Can Reference Blobs: Yes¶

Can Use For State Change: Yes¶

Capability: urn:ietf:params:jmap:filenode¶

Reference: this document¶

11.5. JMAP FileNode Types Registry

IANA is requested to create a new "JMAP FileNode Types" registry with the following initial values. New registrations are subject to Specification Required ([IANA-GUIDELINES]). A registration MUST reference a specification that defines the properties specific to the type and whether nodes of the type may have children.¶

11.6. JMAP FileNode Roles Registry

IANA is requested to create a new "JMAP FileNode Roles" registry with the following initial values. New registrations are subject to Expert Review ([IANA-GUIDELINES]).¶

11.7. JMAP Metadata Namespace Registration for "xattr"

IANA is requested to register the "xattr" namespace in the "JMAP Metadata Namespaces" registry established by [JMAP-METADATA]:¶

Namespace Identifier: xattr¶

Value Type: String[XattrValue] — an object mapping an attribute name to an XattrValue object, as defined in "Extended Attributes and Named Streams" of this document.¶

Applicable Properties: metadata, privateMetadata¶

Applicable Data Types: FileNode¶

Reference: this document¶

Intended Usage: common¶

Change Controller: IETF¶

15.1. Normative References

[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, June 2017, <https://www.rfc-editor.org/rfc/rfc8126>.

[JMAP-BLOBEXT]

Gondwana, B., "JMAP Blob Extensions", Work in Progress, Internet-Draft, draft-gondwana-jmap-blobext-06, 7 April 2026, <https://datatracker.ietf.org/doc/html/draft-gondwana-jmap-blobext-06>.

[JMAP-CONDITIONAL]

Gondwana, B., "JMAP Conditional Set", Work in Progress, Internet-Draft, draft-gondwana-jmap-conditional-00, 20 June 2026, <https://datatracker.ietf.org/doc/html/draft-gondwana-jmap-conditional-00>.

[JMAP-CORE]

Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, <https://www.rfc-editor.org/rfc/rfc8620>.

[JMAP-METADATA]

De Gennaro, M., "JMAP Object Metadata", Work in Progress, Internet-Draft, draft-ietf-jmap-metadata-02, 27 May 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-jmap-metadata-02>.

[JMAP-SHARING]

Jenkins, N., Ed., "JSON Meta Application Protocol (JMAP) Sharing", RFC 9670, DOI 10.17487/RFC9670, November 2024, <https://www.rfc-editor.org/rfc/rfc9670>.

[MEDIATYPE]

Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <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, March 1997, <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, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[URI-TEMPLATE]

Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, March 2012, <https://www.rfc-editor.org/rfc/rfc6570>.

15.2. Informative References

[CALDAV]

Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007, <https://www.rfc-editor.org/rfc/rfc4791>.

[CARDDAV]

Daboo, C., "CardDAV: vCard Extensions to Web Distributed Authoring and Versioning (WebDAV)", RFC 6352, DOI 10.17487/RFC6352, August 2011, <https://www.rfc-editor.org/rfc/rfc6352>.

[JMAP-CALENDARS]

Jenkins, N. and M. Douglass, "JSON Meta Application Protocol (JMAP) for Calendars", Work in Progress, Internet-Draft, draft-ietf-jmap-calendars-33, 13 October 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-jmap-calendars-33>.

[JMAP-CONTACTS]

Jenkins, N., Ed., "JSON Meta Application Protocol (JMAP) for Contacts", RFC 9610, DOI 10.17487/RFC9610, December 2024, <https://www.rfc-editor.org/rfc/rfc9610>.

[JMAP-MAIL]

Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP) for Mail", RFC 8621, DOI 10.17487/RFC8621, August 2019, <https://www.rfc-editor.org/rfc/rfc8621>.

[JMAP-QUOTAS]

Cordier, R., Ed., "JSON Meta Application Protocol (JMAP) for Quotas", RFC 9425, DOI 10.17487/RFC9425, June 2023, <https://www.rfc-editor.org/rfc/rfc9425>.

[UNICODE]

Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, DOI 10.17487/RFC5198, March 2008, <https://www.rfc-editor.org/rfc/rfc5198>.

[WEBDAV]

Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007, <https://www.rfc-editor.org/rfc/rfc4918>.