PivoGraph

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 v1 Open PivoGraph
  • Complete projectTables, analyses, and graph settings together
  • Saved locallyResearch data stays on your device
  • Schema version 1Included with PivoGraph 1.3

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 v1

File semantics, compatibility rules, limits, and validation behavior.

Read the HTML specification JSON Schema

JSON Schema v1

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 v1 specification in a compact text-first form. The site index is also available as llms.txt.

Read the Markdown version
Browse all schema v1 examples
Column XY Grouped Heat map Nested Contingency Survival Parts of whole Multiple variables Complete representative project

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.

  1. Copy the format promptIn PivoGraph, choose Help → Copy Prompt for AI Assistants…. The prompt matches the running version.
  2. Describe the data and figureAsk an AI assistant to return only a .pivograph JSON document. For automation, provide the schema and a close example.
  3. 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 1

Current Introduced in PivoGraph 1.3.

HTML specification Markdown JSON Schema

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.

Editor integration

Validate while authoring

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