These lexicons define a shared language for describing book editions and an interoperable format for book data across divergent sources. As I discussed in my first blog post, books don’t have a reliable way of being identified in the general case. Different sources organize their datasets for different purposes: selling physical copies, sharing reviews, or bibliographical research.
Given these different understandings of what a “book” is, my second blog post proposes editions as the common ground for interoperability. Applications decide how to group those editions into works, and those groupings can differ between providers.
These lexicons establish a common baseline for describing editions, with a heavy focus on interpreting and matching books across datasets. Records carry identifiers alongside enough descriptive information to remain useful independently. If all you store in your PDS is a provider’s identifier, "abc", that tells you very little once the provider shuts down. Keeping the title, contributors, and other known identifiers gives you a way to understand the record and find the book elsewhere.
The goal is a loosely interoperable network of book applications with a shared shape and interfaces that support user agency (see the day-after test in my BookHive talk at ATmosphereConf) while leaving applications room to differ in their data, organization, and user experience.
Technical details
-
Editions are the shared unit; work groupings belong to applications. Providers can disagree about whether translations, audiobooks, or omnibus editions belong together without needing to agree on a universal work model.
-
Identifiers support matching across catalogs. An edition can carry identifiers from multiple sources. Each identifier has an issuer naming its namespace and a value; matching compares those pairs exactly, without requiring consumers to interpret provider-specific IDs.
-
References carry enough information to stand alone. Titles, contributors, and identifiers make records understandable when identifiers cannot be resolved or the original provider disappears. Optional cover blobs let applications preserve the image too.
-
Reviews and ratings are portable. Review records embed the descriptive edition reference rather than depending solely on a link to a provider’s catalog. They support ratings, plain-text reviews, and optional client-specific rich content.
-
Resolution and search serve different purposes. Resolution returns editions matching at least one supplied identifier pair exactly; search helps discover candidates using descriptive information. Providers control result ranking and search behavior.
-
Established standards guide the vocabulary. ONIX supplies contributor-role codes, ISO 8601 preserves publication-date precision, and Schema.org Book guides future metadata fields.
-
Catalog storage remains a provider choice. The shared APIs work with catalogs stored on or off AT Protocol. Applications can participate without adopting the same database or publishing model.
This proposal also updates CI to discover lexicon files recursively, so the new nested namespace is included in API generation.
Original PR on GitHub into BookHive: https://github.com/nperez0111/bookhive/pull/229
