# PivoGraph project file format (`.pivograph`) - schema version 1

Status: schema version 1 is the first public version, introduced in PivoGraph 1.3. PivoGraph's compatibility policy is to keep published older versions openable through the built-in migration chain (see "Versioning").

This document describes the file that PivoGraph writes with **File -> Save Project...** and reads with **File -> Open Project...** or by drag-and-drop. It also defines how external tools and AI agents can create projects that open for further editing in PivoGraph.

- Machine-readable schema (JSON Schema draft-07): `https://pivograph.com/schemas/project/v1.json`
- Version catalog: `https://pivograph.com/schemas/project/index.json`
- Examples, one per table family: `https://pivograph.com/schemas/project/v1/examples/`
- This page as Markdown: `https://pivograph.com/developers/project-format/v1.md`

The JSON Schema is generated from the same validator the application uses, so it is authoritative for field names, enumerations and limits. This page explains the semantics that a schema cannot express.

## 1. File basics

- Plain **UTF-8 JSON**, no byte-order mark (a leading BOM is tolerated when reading). Extension `.pivograph`; MIME type `application/json`. Where a tool needs the JSON language recognised from the file name, `.pivograph.json` is also accepted when opening.
- The whole document is one JSON object. **Unknown keys are rejected** at every level with the JSON path of the offending key. Tool-specific data belongs in `usermeta` (document level or per table).
- Everything in the file is data. There is no executable content, no external references are fetched when a file is opened, and the application never downloads the `$schema` URL.
- **Write complete, read tolerant.** PivoGraph writes resolved document state explicitly so that saved settings do not silently inherit future defaults. Hand-written or generated documents may omit any optional field - and may give any nested object *partially*; the application fills its current defaults. Optional fields are expressed by **omitting the key**; `null` is only valid where the field's type includes it (missing cells, unmapped variable roles, automatic geometry).
- Opening reports two kinds of problems: **errors** (the file is not opened; the current project is untouched) and **warnings** (the file opens, but the listed parts were ignored or replaced by defaults, for example a style override keyed to a data set that does not exist). Both carry JSON paths.

## 2. Envelope

```json
{
  "$schema": "https://pivograph.com/schemas/project/v1.json",
  "format": "pivograph-project",
  "schemaVersion": 1,
  "generator": { "name": "PivoGraph", "version": "1.3.0", "url": "https://pivograph.com" },
  "createdAt": "2026-09-06T10:00:00.000Z",
  "modifiedAt": "2026-09-06T12:00:00.000Z",
  "meta": { "title": "Dose response" },
  "usermeta": {},
  "view": { "activeTableId": "dose", "workspaceView": "graph" },
  "tables": []
}
```

- `format` (required): always `"pivograph-project"`. Together with `schemaVersion` this is how a reader recognises the file; `$schema` is informational.
- `schemaVersion` (required): integer. See "Versioning".
- `tables` (required): array of tables in sidebar order (maximum 200). A minimal valid document is exactly `format` + `schemaVersion` + `tables`.
- `generator` (optional): the program that wrote the file (`name`, `version`, optional `url`). Purely informational; PivoGraph always writes it.
- `createdAt` / `modifiedAt` (optional): ISO 8601 timestamps with timezone. PivoGraph keeps `createdAt` from the first save and rewrites `modifiedAt`.
- `meta` (optional): `title` (required inside `meta`, may be empty), optional `description`, `authors[]`, `license`, `source`, `keywords[]`. `license` and `source` are meant for example / template projects.
- `usermeta` (optional): a JSON object for tool-specific data. Its JSON value is preserved across save and reopen, never interpreted, and limited to 64 KB when serialised; whitespace and object formatting are not preserved.
- `view` (optional): which table is active (`activeTableId`, must be an explicit table id) and whether the editor opens in `"table"` or `"graph"` view. This is the only presentation state in the file.

## 3. Tables

Each table is one data table of one of the eight families:

`xy`, `column`, `grouped`, `nested`, `contingency`, `survival`, `partsOfWhole`, `multipleVariables`.

```json
{
  "id": "dose",
  "name": "Dose response",
  "format": "xy",
  "replicates": 3,
  "x": [-9, -8, -7],
  "rowLabels": ["low", "mid", "high"],
  "dataSets": [
    { "name": "Control", "values": [[1.1, 1.2, null], [2.0, 2.1, 1.9], [5.0, 4.8, 5.1]] },
    { "name": "Treated", "values": [[0.9, 1.0, 1.1], [1.5, 1.6, 1.4], [2.9, 3.1, 3.0]] }
  ],
  "graph": { "variantId": "xy-points-error" },
  "analyses": [],
  "annotations": [],
  "titles": {},
  "usermeta": {}
}
```

- `format` (required): the family.
- `dataSets` (required unless `derivedFrom` is present; at least one): one entry per data set, corresponding to the table's data columns. `values[row][replicate]` holds finite numbers, `null` for missing, or text. Rows may be shorter than `replicates` (missing cells are filled with `null`). Data set names must be unique within a table.
  - Text is accepted only in `multipleVariables` tables (text categories and labels). In every other family a text cell is an error, except that numeric-looking strings such as `"1.5"` are read as numbers.
- `id` (optional): any non-empty string (<= 128 characters), unique among tables; generated when omitted. Tables referenced by `derivedFrom` or `view.activeTableId` need an explicit id. Human-readable slugs are fine.
- `name` (optional): defaults to `Table N`.
- `replicates` (optional): number of sub-columns per data set. Fixed at 1 for `column`, `contingency`, `survival`, `partsOfWhole` and `multipleVariables`; >= 2 for `nested`; free for `xy` and `grouped`. When omitted it is inferred from the widest row (never below the family minimum).
- `x`: only for `xy` and `survival` - the shared X column, one entry per row, aligned with `values`. In survival tables X is time and the cells are event codes (1 = event, 0 = censored).
- `rowLabels`: optional row titles (categories for `grouped` / `contingency` / `partsOfWhole`, sample names for heat maps).
- `variableTypes`: `multipleVariables` only - explicit overrides of the inferred variable type (`continuous`, `categorical`, `label`) keyed by variable (data set) name.
- `columnWidths`: optional spreadsheet column widths; presentation only.
- `usermeta`: optional tool-specific data for this table; same rules as the document-level slot.
- `derivedFrom`: marks a **results table** produced by an analysis on another table: `{ "sourceTableId", "analysisId" }`. Such tables carry no `dataSets`, `x`, `rowLabels` or `variableTypes`; their content is recomputed when the file opens. The referenced analysis must exist on the source table (with an explicit id) and must be one that produces a results table (`frequencyDistribution`, `correlationMatrix`).
- Row count is the longest of `x`, `rowLabels` and any `values`; trailing empty rows are not stored.

## 4. Graph

`graph` is the graph document of the table (one graph per table). Only `variantId` is required; every other field, and every nested object inside them, may be given partially.

- `variantId`: a graph variant from the PivoGraph registry, for example `bar`, `column-box-whiskers`, `xy-points-line-error`, `grouped-heat-map`, `survival-staircase-ticks`, `parts-donut`, `mv-volcano`. The full list is the `GraphVariantId` definition in the JSON Schema. The variant must belong to the table's family and be available for the table's replicate count (for example `xy-points-error` needs `replicates > 1`).
- `plot`: statistical / topology options of the family (`{ "family": "...", "options": {...} }`); `family` must equal the table format. Options are merged over the defaults of the variant; a `mode` that the variant does not offer is replaced by the variant default with a warning. For `multipleVariables` tables `plot` is **required** because it carries the variable mapping: `plot.options.kind` must match the variant (`bubble` -> `mv-bubble`, `scatter` -> `mv-scatter`, `volcano` -> `mv-volcano`, `forest` -> `mv-forest`) and `plot.options.mapping` gives data set indexes per role (`x` required; `y`, `size`, `color`, `shape`, `label`, `lower`, `upper` as the plot kind requires; omitted roles are unmapped).
- `activePresetId`: built-in theme preset (`modern`, `classic`, `floral`, `starry`). `applyPresetNonColor`: whether the preset's non-colour constants are applied.
- `styleOverrides`: user overrides on top of the theme, in three layers - `global`, `perDataSet` (keyed by data set **name**, or a semantic key such as `volcano:up`) and `perPoint` (data set name -> point index). Each layer is a partial patch per element kind (`bar`, `symbol`, `errorBar`, `line`, ...). Colours are either `"theme"` (follow the preset) or `{ "hex": "#rrggbb", "alpha": 0.8 }`; hex colours have 3 or 6 digits and transparency always goes in `alpha`.
- `graphSettingsOverride`: partial graph settings (bar width, gaps, baseline, line of identity, ...).
- `axesOverrides`: six partial buckets (`frameAndOrigin`, `xCategorical`, `xContinuous`, `leftY`, `rightY`, `titlesAndFonts`); `"auto"` means automatic where a number is otherwise expected. Nested objects (grid lines, tick appearance, number format, title font) may be partial. Title *text* is not part of the axes - see `titles`.
- `plotGeometry`: plot-area size in points (`null` or omitted = automatic).
- `dataSetVisibility`: data set **index** (as a string key) -> `false` to hide; missing = visible.
- `elementActivation`: optional-element switches in three scopes (`global`, `perDataSet` by index, `graph`).
- `legend`: legend configuration including `itemOverrides` keyed by data set index or semantic id.
- `partsOfWholeBorders`: outer / inner border of pie, donut and slice graphs.

Keys that refer to data sets by name and keys that refer to them by index coexist in version 1 (they mirror the application's model). Keys that match no data set are ignored with a warning. A future schema version may unify them; documents will be migrated automatically.

## 5. Analyses

`analyses` is a list of analysis instances attached to the table: `{ "id", "method", "params" }`. `id` is optional (generated when omitted; required when a results table refers to it) and `params` may be partial (method defaults fill the rest). Results are not stored; they are recomputed from the data and the parameters.

- `ttest` (column, xy): `{ "groupA": "name" | null, "groupB": "name" | null, "design": "unpaired" | "paired", "variance": "welch" | "equal" }`. Group names refer to data set names; `null` uses the first two populated data sets.
- `linearRegression` (xy): `{ "confidenceLevel": 90 | 95 | 99 }`.
- `nonlinearRegression` (xy, four-parameter logistic): `{ "model": "logX" | "linearX" }`.
- `frequencyDistribution` (column): `{ "binWidth": number | null, "binStart": number | null, "output": "count" | "fraction" | "percent", "cumulative": boolean }`. Produces a results table (`grouped`).
- `correlationMatrix` (multipleVariables): `{ "method": "pearson" | "spearman" }`. Produces a results table (`grouped`) rendered as a heat map.

A method must be available for the table's family. Explicit analysis ids must be unique within their table.

## 6. Annotations and titles

`annotations` holds drawing objects placed on the graph, discriminated by `type` (`id` optional, generated when omitted):

- `bracket`: significance bracket. `left` / `right` anchors are `{ "kind": "group", "groupIndex": n }` (snapped to the n-th plotted data set) or `{ "kind": "free", "x": pt }`; `y` is the bar position, `text` the label (`"*"`, `"ns"`, ...).
- `text`: free text at `x`, `y` (points). `text` may contain `\n` and `^{...}` / `_{...}` for super- and subscripts.
- `shape`: lines, arrows, rectangles, ellipses, brackets, ... (`shape` enum), with two or three control points and optional bound text.

`titles` overrides the graph, X and Y titles (`graph`, `x`, `y`): text, drag offset (`dx`, `dy`), font and colour. This is the only place where title text lives.

## 7. Versioning and compatibility

- `schemaVersion` is an integer. Every change to the document structure or to rendering-relevant defaults increases it by one and ships with a migration step. Migrations run once, at open time, before validation.
- A reader opens every version from 1 up to its own. Older files are migrated in memory; the original file is never rewritten.
- A file with a **newer** `schemaVersion` than the reader supports is refused with an explicit message (in the web application: reload the page to get the latest version). Nothing is guessed or silently dropped.
- Registry identifiers (variants, presets, methods, symbols, colormaps) are part of the format contract. Deprecated identifiers are handled by migrations, not by aliases.
- Every version has exactly one JSON Schema (`/schemas/project/v<N>.json`, immutable), one specification page (`/developers/project-format/v<N>/`, plus the Markdown copy `v<N>.md`) and one set of examples (`/schemas/project/v<N>/examples/`). `/schemas/project/index.json` lists all versions and which one is current. There is deliberately no "latest" schema URL: a file's `$schema` must stay stable.
- Fixtures of every published version are kept in the repository and tested on every build.

## 8. Limits

Files larger than 50 MB, more than 200 tables, more than 2,000,000 cells in total, more than 200,000 rows or 500 data sets per table, more than 2,000 annotations or 200 analyses per table, non-finite numbers, over-long strings, or record keys named `__proto__`, `constructor` or `prototype` are rejected. Exact values are in the JSON Schema.

## 9. Validation

Opening a file goes through: size limit -> strict UTF-8 -> JSON parse -> envelope (`format`, `schemaVersion`) -> version gate -> forbidden-key scan -> migration -> strict structural validation (JSON Schema equivalent) -> semantic validation -> import. Semantic errors include: duplicate ids, dangling `derivedFrom` or `view.activeTableId` references, replicate counts invalid for the family, variant / plot family not matching the table, variant unavailable for the replicate count, incomplete variable mapping, analysis methods unavailable for the family, text cells outside `multipleVariables`, rows wider than `replicates`, total cell count. Semantic warnings include: style / visibility / legend keys that match no data set, and plot modes the variant does not offer.

All problems are reported together with JSON paths (for example `tables[0].graph.variantId`). If any error occurs, the current project in the editor is left untouched.

## 10. Minimal example

```json
{
  "format": "pivograph-project",
  "schemaVersion": 1,
  "tables": [
    {
      "name": "Cell viability",
      "format": "column",
      "dataSets": [
        { "name": "Vehicle", "values": [[98], [102], [95]] },
        { "name": "Compound", "values": [[71], [68], [74]] }
      ],
      "graph": { "variantId": "scatter-bar", "plot": { "family": "column", "options": { "mode": "meanWithSd" } } }
    }
  ]
}
```

More examples, one per table family, are published at `https://pivograph.com/schemas/project/v1/examples/`; `representative.pivograph` there is a complete document written by PivoGraph itself.

## 11. For AI assistants

PivoGraph's Help menu offers **Copy Prompt for AI Assistants...**: a prompt generated from the running version that lists every family, variant id, analysis method, the main format rules, and a minimal example. Give that prompt to an AI assistant, describe the data and intended figure, save the returned JSON as `.pivograph`, and open it in PivoGraph. Treat generated projects as drafts: verify the source values, analysis choices, and graph before using the result. Agents can also use this page, its Markdown copy, `llms.txt` at the site root, the JSON Schema, and the examples.

## Changelog

- **v1** - first public version (PivoGraph 1.3).