Skip to content
Documents

JSON Canvas

Build an editable canvas document with typed nodes, stable references and connections between ideas.

Install with Skills CLI
npx skills add obsidianmd/obsidian-skills@json-canvas

What it does

A diagram can contain valid JSON yet lose a connection when an edge points to an obsolete node ID. JSON Canvas describes how to edit the document structure and check those relationships.

What changes after install

  • Choose text, file, link or group nodes for the material.
  • Position nodes and connect them using stable IDs.
  • Validate the JSON and check every edge endpoint.

Install

Run this command with Node.js 22.20 or later and select your agent in the Skills CLI.

Install with Skills CLI
npx skills add obsidianmd/obsidian-skills@json-canvas

Before using JSON Canvas

  • A .canvas file or diagram brief, plus an editor or viewer that supports JSON Canvas.

Read the reviewed setup instructions for the selected workflow.

When to use it

  • Turn research notes into an editable concept map.
  • Extend a project board while preserving existing connections.

When not to use it

  • Delivering a presentation with speaker notes and slide timing.

A worked example

Map a decision, its evidence note and two options. Give the agent a vault containing Research/Station interviews.md and an existing canvas with a “Platform access” group. Ask for two options, “Extend the ramp” and “Move the entrance,” beside the decision. Keep the evidence note editable in the vault. Label the connections so a reader can tell which observation supports each option.

  1. Read the existing canvas and list the IDs already used by nodes and edges. Locate the group and measure the open space next to it from its coordinates and dimensions. Preserve the existing nodes, edges and their order as you add to the file. A group drawn over earlier nodes can cover the material it was meant to organize.
  2. Use a file node for the interview note. Give it the path relative to the vault, including the folder, and use short text nodes for the decision and two options. If the source note mentions both ramps, an excerpt pasted onto a card can go stale when the interview is corrected. Keeping the file reference gives the researcher one place to maintain that account.
  3. Assign a fresh ID to each new node and edge. Lay out the options far enough apart for both labels to wrap. Reserve space for the evidence preview and a gutter for the edge text. In this format x and y locate the top left of a node. Two nodes with the same x value align on the left even if their widths differ.
  4. Connect the decision to each option and connect the relevant observation to the option it supports. Use the ID from the intended node in each endpoint field. Review the arrowhead direction with the edge label as a sentence. “Evidence supports moving the entrance” has a different meaning when someone follows the arrow in reverse.
  5. Save the canvas and inspect it beside the original in a compatible viewer. Move one option a short distance. Its connection should travel with it. A line can look as though it reaches the correct option at one zoom level even when its endpoint actually names the neighboring node.

Upstream instructions: SKILL.md and references/EXAMPLES.md.

Troubleshooting

  • The viewer refuses to open the canvas. Parse the saved file as JSON before adjusting the layout. Inspect quotations inside a text node or a filename such as Station "East".md. A quote inside a JSON string needs escaping; the value after parsing should still contain the actual quote in the vault filename. The same distinction applies to a line break in a text card.
  • A connection disappears after copying an option. Compare every edge’s source and destination IDs with the node list. A copied card may share its ID with the original, or the edge may still point to the ID of a deleted draft. Assign the duplicate a fresh ID and update only those connections that belong to it.
  • The final words of a label are hidden. Increase the node dimensions and inspect the result in the viewer. The guide gives wider starting dimensions for Chinese, Japanese and Korean text. When widening an option, move the neighboring card and its group boundary as needed; otherwise the full label can reappear under another node.

How it chooses an approach

Use a file node when the original note should remain editable in place. Use a text node for a short explanation written specifically for this decision. A link node holds an external URL, such as a published accessibility standard. A group gives related cards a visible area on the board. Group membership by appearance does not express which alternative an interview supports. Put that relationship on a labeled edge.

Before making a new canvas, ask whether the requested output adds to an existing map that other people already navigate. When adding one decision to a shared board, keep existing IDs and unrelated positions. For a new canvas there is more freedom to choose a reading direction. Start with the decision and the item the reader should examine next, then position supporting material around that path.

Read the evidence note before naming an edge. If it records an observation about the steep ramp but says nothing about a proposed entrance, a line labeled “proves” would give the interview more weight than its author did. A shorter label such as “reports steep incline” helps readers judge the option themselves.

When to use another skill

  • Use Canvas Design when the committee wants a finished visual to hang in the station. Supply the approved wording and the intended print size.
  • Use PowerPoint when a presenter will reveal the alternatives in order and needs editable slides and speaker notes.
  • Use Documentation and ADRs to record the decision after review. Hand over the chosen option, the reason the other lost and the evidence note, rather than asking the diagram alone to preserve that history.

What to check after it runs

  • Parse the saved file. Check ID uniqueness across nodes and edges together and verify that every endpoint resolves to a node. Count the original cards before and after the edit so adding a decision does not silently remove an older one.
  • Open the file node from the canvas and read the note’s heading. Confirm the path reaches the interview in the specified folder, especially if two notes share a name. Edit the note separately and reopen its preview to check that the card references the intended source.
  • Follow each arrow from its source, read its label and name the destination out loud. Move the two option cards apart and repeat the check; this makes edges that merely cross a card easier to distinguish from edges attached to it.
  • At the zoom level participants will use, read the longest option and the last line in the evidence preview. Inspect all four sides of the group for clipped labels, overlapping cards and edges obscured by a card. Save and reopen the canvas before handing it to the researcher.

More in Documents

Related skills in other categories

FAQ

Why does a quotation inside a text node break the file?
Text values must be valid JSON strings. Serialize or correctly escape embedded quotation marks before reopening the canvas.
Why is a valid node hard to read?
Its width and height may be too small for the text. Inspect the rendered canvas, especially for long labels or wide characters.