page.cavu.progress
Schema Diff
+1 -1
Compatibility Analysis
Backward Compatible
No changes detected.
1
1
{
2
2
"id": "page.cavu.progress",
3
3
"defs": {
4
4
"main": {
5
5
"key": "tid",
6
6
"type": "record",
7
7
"record": {
8
8
"type": "object",
9
9
"required": [
10
10
"publication",
11
11
"position",
12
12
"updatedAt"
13
13
],
14
14
"properties": {
15
15
"percent": {
16
16
"type": "integer",
17
17
"maximum": 100,
18
18
"minimum": 0,
19
19
"description": "Denormalized whole-book completion percent at `position`, weighted over body-matter chapters, computed by the writing client (which has the book loaded). Lets list views render progress bars from this record plus the publication record alone. A serial's denominator grows with each release, so display against the live spine when possible."
20
20
},
21
21
"finished": {
22
22
"type": "array",
23
23
"items": {
24
24
"ref": "com.atproto.repo.strongRef",
25
25
"type": "ref"
26
26
},
27
27
"description": "Spine documents read to completion, each pinned at the cid it had when finished. A finished entry whose cid no longer matches the live record marks a chunk that changed after the reader read it; re-reading a changed chunk to completion replaces its entry with the new cid."
28
28
},
29
29
"furthest": {
30
30
"ref": "#position",
31
31
"type": "ref",
32
32
"description": "Furthest position ever reached, when it differs from position (re-reading, or a device syncing an older current position). Clients max-merge by spine order: position is last-writer-wins, furthest never regresses."
33
33
},
34
34
"position": {
35
35
"ref": "#position",
36
36
"type": "ref",
37
37
"description": "Where the reader currently is — the resume point."
38
38
},
39
39
"startedAt": {
40
40
"type": "string",
41
41
"format": "datetime",
42
42
"description": "When the reader started the book."
43
43
},
44
44
"updatedAt": {
45
45
"type": "string",
46
46
"format": "datetime",
47
47
"description": "When this record was last written. Doubles as last-read-at for surfacing recently read books."
48
48
},
49
49
"finishedAt": {
50
50
"type": "string",
51
51
"format": "datetime",
52
52
"description": "When the reader finished the book. Presence marks the book finished regardless of percent."
53
53
},
54
54
"publication": {
55
55
"type": "string",
56
56
"format": "at-uri",
57
57
"description": "AT-URI of the book's site.standard.publication record — the backlink target."
58
58
}
59
59
}
60
60
},
61
-
"description": "Reading progress for one book, written to the reader's own repo. One record per (reader, publication) by convention: clients list their own repo and update the existing record for a publication rather than create a second (the BookHive shelf pattern). The publication AT-URI makes records discoverable by backlink index (Microcosm/Constellation), so 'who is reading this book' needs no app-side database. Positions anchor documents by strongRef: the cid pins the chunk *as read*, so a later edit to an already-read chunk is detectable by cid drift and clients can flag it. Repo records are currently public: clients must disclose at sign-in that reading positions are saved to the reader's own repo. These records are intended to move into permissioned spaces once that capability is live."
61
+
"description": "Reading progress for one book, written to the reader's own repo. One record per (reader, publication) by convention: clients list their own repo and update the existing record for a publication rather than create a second (the BookHive shelf pattern). The publication AT-URI makes records discoverable by backlink index (Microcosm/Constellation), so 'who is reading this book' needs no app-side database. Positions anchor documents by strongRef: the cid pins the chunk *as read*, so a later edit to an already-read chunk is detectable by cid drift and clients can flag it. Where the reader's PDS implements atproto permissioned data (proposal 0016), clients write these records into the reader's personal space instead — at://<did>/space/page.cavu.personal/self, an owner-only (empty member list) space anchored on the reader's own DID so their PDS is also the space host — and migrate any public record there on first read (merge, rewrite into the space, delete the public copy). Space records are invisible to backlink indexes, so private progress deliberately drops out of 'who is reading this book'. On any other PDS the record is a public repo record and clients must disclose at sign-in that reading positions are saved to the reader's own repo."
62
62
},
63
63
"position": {
64
64
"type": "object",
65
65
"required": [
66
66
"document"
67
67
],
68
68
"properties": {
69
69
"document": {
70
70
"ref": "com.atproto.repo.strongRef",
71
71
"type": "ref",
72
72
"description": "Spine document the reader is in, at the cid last seen by this client."
73
73
},
74
74
"thousandths": {
75
75
"type": "integer",
76
76
"maximum": 1000,
77
77
"minimum": 0,
78
78
"description": "How far through the document the reader is, in thousandths (0 = top, 1000 = end). Omit when unknown; clients treat absence as the top of the document."
79
79
}
80
80
},
81
81
"description": "A place in a book: the spine document (pinned at its as-seen cid) plus how far through it the reader is. Fractional depth in thousandths keeps the grammar integer-only and is deliberately edit-tolerant — after an in-place edit it lands near the old spot and clamps, and the strongRef cid tells clients the ground shifted."
82
82
}
83
83
},
84
84
"$type": "com.atproto.lexicon.schema",
85
85
"lexicon": 1
86
86
}