paperspec/spec

The scienting specifications

This is the specification of the scienting formats: exactly what each file holds and how every value in it is computed. For what the formats are for, start with the guides; this text assumes you know why and tells you how. Schemas, SQL, the JSON-LD context, the registries, the vectors and the fixtures are normative too, and the chapters say which. Where a chapter and a vector disagree, the disagreement is a bug; please report it.

Reading paths

If you are writing	Read
Anything at all	0, 1, 3, 4 and 5: conventions, nodes, identity and the content values.
A reader of packages	Then 2, 6, 7 and 12: the model, anchors, geometry and the package.
A converter	Then 9, 10 and 11: figures and tables, references, and corrections with the gate.
A store or a server	Then 8, 13 and 14: receipts, the database form, and rights.
A tool for annotation, teaching or data	Then 15 to 21.
A validator	Chapter 22, with registry/rules.json.

Chapters

Chapter	Subject
00	Scope, conformance, versions and status
01	Canonical JSON, numbers, hashes, normalization, offsets, times, IDs, keys and files
02	Works, versions, witnesses and documents; document.json and witnesses.json
03	Nodes, their kinds and children, content, attributes and inline runs
04	Minting IDs, permanence, retirement, aliases and record IDs
05	The five content values, the projections, alignment, suspects and keyed hashes
06	Addresses, anchors and the five resolutions, with drift
07	Page fingerprints, stamp rules, pages and locations
08	Fidelity levels, receipts, the roster, revocations, spot-checks and error bounds
09	Figures, panels, tables, cells and equations
10	References and citations
11	Corrections and the gate
12	The package
13	The database form and the bundle
14	Rights records, policies, stages and backends
15	Datasets
16	Digitization records
17	Views
18	Layers and annotations
19	Exercises, submissions and grades
20	Projects
21	Drafts: snapshots and sentence-ID sidecars
22	Conformance, the suite and the rule catalog