Shelving and Reading Status

Now that we got the basis of defining a book, should we consider defining something akin to Handling Reviews for the Book Lexicon - #17 by omg.jacky.wtf for books but to determine:

  • whether or not someone is reading a book?
  • if it lives on a particular bookshelf

It’s possible that a Shelf called “To-Read” can represent the same thing as the status but that might be more of an implementation detail that puts too tight of a restriction on how folks build up their apps.

What do you think @nickthesick @jasonbu.online @xardex.dev ?

Especially with spaces

I think it’s totally reasonable to write a reading progress record of some kind which we could use, unless you mean a “now reading” record which would be similar to what atmosphere games build for now playing for video games.

I think the now reading is going to be much harder since the sync for books is more analog.

For the first bullet point: It would be something akin to determining if a book is being actively read, finished reading, abandoned or wanted to be read (these are the four usual states of a book). The second one is a bit moot but more for custom shelving (like if someone wanted to curate a collection of the top 4 books of 2026 for example).

In the case of a “now reading”, we could compute it from the above as folks opt to read. IIRC in @nickthesick’s setup with Bookhive, they implemented a KOReader sync server so a now reading status could be computed in (near-) real time.

Otherwise, my fear of difficulty is around making sure we keep the right progress relevant to the edition that the book is in (for example, audiobook versus paperback versus ebook).

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?

Jacky - this looks great. I’m on mobile so I haven’t read the lexicons closely but when I have a chance later today I’ll prototype adding them to cavu.page and give you any feedback from there.

One open question is if we should progress as a community record. It feels very bound to the medium you’re reading in which is more aligned with the app view.

If we are going to have a shared progress record I think the “killer feature” is being able to do “spoiler free" content across apps. That would point to a stronger need for alignment but also one that can be uni-directional as in it never needs to go from progress record to picking up where you left off in a reading app.

1 Like

I cross-posted your point about spoilers to the reviews thread but I’m curious; since one can’t add any text to any of these records for p, what place would it (a spoiler indicator) be needed for? Like the description of a shelf?

I don’t think four is too many. For dracome, I merged readingStatus and readingProgress into one single state lexicon because - for me - both represent a user state on an edition. However, I don’t seen issue with splitting them. dracome does use an additional lexicon for markers (e.g. favorite) because I view them as separate from the state.

I’m still kinda torn on the question of spoilers. I’m leaning toward a rich text format that would let dracome hide parts of a review behind a spoiler gate. But I still need to discuss this with my co-founder because it would add some complexity.

I still need to diff your proposal with the ones for dracome. Here are the ones currently deployed: dracome.social - Lexicon Garden

1 Like

Sorry kinda came out garbled on mobile.

Spoiler free stuff could be powered by a progress record, reach a certain progress and you unlock discussions about it. This being a community lexicon shared between apps would be super powerful. However IMHO in that case it would make more sense for it to be very specific and not an open enum.

I think reading / listening progress is probably too app specific for the community lexicon unless you constrain it’s use case. For instance I wouldn’t want an audiobook app and a reading app hoping they incidentally get to be synched and instead destroying progress in both. Focusing on a progress record that is written by reading / listening apps but not read by them would be my approach. Progress around milestones (chapters etc) is probably the right primitive there. That gives you a rough ability to resume without needing to work about app specific needs.

I think I disagree on it being too specific for a community lexicon! In closed social applications, being able to determine the reading progress of a book is a given feature and being able to see that across open social apps would prevent friction. I guess if we added a fixed set of states (since the existing ones in the space between Bookhive and I), that could remedy the open enum situation (and there isn’t many states that the reading state of a book could be in).

I do see the benefit of going for a chapter approach since those units are more universal across books. I would add then we have an open metadata field so we can allow for app specific or even more granular information to be stored.

Also I checked https://tangled.org/lexicon.community/lexicons/pulls/18/0#file-community/lexicon/media/book/review.json:R52 and it has a flag for spoilers: would something similar suffice?

Chiming in here, @manton of micro.blog acclaim is introducing blog.micro.shelf to help determine the reading status of a book; more reason to look into implementing a companion lexicon for the such.

You can view the shape of it at blog.micro.shelf - Lexicon Garden

Thanks @omg.jacky.wtf, I actually missed this thread. I’m happy to adapt what I’m doing when a shared lexicon is ready.

I’ve started syncing these new records now. You can see the blog.micro.book and blog.micro.shelf (for custom bookshelves) here: PDSls

For common built-in shelves like “Want to read”, Micro.blog just has a status field of “to-read” on the book record.

1 Like

@omg.jacky.wtf I’ve not gone through everything in detail, but here is some quick feedback that I can give:

For reading status, one thing that I’ve received feedback on in BookHive is that people want to mark that they have read a book multiple times. The lexicon as is does not capture this desired behavior.

One idea that I had for resolving this would be to make reading statuses, actually be shelves. Like you can have a “to-read” shelf, and a “reading” shelf, and on the shelfItem, you can mark the timestamps of when that shelfItem is accurate for, and any current progress if available. This is actually (from what I understand) how Goodreads models books for users.

If we decide to go this way, then you can update an existing shelfItem (or a re-read) create a new shelfItem entirely and also store progress on that same record, obviating the need for the separate readingStatus record. There does need to be some coordination on the shelf names for this to work, but maybe we can define that at the record level (that there should be a community.lexicon.media.book.shelf.to-read record or that there is a separate “built-in” shelf type with an open union of types).

I’m uncertain about the reading progress vs. reading status split. I can see value in it that the items get changed at different intervals, but it is solvable to not have to enforce a read before write (with swapCommit for example). By splitting off into different records, it gives more opportunity for split-brain scenarios. Like a readingProgress saying 20% read & readingStatus saying want-to-read or done, without them being in the same record it can become incoherent what the intention was. So, I’m unsure that I’m sold on that shape.

One very minor note, by having position be an integer on shelfItem, to re-order books will be an annoying shuffle of rewriting N-books (where N is the number of books on the shelf) since inserting a new position 1 on the shuffle, forces all the other records to have to move too. For this, I would recommend that the shelf has a sortOrder which is an array of at-uris to the correct ordering for that shelf. In this way, an update to shelf order would be an O(1) update to the shelf rather than an O(N) update to the shelfItems.

This, actually, sort of invites the idea that maybe the shelf defines what books it owns like items: {subject: ref, subjectRecord: at-uri, createdAt: datetime, updatedAt: datetime }[] which would make it even clearer the relation ship of a shelf to it’s items, without having to split across records. But, I may want to think more on the implications around this. But, it may just get us to merge shelf & shelfItem together