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.
- OverviewWhat a Boeks library is, the principles it follows, and where in this specification to find what.
- 1. Library layoutWhere everything is in a library folder: the books, their editions, and the small files beside them.
- 2. Books and editionsHow a book and its editions relate, and what each of them keeps.
- 3. MetadataHow Boeks reads a book's details from its EPUB, and writes edits back into it.
- 4. Library indexThe derived index,
.boeks/cache/library.json, that lets a device list a library without opening every EPUB. - 5. LogsThe append-only log each device keeps, and the events in it.
- 6. Files written from the logs
Book.mdand each edition's annotations: the plain-text files written from the logs. - 7. Locators and annotationsHow a place in a book, and a highlight, is recorded so that every device finds it.
JSON Schemas
- boeks.schema.json: The library's settings,
.boeks/boeks.json - book.schema.json: The frontmatter of a book's
Book.md - envelope.schema.json: One line of a device's log
- event.schema.json: An event's type and data, for each type
- library.schema.json: The derived index,
.boeks/cache/library.json
Fixtures
Examples to test another implementation against, where the words could be read two ways. The overview lists which sections they pin down.
naming/
Metadata and the folder and file names made from it (§1.3).
fold/
Devices' log lines and the state they fold to, also with each log compacted (§2, §5).
valid/
Files and log lines every reader accepts (§1.2, §5, §6).
invalid/
What no device may write (§5, §6).
newer/
What a later version may write, which this version's schemas reject but its readers still read (§5.2).
files/
Values and the exact
Book.mdorEdition.mdwritten with them, and text written by hand with the values it's read as (§6).locators/
A resource's text as Locators count it, the quote at a point, and where a quote is found again (§7).