Reviews, annotations, and endorsements in Chive

This is the fourth post in a series about Chive , a decentralized eprint service on AT Protocol . The first post covers the architecture, the second covers the knowledge graph, and the third covers collections. The next post will cover discovery and citations.

This post describes Chive v0.3.0 . Details may change as the project develops. You can follow the project on Bluesky at @chive.pub .

The basic model

Chive supports three general ways of commenting on a paper’s contents: reviews, annotations, and endorsements. All are AT Protocol records stored in the reviewer’s PDS . Chive indexes them from the firehose but doesn’t own them. If you write a review, make an annotation, or give an endorsement, it’s yours. You can delete it, edit it, or take it with you to another AppView.

All are currently public and tied to your Bluesky identity, though we may support anonymous review in the future. The goals are threaded discussion, passage-level anchoring, and giving reviewers a persistent record that they control.

Because the record lives in your PDS, you can reference your reviews from your profile, build a track record over time, and carry that history with you if you move to a different service. This makes Chive reviewing very different from standard peer reviewing in a few important ways: (i) they are editable; (ii) they are public; and (iii) they are threadable. This puts the Chive model relatively close to one mode that OpenReview works in, though it has the built in ownership and portability benefits afforded by AT Protocol.

Reviews

A Chive review is a general comment on an eprint. It can optionally reference a passage, but it doesn’t have to. Reviews share the same rich text body model as paper abstracts (allowing for mentions, knowledge graph links, LaTeX math, code, tables, etc.) and support threading and motivations.

Annotations

A Chive annotation is anything anchored to a specific text span. Annotations come in two forms: comments (which carry a rich text body) and entity links (which connect the selected text to a knowledge graph entity without a comment body). Both forms use the same W3C selector model for text targeting. Annotations appear inline alongside the annotated passage.

Endorsements

A Chive endorsement is a structured assertion about which aspects of a paper’s contribution are strong. Chive defines fifteen endorsement types: methodological, analytical, theoretical, empirical, conceptual, technical, data, replication, reproducibility, synthesis, interdisciplinary, pedagogical, visualization, societal-impact, and clinical. You can select any combination and optionally include a comment explaining your assessment. Unlike motivations (described below), endorsement types are defined in the lexicon schema rather than as knowledge graph nodes; adding a new type requires a lexicon update rather than a community governance proposal. Endorsements are displayed separately on the eprint page, with an aggregate summary showing endorsement counts by type and unique endorser count. Over time, a paper accumulates a profile of what other researchers consider its strengths, and those endorsements are queryable across the entire platform.

Document types

Reviews and endorsements work on all document types; but in the current release, inline annotations (text selection, commenting on passages, highlighting, entity linking) are only available for PDFs. The data model is format-agnostic, though, and the frontend has viewer infrastructure for HTML, Markdown, LaTeX, Jupyter, and plain text with text selection support. It’s just that those viewers aren’t yet integrated with the annotation system.

Text targeting

Annotations target text spans using selectors from the W3C Web Annotation Data Model . Each annotation stores the exact selected text along with surrounding context, so the anchor is resilient to minor document edits. If the author revises the paper and character offsets shift, the selector can still find the passage by matching the exact text within its surrounding context. The annotation can also be pinned to a specific eprint version.

For PDFs, the annotation additionally carries page coordinates and a bounding rectangle, so the frontend can render visual highlights over the PDF text layer without re-running text extraction. (The text-based selector is the source of truth for matching; the coordinates are an optimization for rendering.)

When you select text in the PDF viewer, a popover appears with two actions: Comment (to write an annotation) and Link (to create an entity link). The technical details of the selector format are in the review system deep dive.

Annotations are browsed through a sidebar on the eprint page, grouped by page number. You can sort by page, date, or author, and expand or collapse individual pages. Clicking an annotation in the sidebar scrolls the PDF viewer to the anchored passage.

Rich text in reviews

Review and annotation bodies use the same rich text model described in the first post . A review body is an array of typed items: plain text with facets, inline LaTeX math, references to Wikidata entities, knowledge graph nodes, eprints, and authors, as well as code blocks, headings, list items, and blockquotes.

Every typed reference that a reviewer embeds becomes a queryable link in the knowledge graph. If a reviewer mentions a methodology by linking to its knowledge graph node, or cites a related paper by referencing its AT-URI, those connections are indexed. This allows you to find all reviews that discuss a particular methodology, trace how a concept is evaluated across different papers, or discover which reviewers engage with a specific research area. The references in reviews contribute to the same web of structured connections that abstracts and annotations build.

Motivations

Both reviews and annotations carry a motivation, following the W3C Web Annotation vocabulary . Chive ships with ten motivation types: commenting, questioning, highlighting, replying, linking, describing, classifying, tagging, editing, and bookmarking. Each motivation is a knowledge graph node, which means the vocabulary is community-governed the same way fields and licenses are. If the community needs a new motivation type (say, for flagging reproducibility concerns), it can be proposed and added through the governance process described in the second post without any changes to the AppView.

Threading

Reviews support threaded discussion. A reply references its parent, and Chive reconstructs the thread tree from the index. Each thread node carries a reply count so the UI can show conversation depth without loading every reply.

When a review is deleted, the AT Protocol soft-deletion model preserves the record as a tombstone. Thread structure stays intact: replies to a deleted review still appear in the thread, and the deleted parent is shown as removed rather than missing. This prevents deletions from fragmenting conversations.

In principle, annotations thread the same way: the lexicon supports replies to an inline annotation with the idea that replies can appear in context alongside the annotated passage. We’re still working on the frontend support for this though.

Entity linking

Entity linking lets you connect a text span in a document to a knowledge graph entity. For instance, you can select the term CRISPR in a paper, link it to its Wikidata entry, and now that paper is connected to everything Wikidata knows about CRISPR. Over time, entity links build a semantic layer across all papers on the platform.

Entity links use the same W3C selectors as annotations for targeting. The current release supports linking to Wikidata entities and Chive knowledge graph nodes; but the underlying lexicon is broader: it defines four kinds of linked entity (knowledge graph nodes, external identifiers covering eighteen systems including ROR , ORCID , DOI , FAST , MeSH , and arXiv, authors by AT Protocol DID, and other eprints on Chive), and we’ll be adding UI for the remaining link types in future versions.

How this fits together

An eprint accumulates layers of structured commentary: reviews provide general discussion; annotations anchor comments to specific passages; endorsements make structured claims about contribution quality; and entity links connect text spans to the knowledge graph. All of these are AT Protocol records in the respective authors' PDSes, all of them use the rich text system, and every typed reference adds a connection to the knowledge graph.

The collection feed system from the third post ties into this directly. If you’re tracking an eprint in a collection, new reviews, endorsements, and annotations on that eprint show up in your collection’s activity feed, because the feed watches for events on tracked items.