[Part 2] RFC: Work / Book -> Edition Abstraction

[zachyale]

RFC: Work / Book -> Edition Abstraction

Problem statement

Grimmory currently treats a "book" as one object that has one source of truth for metadata between available formats, that have different reader states and files. That model is simple, but it makes it hard to represent the real shape of a library if a user owns multiple versions of the same underlying creative work.

For example, Harry Potter and the Philosopher's Stone can have stable work-level facts that are true across versions: title, author, series, original publication context, genres, a general description, etc. A user may then own several editions of that work: an initial physical publication, a Pottermore EPUB, a Stephen Fry audiobook, a 2025 full cast audiobook, or another translated/localized release. Those editions share the same underlying intellectual work, but they are not interchangeable copies. They may have different narrators, publishers, release dates, covers, identifiers, durations, page counts, languages, abridgement statuses, and more.

The exact name of the top-level concept can be decided during implementation. It could be called Work to emphasize the abstract intellectual title, or kept as the high-level Book to better match user-facing language and metadata sources that model book -> edition. The important shape is the same either way: a top-level group with one ore more Editions, and each Edition representing a specific publication/release/version.

This RFC should be done after the file/format abstraction. It assumes Grimmory can already represent one edition/format as one or more durable files. The goal here is not to unblock M4B creation or audiobook chapter editing; that should be done by the edition RFC work. The goal here is to make Grimmory's top-level library model match how books, audiobooks, digital publications, and physical copies relate to each other.

Goals

• Split the current book-centric model into Work/Book and Edition concepts
• Move metadata that is true for all versions of a title onto the Work/Book
• Move metadata that describes a specific publication/release/version onto the Edition
• Allow an Edition to inherit Work/Book metadata while overriding or extending fields where needed
• Let users group multiple editions of the same work together in the library (similar to how they can collapse by series)
• Keep the previously refactored format/issue/file model as the media/storage layer under an Edition
• Normalize source-specific format labels into Grimmory edition types when metadata providers support book/edition breakdowns (Goodreads/Hardcover)
• Keep simpler metadata sources usable by treating them as "squashed" book+edition metadata when they do not expose a separate edition concept (Amazon, Audible, etc.)
• Preserve existing reading, playback, metadata, cover, progress, download, and API behaviour during migration where possible. After the spike, it can be identified if this needs to be a breaking change or not

Non-goals

• This RFC does not replace the prerequisite file/format abstraction
• This RFC does not implement audiobook chapter editing, M4B creation, provider matching, or metadata embedding
• This RFC does not require solving every possible bibliographic edge case within the first pass
• This RFC does not require all clients to immediately stop using book-oriented endpoints without sufficient justification/communication. It is possible we could go down this path, but it would require significant nightly availability, and comms w/ 3rd parties
• This RFC does not expand upon physical cataloguing functionality in any way besides what is needed to represent physical editions. That can be expanded in the future if there is interest in doing so
• This RFC does not hard-code one provider's format list as Grimmory's canonical model

Proposed solution

Introduce a two-level library model that can be named either Work -> Edition or Book -> Edition:

Work / Book
  Edition
    Format / Issue
      Files

A Work/Book is the abstract title that users expect to see grouped together in the library. An Edition is a specific version or release of that title. The existing post-refactor format/issue/file model remains below the Edition and describes what the user actually owns and can read, play, download, or mutate.

This shape intentionally matches common metadata-provider models.

• Hardcover models books with editions, where an edition has a format such as print, audio, or ebook.
• Goodreads also exposes book editions with source-specific format labels such as Paperback, Hardcover, Kindle Edition, ebook, Audiobook, Audible Audio, Audio CD, MP3 CD, and other physical or audio formats.

Grimmory should be able to consume those richer provider shapes when available without forcing every metadata source to expose the same structure.

The first implementation should stay pragmatic. Existing book rows can be migrated into one Work/Book with one Edition each. Later, users and metadata matching flows can merge duplicate Works/Books or attach newly discovered editions to an existing Work/Book.

Examples:

Harry Potter and the Philosopher's Stone
  Work/Book metadata
    title: Harry Potter and the Philosopher's Stone
    author: J. K. Rowling
    series: Harry Potter #1
    genres: Fantasy, Young Adult
    original publication year: 1997

  Edition: Pottermore EPUB
    publication format: Ebook
    publisher: Pottermore
    identifiers: ISBN/provider IDs
    language: en-GB
    format/issue: EPUB
      files: pottermore-1.epub

  Edition: Stephen Fry audiobook
    publication format: Audiobook
    narrator: Stephen Fry
    identifiers: ASIN/provider IDs
    duration: edition-specific duration
    format/issue: AUDIOBOOK
      files: 001.mp3, 002.mp3, 003.mp3

  Edition: 2025 full cast audiobook
    publication format: Audiobook
    narrators/cast: full cast
    release year: 2025
    format/issue: AUDIOBOOK
      files: philosopher-stone-full-cast.m4b

What are the high level architectural changes?

• Add a Work/Book model as the stable grouping root for a title
• Add an Edition model under Work/Book for version/release/publication-specific metadata
• Move or map existing BookEntity concepts into Work/Book and Edition responsibilities
• Attach the already-refactored format/issue model to Edition instead of directly to the current book root
• Add metadata resolution logic so APIs and UI can ask for "effective metadata" for an Edition: Work/Book fields plus Edition overrides
• Add metadata-source normalization so providers that expose book/edition/format data can map their source format labels into Grimmory edition types and owned format/issues
• Keep provider integrations that only return a flat book result by treating the response as combined Work/Book plus default Edition metadata
• Add user/library flows for grouping, splitting, and merging Works/Books when metadata imports or scans create duplicates
• Keep compatibility routes that resolve existing bookId-style requests to the appropriate Work/Book and Edition during the transition

What are the high level data model changes?

Add a Work/Book table/model with fields that are generally true across editions- including but not limited to:

• id
• canonical title
• original title
• sort title
• primary authors/creators
• series/collection relationships
• original publication date/year
• genres, tags, subjects, and description
• Work/Book-level provider identifiers where appropriate
• created/updated timestamps

Add an Edition table/model with fields that describe one version of the Work/Book:

• id
• work_id
• edition type, such as print, ebook, audiobook, audio media, or unknown
• source format label, such as Hardcover, Kindle Edition, Audiobook, or Audible Audio
• edition title/subtitle override
• edition-specific contributors such as narrator, translator, editor, illustrator, or cast (in the future— just support what grimmer currently supports for now)
• publisher/imprint
• edition publication date
• language/locale
• ISBN, ASIN, and provider identifiers
• cover/artwork override
• page count, duration, abridged/unabridged state, and edition notes
• source/provider metadata and confidence
• created/updated timestamps

The exact field split should be validated during implementation, but the rule of thumb should be:

Question	Belongs on
Is this true for the underlying title regardless of owned version?	Work/Book
Is this true only for this release/publication/audiobook/translation?	Edition
Is this true only for this stored format or filesystem object?	Format/Issue/File

Edition metadata should be able to inherit from Work/Book metadata. If an Edition does not override title, description, series, genre, or creator display fields, Grimmory can display the Work/Book value. If it does override a field, the Edition value should win for that Edition's detail pages, readers, matching, and exports.

Metadata providers should be normalized through a small source-format mapping layer. The mapping should preserve the original provider label for display/debugging, but also normalize it into Grimmory's edition model.

Example mappings:

Source format label	Grimmory edition type	Likely owned format/issue
Paperback, Hardcover, Mass Market Paperback, Library Binding, Board book, Leather Bound, Unbound, Spiral-bound, Unknown Binding	Print / Physical	Physical issue, if tracked
Kindle Edition, Nook, ebook, CD-ROM	Ebook / Digital publication	EPUB, KEPUB, PDF, MOBI/AZW, or other file-backed issue when owned
Audiobook, Audible Audio, Audio CD, Audio Cassette, MP3 CD	Audiobook	AUDIOBOOK issue, often M4B/M4A/MP3/OPUS-backed

For compatible providers, metadata matching should become edition-aware: users should be able to choose the right provider edition before applying metadata, and Grimmory should know whether fetched fields should update the Work/Book or the Edition. For simpler providers, Grimmory can keep the current behavior by treating the result as a combined Work/Book + Edition candidate and creating or updating a default Edition. At that point, it’s more a UI/UX question.

What are the main changes to the UI?

• Library views should be able to group editions under one Work/Book (collapse by book/work)
• Work/Book detail pages should show shared metadata and the user's owned editions
• If there is only one edition of a book, it should just show the edition detail page
• Edition detail pages should show edition-specific metadata, available formats/issues, files, progress, and actions
• Metadata editing should distinguish Work/Book fields from Edition fields
• Metadata matching should show edition choices and source format labels when a provider exposes them
• Users should be able to merge duplicate Works/Books and move an Edition between Works/Books. When merging a work/book, we could show a modal that forces the user to pick for each work metadata field what the merged value should be- from work A, work B, a mix, or manually edit that value
• Search and filtering should support both Work/Book-level and Edition-level fields
• Existing book detail routes should continue to work through compatibility redirects or resolvers while the UI migrates

Risks

Are there any backwards-incompatible changes?

Yes. This is a large conceptual migration than the file/format RFC’s changes. Existing code and clients often assume that one book row is the canonical library item. The rollout should preserve compatibility by keeping current routes and payloads working while introducing explicit Work/Book and Edition APIs.

High-risk areas include:

• metadata editing and provider matching
• provider format normalization and source-specific metadata mapping
• cover selection and fallback
• progress and continue-reading/continue-listening surfaces
• OPDS, Kobo, mobile, and app APIs
• search indexing and filtering
• duplicate detection and merge flows
• permissions, sharing, and user-specific library state

Does this project have special implications for security and data privacy?

Moderate. The model itself does not introduce new file mutation or download permissions, but merge/split operations can change which editions appear grouped together and which metadata appears in user-facing APIs. Permission checks must remain anchored to the user's library access, not only to shared Work/Book records.

Could this change significantly increase load on any of our backend systems?

Yes. Work/Book/Edition resolution can add joins and metadata fallback logic to common library queries. Search indexing may also need to index both Work/Book and Edition fields. The implementation should avoid N+1 metadata resolution and should cache or precompute effective metadata where needed for list views.

Does this project have any dependencies?

Yes. This RFC should come after:

• The file/format abstraction RFC, so an Edition can own multiple formats/issues and each format/issue can own multiple files

Alternative solutions

One alternative is to keep a single book model and add a "related editions" relationship. That is less disruptive, but it keeps shared and edition-specific metadata mixed together and makes inheritance/override rules unclear.

Another alternative is to jump to a fuller Work / Edition / Manifestation model immediately. That may be cleaner from a bibliographic perspective, but the prior file/format RFC already creates a practical lower layer for manifestations/media objects. This RFC should avoid redoing that work and focus on the missing Work/Book -> Edition split.

Another alternative is to keep relying on folders, filenames, and provider metadata to imply relationships between versions. That avoids a migration, but it leaves users with duplicate library entries and no durable way to say "these are editions of the same work."

Implementation and rollout plan

1. Audit current book metadata fields and classify them as Work/Book-level, Edition-level, format/issue-level, or file-level.
2. Add Work/Book and Edition tables/models.
3. Migrate each existing book into one Work/Book and one Edition.
4. Reattach existing format/issue records to Edition.
5. Add effective-metadata resolution for Edition views and API responses.
6. Add compatibility mappers so existing book APIs continue to return stable payloads.
7. Update library list/detail/search APIs to understand Work/Book grouping and Edition selection.
8. Add UI affordances for Work/Book detail, Edition detail, merge duplicate Works/Books, and move Edition to another Work/Book.
9. Add metadata-source format normalization for providers that expose edition formats.
10. Update metadata import/matching flows so fetched metadata can target either the Work/Book or a specific Edition.
11. Keep simpler providers squashed into a default Edition path until they can support richer matching.
12. Gradually migrate clients from ambiguous book routes to explicit Work/Book and Edition routes where needed.

Does this project require a migration?

Yes. The initial migration is very mechanical:

• Create one Work/Book for each current book.
• Create one Edition under each new Work/Book.
• Copy shared metadata to both layers according to the field classification.
• Attach existing format/issue rows to the new Edition.
• Preserve current identifiers and compatibility mappings so old bookId references can resolve.

Follow-up cleanup can merge duplicate Works/Books, improve edition grouping, and move provider-specific metadata into the correct layer. The first migration should not attempt to perfectly deduplicate every library.

Is this project in an experiment or feature flagged?

The schema migration itself should not be user-toggleable, but Work/Book grouping and Edition-specific UI can roll out behind feature flags or staged routes. Existing book screens should remain available until the Work/Book -> Edition UI reaches parity.

Success Criteria

How will you validate the solution is working correctly?

• Existing libraries migrate with no lost books, formats, files, covers, metadata, progress, or reading/playback state
• Each existing book has a Work/Book and at least one Edition after migration
• Existing book-oriented API routes continue to function during the compatibility period
• Users can group multiple editions under one Work/Book and split incorrectly grouped editions apart
• Work/Book-level metadata appears consistently across editions unless an Edition overrides it
• Edition-specific metadata such as narrator, publisher, language, ISBN/ASIN, cover, duration, and abridgement state remains edition-specific
• Metadata providers with edition/format support can map source formats into Grimmory edition types while preserving original provider labels
• Simpler metadata providers continue to work by creating or updating a default Edition
• Search and filters can find Works/Books by shared metadata and editions by edition-specific metadata
• Audiobook editions, ebook editions, physical editions, and generated formats can coexist under one Work/Book without losing their file/format behaviour

What monitoring and alerting will you do to ensure this project doesn't decrease performance and reliability?

• Log migration counts for Works/Books, Editions, format/issues, and compatibility mappings
• Track unresolved legacy bookId lookups after migration
• Monitor list/detail/search latency before and after effective-metadata resolution
• Track merge/split operations and failures
• Monitor API error rates for book, Work/Book, edition, metadata, reader, playback, and download endpoints

[zachyale]

Some cool functionality clear distinctions between editions (with different formats) could unlock:

• Allow users to enable a Storyteller transcription/guided navigation package, generated for each unique audio format edition, triggered either manually or automatically
• Automatically suggest audiobook to ebook mappings using alignment % between a transcription and an ebook's content, to auto-sync progress between audiobooks and ebooks
• More cleanly keep multi-format stories in one place- (for ex., 'The Hedge Knight' by George R.R. Martin- it has an ebook, an audiobook, and a graphic novel. Works/editions would allow you to have one home for all 3 formats)

I also believe that, if in the future we were interested in deprecating rich metadata import/export, and native readers for certain file formats, this abstraction would make it easier to do so while still enabling Grimmory to be the "home" for that media (regardless of the formats supported by the official reader). This could allow us to better justify allowing formats to be uploaded that are read only via custom apps/readers.

And much more :)

[piffio]

It assumes Grimmory can already represent one edition/format as one or more durable files.

nitpicking: "zero or more" if we want to keep supporting physical books with no digital version attached

[zachyale]

Agreed, good catch!

[piffio]

A couple of observations that might apply to either Part 1 https://github.com/orgs/grimmory-tools/discussions/1331 or Part 2 here.

If I remember correctly, with the current implementation of book_files, we only support a max of one file per format per book.
I think it would make sense to elevate and clarify those policies in either one of the two RFCs, and then decide how to evolve them.

Similar policies include file renaming, moving books (and files) across libraries, etc.

Furthermore, in the move from Part 1 to Part 2, will the items in the TBD table containing file metadata be linked to the corresponding book entry or to the corresponding edition entry? It might be the latter, which will automatically allow the possibility of having-say-2 PDF versions of the same book because they correspond to two different editions, etc.

Finally: I'll repeat myself by suggesting adding ER diagrams to this RFC too, showing in particular how the data model will evolphe from Part 1 to Part 2.

[piffio]

It could be called Work to emphasize the abstract intellectual title, or kept as the high-level Book to better match user-facing language and metadata sources that model book -> edition.

I personally find the Work name confusing, as it's too generic and suggests something that has to do with someone's profession.
It could be interesting to reflect on the name based on whether there's a clear intention to support other types of publications in the future, such as academic/journalistic articles, magazines, newspapers, etc. And whether there's a strong belief that those new publication types will use the same data model currently used for books.

That said, if we'd err on the side of a generic term, I'd be tempted to use something like "Publication", which is at least a bit more specific than Work (i.e. it's not a sculpture, or a song :)), and still generic enough in the realm of printing/writing/publishing.

[laszabine]

In my PKM, I use the term "Text".

[zachyale]

Since this high level unit could represent an Audiobook, I don't know that "Text" would reflect that.

I'm partial to either Book, Publication, or Work, into -> Edition -> Issue

[laszabine]

Personally I think that audio books are definitely a form of text: an acoustic recording of a text, much like a physical or digital copy of a book is a visual typesetting of a text.

But, admittedly "text" doesn't work that well for graphic novels and the like.

[zachyale]

https://schema.org/CreativeWork

For some context: A lot of this research was based off of the conventions currently used by Readium for OPDS 2.0, and how they represent ebooks/comics/audiibooks in webpub manifests. One of the sources they regularly defer to are schema.org definitions- particularly books. Books are represented there as "Creative Works"- the highest abstraction of creative works such as books, music, movies, etc., and that is where the inspiration for some of the naming conventions here come from.

I'm open to other suggestions, but not sure "Text" is abstract enough for this purpose

[aaronified]

I think this is alright for normal books. The Book > Edition nomenclature makes sense.

However, this is still confusing for anthologies, collections, magazines and scientific papers. All of which have usecases in Grimmory. Maybe, there should first be a selection dropdown for different categories (including comics, right now the extra functionality seems to only appear for CBX files) first and then the necessary branch specific metadata.

Also, this shouldn't make metadata management more confusing than it is right now.

[zachyale]

1. I'm open to suggestions if you have any for those use cases. Though the way I imagine this would go is that any given instance of those (anthology, collection, magazine, papers) are really just ebooks/digital documents- they would all have one (maybe 2) editions.
   So for example: If you had a copy of scientific american from May 2026, you might have a digital edition, and a physical edition. For June, you may only have a digital edition. Then, June and May's "books" would be part of a collection/series together. As per the RFC, changes to collections/series are not in scope here- so in a future slice of work, we could expand and generalize what a series is to a work.
2. Agreed- you should have a way to mark a general category of a work or edition (an edition as a magazine, or a comic, etc.)
3. The idea is that this actually makes metadata management easier- by making it easier for users to manage the shared metadata between multiple copies or editions of the same work, within one form