Export file format

This page documents the JSON file Bookil writes when you export your library. It’s for users who want to inspect or transform the file. Routine backup and restore use the in-app commands described in Back up your library.

File

• Name: Bookil Library.json (always).
• Format: pretty-printed JSON with sorted keys.
• Dates: ISO 8601 strings.

Root shape

{
  "schemaVersion": 1,
  "books": [ /* ExportBook */ ],
  "collections": [ /* ExportCollection */ ]
}

schemaVersion is currently 1. Older versions of Bookil produced a different format and are not compatible.

ExportBook

{
  "fingerprint": "string",
  "fingerprintSourceRawValue": "pdfID" | "fileNameFallback",
  "name": "string",
  "totalPages": 123,
  "readingDirectionOverride": "leftToRight" | "rightToLeft" | null,
  "currentPage": 0,
  "openedAt": "2026-06-24T12:00:00Z" | null,
  "completedAt": "2026-06-24T12:00:00Z" | null,
  "createdAt": "2026-06-24T12:00:00Z",
  "updatedAt": "2026-06-24T12:00:00Z",
  "bookmarks": [ /* ExportBookmark */ ],
  "inkPages": [ /* ExportInkPage */ ]
}

• fingerprint — Bookil’s stable identifier for a PDF. Bookil takes it from the PDF’s internal /ID. If the PDF has no /ID, Bookil falls back to the file name.
• fingerprintSourceRawValue — pdfID when the fingerprint came from the PDF; fileNameFallback when it came from the file name.
• name — the PDF’s file name as it appears in Bookil’s library.

ExportCollection

{
  "name": "string",
  "sortOrder": 1024,
  "isLocked": false,
  "createdAt": "2026-06-24T12:00:00Z",
  "updatedAt": "2026-06-24T12:00:00Z",
  "items": [ /* ExportCollectionItem */ ]
}

• isLocked — true for a private collection, false for a regular collection. The export holds the lock state, and book metadata is written out in plain text.

ExportCollectionItem

{
  "fingerprint": "string",
  "fingerprintSourceRawValue": "pdfID" | "fileNameFallback",
  "fileName": "string",
  "sortOrder": 1024,
  "createdAt": "2026-06-24T12:00:00Z",
  "updatedAt": "2026-06-24T12:00:00Z"
}

When importing, Bookil tries to match items to books in this order: fingerprint, then fileName.

ExportBookmark

{
  "pageIndex": 41,
  "label": "string" | null,
  "createdAt": "2026-06-24T12:00:00Z",
  "updatedAt": "2026-06-24T12:00:00Z"
}

pageIndex is zero-based.

ExportInkPage

{
  "pageIndex": 0,
  "drawingData": "base64-encoded-bytes",
  "drawingMimeType": "application/x-pkdrawing",
  "boundsX": 0.0,
  "boundsY": 0.0,
  "boundsWidth": 595.0,
  "boundsHeight": 842.0,
  "createdAt": "2026-06-24T12:00:00Z",
  "updatedAt": "2026-06-24T12:00:00Z"
}

drawingData holds the PencilKit drawing in PencilKit’s native format.

Sort order

Lists in the file are sorted deterministically so diffs between two exports stay clean:

• books — by file name, then fingerprint.
• collections — by sortOrder, then name.
• items inside a collection — by sortOrder, then file name.
• bookmarks and inkPages — by pageIndex.

Compatibility

• Bookil reads ISO 8601 dates and numeric (Unix epoch seconds) dates. Either form works.
• Bookil 2025.08.1 and earlier used a different export shape (a flat list of books). Files in that format cannot be imported by this version.
• Future versions may add fields. Bookil ignores fields it doesn’t recognize on import.