Reading profiles and chapter updates
Add EPUB, illustrated chapters, recordings and rankings while keeping identity and snapshots consistent.
On this page
Declare capabilities you implement
The core stays compact. Profiles are optional, and the current specification is a candidate. Schemas and OEPs in the canonical repository define the fields. The builder kit embeds a pinned snapshot, recorded in package metadata.
| Feature | Capability | Representation |
|---|---|---|
| Text and illustrated chapters | content | text/plain, text/markdown, text/html |
| Chapter updates | top.xxread:chapter-updates | Existing catalog plus update state |
| EPUB | top.xxread:publications | Full publication file |
| Image sequences | top.xxread:image-sequence | image/sequence with images |
| Recorded audio | top.xxread:remote-audio | audio/uri with audio |
| Multiple rankings | rankings | Named definitions and paginated entries |
The generated starter implements text, browsing and updates. Other profiles include contracts and original reference fixtures; adding a capability string alone does not implement them.
Updates and cache consistency
Additions, corrections, deletion and reordering invalidate the corresponding catalog snapshot. Text contentVersion hashes exact UTF-8 content; chapter count alone misses corrections.
An extension-aware reader requests v1/books/{bookId}/updates, then loads catalog pages using catalogVersion. On 409, reload state and discard the old snapshot's pages. Do not send the version query to a source that has not declared the profile.
ETag validates one representation, not a whole catalog across different pages. A conditional 304 cannot hide a stale version conflict. Anchors attach to content identity and revision; rendered page numbers remain a reader layout result.
EPUB and illustrated text
EPUB uses v1/books/{bookId}/publications with immutable file identity, an absolute URL, media type, byte count and SHA-256. Change publication ID when bytes change; retain existing text chapters for older readers.
Markdown/HTML relative assets resolve with baseUrl, and readers still sanitize rendered content. Image chapters contain a nonempty images array in reading order and an empty content string. Discovery contentTypes advertises chapter forms, not application/epub+zip; image/audio declarations also require their matching capabilities.
Recordings and media refresh
audio/uri contains audio.url and empty text, with no images array. Recordings differ from client TTS; book background music is a separate future design. HTTP(S) assets and public request hints must not disclose cookies, Authorization or a reader session.
Refresh the same chapter for an expired asset; after supported media failures, retry at most once when its URL changes. Media revisions cover actual assets and order, not the hash of empty text. Revision tokens are not file integrity checksums. Ranges, HLS and platform codecs need real validation; passing a WAV reference test does not prove physical HLS playback.
Rankings and further profiles
v1/rankings lists definitions; v1/rankings/{rankingId} returns entries. rank is an absolute position. When snapshotId changes, reload rather than mix snapshots. Attribution includes source, ranking and snapshot; ranks from independent sources are not one authoritative global chart. Existing browse?sort=popular stays available.
Comments and paragraph comments have a draft OEP-0004 contract. Authentication, paid authorization and reading sync keep separate boundaries. Update the contract, implementation, samples and real HTTP acceptance together before advertising another profile.
Found a problem in this guide? Suggest a correction