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

> Learn to create and edit JSON Canvas files with AI. This guide details how AI models generate and validate Obsidian canvas files using strict JSON Canvas skill specifications.

- Repository: [Steph Ango/obsidian-skills](https://github.com/kepano/obsidian-skills)
- Tags: how-to-guide
- Published: 2026-03-24

---

**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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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:

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

```

## Node Types and Required Attributes

According to the source code in [`skills/json-canvas/SKILL.md`](https://github.com/kepano/obsidian-skills/blob/main/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.

```json
{
  "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.

```json
{
  "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`](https://github.com/kepano/obsidian-skills/blob/main/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

```json
{
  "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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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`](https://github.com/kepano/obsidian-skills/blob/main/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.