SPB Git

Repository Public

SHEET_SCHEMA.md 27.2 KB

# Sheet Document Schema — version 1

A sheet is one JSON value. It is the single contract between the editor, the AI pipeline, the renderer, the exporters and the database. It contains no HTML, no CSS and no script: everything a sheet can show is one of the block types below.

Source of truth: src/schema/sheet.ts (Zod schemas) and src/schema/index.ts (parsing, migration, patches, diff). This file is a reading aid; where it and the code disagree, the code is right.

Every object is strict: an unknown key is a validation error. "Default" means the key may be omitted in input and is filled in by parsing. Lengths are in characters.

# 1. Top level

Field Type Default Constraints
schemaVersion 1 — required; older values are migrated first
metadata object — see below
theme { preset, accent } scientific-light, blue preset: a theme; accent: a tone
layout { type, format, maxWidth } responsive-document, article, 1120 maxWidth 640–1440 (article only)
blocks Block[] — ≤ 80 top-level blocks
sources Source[] [] ≤ 60
claims Claim[] [] ≤ 60
assets AssetRef[] [] ≤ 40
interactions [] [] must be empty; reserved for a later version

Document-level rules checked after the shapes:

  • block ids are unique across the whole document, tab contents included;
  • source ids are unique;
  • every sourceIds entry of a block or claim names an existing source;
  • an image block's assetRef and a chart's datasetRef name an entry of assets;
  • a claim's blockId names an existing block.

# metadata

Field Type Default Constraints
title text — 1–160
slug string — optional proposal, kebab-case, ≤ 96; the public slug lives on the sheet row
author "Simon-Pierre Boucher" that value a literal; no other value validates
locale fr | en — cannot change once the sheet exists
summary text "" ≤ 400
topics text[] [] ≤ 6, each 1–60
tags text[] [] ≤ 12, each 1–40
level beginner | intermediate | advanced intermediate
kind explainer | cheatsheet | comparison | architecture | method | case-study explainer
objectives text[] [] ≤ 6, each 1–300
example boolean — optional; shows the "unreviewed example" banner

# 2. Vocabulary

Ids — ^[a-z0-9][a-z0-9-]{0,47}$: lower-case letters, digits and dashes, 1–48 characters. newId(prefix) generates <prefix>-<8 hex digits>.

Tones — semantic colours; the theme decides the actual values: neutral, blue, teal, green, amber, red, violet, pink.

Icons — a fixed set drawn in src/renderer/icons.tsx: brain, layers, route, database, server, cpu, cloud, network, search, filter, document, code, chart, trend, sigma, function, clock, bolt, lock, key, shield, users, user, globe, flask, atom, book, target, check, cross, warning, info, scale, coins, bank, cube, gear, arrows, split, merge, token, memory, queue, table, eye, sparkles, puzzle, microscope, calculator, link.

Themes — scientific-light, scientific-dark, editorial, blueprint, finance.

Formats

Format Width × height (CSS px) Safe margin Behaviour
article 1120 × fluid 24 responsive document; layout.maxWidth applies
a4 794 × 1123 48 fixed canvas
slide-16-9 1600 × 900 56 fixed canvas
square 1080 × 1080 48 fixed canvas
portrait-4-5 1080 × 1350 48 fixed canvas

Data kinds — the nature of the numbers a chart or matrix shows, printed with the figure: empirical (real observations; the quality report requires a source), synthetic (generated by a stated process), illustrative (hand-chosen values that show a shape).

URLs — https: or mailto: only, ≤ 2 000 characters.

# 3. Inline syntax

Text fields accept a small Markdown subset, parsed by src/renderer/inline.tsx. Nothing else is interpreted; raw HTML is shown as text.

Syntax Result Notes
**bold** bold must not start or end with a space
*italic* italic same
`code` inline code no nesting inside
$x^2$ inline LaTeX (KaTeX) the opening $ is followed by a non-space and the closing $ is preceded by one, so "5 $ and 10 $" stays text
[label](https://…) link https: or mailto: only; other targets stay text; links do not nest; label ≤ 300, target ≤ 2 000
[^source-id] numbered citation linking to the references block renders nothing if the source does not exist (and the quality report raises an error)
\*, \`, \$, \[, \], \\ the literal character

Nesting depth is limited to 4. Labels drawn inside SVG (diagram nodes, chart axes) use the plain text of the string.

KaTeX runs with trust: false, strict: "ignore", maxExpand: 1000.

# 4. Blocks

# Fields common to every block

Field Type Default Meaning
id Id — unique in the document
type string — discriminator
span 3 | 4 | 6 | 8 | 12 12 width on the 12-column desktop grid; below 768 px of sheet width every block is full width, in document order
alt text ≤ 600 — text alternative; required by the quality report on diagram, chart, matrix, svg, image (error) and simulation (warning)
sourceIds Id[] ≤ 12 — sources shown under the block
locked boolean — cannot be moved or deleted in the editor; never touched by AI edits

The tables below list the type-specific fields.

# heading

Field Type Default Constraints
level 1 | 2 | 3 — the first level-1 heading is the page's h1; others render as h2
text text — 1–200
eyebrow text — ≤ 80

# paragraph

Field Type Default Constraints
text text — 1–4 000
lead boolean — lead paragraph styling

# list

Field Type Default Constraints
style bullet | number | check —
items text[] — 1–30 items, each 1–800

# equation

Field Type Default Constraints
latex string — 1–2 000; display LaTeX; syntax checked by the quality report
label text — ≤ 80
explanation text — ≤ 1 200
variables { symbol, meaning, unit? }[] — ≤ 20; symbol 1–120 (LaTeX), meaning 1–300, unit ≤ 60
derivation standard | derived | unverified standard unverified is flagged to the reader

# callout

Field Type Default Constraints
tone note | tip | warning | definition | theorem | example | assumption — a callout kind, not a colour tone
title text — ≤ 200
text text — 1–4 000

# table

Field Type Default Constraints
caption text — ≤ 300
columns { label, align }[] align: left 1–8; label ≤ 200; align left | right | center
rows text[][] — 1–40 rows; each cell ≤ 600; every row has one cell per column
headerColumn boolean — first column is a header

# cards

Field Type Default Constraints
columns 2 | 3 | 4 3
items { icon?, title, text, tone, badge? }[] tone: neutral 1–12; title 1–200, text ≤ 800, badge ≤ 40

# steps

Field Type Default Constraints
items { title, text, icon? }[] — 1–12; title 1–200, text ≤ 800

# legend

Field Type Default Constraints
title text — ≤ 200
items { label, tone, shape }[] shape: square 1–12; label 1–200; shape square | circle | line | dashed | arrow

# diagram

Field Type Default Constraints
kind flow | architecture | tree | graph flow
direction TB | LR TB
routing orthogonal | curved | straight curved
title text — ≤ 200
caption text — ≤ 400
nodes Node[] — 1–60
edges Edge[] [] ≤ 120
groups { id, label, tone }[] [], tone: neutral ≤ 12; label ≤ 80
legend { label, tone, shape }[] [], shape: square ≤ 8
animation { steps: Step[] } — optional; 2–20 steps

Node:

Field Type Default Constraints
id Id — unique among nodes
label text — 1–80
sublabel text — ≤ 120
shape rect | round | pill | diamond | cylinder | circle | hexagon | note round
tone Tone neutral
icon Icon —
group Id — must name a group
x, y number — −20 000…20 000; manual centre position; both or neither; unset = placed by the layout engine
locked boolean — not moved by the visual editor

Edge:

Field Type Default Constraints
id Id — unique among edges
from, to Id — must name nodes
label text — ≤ 80
style solid | dashed | dotted solid
arrow end | both | none end
tone Tone neutral
fromPort, toPort auto | top | right | bottom | left auto

Animation step: title (1–200), text? (≤ 600), nodes (Id[] ≤ 60, default []), edges (Id[] ≤ 120, default []); every id must exist in the diagram. The reader can play, pause and step through them.

# timeline

Field Type Default Constraints
orientation vertical | horizontal vertical
items { when, title, text?, tone }[] tone: neutral 2–20; when 1–60, title 1–200, text ≤ 600

# matrix

Field Type Default Constraints
title text — ≤ 200
caption text — ≤ 400
rowLabels, colLabels text[] — 1–16 each, labels ≤ 60
values number[][] — finite numbers; exactly rowLabels × colLabels
scale sequential | diverging | none sequential
showValues boolean true
decimals integer 2 0–4
dataKind data kind — required

# code

Field Type Default Constraints
language python | typescript | javascript | r | sql | bash | json | yaml | latex | julia | rust | go | c | pseudo | text —
code string — 1–6 000
caption text — ≤ 300

# chart

Field Type Default Constraints
kind line | area | bar | scatter | histogram —
title text — ≤ 200
caption text — ≤ 400
dataKind data kind — required
x Axis + type type: number type number | category
y Axis
series { name, tone, points }[] tone: blue 1–8 series; name 1–200
series[].points { x, y, lo?, hi? }[] — 1–600; x a finite number or a label ≤ 60; y, lo, hi finite numbers; lo/hi draw a band or error bar
annotations { x?, y?, label }[] — ≤ 8; label 1–120
datasetRef Id — an assets[] entry of kind dataset the points were built from

Axis: label (1–200), unit? (≤ 40), scale (linear | log, default linear), min?, max?.

The quality report adds: non-numeric x on a numeric axis, non-positive values on a log scale and an interval that does not contain its value are errors.

# svg

Field Type Default Constraints
tree SvgNode — a sanitised tree, never markup
caption text — ≤ 400
maxWidth integer — 80–1120

SvgNode: { tag, attrs, children }. tag is one of svg, g, path, rect, circle, ellipse, line, polyline, polygon, text, tspan, defs, linearGradient, radialGradient, stop, clipPath, title, desc. attrs maps attribute names (^[a-zA-Z][a-zA-Z0-9:-]{0,40}$) to strings ≤ 20 000. children holds ≤ 400 nodes or strings ≤ 2 000. Trees are produced by sanitizeSvg (POST /api/admin/svg/sanitize); the renderer re-checks every attribute.

# image

Field Type Default Constraints
assetRef Id — an assets[] entry
caption text — ≤ 400
maxWidth integer — 80–1120

# comparison

Field Type Default Constraints
caption text — ≤ 300
columns { title, tone, badge? }[] tone: neutral 2–4; title 1–200, badge ≤ 40
rows { label, cells }[] — 1–16; label 1–200; cells 2–4 texts ≤ 600; one cell per column
verdict text — ≤ 800

# accordion

Field Type Default Constraints
items { title, text }[] — 1–12; title 1–200, text 1–4 000

# quiz

Field Type Default Constraints
question text — 1–600
choices { text, correct, explanation? }[] — 2–6; text 1–400, explanation ≤ 600; at least one correct choice

# simulation

Field Type Default Constraints
kind simulation kind — see the catalogue in §9
title text — ≤ 200
caption text — ≤ 400
params { [key]: number } {} keys ^[a-zA-Z][a-zA-Z0-9]{0,23}$; finite numbers
seed integer 1 0…2³¹−1
config { [key]: string | number | boolean } {} same key pattern; strings ≤ 300

The schema accepts any key; validateSimulation (src/sim/registry.ts) checks keys and bounds against the kind, and the quality report turns each problem into a blocking error — including a value outside its bounds, even though the renderer would clamp it.

# references

Field Type Default Constraints
title text — ≤ 200

Renders the document's sources, numbered in array order.

# divider

No specific field.

# tabs

Field Type Default Constraints
tabs { id, label, blocks }[] — 2–6 tabs; label 1–60; blocks 1–12

A tab holds any block type except tabs (tabs do not nest). Blocks inside tabs count for id uniqueness and can be addressed by patches.

# 5. Sources, claims, assets

# Source

Field Type Default Constraints
id Id — cited as [^id]
type article | book | preprint | documentation | dataset | web | report | upload —
title text — 1–400
authors text[] [] ≤ 30, each ≤ 120
year integer — 1500–2100
container text — ≤ 300 (journal, publisher)
doi string — ^10\.\d{4,9}/\S+$, ≤ 200
url URL — https or mailto
license text — ≤ 120
note text — ≤ 600
status see below unverified
checkedAt ISO date-time —

Statuses:

Status Meaning Set by
unverified written by the model or typed by hand, never checked default; forced on everything the model writes
resolved the server fetched the DOI or URL and the record exists (title matched for DOIs) the source check job
reviewed the administrator confirmed the reference the sources panel
unreachable the server tried and could not reach it the source check job

# Claim

Field Type Default Constraints
id Id —
text text — 1–600
status sourced | derived | unverified — derived = follows from sourced material by an argument given in the sheet
sourceIds Id[] [] ≤ 12
blockId Id — the block that makes the claim

A sourced claim without a source is a blocking quality error; an unverified claim is a warning.

# AssetRef

Field Type Default Constraints
id Id — local id used by assetRef / datasetRef
kind image | dataset —
assetId UUID — row of the assets table
alt text "" ≤ 400
credit text — ≤ 300

Assets are references, not content: an exported JSON does not carry the files, and importing a JSON removes image blocks, removes datasetRef from charts (their points stay) and empties assets.

# 6. Patch operations

Structured changes addressed by id (PatchOpSchema, applyPatch). They are how the AI edits an existing sheet; a patch holds at most 120 operations.

op Fields Rules
replace_block id, block the block keeps id; refused if unknown or locked; a tab child cannot become tabs
insert_block block, afterId (null = top), tabId? block.id must be new; afterId must be in the target list; no tabs inside a tab
remove_block id refused if unknown or locked
move_block id, afterId (null = top) top-level blocks only; refused if locked
set_metadata metadata (partial, without author) merged into the metadata
set_theme preset?, accent?, format?
upsert_source source replaces by id or appends
remove_source id also removes the id from block sourceIds and claim sourceIds
set_claims claims replaces the list

applyPatch works on a copy, throws PatchError (with the index of the failing operation) on the first bad operation, and re-validates the result with SheetSchema. Locks are honoured unless respectLocks: false is passed. A block is protected when it is locked itself, or when it is a tabs block that contains a locked child (so a locked child cannot be removed by replacing its tab group). A locked tabs block does not lock its children one by one.

diffSheets(a, b) returns { added, removed, changed, moved, metadata, theme, sources, claims } — block ids for the first four, changed metadata keys, and booleans — for the revision history and the Claude panel.

# 7. Versioning and migrations

  • SCHEMA_VERSION is 1. Every stored document carries schemaVersion.
  • parseSheet(raw) is the only way a document enters the system: migrateSheet then SheetSchema.safeParse. mustParseSheet throws instead of returning issues.
  • migrateSheet upgrades one step at a time through MIGRATIONS. The only step is 0 → 1: documents without a version (pre-release drafts) kept claims under evidence; the step renames it to claims and sets the version.
  • A document whose version is newer than the server's is refused.
  • Stored documents are never rewritten by a migration: revisions and publications are migrated when read. When SCHEMA_VERSION is bumped, add the step to MIGRATIONS in src/schema/index.ts.
  • stableStringify serialises with sorted keys; sheet_revisions.doc_hash is the SHA-256 of that string, which is how an unchanged save is detected.

Helpers in the same module: allBlocks, findBlock, blockText, sheetText, readingMinutes (220 words a minute plus half a minute per visual, interactive or equation block, at least 1), tableOfContents, slugify, emptySheet, newId.

# 8. A complete example

This document was passed through parseSheet with node_modules/.bin/tsx when this file was written; it validates, and the quality report finds no blocking error (one warning: the source is unverified).

json
{
  "schemaVersion": 1,
  "metadata": {
    "title": "Ordinary least squares in one page",
    "locale": "en",
    "summary": "What the OLS estimator minimises, and how noise changes the fitted line.",
    "topics": ["Econometrics"],
    "tags": ["regression", "ols"],
    "level": "beginner",
    "kind": "explainer",
    "objectives": ["State the OLS criterion", "Read a fitted line and its confidence band"]
  },
  "theme": { "preset": "scientific-light", "accent": "teal" },
  "layout": { "format": "article" },
  "blocks": [
    { "id": "title", "type": "heading", "level": 1, "eyebrow": "Econometrics", "text": "Ordinary least squares" },
    { "id": "intro", "type": "paragraph", "lead": true, "text": "OLS picks the line that makes the **sum of squared residuals** as small as possible[^s-gauss1809]." },
    { "id": "eq-ols", "type": "equation", "span": 6,
      "latex": "\\hat{\\beta} = \\arg\\min_{\\beta} \\sum_{i=1}^{n} (y_i - x_i^\\top \\beta)^2",
      "variables": [
        { "symbol": "y_i", "meaning": "Observed outcome of unit $i$" },
        { "symbol": "x_i", "meaning": "Vector of regressors of unit $i$" },
        { "symbol": "\\beta", "meaning": "Coefficients" }
      ],
      "derivation": "standard" },
    { "id": "d-flow", "type": "diagram", "span": 6, "direction": "LR",
      "alt": "Data go into the least-squares criterion, which returns the estimated coefficients.",
      "nodes": [
        { "id": "n-data", "label": "Data", "sublabel": "(x, y)", "tone": "blue", "icon": "database" },
        { "id": "n-criterion", "label": "Squared residuals", "tone": "neutral" },
        { "id": "n-beta", "label": "Estimate", "tone": "teal", "shape": "pill" }
      ],
      "edges": [
        { "id": "e-1", "from": "n-data", "to": "n-criterion", "label": "fit" },
        { "id": "e-2", "from": "n-criterion", "to": "n-beta", "label": "minimise" }
      ] },
    { "id": "sim-ols", "type": "simulation", "kind": "regression", "seed": 7,
      "params": { "slope": 1.5, "sigma": 2, "n": 40 },
      "alt": "Scatter of simulated points with the fitted line and its 95 % confidence band." },
    { "id": "quiz-1", "type": "quiz", "question": "What does OLS minimise?",
      "choices": [
        { "text": "The sum of squared residuals", "correct": true },
        { "text": "The sum of absolute residuals", "correct": false, "explanation": "That is least absolute deviations." }
      ] },
    { "id": "refs", "type": "references" }
  ],
  "sources": [
    { "id": "s-gauss1809", "type": "book", "title": "Theoria motus corporum coelestium in sectionibus conicis solem ambientium", "authors": ["Carl Friedrich Gauss"], "year": 1809 }
  ],
  "claims": [
    { "id": "c-1", "text": "OLS minimises the sum of squared residuals.", "status": "sourced", "sourceIds": ["s-gauss1809"], "blockId": "intro" }
  ]
}

To check a document of your own from the project root:

bash
cat > /tmp/check.mts <<'EOF'
import { readFileSync } from "node:fs";
const { parseSheet } = await import(process.cwd() + "/src/schema/index.ts");
const r = parseSheet(JSON.parse(readFileSync(process.argv[2], "utf8")));
console.log(r.ok ? "valid" : r.issues);
EOF
node_modules/.bin/tsx /tmp/check.mts my-sheet.json

In the studio, POST /api/admin/validate does the same and the dashboard's "Import a JSON" dialog uses it.

# 9. Simulation catalogue

Thirteen pre-approved kinds (src/sim/registry.ts; details and formulas in src/sim/README.md). A document picks a kind and gives numbers; it never supplies code. Every number shown comes from a pure compute(params, seed, config); the same inputs draw the same picture. Values are clamped to their bounds and rounded to the slider step when rendered.

Config keys accepted by every kind: autoplay (boolean; animated kinds play once when first visible, never under reduced motion) and locale (set by the block itself).

Parameters are written key (min … max, step, default).

Kind Random Animated Parameters Config
moe-routing yes one frame per token experts (2…8, 1, 6), topK (1…8, 1, 2; capped at experts), tokens (4…12, 1, 8), temperature (0.1…3, 0.1, 1) —
neural-forward yes one frame per layer layers (2…4, 1, 2), width (2…6, 1, 4), inputs (2…4, 1, 3), scale (0.2…3, 0.1, 1.5) activation: tanh | relu | sigmoid
kv-cache no one frame per generated token prompt (1…8, 1, 4), newTokens (2…16, 1, 8), layers (1…12, 1, 4) —
attention yes no temperature (0.1…5, 0.1, 1), dim (4…32, 4, 16), locality (0…3, 0.1, 0) tokens (comma-separated, 2–10), causal (boolean)
distribution no no depends on family — normal: mu (−3…3, 0.1, 0), sigma (0.3…3, 0.1, 1), a, b (−8…8, 0.1, −1/1); student: df (1…30, 1, 4), a, b (−8…8, 0.1, −2/2); lognormal: mu (−1…1.5, 0.1, 0.5), sigma (0.1…1.5, 0.05, 0.5), a, b (0…10, 0.1, 1/3); exponential: lambda (0.2…5, 0.1, 1), a, b (0…10, 0.1, 0/1); uniform: low (−5…3, 0.1, 0), width (0.5…5, 0.1, 2), a, b (−6…9, 0.1, 0.5/1.5) family: normal | student | lognormal | exponential | uniform
confidence-interval yes no n (2…200, 1, 20), m (10…100, 5, 50), level (0.5…0.99, 0.01, 0.95), mu (−5…5, 0.5, 0), sigma (0.5…5, 0.5, 1) —
regression yes no slope (−3…3, 0.1, 1.5), intercept (−5…5, 0.5, 1), sigma (0…6, 0.1, 2), n (5…200, 1, 40) —
correlation yes no rho (−0.99…0.99, 0.01, 0.6), n (10…500, 10, 150) —
garch yes no omega (0.01…1, 0.01, 0.05), alpha (0…0.5, 0.01, 0.1), beta (0…0.99, 0.01, 0.85), n (100…600, 50, 400) —
random-walk yes no drift, volatility (bounds depend on process), paths (1…20, 1, 8), horizon (1…20, 1, 5), and for ou reversion (0.1…5, 0.1, 1) process: brownian | gbm | ou; x0 (number)
impulse-response no no a11 (0.6), a12 (0.2), a21 (0.3), a22 (0.5), each −1.2…1.2 step 0.05; horizon (5…40, 1, 20) shock: 1 or 2
event-study yes no jump (−5…5, 0.1, 2), drift (−0.5…0.5, 0.01, 0.1), sigma (0.5…5, 0.1, 2), events (5…200, 5, 50) window (integer 3…20, default 10)
function-plot no no one slider per name other than x found in the expressions (at most 5), default 1 expr (required), expr2…expr4, label, label2…label4, xMin, xMax, yMin, yMax, xLabel, yLabel, and per parameter <name>Min, <name>Max, <name>Step

random-walk bounds by process — brownian: drift (−2…2, 0.1, 0.5), volatility (0.1…3, 0.1, 1); gbm: drift (−0.3…0.5, 0.01, 0.08), volatility (0.05…0.8, 0.01, 0.2); ou: drift = long-run level (−2…2, 0.1, 0), volatility (0.1…2, 0.1, 0.5).

function-plot expression grammar: numbers, x, names, + - * / ^ (^ right-associative; -x^2 is -(x^2)), parentheses, constants pi and e, functions exp log ln log10 sqrt abs sin cos tan tanh sigmoid relu max min pow floor (log is natural). At most 300 characters and 32 nesting levels. The parser is a tokeniser and recursive descent in src/sim/core/expr.ts; there is no eval.

In print mode (PDF/PNG export) a simulation is drawn in its initial state.

Files main
Menu

Theme