# Overview

> What a Boeks library is, the principles it follows, and where in this specification to find what.

Canonical: https://boeks.app/docs/specs/overview

A Boeks library is a folder of plain files: the books as EPUBs and audiobook files, and beside them small JSON and Markdown files with everything about reading them. There's no database and no server. This specification describes that folder, so any tool can read a library and add to it. It's licensed under MIT.

**Status:** the format is in development and may still change before 1.0. `version` in `.boeks/boeks.json` (§1.2) says which version a library is in.

## Terms

These are the words for these things everywhere: in this specification, the code, and what each app, the CLI, the e-reader plugins, and the website show. Where what people see uses another word than the format, it's said here.

- **Library:** a folder whose `.boeks/` holds `boeks.json`. Its books are in folders below it.
- **Book:** a work, like *Dune*, with one folder in the library. It has one or more editions (§2).
- **Edition:** one version of a book: an EPUB (an ebook), like the original or a translation, or an audiobook (§2, §9).
- **Primary edition:** the edition that gives its book its folder name, cover, and metadata (§2.2).
- **Transform:** a change to an edition's file that keeps its text, such as the upgrade to EPUB 3, logged and then applied like an edit (§3.4).
- **Creator:** a person credited on an edition, with MARC roles, as the OPF's `dc:creator` has them (§3). What people see names the role: author, editor, translator, narrator.
- **Device:** something that reads the library, like an iPhone or a Kobo, with an ID of its own (§5.7).
- **Log:** a device's file of events, one per book and one for the library (§5). The logs are where reading data lives.
- **Event:** one line in a log, like progress or a highlight (§5.3).
- **Locator:** a location in an edition's text, or an audiobook's time (§7).
- **Progress:** where reading is in an edition, as a device saves it: a Locator in `progress.updated` (§5.3). Following another device's newer progress is §5.5.
- **Place:** where progress, or any Locator, is for people: its page (§7) and chapter, worked out from the edition's positions and contents, or for an audiobook its time. It's shown, never stored.
- **Reading status:** unread, reading, paused, read, or stopped; one per book (§5.3). Code calls it `ReadingStatus`.
- **Read-through:** one reading of a book, from start to finish or stop (§5.3). `Book.md` lists them under `readthroughs` (§6.2).
- **Stated date:** a read date someone gave, to the year, month, day, or minute, rather than a moment a device recorded. It has no time zone, and is shown as it was given (§5.3).
- **Offset:** how far from UTC an event's moment happened, in minutes, so its time is shown as it was where it happened (§5.2).
- **Session:** a stretch of reading or listening, found in a device's progress (§5.3).
- **Annotation:** a highlight, with or without a note, or a page bookmark, modeled on the W3C Web Annotation, with a Locator as its target (§7). What people see says annotations for all of them together, and highlights, notes, or bookmarks where it means only those.
- **Collection:** a name the reader gives books, like "Favorites"; a book can be in several, and a collection exists while a book is in it, as a tag does (§5.4).
- **Genre:** a subject from the edition's metadata, like "Science Fiction", not chosen by the reader as a collection is (§3.1, §11).
- **Sync:** bringing devices' logs together: through the folder sync that carries the library, or directly over Wi-Fi (§8.2) or, with a Kobo, USB (§17.3).
- **Shared work file:** a file of slow work any device may do and every device uses, written whole by whichever saves it, such as an alignment (§1.4).
- **Timeline:** what was done with a book on each device, by day, newest first, as read from its logs, each time as it was where it happened (§5.3). The Apple app shows it as the book's History.
- **Pair:** an ebook and an audiobook of the same book, where the audio is a reading of that ebook's text (§9.1).
- **Alignment:** what maps times in a pair's audiobook to Locators in its ebook (§9.2).
- **Reading along:** playing an aligned audiobook in its ebook, the sentence being read standing out (§9.4).
- **Boeks for Kobo:** the mod for Kobo's own reader, Nickel (§17).

Each device's own screens follow its platform's wording and conventions over the app's: "Sync now" in KOReader and on the Kobo, "Sync Now" on Apple's; "Last sync:" on the Kobo, as Nickel says it, and "Last Synced" in the app.

## Principles

1. **The EPUB is the source of truth for its edition's metadata.** Edits are logged first and then written into the EPUB (§3.3).
2. **What you do with a book lives outside the EPUB,** in each device's logs (§5). It can also be read and edited as plain-text files written from the logs: `Book.md` and each edition's annotations (§6).
3. **Each device writes only its own files.** The exceptions are written so that any device writes the same, or so that it doesn't matter which one does:
   - from the logs: the EPUBs and audiobooks' tags when edits are applied, and the renames that follow them (§1.3, §3.3), and the files of §6
   - `boeks.json`, whose settings change rarely, rewritten by whichever device changes one (§1.2)
   - the derived files in `.boeks/cache/`, which any device can rebuild (§4)
   - the files of slow work any device may do and every device uses, written whole by whichever saves them, such as an audiobook's alignment (§1.4)
   - a device's log written by the device holding its storage, as the Mac does a Kobo's over USB (§5.1)
4. **Derived data is disposable.** The index and the cached covers can be deleted and rebuilt.
5. **Plain text** for everything but books and media.
6. **Paths are presentation; IDs are identity.** Renaming a folder never loses data.
7. **Standards before inventions:** the Readium Locator, W3C Web Annotation, EPUB 3 metadata, and the conventions of Goodreads, Hardcover, and Open Library.
8. **A small footprint:** the format's own files live only in folders named `.boeks/`, one at the library's root and one in each book. `Book.md` and each edition's `Edition.md` are the exception on purpose: they're the reader's files, next to the books.
9. **Anyone can edit any file.** Everything is plain text, so code reading it assumes nothing: what doesn't check out is skipped, or replaced by its default.

## Reading a library

1. Find the root: the folder whose `.boeks/` holds `boeks.json`.
2. Each book is a folder with a `.boeks/` of its own, holding one log per device (§1, §5.1).
3. Read every device's log of a book, order the events by `(timestamp, device, sequence)`, and fold them into the book's state (§5.2, §5.4). Skip what you don't understand.
4. Progress and annotations are Locators into an edition (§7). Each edition's annotations are also in its Markdown file, written from the logs (§6.3).

Everything in `.boeks/cache/`, the index and the covers, is derived (§4): read them for speed, but you can always rebuild them from the files.

## Writing to a library

- **Write only your own log.** Pick a device ID (§5.7), register it with `device.registered`, and append events to your own files. Never change another device's.
- **Keep what you don't know.** Keep unknown fields when you rewrite `boeks.json` and the files of §6, and never drop an event type you don't know.
- **Mind the version.** If `boeks.json` says a higher `version` than you know, open the library read-only.

Every file has a JSON Schema, and the sections under Conformance have fixtures to test against: both are listed beside this specification, on [its page](https://boeks.app/docs/specs).

## Conformance

These sections are required: an app that reads or writes a library follows them exactly, or devices disagree about what's in it. Fixtures pin them down where words could be read two ways, and Boeks is tested against the same files.

| Section | What | Fixtures |
|---|---|---|
| §1.1–1.3 | Where everything is, `boeks.json`, and folder and file names | `naming/` |
| §1.4 | Shared work files | |
| §2.1, §2.2, §2.4, §2.5 | Book and edition IDs, fanning out edits, merging, deleting and removing | `fold/` |
| §3.1–3.4 | Reading metadata, writing edits and transforms into a file | |
| §4 | The index, for an app that writes it | |
| §5.1–5.4, §5.6, §5.7 | Logs, ordering, events, merging, compaction, devices | `valid/`, `invalid/`, `newer/`, `fold/` |
| §6 | `Book.md` and `Edition.md` | `valid/Book.md`, `valid/Edition.md`, `files/` |
| §7 | Locators and annotations | `locators/` |

How an app behaves is recommended, not required: following progress from another device (§5.5), and when a device applies edits.

## Sections

- **§1 Library layout:** where everything is.
- **§2 Books and editions:** how a book and its editions relate.
- **§3 Metadata:** what's read from an EPUB, and how edits are written back.
- **§4 Library index:** the derived index.
- **§5 Logs:** the events, and how they're merged.
- **§6 Files written from the logs:** `Book.md`, and each edition's annotations.
- **§7 Locators and annotations:** progress and annotations in a book.
