Decrypted data objects are cleartext JSON strings.
Each collection can have its own object structure. This page documents the format of each collection.
The object structure is versioned with the version metadata stored in the meta/global payload.
The following sections, named by the corresponding collection name, describe the various object formats and how they’re used. Note that object structures may change in the future and may not be backwards compatible.
In addition to these custom collection object structures, the Encrypted DataObject adds fields like id and deleted. Also, remember that there is data at the Weave Basic Object (WBO) level as well as id, modified, sortindex and payload.
Version 1 is likely only affiliated with storage format 5 clients.
One bookmark record exists for each bookmark item, where an item may actually be a folder or a separator. Each item will have a type that determines what other fields are available in the object. The following sections describe the object format for a given type.
Each bookmark item has a parentid and predecessorid to form a structure like a tree of linked-lists to provide a hierarchical ordered list of bookmarks, folders, etc.
This describes a regular bookmark that users can click to view a page.
Microsummaries allow pages to be summarized for viewing from the toolbar. This extends bookmark, so the usual bookmark fields apply.
Place queries are special bookmarks with a place: uri that links to an existing folder/tag. This extends bookmark, so the usual bookmark fields apply.
Folders contain bookmark items like bookmarks and other folders.
Livemarks act like folders with a dynamic list bookmarks, e.g., a RSS feed. This extends folder, so the usual folder fields apply.
Separators help split sections of a folder.
Same as engine version 1, except:
Note
Proposal corresponding with storage format 6.
Same as version 2 except:
TODO document full format here since diffs are inconvenient to read.
Client records identify a user’s one or multiple clients that are accessing the data. The existence of client records can change the behavior of the Firefox Sync client – multiple clients and/or mobile clients result in syncs to happen more frequently.
In Protocol 1.5, client records additionally include:
In Bug 1097222 additional optional fields were added:
If these fields are missing, clients are expected to fall back to behaviors that do not depend on the missing data.
Clients should preserve existing fields if possible when sending commands to another client.
Note
Proposal corresponding with storage format 6.
Each client has its own record which it is authoritative for. No other client should modify another client’s record except in the case where records are deleted.
The payload of a client record has the following fields:
Note
Proposal corresponding with storage format 6.
This collection holds commands for clients to process. The ID of command records is randomly generated.
Command records contain an extra unencrypted field in the BSO that says which client ID they belong to. The value is the hash of the client ID with the commands engine salt.
Command data is an object with the following fields:
Form data is used to give suggestions for autocomplete for a HTML text input form. One record is created for each form entry.
Every page a user visits generates a history item/page. One history (page) per record.
Note
Proposal corresponding with storage format 6.
History visits are now stored as a timeline/stream of visits. The historical information for a particular site/URL is spread out of N>=1 records.
Payloads have the structure:
{
"items": [
"uri": "http://www.mozilla.org/",
"title": "Mozilla",
"visits": {
1: [1340757179.82, 184],
2: [1340341244.31, 12, 4]
}
]
}
The bulk of the payload is a list of history items. Each item is both a place and a set of visits.
The keys in visits define the transition type for the visit. They can be one of the following:
These correspond to nsINavHistoryService’s transition type constants <https://developer.mozilla.org/en/nsINavHistoryService#Constants>.
The values for each visit type are arrays which encode the visit time. The initial array element is the wall time of the first visit being recorded in seconds since epoch, typically with millisecond resolution. Each subsequent value is the number of seconds elapsed since the previous visit. The values:
[100000000.000, 10.100, 5.200]
Correspond to the times:
100000000.000
100000010.100
100000015.300
The use of deltas to represent times is to minimize the serialized size of visits.
Saved passwords help users get back into websites that require a login such as HTML input/password fields or HTTP auth.
If possible, clients should also write fields corresponding to nsILoginMetaInfo:
Note that these fields are not required as part of the record, so clients should expect them to be missing. Clients that don’t use this data locally are encouraged to pass through when it makes sense (timeCreated), or wipe when invalidation is the best option (e.g., timePasswordChanged).
Note also that clients should use judgment when updating these fields. It is typically not feasible to upload new records each time a password is used on the web. Neither would it make sense during download to treat a non-matching timestamp, or a missing field in an otherwise matching local record, as a record collision. The handling of these fields introduces new complexities in reconciliation.
The Firefox desktop client began recording this data in Bug 555755.
Some preferences used by Firefox will be synced to other clients. There is only one record for preferences with a GUID “preferences”.
There is only one record for preferences, using nsIXULAppInfo.ID as the GUID. Custom preferences can be synced by following these instructions.
Note: The preferences that determine which preferences are synced are now included as well.
Tabs describe the opened tabs on a given client to provide functionality like get-up-n-go. Each client will provide one record.
Note
Proposal corresponding with storage format 6.
In version 2, each tab is represented by its own record. (This is a change from version 1.)
The payload of the BSO is a JSON object containing the following fields: