Developers › File formats Beta
TextShelf file formats
TextShelf's two products, the web service at textshelf.com and the TextShelf app for Mac, exchange a reviewer's work as plain JSON files, and the Mac app keeps each shelf as a folder of JSON and PDF files. This folder is the specification of every one of them, so that other software can read and write them too.
Status: v1, beta. Each format below is at version 1. Fields may be added within a version; a reader that meets a higher version must stop.
The formats
| Format | kind |
Version field | Written by | Read by | Spec |
|---|---|---|---|---|---|
| Review packet | textshelf-review-packet |
formatVersion |
web | Mac app | review-packet.md |
| Review return | textshelf-review-return |
formatVersion |
Mac app | web | review-return.md |
| Review inbox | textshelf-review-inbox |
formatVersion |
web | Mac app | review-inbox.md |
Shelf bundle (.textshelf) |
none; one schemaVersion per file |
schemaVersion |
Mac app, other programs | Mac app, other programs | shelf-bundle.md |
Web link (web-link.json, in a bundle) |
textshelf-web-link |
schemaVersion |
Mac app | Mac app | shelf-bundle.md |
Document source (source.json, in a bundle) |
textshelf-document-source |
schemaVersion |
Mac app, other programs | Mac app, other programs | shelf-bundle.md |
Agent brief (agent-brief.json, in a bundle) |
textshelf-agent-brief |
schemaVersion |
other programs | other programs (the app keeps it unread) | shelf-bundle.md |
Assistant policy (assistant-policy.json, in a bundle) |
textshelf-assistant-policy |
schemaVersion |
the person's own app | any program that hands a document to an AI assistant | shelf-bundle.md |
| Workspace packs | none | none | web (generated) | Mac app | workspace-packs.md |
The packet and the return are one round trip: the web hands a reviewer their assigned entries as a packet, and the Mac app hands their scores back as a return. textshelf.com does not serve packets yet. The review inbox goes one way, from the web to the Mac app: it carries the web reviewers' scores so a reader on a Mac can see them beside their own.
Rules every format follows
These hold for the three exchanged files, the packet, the return and the inbox. A shelf bundle is a different kind of thing, a folder the Mac app rewrites on every save, and its rules differ by file: shelf-bundle.md §3 states them exactly, including where today's app checks less than it should.
- Versions. A reader refuses a higher
formatVersionthan it knows, and a file whosekindis not the one it expects. Adding an optional field keeps the version; anything a version-1 reader would misread raises it. - Values. A score is an int or a string, never a float. The one number
that can be fractional, a criterion's
weightin the review inbox'srubriclist, is there for display and never stored as a score. - Dates. UTC, ISO 8601, written with a millisecond fraction
(
2026-09-20T14:00:00.000Z). Readers also accept a date without the fraction. - One bad element. A reader skips an element it cannot read, reports it, and keeps the rest: one bad review never sinks the file. Inside a shelf bundle it is the other way round: one bad element fails its file.
- Unknown fields. Readers ignore fields they don't know.
- Identity. No exchanged file names the person who sends it back. The web applies a return as the signed-in reviewer who uploads it.
Examples and schemas
Every JSON example in these pages is also a file in examples/
(the bundle's in examples/shelf-bundle/), and the tests hold them equal: textshelf/core/tests/test_formats_doc.py
checks each page against its files, the web's own tests build and read the
same files, and the Mac app's tests load them as resources. JSON Schemas for
the three exchanged formats are in schemas/; they are generated
from the web's own validators (textshelf/submissions/format_schemas.py), and
a test fails when a checked-in schema differs from a fresh one.
Licence
This specification is licensed under CC BY 4.0; the example and schema files under the MIT licence. Anyone may implement these formats in their own software.
This specification is licensed under CC BY 4.0, and its example and schema files under the MIT licence. Anyone may implement these formats in their own software. CC BY 4.0