]> Stalwart Labs LLC

1309 Coffeen Avenue, Suite 1200 Sheridan WY 82801 USA mauro@stalw.art https://stalw.art

JMAP Internet-Draft This document defines an extension to the JSON Meta Application Protocol (JMAP) that lets clients and servers attach metadata to objects of existing JMAP data types. Each data type the server lists gains two new properties, metadata and privateMetadata, whose values are objects keyed by namespace identifier. A namespace identifier is either a name registered with IANA or a domain name controlled by the vendor providing the namespace; the latter allows vendors and applications to extend the metadata schema without prior coordination. Because metadata is carried as a property on the related object, clients use the existing /get, /set, /changes, and /query methods to read, modify, and synchronize it.

Introduction The JSON Meta Application Protocol (JMAP) is a generic protocol for synchronizing data, such as mail, calendars or contacts, between a client and a server. It is optimized for mobile and web environments, and aims to provide a consistent interface to different data types. Metadata, or annotations, are auxiliary data elements that provide additional context, user-defined properties, or system-specific information about primary data objects. They enable user annotations, application-specific settings, collaborative tagging, and similar functionality. Other protocols have addressed this need with mechanisms such as the IMAP METADATA extension and WebDAV dead properties ; this specification provides an analogous facility within JMAP. The term "metadata" in this document refers only to the properties defined here, not to the Email properties described in . This document defines a uniform mechanism for managing such metadata. Each listed JMAP data type gains a metadata property (shared metadata) and, optionally, a privateMetadata property (per-user metadata). The value of each property is an object keyed by namespace identifier. This document defines no initial namespaces; vendors use domain-name identifiers for proprietary extensions, and additional registered identifiers may be defined by future specifications. Because metadata is carried as a property on the related object, the existing JMAP methods for that data type apply unchanged. Clients fetch metadata with the type's /get method, modify it through /set patches, learn of changes through /changes, and search across metadata and primary properties together through /query.

Notational Conventions 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 when, and only when, they appear in all capitals, as shown here. The definitions of JSON keys and datatypes in this document follow the conventions described in . The terms "Foo", "SetError", "PatchObject" and "state string" are used as defined in . This document also uses the following terms: related object: the JMAP object carrying the metadata and privateMetadata properties. listed data type: a data type that appears in the dataTypes field of the account capability (). user: the authenticated identity of the session, which is not necessarily the owner of the account.

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

urn:ietf:params:jmap:metadata This capability represents support for the metadata extension defined in this document. Servers that include this capability provide the metadata and (optionally) privateMetadata properties on the data types they list. The value of this property in the JMAP Session "capabilities" property is an empty object. The value of this property in an account's "accountCapabilities" property is an object containing the following field:

dataTypes: String[DataTypeMetadataInfo]

An object whose keys are the names of JMAP data types for which the server supports metadata in this account. A type that does not appear in this object does not gain the metadata or privateMetadata properties in this account. The value associated with each type is a DataTypeMetadataInfo object as defined below.

A DataTypeMetadataInfo object has the following fields:

namespaces: String[]

The set of IANA-registered metadata namespace names (as defined in ) that the server supports on this data type. Each value MUST be a registered name (). A registered namespace MUST NOT be listed for a data type, or written under a property, that its registration does not allow. Vendor (domain-name) namespaces MUST NOT appear in this list; their support is signalled by supportsVendorNamespaces instead.

supportsVendorNamespaces: Boolean (default: false)

Indicates whether the server accepts vendor (domain-name) namespaces on this data type. If true, any well-formed domain-name namespace () may be written by clients, subject to the other constraints of this specification (access control, maxDepth, quota). If false, any /set operation that targets a domain-name namespace MUST be rejected with an "invalidProperties" SetError, and any subselector or filter condition referencing such a namespace MUST be treated as unsupported per the rules of and .

supportsPrivate: Boolean (default: false)

Indicates whether this account, on this data type, supports per-user privateMetadata. This is a server feature flag, not a per-user permission. If false, the privateMetadata property MUST be absent from response objects of this type, all privateMetadata* filter conditions () MUST be rejected with an "unsupportedFilter" error, and any /set operation that targets privateMetadata MUST be rejected with an "invalidProperties" SetError. Per-user authorization of a privateMetadata write that the server otherwise supports is defined in .

maxDepth: UnsignedInt|null (default: null)

Maximum depth of nested objects within a namespace value on this data type. A depth of 1 indicates only flat properties are supported; a depth of 2 allows one level of nesting; and so forth. If not null, the value MUST be at least 1. A value of null means there is no server-enforced depth limit beyond quota and size limits. Depth is defined in .

A server SHOULD NOT advertise a data type that supports neither registered namespaces (empty namespaces) nor vendor namespaces (supportsVendorNamespaces: false), since such an entry advertises support for nothing. If no data type would be listed in dataTypes, the server SHOULD NOT include the capability in the account's "accountCapabilities". A worked example of the capability object appears in .

The Metadata Properties This extension introduces two properties on each listed data type:

metadata: String[Object] (default: {})

An object containing shared metadata associated with the object. Each key is a namespace identifier (see ) and each value is structured according to the namespace's definition. Shared metadata is visible to every user with read access to the related object, subject to . When returned, its value MUST be an object ({} when no metadata is set), never null.

privateMetadata: String[Object] (default: {})

An object containing per-user metadata associated with the object, with the same structure as metadata. Private metadata is visible only to the user who set it; the server MUST filter responses so that each user sees only their own privateMetadata content, as described in . When returned, its value MUST be an object ({} if the user has set no private metadata on the object), never null. When supportsPrivate is false for the data type, this property MUST NOT be returned.

Both properties are mutable and behave like any other property of the related object. They appear in /get responses, accept patches through /set, contribute to the related type's state string (), and may be searched through the /query filter conditions defined in .

Namespaces The keys of the metadata and privateMetadata objects are namespace identifiers. Each identifier MUST be one of: A registered name: a sequence of lowercase US-ASCII letters, digits, hyphens, and underscores, with no dot ("."). Registered names may be registered using the procedure in ; this document defines no registered names. A domain name controlled by the vendor providing the namespace, in DNS form (containing at least one ".", e.g., example.com, acme.example.org). Vendors MAY use domain-name namespaces for proprietary metadata without registration; the dot in the name guarantees no collision with registered names. Domain-name identifiers MUST be in lowercase, with internationalized labels in A-label form. Servers MUST reject, with an "invalidProperties" SetError, a /set operation that uses a key that is not a valid namespace identifier, including a domain name containing uppercase ASCII letters. A namespace is supported on a data type if it is a registered name listed in that type's namespaces, or a domain name and the type's supportsVendorNamespaces is true. The value associated with each namespace key MUST be a JSON object, whose internal structure is defined by the specification or vendor owning that namespace; a namespace set to {} remains stored until it is removed with null. Property names within the namespace object follow normal JSON conventions; they do not need to be domain-prefixed, since cross-namespace isolation is already provided by the top-level key. Example:

The depth of a value is defined recursively: a scalar (string, number, boolean or null) or a Binary value () has depth 0; an array has the maximum depth of its elements (0 if empty); an object has depth 1 plus the maximum depth of its member values (1 if empty). For example, {"a": 1} has depth 1 and {"x": [{"y": 1}]} has depth 2. If the account capability specifies a maxDepth for a data type, the depth of a namespace value MUST NOT exceed it; servers MUST reject writes that would exceed it with an "invalidProperties" SetError. A patch that targets one namespace MUST NOT remove or alter any other namespace, including namespaces that are not supported on the data type. Vendors are encouraged to register namespace identifiers that are likely to be useful beyond the vendor's own products, using the procedure in . Registration enhances interoperability and avoids fragmentation.

Binary Values JSON strings hold Unicode text, so a namespace value cannot carry arbitrary bytes directly. A namespace that needs to store bytes uses a Binary object, which has exactly the following members:

@type: String

The value "Binary".

base64: String

The bytes, encoded in base64 with padding ().

Any object within a namespace value that has an @type member with the value "Binary" is a Binary value. A namespace definition MUST NOT use such an object for anything else. A Binary value that has any other member, or whose base64 member is not valid base64 with padding, is malformed. A Binary value is a single value, like a string: it has depth 0 (), a patch path or filter path cannot address its members, and the text-match filter conditions () never match it. The server stores and returns it exactly as given. Example, a vendor namespace holding a 32-byte value:

Data in Unsupported Namespaces Data can be stored under a namespace that is not supported on the data type, for example after a server reconfiguration, after a vendor withdraws support, or when the data was copied from another account (). Such data MUST continue to be returned by /get for read-only access. Any /set operation that targets the namespace, other than a patch that removes the namespace entirely ("metadata/<namespace>": null or "privateMetadata/<namespace>": null), MUST be rejected with an "invalidProperties" SetError. A complete replacement of metadata or privateMetadata MAY include such a namespace only with a value equal to the stored one, where two JSON objects are equal when they have the same members with equal values, regardless of member order; omitting the namespace from a complete replacement removes it. This ensures clients can always migrate data off an unsupported namespace, but cannot continue to extend it.

State Behavior Changes to metadata or privateMetadata are changes to the related object. They advance the related type's state string, appear in the related type's /changes response, and are otherwise indistinguishable from changes to any other property of that type, with the following clarification: Because privateMetadata is filtered per viewer, a change made by user A to privateMetadata on a shared object MUST advance the related type's state string for user A and SHOULD NOT advance it for any other user. Such a change MUST NOT cause the object to be reported in any other user's Foo/changes or Foo/queryChanges response. A server that advances other users' state reveals when a private change occurred (see ). Changes to metadata or privateMetadata alone MUST NOT update server-maintained modification timestamps of the related object, such as the changed property of FileNode or the updated property of CalendarEvent . This overrides any requirement of those specifications that the timestamp change on every update.

Standard Method Extensions For each data type listed in the dataTypes field of the account capability, the standard JMAP methods for that type are extended as described in the following subsections; a server MUST implement these extensions for every listed data type. These extensions apply to requests whose using includes urn:ietf:params:jmap:metadata. For other requests, metadata and privateMetadata are not default properties of Foo/get (although they are still returned when requested by name), Foo/set MUST reject any write to them with an "invalidProperties" SetError, and Foo/changes MUST behave as if ignoreMetadataOnlyChanges were true. The state string is the same as for requests that use this capability. This document does not extend methods that create or parse objects from uploaded data, such as Email/import and Email/parse (). Objects created or returned by such methods have empty metadata and privateMetadata.

/get For a listed data type, when properties is omitted or null, the server MUST include metadata and, where supportsPrivate is true, privateMetadata in each returned object, except for Email/get, whose default property list () is unchanged. The two properties may also be requested explicitly by name in the properties array, like any other JMAP property. When a client wants only a subset of the metadata, it MAY request individual namespaces using slash-separated subselector paths in the properties argument. The following rules apply to subselectors introduced by this specification: A subselector has the form metadata/<namespace> or privateMetadata/<namespace>, where <namespace> is a non-empty namespace identifier. Any other properties entry beginning with metadata/ or privateMetadata/ MUST be rejected with an "invalidArguments" method-level error. Multiple subselectors with the same root combine by union. For example, ["metadata/x", "metadata/y"] returns {"metadata": {"x": ..., "y": ...}} (and nothing else under metadata). An explicit root entry supersedes subselectors with the same root. For example, ["metadata", "metadata/x"] returns the complete metadata object; the metadata/x entry is redundant rather than restrictive. A subselector naming a namespace that is not supported () on the data type MUST be silently omitted from the response, unless the object has data stored under that namespace (), which is then returned. This lets clients perform capability-tolerant fetches without first consulting the session capability. This specification defines slash-path subselectors only for metadata and privateMetadata. The use of slash-path subselectors with any other property name is outside the scope of this document.

/set The metadata and privateMetadata properties are mutable. In a create entry of Foo/set, each property's value MUST be a complete JSON object (possibly the empty object {}). A value of null for either property MUST be rejected with an "invalidProperties" SetError; the canonical "no metadata" form is {}. In an update, null is equivalent to {}. In an update entry of Foo/set, clients MAY either send a complete object as the value of metadata or privateMetadata (replacing the previous value entirely), or use the PatchObject form (). Patch paths start with metadata/<namespace> or privateMetadata/<namespace> (replacing or removing an entire namespace value) and MAY continue to any depth below it (for example, metadata/<namespace>/<key>/<subkey>), with the semantics of : the parent of the target MUST exist, and a path that traverses an array or a Binary value () is rejected with an "invalidPatch" SetError. Setting a patch value to null removes the targeted key, per standard PatchObject semantics (). Setting a path to a complete object value replaces whatever was previously at that path; in particular, a patch of the shape "metadata/<namespace>": { ... } replaces the entire content of that namespace, deleting any keys not present in the new value. Clients that want to add or update individual properties without removing others need to patch the specific keys. The server MUST validate every write against the account capability for the data type. When more than one of the following rules applies, the server MUST evaluate them in the order listed; the first matching rule determines the SetError: If the user cannot read the related object, reject with "notFound". If the write targets metadata and the user lacks maySetMetadata (), reject with "forbidden". If the path begins with privateMetadata and supportsPrivate is false for this data type, reject with "invalidProperties". If the targeted namespace is not supported on this data type, reject with "invalidProperties" (except for the migration case in ). If a namespace value would exceed maxDepth, reject with "invalidProperties". If a namespace value contains a malformed Binary value (), reject with "invalidProperties". Patch errors that can be determined from the request alone (for example, two paths where one is a prefix of the other) MUST be reported with "invalidPatch" before rule 1 is evaluated. Patch errors that depend on the current value of the property (a missing parent, or a path through an array or a Binary value) MUST be reported with "invalidPatch" after rule 3 and before rule 4.

Quota Enforcement on /set Servers SHOULD enforce quota limits on the total storage consumed by metadata within an account, as described in . If a create, update, or copy would cause the account to exceed its metadata quota, the server MUST reject the operation with an "overQuota" SetError.

/changes For each data type listed in dataTypes, the Foo/changes request accepts the following additional optional argument:

ignoreMetadataOnlyChanges: Boolean (default: false)

If true, the server MUST exclude from the updated array any id whose only changes since sinceState, from the viewer's perspective, are confined to metadata and/or privateMetadata. Ids with any other change remain in updated. If the server cannot determine that an id's changes are metadata-only, it MUST include the id. Excluded ids do not count toward maxChanges. The state string still advances normally, so a client using this argument continues to see correct synchronization for all non-metadata-only changes; metadata-only changes are simply not reported to this client. When this argument is true, updatedProperties (defined below) MUST NOT list metadata or privateMetadata. For Mailbox/changes it may list the count properties (); for other types it MUST be null.

The response is extended to include the following additional argument:

updatedProperties: String[]|null

This argument is determined per viewer: each user's Foo/changes response is computed against the changes visible to that user (in particular, privateMetadata written by other users is invisible). If, from the viewer's perspective, the only properties that have changed on every id in the updated array since the old state are metadata and/or privateMetadata, this argument MUST be set to a list containing only those property names (e.g., ["metadata"], ["privateMetadata"], or ["metadata", "privateMetadata"]). If any other property (apart from the Mailbox count properties described below) of any id in the array may also have changed (from the viewer's perspective), or if the server cannot determine the answer for any id in the array, this argument MUST be null. The argument applies uniformly to all ids in updated; per-id granularity is not provided. It is always present, and is null when updated is empty.

This argument follows the same convention used by Mailbox/changes in . For Mailbox/changes, when every id in updated changed only in its counts (as defined there) and/or in metadata or privateMetadata, the value is the union of the count property names and the metadata property names that may have changed.

/copy Foo/copy copies metadata to the new object. The copying user's privateMetadata on the source object becomes that user's privateMetadata on the new object; other users' privateMetadata MUST NOT be copied. When the request does not use this capability, only metadata is copied. The create object MAY include metadata and privateMetadata to override the copied values, with the same rules as a create in Foo/set; for Email/copy, this extends the list of properties that may be set in . Copied metadata counts against quota () as any other write. Copied values are not revalidated against the destination account: data in a copied namespace that is not supported there is handled as described in , and maxDepth applies only to values supplied in the create object. privateMetadata is not copied when the destination does not support it, and neither property is copied when the data type is not listed in the destination account. With onSuccessDestroyOriginal, other users' privateMetadata on the source object is destroyed together with it.

/queryChanges Foo/queryChanges is unchanged in its method signature and follows the per-viewer rule in .

/query For each data type listed in dataTypes, the FilterCondition object for Foo/query is extended with the optional fields defined below. Several of those fields take a MetadataTextMatch value. A MetadataTextMatch object has the following fields:

path: String

The path within the metadata object to match against: a namespace identifier, optionally followed by a JSON Pointer into the namespace value (for example, <namespace>, <namespace>/<key> or <namespace>/<key>/<subkey>). Object members are addressed by name; a path that would traverse an array, a scalar or a Binary value () addresses no value. A path that is not well formed (for example, one with an invalid ~ escape) MUST be rejected with an "invalidArguments" error.

value: String

The string to search for at path. The interpretation of this string (substring containment versus exact equality) is determined by the FilterCondition field that carries the MetadataTextMatch.

The extended FilterCondition fields are:

metadataExists: String

A path, with the syntax defined for MetadataTextMatch. Matches an object if and only if a value is present at the given path within the object's metadata property. A namespace-only path matches if the namespace key is present and its value is not the empty object {}.

privateMetadataExists: String

As metadataExists, but matches against the authenticated user's privateMetadata.

metadataTextContains: MetadataTextMatch

Matches an object if the metadata value at the supplied path is a string that contains the supplied value as a substring under the "i;unicode-casemap" collation . The condition does not match if the path does not exist within metadata, or if the value at the path is not a string.

privateMetadataTextContains: MetadataTextMatch

As metadataTextContains, but searches the authenticated user's privateMetadata.

metadataTextEquals: MetadataTextMatch

Matches an object if the metadata value at the supplied path is a string that is exactly equal to the supplied value, comparing Unicode code points without case folding or normalization. The condition does not match if the path does not exist within metadata, or if the value at the path is not a string.

privateMetadataTextEquals: MetadataTextMatch

As metadataTextEquals, but searches the authenticated user's privateMetadata.

The following availability rules apply to all six conditions: Servers MUST support metadataExists and privateMetadataExists (where supportsPrivate is true). Servers MAY reject any of the four text-match conditions with an "unsupportedFilter" error if implementation cost or storage layout makes them infeasible. Clients need to be prepared to fall back to a client-side scan in this case. Any privateMetadata* condition (existence or text) MUST be rejected with an "unsupportedFilter" error if supportsPrivate is false for the data type. Conditions are evaluated against the stored data whether or not the namespace is supported on the data type, so data stored under an unsupported namespace () can still be found. A condition naming an unsupported namespace with no stored data, or a string that is not a valid namespace identifier, matches no objects; it does not produce an error. These conditions compose with the data type's existing filter conditions through the usual AND/OR/NOT operators (). For example, a client may query for Email objects in a particular mailbox whose vendor metadata contains a search term in a single server-side query, as shown in .

Access Control Access control for metadata follows the access control of the related object. The two properties are governed by different rules: The metadata property is shared. A user who can read the related object can read its metadata. Modifying it requires the maySetMetadata right (). The privateMetadata property is per-user. The server MUST filter responses so that each user sees only the privateMetadata content they themselves wrote. Private metadata written by another user on the same related object MUST NOT be visible. To write privateMetadata on a related object, the user needs only read access to the related object; write access on the related object is not required.

The maySetMetadata Right For every data type that has a myRights property (for example Mailbox , Calendar , AddressBook and FileNode ) and that is a listed data type or contains objects of a listed data type, the rights object gains the following property:

maySetMetadata: Boolean

The user may modify the shared metadata of this object, and of the objects it contains that have no rights object of their own. For Mailbox, this corresponds to the IMAP ACL "n" right .

The right is returned in myRights and can be granted through shareWith () like any other right of that type. An object without a rights object of its own, such as an Email, CalendarEvent or ContactCard, takes the right from its containers. Modifying its metadata requires maySetMetadata on every container it belongs to; when the same update changes its containers, on every container both before and after the change; and on create, on the containers given in the create. For a listed data type that neither has a rights object nor belongs to a container that has one, such as SieveScript , modifying metadata requires that the account is not read-only (isReadOnly is false, ). The server MUST enforce these rules consistently across /get, /set, /query, /queryChanges, and /changes. An object the user cannot read is treated for metadata and privateMetadata exactly as for its other properties (for example, it is reported in notFound). A write to an object the user cannot read MUST be rejected with a "notFound" SetError, so that the existence of the object is not revealed. A write to metadata without maySetMetadata MUST be rejected with a "forbidden" SetError. When sharing permissions on a related object change, the visibility of its metadata changes accordingly. privateMetadata belonging to a user remains visible to that user as long as the user retains read access to the related object. If read access is revoked, the object, including the user's privateMetadata, becomes inaccessible to that user; the server MAY delete that privateMetadata, and if it does not and access is restored, it is visible again. A user's privateMetadata is destroyed together with the related object.

Account Delegation and Administrative Access privateMetadata is keyed by the authenticated identity of the session. A delegate, an impersonating administrator, or any other session authenticated as a different identity than the account owner MUST see and write only its own privateMetadata, never the account owner's. Exposing the account owner's privateMetadata to such a session is outside the scope of this document.

Quota Servers SHOULD enforce quota limits on the storage consumed by metadata within an account. Unbounded metadata growth could be exploited to exhaust resources, particularly because privateMetadata is per-user and so a single shared object can carry one private payload per user with access to it. Servers that support the JMAP Quotas extension SHOULD integrate metadata storage into the quota framework defined there. Servers that do not implement SHOULD still enforce implementation-defined limits and reject overruns with an "overQuota" SetError. The size metric used for metadata quota is implementation-defined; clients cannot assume that two servers compute identical sizes for the same data. Servers can document the metric they use. A server that also exposes the related object over other protocols (for example, as WebDAV dead properties or IMAP METADATA ) MAY count data that is not visible through JMAP against the quota and limits described in this section. Clients therefore need to be prepared for a limit error on an object whose visible metadata is small.

Examples

Capability A session for an account whose server supports metadata on four data types, with varying private-metadata and depth settings:

Fetching a Mailbox with Its Metadata Request the shared metadata and the user's private metadata for a single Mailbox:

Response:

Patching a Single Property within a Namespace Update one property inside a namespace without disturbing the others:

Removing a single property uses a patch to null:

Creating an Email with Private Metadata Create a draft Email and attach a private workflow annotation atomically. The metadata is just another property on the create:

The response is a single Email/set response; there is no separate metadata response, because metadata is part of the Email object.

Attaching Photography Metadata to a FileNode This example uses a fictional IANA-registered namespace photography, assumed for the purpose of this example to be specified for photographic information about image files and applicable to the FileNode data type. The capability for the account in advertises FileNode as supporting photography and no vendor namespaces. Request:

Subsequent retrieval of the FileNode, requesting only the relevant metadata namespace:

Response:

Updating a CalendarEvent and Its Metadata Atomically This example updates a primary property of a CalendarEvent and two vendor metadata properties in the same /set call. As with any update entry, either all of these changes apply or none do. Request:

A successful response is a single CalendarEvent/set response; metadata changes do not produce a separate response because they are properties of the event itself:

Querying by Metadata and a Primary Property Together Find all Email objects in a particular Mailbox whose private vendor memo contains the text "follow up":

Detecting a Metadata-Only Change through /changes After another client updates the shared metadata of two Emails, the next Email/changes call returns:

The client knows it only needs to refetch the metadata property of EM1 and EM2, not the full Email objects.

Security Considerations

Metadata Confidentiality Metadata may contain sensitive information: personal notes, workflow states, application-specific data, and other user-generated content. Servers MUST enforce the access-control rules in . Failures here are direct privacy breaches. privateMetadata is per-user. The server MUST ensure that each user sees only their own content, even on shared related objects. This is the most common implementation pitfall in this specification: a query or /get implementation that returns another user's privateMetadata is a serious bug. Servers MUST verify that result filtering applies uniformly to /get, /query, /changes, /queryChanges, and to any cached or denormalized representation. A server that advances the related type's state for user B in response to user A's private write () does not reveal the metadata content, but it does reveal that something private changed in the account, and when. Such a server also wakes up every client of every user sharing the data. Keeping state per viewer avoids both.

User Identity and Authentication The private-metadata model relies on accurate user identification. Servers need to identify the authenticated user reliably for every metadata operation and keep each privateMetadata value associated with the user that wrote it, so that identity spoofing or authentication bypass cannot expose another user's private metadata. Delegated and administrative sessions are covered in .

Untrusted Namespace Values Namespace values are arbitrary client-supplied content. Servers and clients need to treat them as untrusted input: validate them before use, apply context-appropriate output encoding (for example, when rendering them in a web page or storing them in a database), and never interpret them as code. Servers store namespace values as given; they do not alter them, since clients and metadataTextEquals rely on exact values. Clients that render metadata need appropriate sandboxing and Content Security Policy, and need to distinguish clearly in their user interface between metadata (visible to others) and privateMetadata (visible only to the user), so that users do not inadvertently disclose private notes. Clients also cannot assume the structure of a namespace value without checking it.

Resource Exhaustion Without controls, metadata can be abused for denial of service: Storage exhaustion: bulk creation of large metadata payloads, particularly under privateMetadata, where every user with access to a shared object can independently consume space. Processing exhaustion: deeply nested or pathologically large namespace values. Query complexity: text-match filter conditions (metadataTextContains/metadataTextEquals and their private variants) that require expensive scanning, particularly when combined with per-user filtering across many users. Servers MAY reject such conditions with "unsupportedFilter" () to bound the cost. Servers SHOULD apply the quota mechanism in , and can also bound value sizes, enforce maxDepth, time out long-running queries, rate-limit metadata writes, and monitor for unusual usage patterns (for example, a single user creating private metadata on unusually many objects). Per-user filtering of privateMetadata needs to be efficient so that it does not itself become a denial-of-service vector.

IANA Considerations

JMAP Capability Registration for "metadata" IANA will register the "metadata" JMAP Capability as follows: Capability Name: urn:ietf:params:jmap:metadata
Specification document: this document
Intended use: common
Change Controller: IETF
Security and privacy considerations: this document,

Creation of the "JMAP Metadata Namespaces" Registry IANA is requested to create the "JMAP Metadata Namespaces" registry to record metadata namespace identifiers used as top-level keys in the metadata and privateMetadata properties defined by this specification. This registry uses the Expert Review process (). Registrants must propose a name without a dot ("."), since names containing a dot are reserved for vendor domain-name namespaces and need no registration. The designated expert MUST ensure that the proposed name does not collide with an existing registration and that the specification provides sufficient detail for interoperability (in particular, the structure of the namespace's value). Registrations may be of Intended Use "common", "reserved", or "obsolete". A "reserved" registration reserves a name without assigning semantics; an "obsolete" registration marks a name that should no longer be used by up-to-date implementations.

Preliminary Community Review Notice of a potential new registration SHOULD be sent to the JMAP mailing list jmap@ietf.org for review. The intent is to solicit comments on the namespace identifier, the clarity of the specification, and any interoperability or security considerations. The submitter MAY revise or withdraw the proposal at any time.

Change Procedures The change controller for a registration MAY request changes to its definition using the same procedure as the original registration. Significant changes that would invalidate existing data SHOULD be made only to correct serious errors. Registrations MUST NOT be deleted; namespaces that are no longer appropriate for use can be marked obsolete by a change to their intended-use field. The change controller of a registration MAY transfer responsibility to another person or agency by informing IANA.

"JMAP Metadata Namespaces" Registry Template

Namespace Identifier:

The name registered for use as a key in the metadata or privateMetadata object. MUST consist of lowercase US-ASCII letters, digits, hyphens, and underscores, and MUST NOT contain a dot.

Value Type:

A description of the structure of values stored under this namespace key (for example, "object whose values are strings").

Applicable Properties:

One of: "metadata" (this namespace may appear only under metadata), "privateMetadata" (only under privateMetadata), or "both" (under either).

Applicable Data Types:

A list of JMAP data type names on which this namespace is meaningful, or "any" if the namespace is not restricted.

Reference or Description:

A brief description, or an RFC number and section reference, describing the namespace's contents. May be omitted for "reserved" entries.

Intended Use:

"common", "reserved", or "obsolete".

Change Controller:

Who may request changes to this entry (IETF for RFCs from the IETF stream).

Submit Request to IANA Registration requests can be sent to iana@iana.org.

Designated Expert Review The designated expert (DE) is primarily concerned with preventing name collisions and ensuring that the specification provides enough detail for interoperability. For common-use registrations, the DE is expected to confirm that suitable documentation (per ) is available. A published specification is not required for reserved or obsolete registrations. The DE will either approve or deny the registration and publish a notice of the decision to the JMAP working group mailing list (or its successor) and to IANA. A denial MUST be justified and SHOULD include concrete suggestions for how the request can be modified to become acceptable.

Initial Contents This document defines no initial entries for the "JMAP Metadata Namespaces" registry. Future specifications may register entries through the procedure defined in this section.

This document specifies a protocol for clients to efficiently query, fetch, and modify JSON-based data objects, with support for push notification of changes and fast resynchronisation and for out-of- band binary data upload/download. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. This document specifies a data model for sharing data between users using the JSON Meta Application Protocol (JMAP). Future documents can reference this document when defining data types to support a consistent model of sharing. JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. This document describes "i;unicode-casemap", a simple case-insensitive collation for Unicode strings. It provides equality, substring, and ordering operations. [STANDARDS-TRACK] This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document specifies a data model for synchronising email data with a server using the JSON Meta Application Protocol (JMAP). Clients can use this to efficiently search, access, organise, and send messages, and to get push notifications for fast resynchronisation when new messages are delivered or a change is made in another client. This document specifies a data model for managing Sieve scripts on a server using the JSON Meta Application Protocol (JMAP). Clients can use this protocol to efficiently search, access, organize, and validate Sieve scripts. This document specifies a data model for synchronising contact data with a server using the JSON Meta Application Protocol (JMAP). The ANNOTATE extension to the Internet Message Access Protocol permits clients and servers to maintain "meta data" for messages, or individual message parts, stored in a mailbox on the server. For example, this can be used to attach comments and other useful information to a message. It is also possible to attach annotations to specific parts of a message, so that, for example, they could be marked as seen, or important, or a comment added. Note that this document was the product of a WG that had good consensus on how to approach the problem. Nevertheless, the WG felt it did not have enough information on implementation and deployment hurdles to meet all of the requirements of a Proposed Standard. The IETF solicits implementations and implementation reports in order to make further progress. Implementers should be aware that this specification may change in an incompatible manner when going to Proposed Standard status. However, any incompatible changes will result in a new capability name being used to prevent problems with any deployments of the experimental extension. This memo defines an Experimental Protocol for the Internet community. Fastmail Spherical Cow Group This document specifies a data model for synchronizing calendar data with a server using JMAP. Clients can use this to efficiently read, write, and share calendars and events, receive push notifications for changes or event reminders, and keep track of changes made by others in a multi-user environment. Fastmail The JMAP base protocol (RFC 8620) provides the ability to upload and download arbitrary binary data. This binary data is called a "blob", and can be used in all other JMAP extensions. This extension adds a FileNode data type and methods to expose blobs as a filesystem, along with the types of metadata that are provided by other remote filesystem protocols. This document specifies a data model for handling quotas on accounts with a server using the JSON Meta Application Protocol (JMAP). The METADATA extension to the Internet Message Access Protocol permits clients and servers to maintain "annotations" or "metadata" on IMAP servers. It is possible to have annotations on a per-mailbox basis or on the server as a whole. For example, this would allow comments about the purpose of a particular mailbox to be "attached" to that mailbox, or a "message of the day" containing server status information to be made available to anyone logging in to the server. [STANDARDS-TRACK] Web Distributed Authoring and Versioning (WebDAV) consists of a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of resource properties, creation and management of resource collections, URL namespace manipulation, and resource locking (collision avoidance). RFC 2518 was published in February 1999, and this specification obsoletes RFC 2518 with minor revisions mostly due to interoperability experience. [STANDARDS-TRACK]

Changes [[This section to be removed by RFC Editor]] draft-ietf-jmap-metadata-05 Added the Binary value, so namespaces can store bytes that are not UTF-8 text. draft-ietf-jmap-metadata-04 Replaced the mapping of metadata write access onto existing rights with a new maySetMetadata right. Relaxed the per-viewer state requirement for private writes to SHOULD NOT, while still forbidding other users' /changes and /queryChanges from reporting the object. draft-ietf-jmap-metadata-03 Clarified that metadata-only changes do not update server-maintained modification timestamps. Defined behavior for requests that do not use the capability. Allowed patch paths at any depth, and placed "invalidPatch" in the /set validation order. Defined the interaction of updatedProperties and ignoreMetadataOnlyChanges with the Mailbox count properties. Added /copy behavior; excluded /import and /parse style methods. Excluded metadata from the Email/get default property list. Specified the "i;unicode-casemap" collation for metadataTextContains. Required lowercase domain-name namespace identifiers. Defined read and write rights for the data types of JMAP Mail, Calendars, Contacts, FileNode and Sieve, and the rule for objects in several containers. Clarified handling of data in unsupported namespaces in subselectors, filters, complete replacements and copies. Allowed filter condition paths at any depth below a namespace. Added terminology, defined depth recursively, and made editorial clarifications throughout. Recommended omitting the capability when no data type is listed, and noted that limits may count data from other protocols. draft-ietf-jmap-metadata-02 Redesigned the extension around two properties (metadata and privateMetadata) on each opted-in JMAP data type, rather than a separate Metadata data type with its own methods. Removed the Metadata data type, all Metadata/* methods, the related object types, the extended /get//set arguments, and the uniqueness and cascading-deletion machinery. Added a per-data-type capability advertising IANA-registered namespace support (namespaces), vendor (domain-name) namespace support (supportsVendorNamespaces), private-metadata support (supportsPrivate), and a nesting limit (maxDepth). Added updatedProperties to Foo/changes for opted-in types, modelled on Mailbox/changes in RFC 8621. Specified per-viewer behavior for /changes and /queryChanges on shared objects carrying per-user private metadata. Added FilterCondition fields to Foo/query: metadataExists, privateMetadataExists, metadataTextContains, metadataTextEquals, and the corresponding private variants. Servers MAY reject the text-match conditions with "unsupportedFilter" when implementation cost is prohibitive. Added an ignoreMetadataOnlyChanges argument to Foo/changes, letting metadata-uninterested clients skip wakeups for metadata-only changes on data types they otherwise care about. Specified PatchObject semantics for metadata and privateMetadata, including handling of unknown namespaces, error ordering on /set, and the migration case where a namespace is removed from the server's advertised set after data has been written. Replaced the previous metadata-types and metadata-properties registries with a single "JMAP Metadata Namespaces" registry. This document defines no initial entries; bindings to other protocols (e.g., IMAP METADATA, WebDAV dead properties) are expected to be defined in separate specifications. draft-ietf-jmap-metadata-01 Renamed parentType and parentId properties to relatedType and relatedId throughout the document to better reflect their purpose and avoid implying a strict hierarchy. Added filterRelatedType and filterMetadataType optional parameters to Metadata/changes method to allow filtering changes by related object type and metadata type. Changed the error type from "invalidProperties" to "alreadyExists" when a client attempts to create a Metadata object that violates the uniqueness constraint. Added requirement that relatedType must be specified in the same FilterCondition object whenever relatedIds is used in Metadata/query. Added id as a MUST support property for sorting in Metadata/query; other properties changed to SHOULD support. Replaced the metadataTypes argument with a fetchMetadata Boolean argument (default: false) in the extended /get method. Added onSuccessCreateMetadata and onSuccessUpdateMetadata arguments to the extended /set method to enable transactional metadata operations that are conditional on the success of the related object operation. draft-ietf-jmap-metadata-00 Initial version