C+

JSON Canvas Skill

Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. Use when working with .canvas files, creating visual canvases, mind maps, flowcharts, or when the user mentions Canvas files in Obsidian.

npx skills add github:pantheon-org/tekhne --skill documentation--obsidian--json-canvas

Mindset

JSON Canvas is a minimal open standard: nodes positioned on an infinite grid, connected by edges. The entire spec fits in two arrays. Design with this simplicity in mind — when a layout feels complex, it is usually a positioning or ID-management problem, not a schema problem.

When to apply: Creating or editing .canvas files, building visual mind maps or flowcharts in Obsidian, or generating canvas files programmatically. When NOT to apply: The user wants a Markdown note, a database view (use Bases), or a diagram format that outputs to image/PDF — JSON Canvas is a live interactive format, not a rendering target.

File Structure

A canvas file (.canvas) contains two top-level arrays following the JSON Canvas Spec 1.0:

{
  "nodes": [],
  "edges": []
}

nodes (optional): Array of node objects
edges (optional): Array of edge objects connecting nodes

Common Workflows

1. Create a New Canvas

Create a .canvas file with the base structure {"nodes": [], "edges": []}
Generate unique 16-character hex IDs for each node (e.g., "6f0ad84f44ce9c17")
Add nodes with required fields: id, type, x, y, width, height
Add edges referencing valid node IDs via fromNode and toNode
Validate: Parse the JSON to confirm it is valid. Verify all fromNode/toNode values exist in the nodes array

2. Add a Node to an Existing Canvas

Read and parse the existing .canvas file
Generate a unique ID that does not collide with existing node or edge IDs
Choose position (x, y) that avoids overlapping existing nodes (leave 50-100px spacing)
Append the new node object to the nodes array
Optionally add edges connecting the new node to existing nodes
Validate: Confirm all IDs are unique and all edge references resolve to existing nodes

3. Connect Two Nodes

Identify the source and target node IDs
Generate a unique edge ID
Set fromNode and toNode to the source and target IDs
Optionally set fromSide/toSide (top, right, bottom, left) for anchor points
Optionally set label for descriptive text on the edge
Append the edge to the edges array
Validate: Confirm both fromNode and toNode reference existing node IDs

4. Edit an Existing Canvas

Read and parse the .canvas file as JSON
Locate the target node or edge by id
Modify the desired attributes (text, position, color, etc.)
Write the updated JSON back to the file
Validate: Re-check all ID uniqueness and edge reference integrity after editing

Nodes

Nodes are objects placed on the canvas. Array order determines z-index: first node = bottom layer, last node = top layer.

Generic Node Attributes

Attribute	Required	Type	Description
`id`	Yes	string	Unique 16-char hex identifier
`type`	Yes	string	`text`, `file`, `link`, or `group`
`x`	Yes	integer	X position in pixels
`y`	Yes	integer	Y position in pixels
`width`	Yes	integer	Width in pixels
`height`	Yes	integer	Height in pixels
`color`	No	canvasColor	Preset `"1"`-`"6"` or hex (e.g., `"#FF0000"`)

Type	Extra Required Field	Notes
`text`	`text` (string)	Markdown content; use `\n` for newlines, NEVER `\\n`
`file`	`file` (path)	Optional `subpath` for heading/block anchor
`link`	`url` (string)	External URL
`group`	none	Optional `label`, `background`, `backgroundStyle`

See NODE-REFERENCE.md for full attribute tables and JSON examples for each type.

Edges

Edges connect nodes via fromNode and toNode IDs.

Attribute	Required	Type	Default	Description
`id`	Yes	string	-	Unique identifier
`fromNode`	Yes	string	-	Source node ID
`fromSide`	No	string	-	`top`, `right`, `bottom`, or `left`
`fromEnd`	No	string	`none`	`none` or `arrow`
`toNode`	Yes	string	-	Target node ID
`toSide`	No	string	-	`top`, `right`, `bottom`, or `left`
`toEnd`	No	string	`arrow`	`none` or `arrow`
`color`	No	canvasColor	-	Line color
`label`	No	string	-	Text label

{
  "id": "0123456789abcdef",
  "fromNode": "6f0ad84f44ce9c17",
  "fromSide": "right",
  "toNode": "a1b2c3d4e5f67890",
  "toSide": "left",
  "toEnd": "arrow",
  "label": "leads to"
}

Colors

The canvasColor type accepts either a hex string or a preset number:

Preset	Color
`"1"`	Red
`"2"`	Orange
`"3"`	Yellow
`"4"`	Green
`"5"`	Cyan
`"6"`	Purple

Preset color values are intentionally undefined – applications use their own brand colors.

ID Generation

Generate 16-character lowercase hexadecimal strings (64-bit random value):

"6f0ad84f44ce9c17"
"a3b2c1d0e9f8a7b6"

Layout Guidelines

Coordinates can be negative (canvas extends infinitely)
x increases right, y increases down; position is the top-left corner
Space nodes 50-100px apart; leave 20-50px padding inside groups
Align to grid (multiples of 10 or 20) for cleaner layouts

Node Type	Suggested Width	Suggested Height
Small text	200-300	80-150
Medium text	300-450	150-300
Large text	400-600	300-500
File preview	300-500	200-400
Link preview	250-400	100-200

Validation Checklist

After creating or editing a canvas file, verify:

All id values are unique across both nodes and edges
Every fromNode and toNode references an existing node ID
Required fields are present for each node type (text for text nodes, file for file nodes, url for link nodes)
type is one of: text, file, link, group
fromSide/toSide values are one of: top, right, bottom, left
fromEnd/toEnd values are one of: none, arrow
Color presets are "1" through "6" or valid hex (e.g., "#FF0000")
JSON is valid and parseable

If validation fails, check for duplicate IDs, dangling edge references, or malformed JSON strings (especially unescaped newlines in text content).

Complete Examples

See references/EXAMPLES.md for full canvas examples including mind maps, project boards, research canvases, and flowcharts.

Common Mistakes

NEVER embed literal newlines in JSON string values — use \n. NEVER use \\n — it renders as literal backslash-n on screen. NEVER reuse the same id across nodes or edges — duplicates silently overwrite each other with no error. NEVER reference a fromNode/toNode ID that does not exist in nodes — the edge renders invisibly. NEVER place child nodes outside the group’s coordinate bounds — they appear as free-floating items. NEVER set fromEnd/toEnd to anything other than "none" or "arrow" — other values are silently discarded. NEVER supply a bare integer for color — the canvasColor type requires a quoted string ("1", not 1).

WHY: JSON Canvas validation errors are silent — corrupted files and dangling references produce no error messages, making bad state invisible until the canvas is manually inspected.

See COMMON-MISTAKES.md for full Bad/Good JSON examples.

References

109/ 140

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Runtime validation via eval scenarios proving the skill actually changes agent behaviour. Requires evals/ directory, instructions.json, ≥3 scenarios, and ≥80% instruction coverage in summary.json.

Appropriate rigidity for the skill type: strict rules for critical/security skills, balanced steps for process skills, flexible options for tool skills. Mismatched calibration (too rigid or too loose) reduces score.

Expert-only knowledge the AI couldn't derive on its own — domain-specific patterns, production gotchas, decision frameworks, and non-obvious tool behaviour. High scores mean <5% redundancy with what the model already knows.

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Rich activation keywords and trigger scenarios in the description so the skill fires when needed. Best descriptions read like an exhaustive list of the tasks and concepts that should invoke this skill.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

194 lines · 3 references

123/ 140

A clear philosophy plus numbered step-by-step workflows with explicit entry/exit points. Should answer: what is the core principle, how to execute it, and when (and when not) to apply it.

Explicit NEVER/WHY/consequence triplets with side-by-side bad/good examples. Generic warnings score low — concrete failure modes with real impact (security, correctness, performance) score high.

Proper frontmatter, single-task focus, activation keywords, and cross-harness portability. Skills must work across 40+ agentic harnesses without hardcoded paths or agent-specific references.

SKILL.md as a <100-line navigation hub pointing to focused references/ files. Content should be lazy-loaded on demand, not front-loaded. Includes actionable 'When to Use' conditions per reference.

Copy-paste-ready code, complete runnable examples, real file paths and commands. Pseudocode and abstract descriptions score low — concrete, executable content scores high.

195 lines · 3 references

JSON Canvas Common Mistakes

1. Using literal newlines instead of `\n` escape in JSON strings

NEVER embed literal newline characters or double-escaped \\n sequences inside JSON string values. JSON strings must use the escape sequence \n for line breaks.

WHY: Literal newlines produce unparseable JSON that silently corrupts the canvas file, while \\n renders as visible backslash-n characters on screen instead of the intended line break.

Bad — literal newline (invalid JSON):

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "text": "Line one
Line two"
}

Bad — double-escaped (renders as literal \n on screen):

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "text": "Line one\\nLine two"
}

Good — single JSON escape:

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "text": "Line one\nLine two"
}

2. Reusing the same ID for multiple nodes or edges

NEVER reuse the same id value for more than one node or edge. Every id must be unique across all nodes and edges.

WHY: Duplicate IDs cause one element to silently overwrite another, resulting in missing nodes or edges with no error reported by Obsidian.

Bad:

{
  "nodes": [
    { "id": "aabbccdd11223344", "type": "text", "x": 0, "y": 0, "width": 200, "height": 100, "text": "Node A" },
    { "id": "aabbccdd11223344", "type": "text", "x": 300, "y": 0, "width": 200, "height": 100, "text": "Node B" }
  ]
}

Good — each ID is a distinct 16-char hex value:

{
  "nodes": [
    { "id": "aabbccdd11223344", "type": "text", "x": 0, "y": 0, "width": 200, "height": 100, "text": "Node A" },
    { "id": "11223344aabbccdd", "type": "text", "x": 300, "y": 0, "width": 200, "height": 100, "text": "Node B" }
  ]
}

3. Creating edges that reference non-existent node IDs

NEVER set fromNode or toNode to an ID that does not exist in the nodes array.

WHY: Dangling edge references produce invisible edges with no error, making it impossible to diagnose missing connections just by viewing the canvas.

Bad — toNode references a missing ID:

{
  "nodes": [
    { "id": "aabbccdd11223344", "type": "text", "x": 0, "y": 0, "width": 200, "height": 100, "text": "Start" }
  ],
  "edges": [
    { "id": "edge000000000001", "fromNode": "aabbccdd11223344", "toNode": "doesnotexist1234" }
  ]
}

Good — toNode resolves to an existing node:

{
  "nodes": [
    { "id": "aabbccdd11223344", "type": "text", "x": 0, "y": 0, "width": 200, "height": 100, "text": "Start" },
    { "id": "11223344aabbccdd", "type": "text", "x": 300, "y": 0, "width": 200, "height": 100, "text": "End" }
  ],
  "edges": [
    { "id": "edge000000000001", "fromNode": "aabbccdd11223344", "toNode": "11223344aabbccdd" }
  ]
}

4. Placing child nodes outside group bounds

NEVER place a child node at coordinates outside the group’s x/y/width/height rectangle.

WHY: Nodes outside the group bounds appear as free-floating canvas items, breaking the visual grouping.

Bad — child at x=1200 is outside group that ends at x=1000:

{
  "nodes": [
    { "id": "group00000000001", "type": "group", "x": 200, "y": 100, "width": 800, "height": 500, "label": "My Group" },
    { "id": "child00000000001", "type": "text", "x": 1200, "y": 150, "width": 200, "height": 80, "text": "Orphaned child" }
  ]
}

Good — child fits inside group bounds (x=200..1000, y=100..600):

{
  "nodes": [
    { "id": "group00000000001", "type": "group", "x": 200, "y": 100, "width": 800, "height": 500, "label": "My Group" },
    { "id": "child00000000001", "type": "text", "x": 250, "y": 150, "width": 200, "height": 80, "text": "Inside group" }
  ]
}

5. Setting `fromEnd`/`toEnd` to unsupported values

NEVER set fromEnd or toEnd to any value other than "none" or "arrow".

WHY: Unsupported end-marker values are either silently discarded or cause the edge to render incorrectly, with no validation error.

Bad:

{ "id": "edge000000000001", "fromNode": "aabbccdd11223344", "toNode": "11223344aabbccdd", "fromEnd": "circle", "toEnd": "diamond" }

Good:

{ "id": "edge000000000001", "fromNode": "aabbccdd11223344", "toNode": "11223344aabbccdd", "fromEnd": "none", "toEnd": "arrow" }

6. Using integer color values instead of string color values

NEVER supply a bare integer for the color field. The canvasColor type is always a JSON string.

WHY: Canvas implementations that enforce strict typing will reject the file or ignore the color when an integer is provided instead of a quoted string.

Bad — integer value: "color": 1

Good — string value: "color": "1"

JSON Canvas Complete Examples

Simple Canvas with Text and Connections

{
  "nodes": [
    {
      "id": "8a9b0c1d2e3f4a5b",
      "type": "text",
      "x": 0,
      "y": 0,
      "width": 300,
      "height": 150,
      "text": "# Main Idea\n\nThis is the central concept."
    },
    {
      "id": "1a2b3c4d5e6f7a8b",
      "type": "text",
      "x": 400,
      "y": -100,
      "width": 250,
      "height": 100,
      "text": "## Supporting Point A\n\nDetails here."
    },
    {
      "id": "2b3c4d5e6f7a8b9c",
      "type": "text",
      "x": 400,
      "y": 100,
      "width": 250,
      "height": 100,
      "text": "## Supporting Point B\n\nMore details."
    }
  ],
  "edges": [
    {
      "id": "3c4d5e6f7a8b9c0d",
      "fromNode": "8a9b0c1d2e3f4a5b",
      "fromSide": "right",
      "toNode": "1a2b3c4d5e6f7a8b",
      "toSide": "left"
    },
    {
      "id": "4d5e6f7a8b9c0d1e",
      "fromNode": "8a9b0c1d2e3f4a5b",
      "fromSide": "right",
      "toNode": "2b3c4d5e6f7a8b9c",
      "toSide": "left"
    }
  ]
}

Project Board with Groups

{
  "nodes": [
    {
      "id": "5e6f7a8b9c0d1e2f",
      "type": "group",
      "x": 0,
      "y": 0,
      "width": 300,
      "height": 500,
      "label": "To Do",
      "color": "1"
    },
    {
      "id": "6f7a8b9c0d1e2f3a",
      "type": "group",
      "x": 350,
      "y": 0,
      "width": 300,
      "height": 500,
      "label": "In Progress",
      "color": "3"
    },
    {
      "id": "7a8b9c0d1e2f3a4b",
      "type": "group",
      "x": 700,
      "y": 0,
      "width": 300,
      "height": 500,
      "label": "Done",
      "color": "4"
    },
    {
      "id": "8b9c0d1e2f3a4b5c",
      "type": "text",
      "x": 20,
      "y": 50,
      "width": 260,
      "height": 80,
      "text": "## Task 1\n\nImplement feature X"
    },
    {
      "id": "9c0d1e2f3a4b5c6d",
      "type": "text",
      "x": 370,
      "y": 50,
      "width": 260,
      "height": 80,
      "text": "## Task 2\n\nReview PR #123",
      "color": "2"
    },
    {
      "id": "0d1e2f3a4b5c6d7e",
      "type": "text",
      "x": 720,
      "y": 50,
      "width": 260,
      "height": 80,
      "text": "## Task 3\n\n~~Setup CI/CD~~"
    }
  ],
  "edges": []
}

Research Canvas with Files and Links

{
  "nodes": [
    {
      "id": "1e2f3a4b5c6d7e8f",
      "type": "text",
      "x": 300,
      "y": 200,
      "width": 400,
      "height": 200,
      "text": "# Research Topic\n\n## Key Questions\n\n- How does X affect Y?\n- What are the implications?",
      "color": "5"
    },
    {
      "id": "2f3a4b5c6d7e8f9a",
      "type": "file",
      "x": 0,
      "y": 0,
      "width": 250,
      "height": 150,
      "file": "Literature/Paper A.pdf"
    },
    {
      "id": "3a4b5c6d7e8f9a0b",
      "type": "file",
      "x": 0,
      "y": 200,
      "width": 250,
      "height": 150,
      "file": "Notes/Meeting Notes.md",
      "subpath": "#Key Insights"
    },
    {
      "id": "4b5c6d7e8f9a0b1c",
      "type": "link",
      "x": 0,
      "y": 400,
      "width": 250,
      "height": 100,
      "url": "https://example.com/research"
    },
    {
      "id": "5c6d7e8f9a0b1c2d",
      "type": "file",
      "x": 750,
      "y": 150,
      "width": 300,
      "height": 250,
      "file": "Attachments/diagram.png"
    }
  ],
  "edges": [
    {
      "id": "6d7e8f9a0b1c2d3e",
      "fromNode": "2f3a4b5c6d7e8f9a",
      "fromSide": "right",
      "toNode": "1e2f3a4b5c6d7e8f",
      "toSide": "left",
      "label": "supports"
    },
    {
      "id": "7e8f9a0b1c2d3e4f",
      "fromNode": "3a4b5c6d7e8f9a0b",
      "fromSide": "right",
      "toNode": "1e2f3a4b5c6d7e8f",
      "toSide": "left",
      "label": "informs"
    },
    {
      "id": "8f9a0b1c2d3e4f5a",
      "fromNode": "4b5c6d7e8f9a0b1c",
      "fromSide": "right",
      "toNode": "1e2f3a4b5c6d7e8f",
      "toSide": "left",
      "toEnd": "arrow",
      "color": "6"
    },
    {
      "id": "9a0b1c2d3e4f5a6b",
      "fromNode": "1e2f3a4b5c6d7e8f",
      "fromSide": "right",
      "toNode": "5c6d7e8f9a0b1c2d",
      "toSide": "left",
      "label": "visualized by"
    }
  ]
}

Flowchart

{
  "nodes": [
    {
      "id": "a0b1c2d3e4f5a6b7",
      "type": "text",
      "x": 200,
      "y": 0,
      "width": 150,
      "height": 60,
      "text": "**Start**",
      "color": "4"
    },
    {
      "id": "b1c2d3e4f5a6b7c8",
      "type": "text",
      "x": 200,
      "y": 100,
      "width": 150,
      "height": 60,
      "text": "Step 1:\nGather data"
    },
    {
      "id": "c2d3e4f5a6b7c8d9",
      "type": "text",
      "x": 200,
      "y": 200,
      "width": 150,
      "height": 80,
      "text": "**Decision**\n\nIs data valid?",
      "color": "3"
    },
    {
      "id": "d3e4f5a6b7c8d9e0",
      "type": "text",
      "x": 400,
      "y": 200,
      "width": 150,
      "height": 60,
      "text": "Process data"
    },
    {
      "id": "e4f5a6b7c8d9e0f1",
      "type": "text",
      "x": 0,
      "y": 200,
      "width": 150,
      "height": 60,
      "text": "Request new data",
      "color": "1"
    },
    {
      "id": "f5a6b7c8d9e0f1a2",
      "type": "text",
      "x": 400,
      "y": 320,
      "width": 150,
      "height": 60,
      "text": "**End**",
      "color": "4"
    }
  ],
  "edges": [
    {
      "id": "a6b7c8d9e0f1a2b3",
      "fromNode": "a0b1c2d3e4f5a6b7",
      "fromSide": "bottom",
      "toNode": "b1c2d3e4f5a6b7c8",
      "toSide": "top"
    },
    {
      "id": "b7c8d9e0f1a2b3c4",
      "fromNode": "b1c2d3e4f5a6b7c8",
      "fromSide": "bottom",
      "toNode": "c2d3e4f5a6b7c8d9",
      "toSide": "top"
    },
    {
      "id": "c8d9e0f1a2b3c4d5",
      "fromNode": "c2d3e4f5a6b7c8d9",
      "fromSide": "right",
      "toNode": "d3e4f5a6b7c8d9e0",
      "toSide": "left",
      "label": "Yes",
      "color": "4"
    },
    {
      "id": "d9e0f1a2b3c4d5e6",
      "fromNode": "c2d3e4f5a6b7c8d9",
      "fromSide": "left",
      "toNode": "e4f5a6b7c8d9e0f1",
      "toSide": "right",
      "label": "No",
      "color": "1"
    },
    {
      "id": "e0f1a2b3c4d5e6f7",
      "fromNode": "e4f5a6b7c8d9e0f1",
      "fromSide": "top",
      "fromEnd": "none",
      "toNode": "b1c2d3e4f5a6b7c8",
      "toSide": "left",
      "toEnd": "arrow"
    },
    {
      "id": "f1a2b3c4d5e6f7a8",
      "fromNode": "d3e4f5a6b7c8d9e0",
      "fromSide": "bottom",
      "toNode": "f5a6b7c8d9e0f1a2",
      "toSide": "top"
    }
  ]
}

JSON Canvas Node Reference

Full attribute tables and JSON examples for each node type.

Text Nodes

Attribute	Required	Type	Description
`text`	Yes	string	Plain text with Markdown syntax

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "x": 0,
  "y": 0,
  "width": 400,
  "height": 200,
  "text": "# Hello World\n\nThis is **Markdown** content."
}

Newline pitfall: Use \n for line breaks. Do not use literal newlines (invalid JSON) or \\n (renders as \n on screen).

File Nodes

Attribute	Required	Type	Description
`file`	Yes	string	Path to file within the system
`subpath`	No	string	Link to heading or block (starts with `#`)

{
  "id": "a1b2c3d4e5f67890",
  "type": "file",
  "x": 500,
  "y": 0,
  "width": 400,
  "height": 300,
  "file": "Attachments/diagram.png"
}

With heading anchor:

{
  "id": "a1b2c3d4e5f67891",
  "type": "file",
  "x": 500,
  "y": 350,
  "width": 400,
  "height": 300,
  "file": "Notes/Architecture.md",
  "subpath": "#Overview"
}

Link Nodes

Attribute	Required	Type	Description
`url`	Yes	string	External URL

{
  "id": "c3d4e5f678901234",
  "type": "link",
  "x": 1000,
  "y": 0,
  "width": 400,
  "height": 200,
  "url": "https://obsidian.md"
}

Group Nodes

Groups are visual containers for organizing other nodes. Position child nodes inside the group’s coordinate bounds.

Attribute	Required	Type	Description
`label`	No	string	Text label for the group
`background`	No	string	Path to background image
`backgroundStyle`	No	string	`cover`, `ratio`, or `repeat`

{
  "id": "d4e5f6789012345a",
  "type": "group",
  "x": -50,
  "y": -50,
  "width": 1000,
  "height": 600,
  "label": "Project Overview",
  "color": "4"
}

A child node must have its top-left corner (x, y) and full bounds (x+width, y+height) within the group’s rectangle. For group above: child x must be in [-50, 950] and y in [-50, 550].

Edit this page on GitHub