2.6 KiB
FAQ
Can I read these files without the studio's software? Yes. Every file is JSON or JSON Lines, every format is specified in spec/, and the examples read a package with a few lines of Python.
Why not keep using PDFs and page numbers? A page number names a region, not a statement, and it changes between a preprint and the version of record. An address names a sentence or a cell, survives reconversion, and can be checked against the exact text.
Why are numbers stored as strings?
Because databases and JSON libraries rewrite numbers: 310.0 becomes 310 and 1.5260 becomes 1.526, and the printed digits are part of what a paper says.
What happens when a better converter comes along? Its reading is aligned with the established document sentence by sentence. Sentences it reads the same keep their IDs; every difference becomes a suspect for review; nothing changes until a correction passes the gate.
Do I need receipts, rights records and spot-checks for a personal library? No. One person can leave receipts out entirely and record only a license. The fields are defined so that a personal library loads into a team's store later without conversion.
Is a model allowed to correct a document? A model may propose corrections and answer suspects in a review session, under the same gate as a person, and its corrections record the model and the run. Only a named person can sign a receipt.
Why are annotations W3C Web Annotations? So existing tools can read them. A tool that does not know the anchor selector falls back to the text-quote selector beside it.
What is the difference between a claim and an annotation? A statement true independently of the paper, such as "K_r is the bond force constant of the AMBER energy", is a claim and belongs in Lode, where it is checked. A statement about reading the paper, such as "the authors pass quickly over the scaling here", is an annotation in a layer, attributed but not checked.
Can a team share notes on a paywalled paper? Yes, without sharing the paper: a checks-only package or a public layer carries IDs, offsets and keyed hashes, and is shown over each reader's own copy. Whether a team may do so is a question for its own counsel; nothing here is legal advice.
How do I add a node kind or a run kind? Propose it with the vector or fixture that shows it; a new kind is a minor version. See CONTRIBUTING.md.
What are the files in tools/ for?
They compute and check every vector and fixture so that no expected value is typed by hand.
They are not a library; implementations follow the specification.