Obsidian Canvas Architect

Status: Active
Author: Richard Fremmerlid
Domain: Obsidian Integration
Depends On: obsidian-vault-crud (WP06)

Purpose

Obsidian Canvas files (.canvas) use the JSON Canvas Spec 1.0 to define visual
boards with nodes (text, file references, URLs) connected by directional edges.
This skill lets agents programmatically generate visual planning boards, architecture
diagrams, and execution flowcharts.

JSON Canvas Spec 1.0 Overview

A .canvas file is JSON with two top-level arrays:

{
  "nodes": [
    {"id": "1", "type": "text", "text": "Hello", "x": 0, "y": 0, "width": 250, "height": 60},
    {"id": "2", "type": "file", "file": "path/to/note.md", "x": 300, "y": 0, "width": 250, "height": 60}
  ],
  "edges": [
    {"id": "e1", "fromNode": "1", "toNode": "2", "fromSide": "right", "toSide": "left"}
  ]
}

Node Types

Type	Required Fields	Purpose
text	text, x, y, width, height	Inline text content
file	file, x, y, width, height	Reference to a vault note
link	url, x, y, width, height	External URL
group	label, x, y, width, height	Visual grouping container

Edge Properties

Field	Required	Description
fromNode	Yes	Source node ID
toNode	Yes	Target node ID
fromSide	No	top, right, bottom, left
toSide	No	top, right, bottom, left
label	No	Edge label text

Available Commands

Create a Canvas

python plugins/obsidian-integration/skills/obsidian-canvas-architect/scripts/canvas_ops.py create --file <path.canvas>

Add a Node

python plugins/obsidian-integration/skills/obsidian-canvas-architect/scripts/canvas_ops.py add-node \
  --file <path.canvas> --type text --text "My Node" --x 100 --y 200

Add an Edge

python plugins/obsidian-integration/skills/obsidian-canvas-architect/scripts/canvas_ops.py add-edge \
  --file <path.canvas> --from-node id1 --to-node id2

Read a Canvas

python plugins/obsidian-integration/skills/obsidian-canvas-architect/scripts/canvas_ops.py read --file <path.canvas>

Safety Guarantees

• All writes go through obsidian-vault-crud atomic write protocol
• Malformed JSON triggers a clean error report, never a crash
• Node IDs are auto-generated (UUID) to prevent collisions
• Schema validation ensures all required fields are present before write