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.
Bookmarks
Version 1
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.
bookmark
This describes a regular bookmark that users can click to view a page.
- title string: name of the bookmark
- bmkUri string uri of the page to load
- description string: extra description if provided
- loadInSidebar boolean: true if the bookmark should load in the sidebar
- tags array of strings: tags for the bookmark
- keyword string: alias to activate the bookmark from the location bar
- parentid string: GUID of the containing folder
- parentName string: name of the containing folder
- predecessorid string: GUID of the item before this (empty if it’s first)
- type string: “bookmark”
microsummary
Microsummaries allow pages to be summarized for viewing from the toolbar. This extends bookmark, so the usual bookmark fields apply.
- generatorUri string: uri that generates the summary
- staticTitle string: title to show when no summaries are available
- title string: name of the microsummary
- bmkUri string uri of the page to load
- description string: extra description if provided
- loadInSidebar boolean: true if the bookmark should load in the sidebar
- tags array of strings: tags for the bookmark
- keyword string: alias to activate the bookmark from the location bar
- parentid string: GUID of the containing folder
- parentName string: name of the containing folder
- predecessorid string: GUID of the item before this (empty if it’s first)
- type string: “microsummary”
query
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.
- folderName string: name of the folder/tag to link to
- queryId string (optional): identifier of the smart bookmark query
- title string: name of the query
- bmkUri string place: uri query
- description string: extra description if provided
- loadInSidebar boolean: true if the bookmark should load in the sidebar
- tags array of strings: tags for the query
- keyword string: alias to activate the bookmark from the location bar
- parentid string: GUID of the containing folder
- parentName string: name of the containing folder
- predecessorid string: GUID of the item before this (empty if it’s first)
- type string: “query”
folder
Folders contain bookmark items like bookmarks and other folders.
- title string: name of the folder
- parentid string: GUID of the containing folder
- parentName string: name of the containing folder
- predecessorid string: GUID of the item before this (empty if it’s first)
- type string: “folder”
livemark
Livemarks act like folders with a dynamic list bookmarks, e.g., a RSS feed. This extends folder, so the usual folder fields apply.
- siteUri string: site associated with the livemark
- feedUri string: feed to get items for the livemark
- title string: name of the livemark
- parentid string: GUID of the containing folder
- parentName string: name of the containing folder
- predecessorid string: GUID of the item before this (empty if it’s first)
- type string: “livemark”
separator
Separators help split sections of a folder.
- pos string: position (index) of the separator
- parentid string: GUID of the containing folder
- parentName string: name of the containing folder
- predecessorid string: GUID of the item before this (empty if it’s first)
- type string: “separator”
Version 2
Same as engine version 1, except:
- the predecessorid is removed from all records,
- instead folder and livemark records have a children attribute which is an array of child GUIDs in order of their appearance in the folder:
- children array of strings: ordered list of child GUIDs
- the special folders ‘menu’ and ‘toolbar’ now have records that are synced, purely to maintain order within them according to their ‘’’children’’’ array.
- dateAdded unix timestamp: The best lower bound on the creation date for this record we have. May be missing, in the case of records uploaded by older clients when no newer client is available to fix it up.
Version 3
Note
Proposal corresponding with storage format 6.
Same as version 2 except:
- Support for microsummaries is removed
- We use the ASCII URL
TODO document full format here since diffs are inconvenient to read.
Clients
Version 1
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.
- name string: name of the client connecting
- type string: type of the client: “desktop” or “mobile”
- commands array: commands to be executed upon next sync - see below for more
In Protocol 1.5, client records additionally include:
- version string: a version indicator for this client, such as “29.0a1”. Optional.
- protocols array: an array of Sync protocol versions supported by this client, such as [“1.1”, “1.5”]. Optional.
In Bug 1097222 additional optional fields were added:
- os string: an OS name, most likely one of “Darwin” (Mac OS X), “WINNT” (Windows), “Android”, or “iOS”.
- appPackage string: an unambiguous identifier for the client application. For Android, this is the package (e.g., org.mozilla.firefox_beta). For desktop this is the value of Services.appinfo.ID.
- application string: a human-readable application name, such as “Nightly” or “Firefox”.
- formfactor string: a value such as “phone”, “tablet” (or the more specific “largetablet”, “smalltablet”), “desktop”, “laptop”, “tv”.
- device string: a description of the hardware that this client uses. Currently only supported by Android; returns values like “HTC One”.
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.
commands
commands is an array of JSON objects. Each element has the following attributes:
- command string: The name of the command to execute. Currently supported commands include “resetAll”, “resetEngine”, “wipeAll”, “wipeEngine”, “logout”, “displayURI”, “repairRequest” and “repairResponse”, although not all commands are supported by all implementations.
- args array of strings/objects: Arguments for the command. These are specific to the command.
- flowIID optional, string: A guid used for reporting telemetry. Both the sender and receiver of the command should report this ID in telemetry so the reliability of the sending and reception of the command can be tracked.
Version 2 (never deployed)
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:
- name string: The name of the client. This is a user-facing value and
may be provided by the user.
- formfactor string: The form factor of the client. Recognized values
include phone, tablet, laptop, desktop.
- application string: String identifying the application behind the
client. This should only be used for presentation purposes (e.g. choosing what
logo to display).
- version string: The version of the client. This is typically the
version of the application. Again, this should only be used for presentation
purposes.
- capabilities object: Denotes the capabilities a client possesses. Keys
are string capability names. Values are booleans indicating whether the
capability is enabled. Modifying the capabilities of another client’s record
should not change the enabled state on that client.
- mpEnabled bool: Whether master password is enabled on the client. If
master password is enabled on any client in an account, the current client
should hesitate before downloading passwords if master password is not
enabled locally, as this would decrease the security of the passwords locally
since they wouldn’t be protected with a master password.
History
Version 1
Every page a user visits generates a history item/page. One history (page) per record.
- histUri string: uri of the page
- title string: title of the page
- visits array of objects: a number of how and when the page was visited
- date integer: datetime of the visit
- type integer: transition type of the visit
Version 2 (never deployed)
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.
- uri string: URI of the page that was visited.
- title string: Title of the page that was visited.
- visits object: Mapping of visit type to visit times.
The keys in visits define the transition type for the visit. They can be
one of the following:
- 1: A link was followed.
- 2: The URL was typed by the user.
- 3: The user followed a bookmark.
- 4: Some inner content was loaded.
- 5: A permanent redirect was followed.
- 6: A temporary redirect was followed.
- 7: The URL was downloaded.
- 8: User follows a link that was in a frame.
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.
Passwords
Saved passwords help users get back into websites that require a login such as HTML input/password fields or HTTP auth.
- hostname string: hostname that password is applicable at
- formSubmitURL string: submission url (GET/POST url set by <form>)
- httpRealm string: the HTTP Realm for which the login is valid. if not provided by the server, the value is the same as hostname
- username string: username to log in as
- password string: password for the username
- usernameField string: HTML field name of the username
- passwordField string: HTML field name of the password
If possible, clients should also write fields corresponding to nsILoginMetaInfo:
- timeLastUsed unsigned long: local Unix timestamp in milliseconds at which this password was last used.
Note that client clocks can be wrong, and thus this time can be dramatically earlier or later than the modified time of the record.
Consuming clients should be careful to handle out of range values.
- timeCreated unsigned long: as with timeLastUsed, but for creation.
- timePasswordChanged unsigned long: as with timeLastUsed, but for password change.
- timesUsed unsigned long: the number of uses of this password.
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.
Preferences
Version 1
Some preferences used by Firefox will be synced to other clients. There is only one record for preferences with a GUID “preferences”.
- value array of objects: each object describes a preference entry
- name string: full name of the preference
- type string: the type of preference (int, string, boolean)
- value depends on type: value of the preference
Version 2
There is only one record for preferences, using nsIXULAppInfo.ID as the GUID. Custom preferences can be synced by following these instructions.
- value object containing name and value of the preferences.
Note: The preferences that determine which preferences are synced are now included as well.