JMAP Object History

Introduction JMAP ( — JSON Meta Application Protocol) provides a standard set of methods for each data type: Foo/get, Foo/changes, Foo/set, Foo/query, and Foo/queryChanges. These methods operate on the current state of objects. The Foo/changes method tells a client which objects have changed, but does not provide the previous values. In many applications it is useful to access historical versions of objects. For example, a user may want to see previous versions of a contact record (), recover a deleted email (), or audit changes to a shared mailbox. This extension adds history support to the standard Foo/get method. When the urn:ietf:params:jmap:object-history capability is included in the request's using array, Foo/get gains additional parameters that allow the client to request previous versions of objects, including objects that have been destroyed.

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 when, and only when, they appear in all capitals, as shown here.

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

urn:ietf:params:jmap:object-history The capability urn:ietf:params:jmap:object-history being present in the "accountCapabilities" property of an account represents support for retrieving historical object versions in that account. 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 for that account: maxHistoryDuration: "UnsignedInt|null" The maximum number of seconds after replacement that the server retains old versions, or null if the server does not impose a time-based limit. A version whose replaced timestamp is more than this many seconds ago may have been discarded.

Extensions to Foo/get When this capability is included in the request's using array, the standard Foo/get method (, Section 5.1) accepts the following additional request arguments: includeReplaced: "Boolean" (default: false) If true, the server returns previous versions of the requested objects in addition to the current version. Each previous version appears as a separate entry in the list array, with the same id as the current version. Every entry includes an objectHistory property (see below). Entries with the same id MUST be ordered by objectHistory.version (ascending). Entries for different objects MAY be interleaved. includeDestroyed: "Boolean" (default: false) If true, the server also returns objects that have been destroyed. If includeReplaced is false, only the final version before destruction is returned. If includeReplaced is true, all retained historical versions of destroyed objects are returned. For destroyed objects, every entry has a non-null objectHistory.replaced value, since every version has been superseded (the final version was replaced by destruction). historyAfter: "UTCDate|null" (default: null) If supplied, only versions with an objectHistory.replaced value strictly after this date are returned, plus the current (live) version which has a null replaced value. If null, no time-based filter is applied. historyLimit: "UnsignedInt|null" (default: null) If supplied, the maximum total number of entries to return in the list array. The server MUST return the most recent entries (those with the highest version numbers), not the oldest. If the limit is reached for any requested id, the response includes a hasMoreHistory property set to true. A client that needs to know which specific objects have more history available must fetch each id individually.

The objectHistory property When includeReplaced or includeDestroyed is true, each object in the list array includes an additional property: objectHistory: "ObjectHistoryInfo" An ObjectHistoryInfo object with the following properties: version: "UnsignedInt" A per-object monotonically increasing number that provides ordering among the versions of a single object within a response. Version numbers MAY have gaps (e.g., a server may use internal sequence numbers such as modseq values). The current (live) version of an object always has the highest version number. Servers SHOULD return consistent version numbers across requests, but clients MUST NOT rely on this — version numbers exist primarily to provide ordering within a single response. replaced: "UTCDate|null" The date and time at which this version was superseded, either by a subsequent update or by destruction. If null, this is the current live version of the object. For destroyed objects, every version has a non-null replaced value — the final version's replaced is the time of destruction. When includeReplaced and includeDestroyed are both false (the default), the objectHistory property is not included in the response, and the behaviour is identical to standard Foo/get. The server is not required to create a new version for every individual change to an object. For example, rapid successive updates may be collapsed into a single version. The server MAY also prune old versions in any order, so there can be gaps in the version history available to the client. Clients MUST NOT assume that the version history is complete or contiguous. If the server does not retain history for a particular data type, it MUST still return the current version with an objectHistory property when requested. In this case, the server MAY return a version of 1 for every object and a replaced of null, and ignore the includeReplaced flag (since there are no previous versions to return). The includeDestroyed flag may still be honoured if the server tracks destroyed object ids even without full history.

Additional response properties When includeReplaced or includeDestroyed is true, the response includes: hasMoreHistory: "Boolean" If true, there are older entries available for at least one requested id. The client can make a wider request (e.g., a larger historyLimit or individual id requests) to retrieve more versions. If false, the server has returned all retained history for the requested ids. The server MAY return false even if more history exists (e.g., if it cannot efficiently determine whether older versions remain). If the server returns true, the client MUST NOT assume the history will still be available in a subsequent request, as the server may purge history at any time.

Examples

Contact history Requesting the history of a contact, including all versions:

The response includes three versions: the original creation, a name update, and the current version with an additional email address:

Recovering destroyed emails A client can use Email/changes to discover which emails have been destroyed, then use a backreference to fetch their final state. This is useful for displaying a "recently deleted" view:

The Email/get response returns the final state of each destroyed email. The objectHistory.replaced value is the time of destruction:

Since includeReplaced was not set, only the final version of each destroyed email is returned. The non-null replaced value indicates when each email was destroyed.

IANA Considerations

JMAP Capability Registration for urn:ietf:params:jmap:object-history IANA is requested to register the "Object History" Capability as follows: Capability Name: urn:ietf:params:jmap:object-history Intended use: common Change Controller: IETF Specification document: this document Security and privacy considerations: this document, Security Considerations

Update to the JMAP Data Types Registry This document adds a "Supports History" column to the "JMAP Data Types" registry defined in , Section 9.4. The value is "Yes" or "No", indicating whether the data type supports the history extensions defined in this document. The initial values for existing registrations are: Type Name Supports History Core/Echo No Mailbox Yes Thread No Email Yes SearchSnippet No Identity Yes EmailSubmission No VacationResponse Yes ContactCard Yes AddressBook Yes Principal No Quota No FileNode Yes The default value for this column is "No". New registrations that do not explicitly include a value are assumed not to support history.

Security Considerations All security considerations from apply to this document.

Storage and Resource Consumption Retaining historical versions of objects can consume significant server storage. Servers SHOULD impose reasonable limits on history retention, either by duration (advertised via maxHistoryDuration) or by total storage. Servers MAY silently discard history entries when storage limits are reached.

Access Control Historical versions of an object MUST respect the same access controls as the current version. A user who does not have permission to read an object MUST NOT be able to read its history. If an object's access permissions have changed over time, the server MUST only return versions for which the requesting user would have had read access.

Information Disclosure Object history may reveal information that the user or an administrator intended to remove. For example, a contact record that was updated to remove a phone number will still have that phone number visible in its history. Servers SHOULD provide administrators with the ability to purge history for specific objects when required for privacy or compliance reasons.

Changes EDITOR: please remove this section before publication. The source of this document exists on github at: https://github.com/brong/draft-gondwana-jmap-object-history/ draft-gondwana-jmap-object-history-00 initial proposal

Acknowledgements TODO {backmatter}