For developers · experimental

The data bundle format

OpenExtract can save an iPhone backup's messages, calls, voicemail, contacts, photo details and people as one folder of plain JSON, with a SHA-256 hash of every file. Any tool can read it: a script, a spreadsheet, or a program of your own. This page describes the format.

Experimental for now

This is version 0.1 of the format. Until it reaches 1.0 it can still change from one version of OpenExtract to the next. Every bundle says which version it is, in manifest.json, and each version has its own JSON Schemas. If you write a tool that reads bundles, check schema_version first.

Making one

Open a backup in OpenExtract, click Save to this computer, and under For other tools click Export next to Export a data bundle. Tick the kinds of data you want and the files to copy in (message attachments and voicemail audio are ticked to start with; photo and video files aren't, because they can take a lot of space). Then choose a folder. Everything happens on your computer: nothing is uploaded.

What's in it

The .jsonl files are JSON Lines, one record per line, so a tool can read millions of messages a line at a time. Every date is in UTC, like 2024-07-05T16:10:00Z, and manifest.json also names the time zone of the computer that made the bundle.

The integrity check

SHA256SUMS is in the format the sha256sum command reads, so anyone can check a bundle from inside its folder:

shasum -a 256 -c SHA256SUMS     # macOS
sha256sum -c SHA256SUMS         # Linux

It shows whether any file has changed since the bundle was made. It doesn't say anything about how the backup itself was made, or who made the bundle.

Versions

While the version starts with 0, a new version can add, rename or remove fields and files. Each change gets a new schema_version, its own schemas, and a line in the format's change list. From 1.0 on, a version like 1.1 will only add things, so a tool written for 1.0 keeps working; a change that would break a tool will be 2.0.

The full description

Every file and field is described in docs/BUNDLE.md on GitHub, next to the JSON Schemas. OpenExtract is open source (MIT), so the code that writes bundles is there too: python/bundle.py. Questions and suggestions are welcome as an issue on GitHub.