How to Create and Edit JSON Canvas Files with AI: A Complete Developer Guide

AI models can generate, modify, and validate Obsidian canvas files by following the JSON Canvas skill specifications defined in the kepano/obsidian-skills repository, which mandates 16-character hexadecimal IDs, strict node/edge schemas, and specific array-based file structures.

The JSON Canvas format powers Obsidian's infinite canvas feature, storing nodes and edges as structured JSON in .canvas files. By leveraging the machine-readable skill definitions in skills/json-canvas/SKILL.md, developers can instruct AI assistants to programmatically build complex visual layouts, automate node connections, and ensure spec compliance without manual editing.

Understanding the JSON Canvas File Structure

Every .canvas file is a JSON object containing exactly two top-level arrays: nodes and edges. This structure is documented in skills/json-canvas/SKILL.md and aligns with the official JSON Canvas specification.

The nodes array holds visual elements positioned on the canvas, while the edges array defines connections between them. Both arrays must exist even when empty, as shown in the minimal valid canvas file:

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

Node Types and Required Attributes

According to the source code in skills/json-canvas/SKILL.md, every node requires a unique 16-character hexadecimal id, a type field, and positional coordinates. The four valid node types are text, file, link, and group.

Text Nodes

Text nodes display Markdown content and require x, y, width, height, and text fields. Newlines in the text content must use literal \n escape sequences.

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

}

File Nodes

File nodes embed external resources and require a file path string instead of text content.

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

Connecting Nodes with Edges

Edges create relationships between nodes by referencing their IDs. As defined in skills/json-canvas/SKILL.md, edges require fromNode and toNode IDs, and can specify connection sides and visual styling.

Valid edge attributes include:

• fromSide and toSide: Specify connection points (top, right, bottom, left)
• toEnd: Set to "arrow" for directional connections
• label: Optional text annotation

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

ID Generation and Validation

The kepano/obsidian-skills repository specifies strict ID generation rules to prevent collisions. Both nodes and edges must use 16-character lowercase hexadecimal strings.

Validation Checklist

Before writing canvas files to disk, AI should verify:

• All IDs are unique across both nodes and edges arrays
• Every fromNode and toNode reference matches an existing node ID
• Required fields (id, type, x, y, width, height) are present and correctly typed
• The JSON is parsable and follows the schema in skills/json-canvas/SKILL.md

Common AI-Driven Workflows

The JSON Canvas skill outlines four primary operations for automating canvas manipulation:

1. Creating a new canvas: Generate the empty structure with nodes and edges arrays
2. Adding a node: Append a properly formatted node object with a unique 16-character hex ID
3. Connecting two nodes: Create an edge object linking the source and target node IDs
4. Editing an existing canvas: Modify node properties such as position, dimensions, color, or content while preserving ID integrity

For complex layouts and real-world patterns, reference skills/json-canvas/references/EXAMPLES.md, which contains complete mind maps and project board implementations.

Helper Functions for Automation

The repository provides utility functions in skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md that AI systems can invoke for file operations. These helpers handle ID generation, JSON parsing, and file I/O when creating and editing JSON Canvas files programmatically.

Summary

• JSON Canvas files use a .canvas extension and contain nodes and edges arrays
• Nodes require 16-character hex IDs, type definitions, and positional coordinates
• Edges connect nodes via fromNode and toNode references with optional directional arrows
• AI validation must check for unique IDs, valid references, and required field presence
• The kepano/obsidian-skills repository provides schema definitions, examples, and helper functions for automated canvas manipulation

Frequently Asked Questions

What is the JSON Canvas format?

JSON Canvas is an open file format used by Obsidian.md to store infinite canvas layouts as structured JSON. It represents visual elements (nodes) and their connections (edges) in a machine-readable structure that supports text, files, links, and groups.

How do I generate valid IDs for canvas nodes?

Generate 16-character lowercase hexadecimal strings for both node and edge IDs. For example, 6f0ad84f44ce9c17 follows the specification documented in skills/json-canvas/SKILL.md. Ensure all IDs within a canvas file are unique across both the nodes and edges arrays.

Can AI tools automatically validate JSON Canvas syntax?

Yes, AI tools can validate canvas files by checking against the schema in skills/json-canvas/SKILL.md. Validation includes verifying ID uniqueness, ensuring all edge references point to existing nodes, confirming required fields are present, and validating that the JSON structure matches the official specification.

Where can I find complete examples of canvas files?

The skills/json-canvas/references/EXAMPLES.md file in the kepano/obsidian-skills repository contains production-ready canvas implementations, including mind maps and project boards. These examples demonstrate proper node positioning, edge routing, and color configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}