Specification · §1
Library layout
Where everything is in a library folder: the books, their editions, and the small files beside them.
1. Library layout
Library/
.boeks/
boeks.json # the library's settings; marks the root (§1.2)
cache/ # derived, and disposable (§4)
library.json # the index
covers/<edition-id>.jpg # each edition's cover
mac-studio-4f2.jsonl # library-level logs, one per device (§5)
iphone-7k3.jsonl
Frank Herbert/
Dune/ # a book (§2)
Book.md # status, rating, collections, and review (§6.2)
Ebook (en)/ # an edition (§1.3), the primary one
Dune - Frank Herbert.epub
Edition.md # that edition's annotations (§6.3)
Ebook (nl)/ # another edition, a translation
Duin - Frank Herbert.epub
Audiobook/ # an audiobook, also an edition (§9)
Dune - Frank Herbert.m4b
.boeks/
iphone-7k3.jsonl # book-level logs, one per device (§5)
kobo-libra-x7m.jsonl
covers/<sha256>.jpg # covers set by edits (§3.6)
alignments/<audiobook>-<ebook>.json # an audiobook aligned with its ebook (§9.2)
1.1 The .boeks/ folders
- What's in a folder named
.boeks/belongs to the format. Everything else in a library is the reader's: the editions' folders and files,Book.md, and each edition'sEdition.md. - The root is the folder whose
.boeks/holdsboeks.json. - A book folder is any folder below the root with a
.boeks/of its own, at most 8 folders down, wherever it is: a moved book is still a book. Nothing inside a book folder is looked through for other books. Hidden folders, readers' sidecars (*.sdr), and symbolic links are passed over, so reading stays inside the library. An EPUB outside any book folder is a file to import. - The folders are hidden, so file browsers and e-readers show a book folder with only the reader's files in it. A library has to be synced with its hidden folders: without a book's
.boeks/, its progress and highlights are gone. Some sync services leave hidden folders out unless told otherwise. - A
Book.mdor an edition's folder without a.boeks/beside it is a book whose.boeks/hasn't arrived, since only a book with a.boeks/gets aBook.md, and only Boeks names folders as editions' (Ebook,Audiobook, alone or with qualifiers, §1.3). An unread book without a rating or collections has noBook.md, so its edition folders are what show it. Don't import its editions as a new book, and don't create a library over such a folder: either would compete with the book or library still syncing.
1.2 boeks.json
{
"version": 1,
"settings": { … }
}
versionis the library's format version: its layout,boeks.json, the logs and their events, and the files of §6. The index (§4) and each shared work file (§1.4) have aversionof their own, for how they're made: a device makes one of an older version again, and leaves one of a newer version alone.- It goes up only for a change older tools can't read safely, such as an event whose meaning changes or a file that moves. An addition, such as a new field, event type, value, or setting, leaves it as it is, since readers pass over what they don't know (§5.2).
- A tool that meets a higher
versionthan it knows opens the library read-only, and writes nothing to it, e-reader plugins included. - Moving a library to a new version rewrites only
boeks.jsonand the derived files (§4), never a device's log.
settingsare the library's own, the same on every device.settings.transformslists the transforms to run on import (§3.4), none unless the library sets some, andsettings.fetchwhich metadata providers to ask online, in order, and how their genres are taken (§11). Keep the settings you don't know as they are.- Rewriting it: whichever device changes a setting rewrites the file, keeping the fields it doesn't know.
1.3 Folder and file names
Every library is filed the same way, so each device puts a book in the same place.
- Book folders are
{author}/{title}, with the author folders at the root. - The author is the first
dc:creatorwith roleaut, in the OPF's order, by its display name (notfile-as). Without one, the firstedt, for anthologies; without that, the first creator with no role; and without any, or with a name that's empty once made safe (below),Unknown Author. - The title is the edition's title, or
Untitledwithout one, or with one that's empty once made safe. - Two books with the same author and title: the one named second gets its year in parentheses after the title (
Dune (1965)), or when that's taken too, the first number from 2 that's free (Dune (2)). The first keeps its name, so a book arriving never renames one already there. A name is cut to fit the 100 bytes with its qualifier. - Edition folders: each edition is a folder in the book's folder, named by its kind:
Ebook, orAudiobook(§9). These are the words the apps show, in English on every device, likeBook.md.- Editions of the same kind are told apart by qualifiers, in parentheses. For ebooks: the language, then the year, then the publisher, then a number. For audiobooks: the language, then the narrator (the first creator with role
nrt), then the year, then a number. Numbers go in the order the editions were added, and by ID for those added at the same time, from 1: unlike books, every edition still sharing a name is qualified, so none keeps a plain name that a later one would take from it. - Each step qualifies every edition whose name is still shared, and only those, by its value there. A step where they all have the same value is skipped, and one without a value is told apart from those with one by having none:
EbookbesideEbook (en). For example, a book with English editions from 1965 and 2019 and a Dutch one hasEbook (en, 1965),Ebook (en, 2019), andEbook (nl). One ebook and one audiobook areEbookandAudiobook. - The primary edition gets no plain name of its own, so making another edition primary renames nothing. Adding an edition can qualify the folder of one already there:
EbookbecomesEbook (en)when a Dutch ebook arrives. - Languages are written as their codes (
nl), years as the edition's publication year, and narrators and publishers by name. Values are compared as names are, ignoring case.
- Editions of the same kind are told apart by qualifiers, in parentheses. For ebooks: the language, then the year, then the publisher, then a number. For audiobooks: the language, then the narrator (the first creator with role
- Edition files are
{title} - {author}.epub, in the edition's folder, from the edition's own metadata, so the name says which book it is wherever the file goes. An edition in several files, such as an audiobook in MP3s, keeps its files' own names.- A name too long has its title cut to fit, keeping
- {author}and the extension whole; when the author would take half the name or more, the whole name is cut instead. - A name another file has gets a qualifier in parentheses after the author, before the extension: the edition's language, then its year, then the first number from 2 that's free (
Dune - Frank Herbert (en).epub). - "Half the name" is half of what's left of the 100 bytes after the qualifier and the extension. A part is cut first, then dots and spaces are trimmed from its ends.
- A name too long has its title cut to fit, keeping
- An edition's own files are in its folder too:
Edition.mdholds its annotations (§6.3). A reader's own files beside the edition's file are left alone, except KOReader's.sdrfolder, which is renamed with the file whose name it has. - Names work on FAT32, the strictest filesystem in use, on a Kobo, and on Windows, whose reserved names apply on any filesystem. Each part of a path is made from its metadata this way:
:becomes-;/,\, and|become-;"becomes'; and*,?,<,>, and control characters are left out- runs of whitespace become one space, and dots and spaces are trimmed from both ends, so no name is hidden or ends in a dot
- at most 100 bytes, cut at a character
- a reserved name before any dot (
CON,PRN,AUX,NUL,COM1–COM9,COM¹–COM³,LPT1–LPT9, orLPT¹–LPT³, in any case) gets a_after it, before the dot:CON.txtbecomesCON_.txt, within the 100 bytes - Unicode in NFC; never transliterated to ASCII
- Names compare as the same when they are after NFC and then each character's Unicode lowercase mapping, taken one character at a time without context (not full case folding:
ßstaysß, and a finalΣbecomesσ, notς). This is how names are compared everywhere in the format: folders and files for collisions, and collection names (§5.4). - Conformance examples:
naming/names.jsongives metadata and the names made from it, for other tools to test against. - Names follow the metadata. A device that applies edits (§3.3) also renames files and folders whose names no longer match. It waits until every edition of the book is downloaded and its edits are written, and logs each rename of an edition's folder or file as
edition.updated. It never overwrites a file that already has the wanted name: the edition gets a qualifier instead. - Anyone can rename or move a book's folder or files. Books are found by the ID in their logs, and editions by their hash (§2.1), never by path, and names are put back in line when edits are next applied.
1.4 Shared work files
Some work is slow to make and the same whichever device makes it, so it's kept in the library for every device, rather than in each device's cache, such as an audiobook's alignment with its ebook (§9.2). Their files, in the book's .boeks/, are the exception to each device writing only its own files. The chapter of each says what its file holds; these rules are the same for all of them.
- Any device writes it, whole: to a temporary file, then renamed over the old one, so a reader never sees half of one.
versionis how its content is made. A device makes a file of an older version again, as what's in it no longer holds, and leaves one of a newer version alone: it neither uses nor overwrites it.deviceandsavedare the device that last saved it, and when, in milliseconds since the Unix epoch. A device that can only do the work in the background, now and then, as a phone or a tablet does, leaves a file to another device that saved it in the last 3 minutes, as that one is at it, and takes it up once it's been quiet that long: the two would otherwise redo each other's work. A device that does it whenever it's on, as a Mac does, never waits, and neither does work someone asked for.- A sync tool's conflict copy (§8.1) is merged into the file as its chapter says, and the merged file replaces the copies when it's next written. Where it has to choose between two that are as good as each other, it keeps the one saved first, so every device keeps the same one.
- Keep what you don't know: fields a later version wrote are kept when the file is written again.