json-canvas

JSON Canvas スキル

ファイル構造

キャンバスファイル（.canvas）には、JSON Canvas Spec 1.0 に準拠した 2 つのトップレベル配列が含まれます。

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

• nodes（任意）: ノードオブジェクトの配列
• edges（任意）: ノード間を接続するエッジオブジェクトの配列

一般的なワークフロー

1. 新しいキャンバスの作成

1. 基本構造 {"nodes": [], "edges": []} を持つ .canvas ファイルを作成します
2. 各ノードに一意の 16 文字の 16 進数 ID を生成します（例: "6f0ad84f44ce9c17"）
3. 必須フィールド id、type、x、y、width、height を持つノードを追加します
4. fromNode と toNode を介して有効なノード ID を参照するエッジを追加します
5. 検証: JSON をパースして有効であることを確認します。すべての fromNode/toNode の値が nodes 配列に存在することを確認します

2. 既存のキャンバスへのノードの追加

1. 既存の .canvas ファイルを読み込んでパースします
2. 既存のノードまたはエッジの ID と衝突しない一意の ID を生成します
3. 既存のノードと重ならない位置（x、y）を選択します（50〜100px の間隔を空けます）
4. 新しいノードオブジェクトを nodes 配列に追加します
5. 必要に応じて、新しいノードを既存のノードに接続するエッジを追加します
6. 検証: すべての ID が一意であり、すべてのエッジ参照が既存のノードに解決されることを確認します

3. 2 つのノードの接続

1. ソースノードとターゲットノードの ID を特定します
2. 一意のエッジ ID を生成します
3. fromNode と toNode をソースとターゲットの ID に設定します
4. 必要に応じて、アンカーポイントとして fromSide/toSide（top、right、bottom、left）を設定します
5. 必要に応じて、エッジ上の説明テキストとして label を設定します
6. エッジを edges 配列に追加します
7. 検証: fromNode と toNode の両方が既存のノード ID を参照していることを確認します

4. 既存のキャンバスの編集

1. .canvas ファイルを JSON として読み込んでパースします
2. id で対象のノードまたはエッジを特定します
3. 目的の属性（テキスト、位置、色など）を変更します
4. 更新した JSON をファイルに書き戻します
5. 検証: 編集後にすべての ID の一意性とエッジ参照の整合性を再確認します

ノード

ノードはキャンバス上に配置されるオブジェクトです。配列の順序が z-index を決定します。最初のノード = 最下層、最後のノード = 最上層です。

汎用ノード属性

属性	必須	型	説明
id	はい	string	一意の 16 文字の 16 進数識別子
type	はい	string	text、file、link、または group
x	はい	integer	X 位置（ピクセル単位）
y	はい	integer	Y 位置（ピクセル単位）
width	はい	integer	幅（ピクセル単位）
height	はい	integer	高さ（ピクセル単位）
color	いいえ	canvasColor	プリセット "1"〜"6" または 16 進数（例: "#FF0000"）

テキストノード

属性	必須	型	説明
text	はい	string	Markdown 構文を含むプレーンテキスト

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

改行の落とし穴: JSON 文字列内の改行には \n を使用してください。リテラルの \\n は使用しないでください -- Obsidian はそれを \ と n という文字としてレンダリングします。

ファイルノード

属性	必須	型	説明
file	はい	string	システム内のファイルへのパス
subpath	いいえ	string	見出しまたはブロックへのリンク（# で始まります）

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

リンクノード

属性	必須	型	説明
url	はい	string	外部 URL

{
  "id": "c3d4e5f678901234",
  "type": "link",
  "x": 1000,
  "y": 0,
  "width": 400,
  "height": 200,
  "url": "https://obsidian.md"
}

グループノード

グループは、他のノードを整理するための視覚的なコンテナです。子ノードはグループの境界内に配置してください。

属性	必須	型	説明
label	いいえ	string	グループのテキストラベル
background	いいえ	string	背景画像へのパス
backgroundStyle	いいえ	string	cover、ratio、または repeat

{
  "id": "d4e5f6789012345a",
  "type": "group",
  "x": -50,
  "y": -50,
  "width": 1000,
  "height": 600,
  "label": "Project Overview",
  "color": "4"
}

エッジ

エッジは fromNode と toNode の ID を介してノードを接続します。

属性	必須	型	デフォルト	説明
id	はい	string	-	一意の識別子
fromNode	はい	string	-	接続元ノードの ID
fromSide	いいえ	string	-	top、right、bottom、または left
fromEnd	いいえ	string	none	none または arrow
toNode	はい	string	-	接続先ノードの ID
toSide	いいえ	string	-	top、right、bottom、または left
toEnd	いいえ	string	arrow	none または arrow
color	いいえ	canvasColor	-	線の色
label	いいえ	string	-	テキストラベル

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

色

canvasColor 型は、16 進数文字列またはプリセット番号のいずれかを受け付けます。

プリセット	色
"1"	赤
"2"	オレンジ
"3"	黄
"4"	緑
"5"	シアン
"6"	紫

プリセットの色の値は意図的に未定義です -- アプリケーションは独自のブランドカラーを使用します。

ID の生成

16 文字の小文字 16 進数文字列（64 ビットのランダム値）を生成します。

"6f0ad84f44ce9c17"
"a3b2c1d0e9f8a7b6"

レイアウトのガイドライン

• 座標は負の値にできます（キャンバスは無限に広がります）
• x は右方向、y は下方向に増加します。位置は左上隅です
• ノードは 50～100px 離して配置します。グループ内には 20～50px の余白を残します
• グリッド（10 または 20 の倍数）に揃えると、より整ったレイアウトになります

ノードの種類	推奨幅	推奨高さ
短いテキスト	200-300	80-150
中程度のテキスト	300-450	150-300
長いテキスト	400-600	300-500
ファイルプレビュー	300-500	200-400
リンクプレビュー	250-400	100-200

検証チェックリスト

キャンバスファイルを作成または編集した後、次を確認します。

1. すべての id 値がノードとエッジの両方を通じて一意である
2. すべての fromNode と toNode が既存のノード ID を参照している
3. 各ノードの種類に必須フィールドが存在する（テキストノードには text、ファイルノードには file、リンクノードには url）
4. type が text、file、link、group のいずれかである
5. fromSide/toSide の値が top、right、bottom、left のいずれかである
6. fromEnd/toEnd の値が none、arrow のいずれかである
7. カラープリセットが "1" から "6"、または有効な 16 進数（例: "#FF0000"）である
8. JSON が有効で解析可能である

検証が失敗した場合は、重複した ID、ぶら下がったエッジ参照、または不正な JSON 文字列（特にテキストコンテンツ内のエスケープされていない改行）を確認してください。

完全な例

マインドマップ、プロジェクトボード、リサーチキャンバス、フローチャートを含む完全なキャンバスの例については、references/EXAMPLES.md を参照してください。

参考資料

• JSON Canvas Spec 1.0
• JSON Canvas GitHub