json-canvas: Create Visual Canvas Files for Obsidian

The json-canvas skill teaches AI coding assistants to create and edit JSON Canvas files — the .canvas format used by Obsidian for infinite visual canvases. Canvas files follow the JSON Canvas Spec 1.0 and contain nodes (text cards, file previews, web links, and groups) connected by directional edges. Load this skill when the user asks to work with .canvas files, create mind maps or flowcharts, or visualize relationships between notes.

File Structure

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

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

nodes (optional): Array of node objects placed on the canvas
edges (optional): Array of edge objects connecting nodes by their id

See /reference/canvas-nodes and /reference/canvas-edges for the full attribute reference.

Common Workflows

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

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 a 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

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

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

Node Types

All nodes share a set of generic attributes, plus type-specific fields. 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"`)

Text
File
Link
Group

Text nodes display plain text with Markdown syntax rendered inside the card.

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."
}

Use \n for line breaks in JSON strings. Do not use the literal \\n — Obsidian renders that as the characters \ and n instead of a line break.

File nodes display a preview of a file from the vault.

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"
}

Link nodes display a preview of an external URL.

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 are visual containers for organizing other nodes. Position child nodes inside the group’s bounding box.

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"
}

Edges

Edges connect nodes via fromNode and toNode IDs. Both ends can have optional directional arrows and anchor side hints.

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 on the edge

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

See /reference/canvas-edges for the full edge reference.

Colors

The canvasColor type accepts either a hex string (e.g., "#FF0000") or one of the preset number strings. Preset colors are intentionally loosely defined — applications use their own brand colors.

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

ID Generation

Generate 16-character lowercase hexadecimal strings (64-bit random values) for all node and edge IDs:

"6f0ad84f44ce9c17"
"a3b2c1d0e9f8a7b6"

IDs must be unique across both the nodes and edges arrays within a single canvas file.

Layout Guidelines

The canvas coordinate system extends infinitely in all directions. Coordinates can be negative.

x increases to the right; y increases downward
Node position (x, y) refers to 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 of the following:

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 a valid hex string (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). See /reference/canvas-examples for full canvas examples including mind maps, project boards, research canvases, and flowcharts.

Overview

Skills

json-canvas: Create Visual Canvas Files for Obsidian

File Structure

Common Workflows

Node Types

Generic Node Attributes

Edges

Colors

ID Generation

Layout Guidelines

Validation Checklist

Build docs developers (and LLMs) love

Overview

Skills

Documentation Index

​File Structure

​Common Workflows

​Node Types

​Generic Node Attributes

​Edges

​Colors

​ID Generation

​Layout Guidelines

​Validation Checklist

Build docs developers (and LLMs) love

File Structure

Common Workflows

Node Types

Generic Node Attributes

Edges

Colors

ID Generation

Layout Guidelines

Validation Checklist