Project file format

Save and reopen PivoGraph projects

A .pivograph file saves the tables, analyses, graph settings, titles, and annotations in your project. Open it later to continue editing, keep it with a manuscript, or send it to a collaborator for review.

Read specification v3 Open PivoGraph

Complete projectTables, analyses, and graph settings together
Saved locallyResearch data stays on your device
Schema version 3Current since PivoGraph 1.7; version 1 and 2 files still open

Documentation

Specification, schema, and examples

Use the specification for field semantics and compatibility rules, the JSON Schema for validation, and the example projects as working references.

Specification

Specification v3

File semantics, what changed since v2, compatibility rules, limits, and validation behavior.

Read the HTML specification JSON Schema

JSON Schema v3

Authoritative field names, types, enumerations, and structural limits.

Open the draft-07 schema Examples

Example projects

Minimal files for every table family and one complete project written by PivoGraph.

Open the representative example Markdown

Markdown specification

The same v3 specification in a compact text-first form. The site index is also available as llms.txt.

Read the Markdown version

Browse all schema v3 examples

Column XY Grouped Heat map Nested Contingency Survival Parts of whole Multiple variables Complete representative project Machine-readable list (index.json)

AI assistants

Create a PivoGraph project with AI

PivoGraph includes a format prompt for asking an AI assistant to create a project file from your data and figure requirements.

Copy the format promptIn PivoGraph, choose Help → Copy Prompt for AI Assistants…. The prompt matches the running version.
Describe the data and figureAsk an AI assistant to return only a .pivograph JSON document. For automation, provide the schema and a close example.
Open, verify, and refineSave the response as .pivograph and drop it into PivoGraph. The application validates it before replacing the current project.

Building an integration? Start with the Markdown specification, use the JSON Schema for exact fields, and consult the closest example. Unknown keys are rejected with their JSON path.

Compatibility and safety

How PivoGraph handles project files

Files save explicit settings

PivoGraph writes resolved project state explicitly. Generated files may omit optional fields or provide partial settings; current defaults fill the gaps.

Older schemas are migrated

Structural and rendering-default changes require a new integer schemaVersion and a migration. Older files are migrated in memory; the source file is not rewritten.

Projects contain no executable code

A project contains data, not executable code. Opening it does not fetch external references, including the optional $schema URL.

Errors do not replace the open project

Invalid fields are reported with JSON paths and do not replace the open project. Recoverable mismatches open with explicit warnings.

Current version

Schema version 3

Current Introduced in PivoGraph 1.7.

HTML specification Markdown JSON Schema Examples

Version 3 adds spike width in points with the same baseline settings as bar graphs; area fill down to the X axis; optional symbols and lines on spike graphs, mean bars on before–after graphs and individual points on floating bars; censor tick marks, two-sided error bars and new default axes for survival curves; minor ticks on continuous axes; the drawn size of pie, donut, slices and dot plot graphs; and the analyses one-way ANOVA, descriptive statistics, nonparametric t-tests, area under the curve and XY correlation. The specification lists every change and how version 2 files are migrated.

PivoGraph's compatibility policy is to keep published older versions openable through migrations. Each schema version has immutable specification, schema, and example URLs. Files should point $schema to a versioned URL; there is intentionally no latest alias. Tools can discover the current version through the version catalog.

Previous version

Schema version 2

Superseded Introduced in PivoGraph 1.6. Files open in PivoGraph and are migrated to version 3 automatically.

HTML specification Markdown JSON Schema Examples

Version 2 added rich text with per-run bold, italic, superscript and subscript; title rotation in degrees; line spacing; exploded pie and donut slices; fitted-curve draw order; error bars on stacked bars; full formatting for significance brackets; summary symbols on scatter plots; more heat-map colour scales; edge spacing as a clear distance; before–after layouts and per-row t-tests on grouped tables. The specification lists every change and how version 1 files are migrated.

Previous version

Schema version 1

Superseded Introduced in PivoGraph 1.3. Files open in PivoGraph and are migrated to version 3 automatically.

HTML specification Markdown JSON Schema Examples

Editor integration

Validate while authoring

Associate *.pivograph or *.pivograph.json with https://pivograph.com/schemas/project/v3.json, or include that URL in the document's $schema field. The version catalog is the machine-readable source for all published versions.