1---
2name: json-canvas
3description: 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.
4---
5 
6# JSON Canvas Skill
7 
8## File Structure
9 
10A canvas file (`.canvas`) contains two top-level arrays following the [JSON Canvas Spec 1.0](https://jsoncanvas.org/spec/1.0/):
11 
12```json
13{
14  "nodes": [],
15  "edges": []
16}
17```
18 
19- `nodes` (optional): Array of node objects
20- `edges` (optional): Array of edge objects connecting nodes
21 
22## Common Workflows
23 
24### 1. Create a New Canvas
25 
261. Create a `.canvas` file with the base structure `{"nodes": [], "edges": []}`
272. Generate unique 16-character hex IDs for each node (e.g., `"6f0ad84f44ce9c17"`)
283. Add nodes with required fields: `id`, `type`, `x`, `y`, `width`, `height`
294. Add edges referencing valid node IDs via `fromNode` and `toNode`
305. **Validate**: Parse the JSON to confirm it is valid. Verify all `fromNode`/`toNode` values exist in the nodes array
31 
32### 2. Add a Node to an Existing Canvas
33 
341. Read and parse the existing `.canvas` file
352. Generate a unique ID that does not collide with existing node or edge IDs
363. Choose position (`x`, `y`) that avoids overlapping existing nodes (leave 50-100px spacing)
374. Append the new node object to the `nodes` array
385. Optionally add edges connecting the new node to existing nodes
396. **Validate**: Confirm all IDs are unique and all edge references resolve to existing nodes
40 
41### 3. Connect Two Nodes
42 
431. Identify the source and target node IDs
442. Generate a unique edge ID
453. Set `fromNode` and `toNode` to the source and target IDs
464. Optionally set `fromSide`/`toSide` (top, right, bottom, left) for anchor points
475. Optionally set `label` for descriptive text on the edge
486. Append the edge to the `edges` array
497. **Validate**: Confirm both `fromNode` and `toNode` reference existing node IDs
50 
51### 4. Edit an Existing Canvas
52 
531. Read and parse the `.canvas` file as JSON
542. Locate the target node or edge by `id`
553. Modify the desired attributes (text, position, color, etc.)
564. Write the updated JSON back to the file
575. **Validate**: Re-check all ID uniqueness and edge reference integrity after editing
58 
59## Nodes
60 
61Nodes are objects placed on the canvas. Array order determines z-index: first node = bottom layer, last node = top layer.
62 
63### Generic Node Attributes
64 
65| Attribute | Required | Type | Description |
66|-----------|----------|------|-------------|
67| `id` | Yes | string | Unique 16-char hex identifier |
68| `type` | Yes | string | `text`, `file`, `link`, or `group` |
69| `x` | Yes | integer | X position in pixels |
70| `y` | Yes | integer | Y position in pixels |
71| `width` | Yes | integer | Width in pixels |
72| `height` | Yes | integer | Height in pixels |
73| `color` | No | canvasColor | Preset `"1"`-`"6"` or hex (e.g., `"#FF0000"`) |
74 
75### Text Nodes
76 
77| Attribute | Required | Type | Description |
78|-----------|----------|------|-------------|
79| `text` | Yes | string | Plain text with Markdown syntax |
80 
81```json
82{
83  "id": "6f0ad84f44ce9c17",
84  "type": "text",
85  "x": 0,
86  "y": 0,
87  "width": 400,
88  "height": 200,
89  "text": "# Hello World\n\nThis is **Markdown** content."
90}
91```
92 
93**Newline pitfall**: Use `\n` for line breaks in JSON strings. Do **not** use the literal `\\n` -- Obsidian renders that as the characters `\` and `n`.
94 
95### File Nodes
96 
97| Attribute | Required | Type | Description |
98|-----------|----------|------|-------------|
99| `file` | Yes | string | Path to file within the system |
100| `subpath` | No | string | Link to heading or block (starts with `#`) |
101 
102```json
103{
104  "id": "a1b2c3d4e5f67890",
105  "type": "file",
106  "x": 500,
107  "y": 0,
108  "width": 400,
109  "height": 300,
110  "file": "Attachments/diagram.png"
111}
112```
113 
114### Link Nodes
115 
116| Attribute | Required | Type | Description |
117|-----------|----------|------|-------------|
118| `url` | Yes | string | External URL |
119 
120```json
121{
122  "id": "c3d4e5f678901234",
123  "type": "link",
124  "x": 1000,
125  "y": 0,
126  "width": 400,
127  "height": 200,
128  "url": "https://obsidian.md"
129}
130```
131 
132### Group Nodes
133 
134Groups are visual containers for organizing other nodes. Position child nodes inside the group's bounds.
135 
136| Attribute | Required | Type | Description |
137|-----------|----------|------|-------------|
138| `label` | No | string | Text label for the group |
139| `background` | No | string | Path to background image |
140| `backgroundStyle` | No | string | `cover`, `ratio`, or `repeat` |
141 
142```json
143{
144  "id": "d4e5f6789012345a",
145  "type": "group",
146  "x": -50,
147  "y": -50,
148  "width": 1000,
149  "height": 600,
150  "label": "Project Overview",
151  "color": "4"
152}
153```
154 
155## Edges
156 
157Edges connect nodes via `fromNode` and `toNode` IDs.
158 
159| Attribute | Required | Type | Default | Description |
160|-----------|----------|------|---------|-------------|
161| `id` | Yes | string | - | Unique identifier |
162| `fromNode` | Yes | string | - | Source node ID |
163| `fromSide` | No | string | - | `top`, `right`, `bottom`, or `left` |
164| `fromEnd` | No | string | `none` | `none` or `arrow` |
165| `toNode` | Yes | string | - | Target node ID |
166| `toSide` | No | string | - | `top`, `right`, `bottom`, or `left` |
167| `toEnd` | No | string | `arrow` | `none` or `arrow` |
168| `color` | No | canvasColor | - | Line color |
169| `label` | No | string | - | Text label |
170 
171```json
172{
173  "id": "0123456789abcdef",
174  "fromNode": "6f0ad84f44ce9c17",
175  "fromSide": "right",
176  "toNode": "a1b2c3d4e5f67890",
177  "toSide": "left",
178  "toEnd": "arrow",
179  "label": "leads to"
180}
181```
182 
183## Colors
184 
185The `canvasColor` type accepts either a hex string or a preset number:
186 
187| Preset | Color |
188|--------|-------|
189| `"1"` | Red |
190| `"2"` | Orange |
191| `"3"` | Yellow |
192| `"4"` | Green |
193| `"5"` | Cyan |
194| `"6"` | Purple |
195 
196Preset color values are intentionally undefined -- applications use their own brand colors.
197 
198## ID Generation
199 
200Generate 16-character lowercase hexadecimal strings (64-bit random value):
201 
202```
203"6f0ad84f44ce9c17"
204"a3b2c1d0e9f8a7b6"
205```
206 
207## Layout Guidelines
208 
209- Coordinates can be negative (canvas extends infinitely)
210- `x` increases right, `y` increases down; position is the top-left corner
211- Space nodes 50-100px apart; leave 20-50px padding inside groups
212- Align to grid (multiples of 10 or 20) for cleaner layouts
213 
214| Node Type | Suggested Width | Suggested Height |
215|-----------|-----------------|------------------|
216| Small text | 200-300 | 80-150 |
217| Medium text | 300-450 | 150-300 |
218| Large text | 400-600 | 300-500 |
219| File preview | 300-500 | 200-400 |
220| Link preview | 250-400 | 100-200 |
221 
222## Validation Checklist
223 
224After creating or editing a canvas file, verify:
225 
2261. All `id` values are unique across both nodes and edges
2272. Every `fromNode` and `toNode` references an existing node ID
2283. Required fields are present for each node type (`text` for text nodes, `file` for file nodes, `url` for link nodes)
2294. `type` is one of: `text`, `file`, `link`, `group`
2305. `fromSide`/`toSide` values are one of: `top`, `right`, `bottom`, `left`
2316. `fromEnd`/`toEnd` values are one of: `none`, `arrow`
2327. Color presets are `"1"` through `"6"` or valid hex (e.g., `"#FF0000"`)
2338. JSON is valid and parseable
234 
235If validation fails, check for duplicate IDs, dangling edge references, or malformed JSON strings (especially unescaped newlines in text content).
236 
237## Complete Examples
238 
239See [references/EXAMPLES.md](references/EXAMPLES.md) for full canvas examples including mind maps, project boards, research canvases, and flowcharts.
240 
241## References
242 
243- [JSON Canvas Spec 1.0](https://jsoncanvas.org/spec/1.0/)
244- [JSON Canvas GitHub](https://github.com/obsidianmd/jsoncanvas)
245