Summary
This source did not publish a separate summary. Review SKILL.md before using the skill.
JSON Canvas Skill
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 objectsedges (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 to the source and target IDs
toNode
Optionally set fromSide/toSide (top, right, bottom, left) for anchor pointsOptionally set label for descriptive text on the edgeAppend the edge to the edges arrayValidate: Confirm both fromNode and toNode reference existing node IDs4. 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") |
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 in JSON strings. Do not use the literal \\n -- Obsidian renders that as the characters \ and n.
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"
}
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 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"
}
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, groupfromSide/toSide values are one of: top, right, bottom, leftfromEnd/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.
References
