So, having gone and written the shapes out rather than leaving it at the question: four records under community.lexicon.media.book, and a shelf that is neither of the other two.
The thing I want to quickly revise on first is my own suggestion that a shelf called “To-Read” could represent the status. It could, but I think it’s exactly the implementation detail that puts too tight a restriction on how folks build up their apps (as aforementioned). If “to-read” is a shelf, then every app that wants the status has to create a shelf and name it the same way - and the moment someone names theirs “Reading, but slowly” or “DNF, probably”, the vocabulary is gone. In short, the status isn’t a shelf, and a shelf isn’t a status; they’re distinct things.
The other split that I think matters more: status and position are two records, not one, because they change on completely different clocks. A status changes a handful of times per book. A position changes every few minutes (I’m thinking of the case of a client that updates the status live, like I’m working on with my desktop and mobile apps). Put both in one record and every position save is also a status save, which means the writer has to have read the status before the last change or it quietly undoes it (which is a bit wasteful, IMO). At BookHive issue #41, where status changes on a mutated record inherited the original createdAt, and I asked the same thing back in the earlier thread; I’d rather not build the bug on purpose.
A shelf is curation: a book can sit on any number of shelves, a shelf can hold books in any state, and the name is the reader’s to pick. So membership has to be its own edge record, and shelf names can never be a vocabulary. This also allows for platforms to publish their own shelves, like that mirroring the New York Times’ weekly bestsellers or NPR’s annual reading list (https://livtet.olamaelcu.net/ currently shows the NYT bestsellers on the homepage).
One status per book, even when you own two copies - that falls out for free here. Positions are per (edition, copy), status is per edition. Below are the proposed lexicons I got for showing progress and shelving status.
community.lexicon.media.book.readingProgress
For the case where something is actually syncing a position - KOReader sync, an ereader, or what have you.
{
"lexicon": 1,
"id": "community.lexicon.media.book.readingProgress",
"description": "How far through a book a reader is, for one copy of one edition, written to the reader's own repository. A position is not a status: whether the book is being read, paused, finished or abandoned lives in community.lexicon.media.book.readingStatus, so a position saved every few minutes never rewrites the state of the read. One record per (edition, copy) by convention: a client lists its own collection and updates the record for that edition and format rather than creating a second. Consumers must tolerate several records for one edition and use the one with the greatest updatedAt.",
"defs": {
"main": {
"type": "record",
"key": "tid",
"description": "The reader's place in one copy of one edition.",
"record": {
"type": "object",
"required": ["subject", "position", "createdAt", "updatedAt"],
"properties": {
"subject": {
"type": "ref",
"ref": "community.lexicon.media.book.defs#editionRef",
"description": "The edition being read, copied in full so the record renders without resolving anything, as community.lexicon.media.book.review does. subject.identifiers is what matches this record to another reader's record for the same edition: compare issuer and value exactly."
},
"subjectRecord": {
"type": "string",
"format": "at-uri",
"description": "Optional AT-URI to a published edition record, for enrichment only. Never part of matching; subject.identifiers remain the matching mechanism."
},
"format": {
"type": "string",
"knownValues": ["physical", "ebook", "audio"],
"description": "The copy the reader is holding, named with the same tokens as defs#edition.format so a position can be read against the edition's own extents. It is the reader's copy, not the edition's merged medium: two readers of one edition can report a print page and an audio second against it. Absent when the reader has one copy or the medium follows from position.unit."
},
"position": {
"type": "ref",
"ref": "#position",
"description": "Where the reader is."
},
"identifier": {
"type": "ref",
"ref": "community.lexicon.media.book.defs#identifier",
"description": "The product identifier whose extent position.total is, when that total did not come from the embedded edition. Two claims for one edition disagree, a print ISBN's page count against an audio ASIN's duration, so a total without its claim cannot be compared."
},
"createdAt": {
"type": "string",
"format": "datetime",
"description": "When this position was first written for this edition and copy."
},
"updatedAt": {
"type": "string",
"format": "datetime",
"description": "When the reader last moved to this position. The ordering key for consumers, and the closest thing to last-read-at; it is not when the reading status changed."
}
}
}
},
"position": {
"type": "object",
"description": "The position, on the unit's own scale. Every scale is an integer: the protocol has no floats, so a fraction of a page, a chapter or a percent is rounded here and carried exactly in locator.",
"required": ["unit", "value"],
"properties": {
"unit": {
"type": "string",
"knownValues": ["page", "virtual_page", "permille", "second", "chapter"],
"description": "The scale value counts on. page is a printed or fixed-layout page, virtual_page a reflowable renderer's page, permille tenths of a percent (0-1000), second an audio position, chapter a chapter number with any fraction in locator. Only permille is absolute; the others count against total."
},
"value": {
"type": "integer",
"minimum": 0,
"description": "The position on unit's own scale."
},
"total": {
"type": "integer",
"minimum": 1,
"description": "The whole in the same unit: the page count the edition or identifier claims, the chapter count, or the duration in seconds. Required for page, virtual_page, second and chapter, because a position without its extent cannot be rendered as progress and every consumer would have to guess. Omit for permille, whose scale is absolute."
},
"locator": {
"type": "string",
"maxLength": 512,
"description": "The precise position the integer rounds off: an EPUB CFI, a printed page label, a clock time. Carries the precision and the document anchors that no integer scale can."
}
}
}
}
}
A few things I’d want to defend here:
subject copies the edition in full, defs#editionRef, same as the review record already does. subject.identifiers is the only matching mechanism: compare issuer and value exactly. Two apps reporting the same paperback match; an audiobook doesn’t, which is correct. This is copying how Bookhive does book information and is a good call for immediate fidelity. Since there’s a reference to the full book by URI, that can be used for later hydration of the resource.
format uses the same tokens as defs#edition.format. This is my answer to my own worry in the thread about keeping progress relevant to the edition: a print page, an ebook renderer page and an audio second are three different records, each measured against its own extent. Nothing ever has to be converted into somebody else’s edition.
- Every scale is an integer, because the protocol has no floats. The CFI (used by ePubs and KOReader, I believe), the clock time, the half-chapter all ride in
locator.
identifier says which product claim total came from, because a print ISBN’s page count and an audio ASIN’s duration are two different totals for one edition, and a total without its claim can’t be compared to anything.
One record per (edition, copy), by convention: a client lists its own collection, finds the record for that edition and format and rewrites it. Consumers take the greatest updatedAt and put up with several records for one edition.
community.lexicon.media.book.readingStatus
The actual four states, which is the first bullet of the thread.
{
"lexicon": 1,
"id": "community.lexicon.media.book.readingStatus",
"description": "Whether a reader is reading a book, has paused it, finished it or abandoned it: the state of one read, written to the reader's own repository. Separate from community.lexicon.media.book.readingProgress because the two change on different clocks. A status changes a handful of times per book; a position changes every few minutes, and one record holding both makes every position save a chance to revive a status it read earlier. One record per edition holds the current state and is rewritten as that state changes; an append-only client writes one record per transition instead, and both validate. Consumers take the greatest updatedAt, falling back to createdAt, so both styles read the same way.",
"defs": {
"main": {
"type": "record",
"key": "tid",
"description": "The state of one read of one edition.",
"record": {
"type": "object",
"required": ["subject", "status", "createdAt"],
"properties": {
"subject": {
"type": "ref",
"ref": "community.lexicon.media.book.defs#editionRef",
"description": "The edition being read, copied in full so the record renders without resolving anything, as community.lexicon.media.book.review does. subject.identifiers is what matches this record to another app's record for the same book: compare issuer and value exactly."
},
"subjectRecord": {
"type": "string",
"format": "at-uri",
"description": "Optional AT-URI to a published edition record, for enrichment only. Never part of matching."
},
"status": {
"type": "string",
"knownValues": ["to-read", "reading", "paused", "read", "abandoned"],
"description": "to-read is an intention with no start; reading is an open read; paused is an open read the reader set aside and may return to; read is a completed read; abandoned is a read the reader ended without finishing. Additional values are permitted: a client must render a value it does not recognise rather than dropping the record."
},
"startedAt": {
"type": "string",
"format": "datetime",
"description": "When this read began. Set for reading, paused, read and abandoned; absent for to-read."
},
"finishedAt": {
"type": "string",
"format": "datetime",
"description": "When this read reached its end, and only for read. An abandoned read's end is the write that set abandoned: updatedAt, or the next record's createdAt in an append-only repository. This field never has to mean 'stopped for some reason'."
},
"createdAt": {
"type": "string",
"format": "datetime",
"description": "When this status record was created. For an append-only client this is when the transition happened, and it may be backdated when history is imported from another service."
},
"updatedAt": {
"type": "string",
"format": "datetime",
"description": "When this status last changed. Consumers order by this, then by createdAt; a client keeping one record per edition sets both."
}
}
}
}
}
}
- Five tokens we can ship with:
to-read, reading, paused, read, abandoned. I’m keeping paused because com.hectorsector.book.status already ships it and people do pause things - I found this via Lexicon Garden.
finishedAt is set only for read. That way it never has to mean “stopped for some reason” - an abandoned read’s end is just the write that set it (good to know operationally)
- Both styles work: one record per edition that you rewrite, or one record per transition, append-only, like
com.hectorsector.book.status does. Consumers order by updatedAt ?? createdAt, and that’s the only rule needed to make the two read alike.
@chris.pardy.family: on the “now reading is harder because book sync is analog” point: a reader who tracks no position writes one small record and nothing else. The thing that’s hard to compute is the position, and this record doesn’t need it. Good for folks who just putting things on a shelf and nothing more. But this also enables folks to add features to their apps like reading streaks or a timeline of updates.
community.lexicon.media.book.shelf and community.lexicon.media.book.shelfItem
Second bullet of the thread - custom shelving, like curating the top four books of 2026 without inventing a “2026” collection somebody else has to guess at.
{
"lexicon": 1,
"id": "community.lexicon.media.book.shelf",
"description": "A named set of books a reader curates, such as a year's favourites or a beach-read pile, written to the reader's own repository. A shelf is curation, not a reading status: a book can sit on any number of shelves, a shelf can hold books in any state, and 'to-read' is a status in this model rather than a shelf every app has to create and name the same way. Membership is community.lexicon.media.book.shelfItem.",
"defs": {
"main": {
"type": "record",
"key": "tid",
"description": "One curated shelf.",
"record": {
"type": "object",
"required": ["name", "createdAt"],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxGraphemes": 128,
"description": "Display name of the shelf, as the reader wrote it. Not a vocabulary: apps refer to a shelf by AT-URI and never match on this string, so two shelves with one name are two shelves."
},
"description": {
"type": "string",
"maxGraphemes": 8192,
"description": "What the shelf is for, in the reader's own words."
},
"createdAt": {
"type": "string",
"format": "datetime",
"description": "When the shelf was created."
},
"updatedAt": {
"type": "string",
"format": "datetime",
"description": "When the shelf's name or description last changed. Membership changes do not touch it: those are shelfItem records."
}
}
}
}
}
}
{
"lexicon": 1,
"id": "community.lexicon.media.book.shelfItem",
"description": "One book placed on one shelf: the membership edge, written to the reader's own repository. Separate from the shelf so a book can sit on any number of shelves without the shelf being repeated, and separate from readingStatus so curating a shelf never overwrites the state of a read. One record per (shelf, edition) by convention: a client lists its own collection and updates the edge for that shelf and edition rather than adding a second. Consumers must tolerate several edges for one pair and use the greatest updatedAt.",
"defs": {
"main": {
"type": "record",
"key": "any",
"description": "One book's place on one shelf.",
"record": {
"type": "object",
"required": ["shelf", "subject", "createdAt"],
"properties": {
"shelf": {
"type": "string",
"format": "at-uri",
"description": "AT-URI of the community.lexicon.media.book.shelf record this book is on. A plain AT-URI and deliberately not a strongRef: a strongRef pins one version of the shelf, so a rename or a description edit would leave every edge pointing at a value that is no longer in the repository and force them all to be rewritten. The URI is the shelf; a CID would only be a moment of it."
},
"subject": {
"type": "ref",
"ref": "community.lexicon.media.book.defs#editionRef",
"description": "The edition on the shelf, copied in full so the shelf renders without resolving every member, as community.lexicon.media.book.review does. subject.identifiers is what matches this edge across apps: compare issuer and value exactly."
},
"subjectRecord": {
"type": "string",
"format": "at-uri",
"description": "Optional AT-URI to a published edition record, for enrichment only. Never part of matching."
},
"position": {
"type": "integer",
"minimum": 1,
"description": "The book's place within the shelf, 1-indexed, for shelves whose order is the point. Absent when order does not matter; consumers order by this and then by record URI, as the app that wrote the shelf expects it to read."
},
"createdAt": {
"type": "string",
"format": "datetime",
"description": "When the book was placed on the shelf."
},
"updatedAt": {
"type": "string",
"format": "datetime",
"description": "When this edge last changed, such as its position."
}
}
}
}
}
}
The one decision in here that isn’t obvious: shelfItem.shelf is a plain AT-URI, not a strongRef. Since the key is any, we can allow for updating a shelf using a fixed representation. This allows for safe editing of the shelf itself. No need for updating backlinks.
This is house precedent more than a new opinion - the book defs publisher reference already carries the same note - and it’s why nothing in these four documents is a strongRef. subject is an embedded copy, subjectRecord is a plain AT-URI, exactly like community.lexicon.media.book.review already does.
Mapping the vocabularies already out there
Statuses, because we’re not all going to land on the same spelling on day one:
| Existing record and its tokens |
Mapping here |
net.olamaelcu.livtet.biblio.defs#readingStatus — to-read, reading, read, dnf |
to-read, reading, read, and dnf → abandoned |
net.olamaelcu.livtet.bookClub.read#main.status — reading, read, abandoned |
unchanged |
buzz.bookhive.book — wantToRead, reading, finished, abandoned |
wantToRead → to-read, reading unchanged, finished → read, abandoned unchanged |
com.hectorsector.book.status — wantToRead, reading, paused, didNotFinish, finished |
wantToRead → to-read, reading and paused unchanged, didNotFinish → abandoned, finished → read |
Units:
| Existing token |
Mapping here |
percentage (0–100) |
permille × 10 |
page |
page |
virtual_page |
virtual_page |
timestamp (seconds) |
second |
chapter |
chapter |
cfi |
permille + locator (Readium locators always carry locations.progression) |
per_mille (0–1000) |
permille, identical integers |
net.olamaelcu.livtet.biblio.defs#progressUnit — pages, seconds, percent, other |
page, second, permille, — |
net.olamaelcu.livtet.bookClub.read#checkpoint.unit — pages, percent, other |
page, permille, — |
page.cavu.progress#position.thousandths |
permille (identical integers, 0–1000) |
Two loose ends
knownValues is an open vocabulary, so adding a token later doesn’t break anyone, and a client has to render a token it doesn’t recognize instead of dropping the record; I ran into this when I wanted to bridge shelving from Bookhive into Livtet. Nothing in community.lexicon.media.book.defs changes: this reuses #editionRef and #identifier as they are, so it’s purely additive.
On visibility, there’s no field for it, deliberately. These are public repo records by default; if you don’t want a position public you write it into a permissioned personal space, assuming your PDS does spaces (Livtet detects this on sign in, I’m considering making a toggle for books to move their updates and records into a per-book space). Where the record lives is the visibility, so the shape doesn’t have to change.
What Livtet would actually write
Livtet writes net.olamaelcu.livtet.biblio.readingProgress and net.olamaelcu.livtet.biblio.bookStatus today and would write these four instead once they’re ratified, with a repo: scope per collection: repo:community.lexicon.media.book.readingProgress, repo:community.lexicon.media.book.readingStatus, repo:community.lexicon.media.book.shelf, repo:community.lexicon.media.book.shelfItem.
—
Treating this as a proposal, not something already shipped — @nickthesick @jasonbu.online @xardex.dev, is four records too many, or does this match what BookHive and the others are already doing?