The .leancanvas file format

Top-level structure

Every .leancanvas file is an object with these fields:

{
  "$schema": "https://leancanvas.online/file-format/schema.json",
  "_viewer": "https://leancanvas.online/viewer",
  "schema": "totally-lean/canvas-export@1",
  "exportedAt": 1714334400000,
  "canvas": { /* LeanCanvas */ },
  "agentHistories": { /* optional, per-agent */ }
}

• $schema — points at this schema for editor / agent autocomplete. Optional but recommended.
• _viewer — discoverability hint for users without our app installed. Underscore prefix is the convention for fields that tooling should ignore.
• schema — version identifier. Bumps on incompatible shape changes. Currently totally-lean/canvas-export@1.
• exportedAt — ms since epoch when the bundle was written.
• canvas — the LeanCanvas itself; see below.
• agentHistories — optional. Per-agent conversation history. Sessions with no exchanges are omitted; whole field absent if no recorded conversations.

The LeanCanvas object

Required fields: id, name, createdAt, updatedAt, sections. The nine sections are the standard Lean Canvas (Ash Maurya), each an array of CanvasItem:

"sections": {
  "problem":               [ ...CanvasItem ],
  "solution":              [ ...CanvasItem ],
  "uniqueValueProposition":[ ...CanvasItem ],
  "channels":              [ ...CanvasItem ],
  "customerSegments":      [ ...CanvasItem ],
  "unfairAdvantage":       [ ...CanvasItem ],
  "keyMetrics":            [ ...CanvasItem ],
  "costStructure":         [ ...CanvasItem ],
  "revenueStreams":        [ ...CanvasItem ]
}

Optional fields: threads (cross-cutting groupings), links (item-to-item directional links), themeId, themeMode, pitch (cached AI-generated pitch text), and per-section layout (sectionHeights, sectionWidths, sectionPositions) for the canvas planning board.

CanvasItem (the sticky note)

{
  "id": "p1",
  "title": "Hotels are expensive",
  "description": "Budget travelers find hotels…",
  "color": "rose",
  "threadIds": ["thread-budget"],
  "validation": "validated",
  "weight": 50000000,
  "unit": "users"
}

• color — one of: amber, rose, sky, lime, violet, orange
• threadIds — references Thread.id values. Multi-thread.
• validation — one of: validated, assumption, invalidated. Treat absent as "not yet evaluated."
• weight + unit — for Sankey flow scaling (e.g. revenue size in dollars). Unitless number + free-form unit string.
• threadId (singular) is deprecated; readers should accept it for backward compatibility, writers should emit threadIds.

Writing files from an AI agent

Three guarantees the format provides for agentic workflows:

1. 01

   Validate before writing

   Fetch the JSON Schema, validate the bundle, surface schema errors before persisting. Most JSON Schema libraries (ajv, zod via json-schema-to-ts, etc.) can drive this directly.

2. 02

   Stable schema versioning

   Major shape changes bump the schema field (currently @1). Additive changes — new optional fields — do not. Reject bundles whose schema value you don’t recognise rather than guessing.

3. 03

   Round-trip safety

   Any bundle produced by Totally Lean must parse and re-export identically. Agents writing bundles should preserve unknown fields they don’t understand — the format reserves the right to add fields without breaking your reader.

See also

• Open a .leancanvas file in the browser viewer — drop a file, see the canvas, edit a copy.
• Create a new Lean Canvas — overview of the framework.
• MCP (Model Context Protocol) integration — agents can connect to a running desktop app and drive canvas operations via typed tools. Coming with the next desktop release.