# 4. Library index

> The derived index, `.boeks/cache/library.json`, that lets a device list a library without opening every EPUB.

Canonical: https://boeks.app/docs/specs/library-index

The index lets a device list and search the library without opening, or even having, every EPUB. It's derived from the files: read it for speed, and rebuild what's stale or missing.

```json
{
  "version": 1,
  "books": {
    "01j9z3k4m5n6p7q8r9s0t1v2w3": {
      "path": "Frank Herbert/Dune",
      "editions": {
        "01j9z3k4m5n6p7q8r9s0t1v2w4": {
          "file": "Ebook/Dune - Frank Herbert.epub",
          "hash": "9f86d081884c7d65…",
          "metadata": { "title": "Dune", "creators": [{ "name": "Frank Herbert", "roles": ["aut"] }] },
          "epub": "3.0"
        }
      }
    }
  }
}
```

- **Books** are keyed by book ID, each with its folder (`path`, relative to the root, with `/` separators) and its editions, keyed by edition ID.
- **Each edition** has the path of its `file` in the book folder, the `hash` of the file it was read from, its `metadata` as read from the file (before any pending edits, §3.3), its `drm` if it's encrypted (`adept`, `lcp`, or `other`), and its EPUB version (`epub`), or an audiobook's length in milliseconds (`duration`) with its metadata read from its tags (§9). An audiobook in several files also has its `tracks`, in the order they play: each file's name in the folder (`file`), its title tag (`title`), and its length in milliseconds (`duration`).
- **An entry is stale** when the edition's file no longer has its `hash`, or when the index's `version` is lower than the one the device reads files as. The version is this specification's, now 1, and goes up with a new version of it when reading a file gives something else, such as a field read that wasn't before: an implementation writes the version whose reading it follows, never a number of its own. An index a newer version wrote is read as it is and left alone, as that version reads files at least as well: otherwise two devices on different versions would each read the whole library again whenever the other had written it. Any device can rebuild the entries it finds stale; one whose file isn't here keeps what the index knew. An entry stale only by `version`, whose `hash` is the one the edition's logs name, is read from the file again without hashing it: hashing every audiobook would hold up opening the library.
- **Covers** are at `.boeks/cache/covers/<edition-id>.<ext>`, one per edition, taken from its file, or from the image of a cover edit not yet written (§3.6), with the extension of the image's type. The book's cover is its primary edition's. An empty file isn't a cover, and is extracted again.
- **Both are disposable,** as everything in `.boeks/cache/` is. A missing or unreadable index is an empty one. A sync-conflict copy of `library.json` is deleted, and the index rebuilt.
