paperspec/spec/09-figures-tables-equations.md

9. Figures, tables and equations

9.1 Figures and panels

A figure holds its panels, its caption and its notes. A panel's own content is its label only. Its image and region are evidence, not content: re-extracting the image at native resolution adds an asset and changes no hash.

Panel attribute	Holds
image	{sha256, media_type, native, dpi?}: the embedded image, at native resolution when the PDF holds one.
crop	{sha256, media_type, dpi}: a crop of the panel's region at a fixed resolution.
figure_text	[{id, text, role, page_fp?, boxes?}]: text found inside the panel, with role axis-label, tick-label, legend, annotation or other.

Text inside a figure is not prose and is not split into sentences. Its items have IDs (4.2) so that a digitization can anchor its axis labels to them. A panel's region on the page is its location (7.4).

9.2 Tables

A table holds its caption, an optional head, one body and its notes. Rows and cells are nodes, with all five values, so the gate, the hashes and the database treat them like any other node, and a cell is addressed like a sentence.

Columns are defined in the table's columns attribute, each with an ID and a header path: the IDs of the header cells above it, outermost first. Header text is stored once, in the header cells. A row's header_path lists the cells that label it: a row-group header and the row's own header cell. A cell records its column, its spans and its role; the expanded grid is derived, never stored.

So inserting a row that a reading dropped adds a row node and changes no other row's or cell's ID or hash, and fixing a header cell changes that cell, not the table. A table continued across pages is one table node; its pages are locations. For people, a cell can be shown as "Table 2, row CT–CT, column K_r" from its header paths.

9.3 Equations

An equation keeps its source as written, tex from a conversion or typst from a draft, and its printed number as its label, so numbering never collides with a renderer's own. An equation that the source numbers line by line (Eq. 3a) has equation-line children, each with its own label and source. A converter that respells TeX in the standard form of 9.4 stores the respelled source and says so with form beside it (3.7); the source as written stays in the witness. MathML is derived by a pinned tool and recorded, with the tool's name and version, in derived/mathml.jsonl, and the form's reading of each formula in derived/math.jsonl (12.7).

9.4 The math form

scienting-math/1 is the standard form of a formula in a paper: one canonical TeX spelling, a tree read from it, a key for each symbol, and the issues a reader should look at. A converter writes a package's equations and math runs in it, a reader renders and searches it, and a claim store reads a paper's equations and its own claims through it, so the two can be matched. papermath is its reference implementation, and what papermath computes is what the form says; this section states what the specification relies on. The identifier names a spelling of formulas, not a file format, so registry/formats.json does not list it; its readings travel in a package's derived/math.jsonl. The form reads TeX only.

Canonical TeX respells and never reinterprets, so it renders as the source did apart from presentation:

1. Unicode NFC, and a math character a converter handed over becomes its command: − is -, ≤ is \leq, α is \alpha.
2. Space is dropped, except inside text and where a command needs one before a letter (\sin x).
3. One spelling per meaning: \le is \leq, \dfrac and \tfrac are \frac, \textrm is \text, x^{\prime} is x'.
4. Presentation is dropped: \displaystyle and the other styles, \big and its sizes, \color, and \left and \right around ordinary delimiters.
5. Every argument and script is braced, and on one base the subscript comes first: x_i^2 is x_{i}^{2}, \frac12 is \frac{1}{2}.
6. \tag is lifted out as the label, and \label, \nonumber and \notag are dropped.
7. An environment goes by one name: align, split and multline are aligned, equation and gather are gathered.
8. A command outside the form's vocabulary is kept as written and reported.

Spelling a canonical source again gives it back unchanged.

The tree is the canonical TeX read as JSON. A node is an array whose first item is a string, its kind; its other items are its parts: strings, null for a part that is absent, nodes, and groups, which are arrays whose first item is not a string. Brackets group and leave no node.

Kind	Parts	Is
num	The digits	A number as printed, a decimal comma read as ..
sym	The key	A symbol.
text	The words	Words in the formula.
const, oper	The command	A constant, such as \infty, or an operator, such as \partial.
dots, empty	None	An ellipsis; nothing.
add	The terms	A sum, in which a subtracted term is a neg node, ± a pm and ∓ an mp, each with one part.
mul	The factors	A product, by juxtaposition or \cdot.
times, div, op	Two operands, after the operator's command for op	\times; / or \div; any other binary operator.
frac, binom, sqrt, root	Numerator and denominator; the radicand, after the index for root	Fractions, binomials and roots.
pow, sub, prime, fact	The base, and the script for pow and sub	Scripts, primes and factorials on what is not a symbol.
prescript	The lower script, the upper script, the base	Scripts before their base, as in the isotope ^{31}\text{P}.
mark	The sign or operator	A sign or operator with no operand: a charge (x^{+}), the radical dot of \cdot\text{OH}, a formula cut by its converter.
apply	The function's command, its argument, and its subscript if any	A named function: \cos(x), \log_{2} n, \max_{i} x_{i}.
lim	The command, what is under it, the body	\lim, \liminf and \limsup.
sum, prod, coprod, int, iint, iiint, oint, bigcup, bigcap	The lower limit, the upper limit, the body	A big operator, whose body runs to the next sign outside brackets.
abs, norm, angle, floor, ceil, braces	The inside	A fence.
interval	The opening and closing brackets, the inside	Brackets that do not match, as in [0, 1).
rel	Operands with a relation between each two	A relation or a chain; a continued line starts with null.
list	The formulas	Formulas side by side, at ,, ;, \quad or \qquad outside brackets.
lines	The lines	The lines of an aligned or gathered block.
cases	A group of value and condition for each case	Cases, a condition being null when there is none.
matrix	The environment, then a group of rows, each a group of cells	A matrix or array.
opaque	Canonical TeX	What the tree does not read.

A tree with no opaque node is complete. A later minor version of the form may add a kind, and a consumer that meets a kind it does not know reads that node as it reads opaque; math.schema.json therefore takes any lowercase kind, and its description lists these.

A symbol is a base, which is a letter, a Greek letter, or a font or accent command on a group (\mathbf{F}, \hat{H}), with any subscript, any superscript that names rather than raises (R^{*}, A^{\dagger}, E^{\text{LJ}}), and primes. A text group alone is a symbol too, unless it holds several words, is a condition in cases, or is the set under a big operator. A symbol's key is its canonical TeX with \mathrm spelled \text, \ast spelled *, \prime spelled ', and no space inside text: K_r and K_{r} have the key K_{r}, and r_{\mathrm{eq}} has the key r_{\text{eq}}. The key is the one a paperclaim claim store gives a symbol, so a symbol in a paper and the same symbol in a claim have one key, and a symbol annotation names its symbol by it (18.4).

Issues never stop the reading; each is {code, message, at}, with at the canonical TeX it is about.

Code	Means
unbalanced	A brace, bracket or fence does not close; with a brace, the whole formula is one opaque node.
unknown-command	A command outside the vocabulary, kept as written.
label-or-power	A superscript that may be a label written without \text, such as E^{LJ}, read as a power.
script-on-group	A script on a braced group rather than on a symbol.
opaque	A part the tree does not read.
infix-fraction	\over, \choose or \atop, rewritten as \frac or \binom.

A later minor version may add a code.

In a package, the canonical source is the equation's or the math run's source, with form beside it (3.7), and the rest is derived: one line of derived/math.jsonl per formula a pinned tool read, {node, run, tool, form, tree, symbols, complete, issues, label?}. run is the index of the math run among the node's runs, or null for an equation or equation line, as in derived/mathml.jsonl; symbols lists the keys in the order the formula first writes them; label is the label the tool lifted from a \tag, omitted when the source has none, as a canonical source never does. The schema is math.schema.json. A validator checks what it can without implementing the form: that each line names a formula of the package (doc.derived.node), and that the formula is TeX, complete is true exactly when the tree has no opaque node, and symbols holds each sym key of the tree once (doc.derived.math). fixtures/packages/hale2026harmonic-damb/derived/math.jsonl holds papermath's reading of the example's equation, of a math run that is one symbol, and of the run _2 of "H₂O", which the tree cannot read alone.