# Specification

> A Boeks library is plain files: EPUBs, small JSON files, and Markdown. This is how they're laid out and what's in them, so other tools can read and write them too. The format is MIT licensed.

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

- [Overview](https://boeks.app/docs/specs/overview.md): What a Boeks library is, the principles it follows, and where in this specification to find what.
- [1. Library layout](https://boeks.app/docs/specs/library-layout.md): Where everything is in a library folder: the books, their editions, and the small files beside them.
- [2. Books and editions](https://boeks.app/docs/specs/books-and-editions.md): How a book and its editions relate, and what each of them keeps.
- [3. Metadata](https://boeks.app/docs/specs/metadata.md): How Boeks reads a book's details from its EPUB, and writes edits back into it.
- [4. Library index](https://boeks.app/docs/specs/library-index.md): The derived index, `.boeks/cache/library.json`, that lets a device list a library without opening every EPUB.
- [5. Logs](https://boeks.app/docs/specs/logs.md): The append-only log each device keeps, and the events in it.
- [6. Files written from the logs](https://boeks.app/docs/specs/files-from-logs.md): `Book.md` and each edition's annotations: the plain-text files written from the logs.
- [7. Locators and annotations](https://boeks.app/docs/specs/locators.md): How a place in a book, and a highlight, is recorded so that every device finds it.

JSON Schemas:

- [boeks.schema.json](https://boeks.app/docs/specs/schemas/boeks.schema.json): The library's settings, `.boeks/boeks.json`
- [book.schema.json](https://boeks.app/docs/specs/schemas/book.schema.json): The frontmatter of a book's `Book.md`
- [envelope.schema.json](https://boeks.app/docs/specs/schemas/envelope.schema.json): One line of a device's log
- [event.schema.json](https://boeks.app/docs/specs/schemas/event.schema.json): An event's type and data, for each type
- [library.schema.json](https://boeks.app/docs/specs/schemas/library.schema.json): The derived index, `.boeks/cache/library.json`

Fixtures, to test another implementation against:

- `naming/`: Metadata and the folder and file names made from it (§1.3). [names.json](https://boeks.app/docs/specs/fixtures/naming/names.json)
- `fold/`: Devices' log lines and the state they fold to, also with each log compacted (§2, §5). [change-before-creation.json](https://boeks.app/docs/specs/fixtures/fold/change-before-creation.json), [collections.json](https://boeks.app/docs/specs/fixtures/fold/collections.json), [deletion-and-restore.json](https://boeks.app/docs/specs/fixtures/fold/deletion-and-restore.json), [devices.json](https://boeks.app/docs/specs/fixtures/fold/devices.json), [duplicate-sequence.json](https://boeks.app/docs/specs/fixtures/fold/duplicate-sequence.json), [newer-format.json](https://boeks.app/docs/specs/fixtures/fold/newer-format.json), [ordering.json](https://boeks.app/docs/specs/fixtures/fold/ordering.json), [progress.json](https://boeks.app/docs/specs/fixtures/fold/progress.json), [rating-cleared.json](https://boeks.app/docs/specs/fixtures/fold/rating-cleared.json), [readthroughs-at-once.json](https://boeks.app/docs/specs/fixtures/fold/readthroughs-at-once.json), [readthroughs-stated-and-deleted.json](https://boeks.app/docs/specs/fixtures/fold/readthroughs-stated-and-deleted.json)
- `valid/`: Files and log lines every reader accepts (§1.2, §5, §6). [Book.md](https://boeks.app/docs/specs/fixtures/valid/Book.md), [Edition.md](https://boeks.app/docs/specs/fixtures/valid/Edition.md), [boeks.json](https://boeks.app/docs/specs/fixtures/valid/boeks.json), [book-log.jsonl](https://boeks.app/docs/specs/fixtures/valid/book-log.jsonl), [kobo-log.jsonl](https://boeks.app/docs/specs/fixtures/valid/kobo-log.jsonl), [library-log.jsonl](https://boeks.app/docs/specs/fixtures/valid/library-log.jsonl)
- `invalid/`: What no device may write (§5, §6). [Book.md](https://boeks.app/docs/specs/fixtures/invalid/Book.md), [Edition.md](https://boeks.app/docs/specs/fixtures/invalid/Edition.md), [events.jsonl](https://boeks.app/docs/specs/fixtures/invalid/events.jsonl)
- `newer/`: What a later version may write, which this version's schemas reject but its readers still read (§5.2). [boeks-unknown-field.json](https://boeks.app/docs/specs/fixtures/newer/boeks-unknown-field.json), [events.jsonl](https://boeks.app/docs/specs/fixtures/newer/events.jsonl)
- `files/`: Values and the exact `Book.md` or `Edition.md` written with them, and text written by hand with the values it's read as (§6). [book-example.json](https://boeks.app/docs/specs/fixtures/files/book-example.json), [book-nothing.json](https://boeks.app/docs/specs/fixtures/files/book-nothing.json), [book-own-text-kept.json](https://boeks.app/docs/specs/fixtures/files/book-own-text-kept.json), [book-quoting.json](https://boeks.app/docs/specs/fixtures/files/book-quoting.json), [book-read-leniently.json](https://boeks.app/docs/specs/fixtures/files/book-read-leniently.json), [book-readthroughs-times.json](https://boeks.app/docs/specs/fixtures/files/book-readthroughs-times.json), [edition-example.json](https://boeks.app/docs/specs/fixtures/files/edition-example.json), [edition-own-text-kept.json](https://boeks.app/docs/specs/fixtures/files/edition-own-text-kept.json)
- `locators/`: A resource's text as Locators count it, the quote at a point, and where a quote is found again (§7). [anchor-after-a-correction.json](https://boeks.app/docs/specs/fixtures/locators/anchor-after-a-correction.json), [anchor-not-found.json](https://boeks.app/docs/specs/fixtures/locators/anchor-not-found.json), [anchor-same-text-twice.json](https://boeks.app/docs/specs/fixtures/locators/anchor-same-text-twice.json), [quote-at-a-point.json](https://boeks.app/docs/specs/fixtures/locators/quote-at-a-point.json), [text-counted.json](https://boeks.app/docs/specs/fixtures/locators/text-counted.json)
