D
Datronis
Kanban Studio›Markdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

概要

すべてのかんばんボードは、読み取り、書き込み、コピー、およびバージョン管理が可能なプレーンテキストの Markdown ドキュメントによって裏付けられています。このドキュメントには 2 つのセクションがあります。1 つはボード データを JSON として保持する機械可読な 構造化 ブロック、もう 1 つは個人的なメモ用の自由形式の カスタム ブロックです。

スキーマ v1JSON + マークダウンドライランセーフ
💡

常に最初に予行運転を行う

「適用」をクリックする前に、「ドライラン」ボタンを使用して編集内容を検証します。バックエンドは、ボードを変更せずにエラーと差分の概要を報告します。

文書構造

完全な Kanban Markdown ドキュメントは、次の 3 つの部分で構成されます。

  • 人間が判読できるヘッダー (ボードのタイトル、世代ノート)
  • 構造化ブロック — HTML コメント マーカー間の JSON データ
  • カスタム ブロック — 無料のマークダウン (メモ、人魚図、リンク)
board.md
# My Project Board

Generated by Kanban Markdown schema v1.

<!-- KANBAN:STRUCTURED:START -->
```kanban-structured
{
  "version": 1,
  "board": {
    "id": "board-abc123",
    "title": "My Project Board"
  },
  "columns": [
    { "id": "col-1", "title": "Backlog",     "color": "#64748b", "order": 0 },
    { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
    { "id": "col-3", "title": "Done",        "color": "#10b981", "order": 2 }
  ],
  "tasks": [
    {
      "id": "task-1",
      "columnId": "col-2",
      "position": 0,
      "title": "Build authentication flow",
      "description": "Implement JWT login, register, and token refresh.",
      "priority": "high",
      "tags": ["backend", "security"],
      "assigneeIds": ["member-uuid-1"],
      "mentionMemberIds": ["member-uuid-2"],
      "estimatePoints": 5,
      "dueDate": "2025-03-15",
      "plannedStartAt": "2025-03-10",
      "plannedEndAt": "2025-03-15",
      "timeboxMinutes": 90,
      "isCompleted": false,
      "archivedAt": null,
      "checklist": [
        { "title": "Design DB schema",   "isDone": true  },
        { "title": "Write unit tests",   "isDone": false },
        { "title": "Deploy to staging",  "isDone": false }
      ]
    }
  ]
}
```
<!-- KANBAN:STRUCTURED:END -->

<!-- KANBAN:CUSTOM:START -->
## Team Notes

- Sprint ends Friday
- Backend review at 3 PM

```mermaid
flowchart LR
  A[Backlog] --> B[In Progress] --> C[Done]
```
<!-- KANBAN:CUSTOM:END -->
すべてのセクションに注釈が付けられた完全なボード文書
⚠️

コメントマーカーは削除しないでください

マーカー <!-- KANBAN:STRUCTURED:START -->、<!-- KANBAN:STRUCTURED:END -->、<!-- KANBAN:CUSTOM:START -->、および <!-- KANBAN:CUSTOM:END --> は必須です。これらを削除すると、解析エラーが発生します。

コラム

列はボードのワークフロー ステージを定義します。これらは、order 値によって左から右にレンダリングされます。

JSON
"columns": [
  { "id": "col-1", "title": "To Do",       "color": "#64748b", "order": 0 },
  { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
  { "id": "col-3", "title": "Review",      "color": "#f59e0b", "order": 2 },
  { "id": "col-4", "title": "Done",        "color": "#10b981", "order": 3 }
]
例: 異なる色を持つ 4 つの列
FieldTypeRequiredDescription
idstringYes一意の列識別子 (UUID または任意の安定したスラッグ)
titlestringYesボードに表示される列見出し
colorstringYes列のアクセントカラー (16 進数)。カードの左枠として表示されます
orderintegerYes0 から始まる表示順序 (昇順、左から右)
ℹ️

Note

列 ID はボード内で一意である必要があります。タスクはこの id によって列を参照します。

タスク

タスクは作業の中核単位です。各タスクは列内に存在し (columnId 経由)、その列内の position によって並べ替えられます。

最小限のタスク

JSON
{
  "id": "task-abc",
  "columnId": "col-1",
  "position": 0,
  "title": "Write release notes",
  "description": "",
  "priority": "medium",
  "tags": [],
  "assigneeIds": [],
  "mentionMemberIds": [],
  "estimatePoints": null,
  "dueDate": null,
  "plannedStartAt": null,
  "plannedEndAt": null,
  "timeboxMinutes": null,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": []
}
必須フィールドのみが入力されます。オプションのフィールドはすべて null または空です

すべてのフィールドを含む完全なタスク

JSON
{
  "id": "task-xyz",
  "columnId": "col-2",
  "position": 0,
  "title": "Redesign checkout page",
  "description": "Full UX overhaul based on user research findings.",
  "priority": "critical",
  "tags": ["ux", "frontend", "q1-goal"],
  "assigneeIds": ["member-alice", "member-bob"],
  "mentionMemberIds": ["member-pm"],
  "estimatePoints": 8,
  "dueDate": "2025-04-01",
  "plannedStartAt": "2025-03-20",
  "plannedEndAt": "2025-04-01",
  "timeboxMinutes": 120,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": [
    { "title": "User interviews",       "isDone": true  },
    { "title": "Wireframes approved",   "isDone": true  },
    { "title": "Implement components",  "isDone": false },
    { "title": "A/B test live",         "isDone": false }
  ]
}
優先順位、タグ、担当者、チェックリスト、時間追跡を含む制作例
FieldTypeRequiredDescription
idstringYes一意のタスク識別子 (UUID または安定したスラッグ)
columnIdstringYesこのタスクが属する列のID
positionintegerYes列内のゼロベースのソート順序
titlestringYesタスクのタイトル (1 ～ 280 文字)
descriptionstringNoMarkdown互換の長い説明
priorityenum
"low""medium""high""critical"
Noタスクの緊急度
tagsstring[]Noフィルタリングとグループ化のための自由形式のラベル文字列
assigneeIdsstring[]Noこのタスクに割り当てられた人のメンバー ID
mentionMemberIdsstring[]Noこのタスクで言及（通知）されたメンバー ID
estimatePointsinteger|nullNoストーリーポイント推定 (フィボナッチ: 1、2、3、5、8、13…)
dueDatestring|nullNoISO 8601 日付文字列: YYYY-MM-DD
plannedStartAtstring|nullNoISO 8601 日時: 開始予定
plannedEndAtstring|nullNoISO 8601 日時: 終了予定
timeboxMinutesinteger|nullNoタイムボックス化のフォーカスセッションの長さ
isCompletedbooleanNoタスクを完了としてマークします (UI に取り消し線を追加します)
archivedAtstring|nullNoタスクがアーカイブされた ISO 8601 日時。アーカイブされたタスクはボードに表示されません
checklistobject[]Noサブタスクのチェックリスト項目 (「チェックリスト」セクションを参照)

チェックリストの項目

各タスクはチェックリスト項目のフラット リストをサポートしています。これは、個別のタスクを作成せずに個別に完了のマークを付けることができる軽量のサブタスクです。

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
3 つのチェックリスト項目: 最初の 1 つは完了、残り 2 つ
FieldTypeRequiredDescription
titlestringYesチェックリスト項目ラベル (1 ～ 255 文字)
isDonebooleanYesこの項目にチェックが入っているかどうか

カスタムメモセクション

<!-- KANBAN:CUSTOM:START --> と <!-- KANBAN:CUSTOM:END --> の間にあるものはすべてスクラッチパッドです。完全な Markdown および Mermaid 図をサポートします。コンテンツはボード エンジンによって解析されることはありません。[プレビュー] タブにのみ表示されます。

Markdown
<!-- KANBAN:CUSTOM:START -->
## Sprint Notes

- Daily standup at 10:00 AM
- Backend API freeze on Friday

```mermaid
gantt
  title Sprint 12
  section Tasks
  Auth flow     :done, 2025-03-10, 3d
  Dashboard UI  :active, 2025-03-13, 4d
  API docs      :2025-03-17, 2d
```

> Reminder: update JIRA tickets before end of day.
<!-- KANBAN:CUSTOM:END -->
マーメイド ガント チャートを使用したメモ
💡

Tip

スプリント ノート、チーム リンク、ガント チャート、アーキテクチャ図など、ボード データと一緒に表示したいものはすべて [カスタム] セクションを使用します。

優先順位の値

priority フィールドは、4 つの値のうち 1 つだけを受け入れます。それぞれが UI 内の個別のバッジの色にマッピングされます。

FieldTypeRequiredDescription
lowenum valueNo緊急性が低い。スレート/グレーで表示されます。
mediumenum valueNoデフォルト。琥珀色/黄色で表示されます。優先順位を省略すると、デフォルトでこれが設定されます。
highenum valueNo重要です。オレンジ色で表示されます。
criticalenum valueNoブロッキング。レッド/ローズで表示されます。

タスクのアーカイブ

タスクをアーカイブするには、archivedAt フィールドを ISO 日時文字列に設定します。アーカイブされたタスクはアクティブなボード ビューから除外されますが、履歴には保存されます。

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
アーカイブされたタスク — ボードから非表示になり、スナップショットに保存されます
ℹ️

Note

archivedAt を null に設定すると、タスクのアーカイブが解除されます。ボード上で現在アクティブなタスクをアーカイブするマークダウン スナップショットを適用すると、差分サマリーに taskToArchive が表示されます。

ドライランと診断

ドライラン機能は、変更を適用せずにマークダウンを検証します。バックエンドは diffSummary (変更内容) と、エラーまたは警告をリストした diagnostics 配列を返します。

成功した予行演習の応答

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: true は、マークダウンが有効であり、安全に適用できることを意味します

エラーのある予行演習

JSON
{
  "ok": false,
  "dryRun": true,
  "diagnostics": [
    {
      "code": "unknown_column_id",
      "message": "Task 'task-xyz' references unknown column 'col-999'.",
      "line": 42,
      "severity": "error"
    },
    {
      "code": "duplicate_task_id",
      "message": "Task ID 'task-abc' is used more than once.",
      "line": 67,
      "severity": "error"
    }
  ],
  "diffSummary": {
    "columnsCreated": 0,
    "columnsTouched": 0,
    "tasksCreated": 0,
    "tasksTouched": 0,
    "tasksToArchive": 0
  }
}
ok: false — 適用する前にエラーを修正します
FieldTypeRequiredDescription
codestringYes機械可読エラーコード (unknown_column_id など)
messagestringYes人間が読める問題の説明
lineintegerYesマークダウンドキュメント内のおおよその行番号
severityenum
"error""warning"
Yes「エラー」(ブロックが適用される) または「警告」(適用が続行される) のいずれか
🚫

エラーブロック適用

診断に重大度「エラー」の項目が含まれている場合、適用操作は続行を拒否します。警告は勧告であり、ブロックするものではありません。

推奨されるワークフロー

Markdown 経由でボードを編集する場合は、次のフローに従います。

  • ボード上で Markdown パネルを開きます
  • 構造化ブロックで JSON を編集します — 列またはタスクを追加/変更します
  • [ドライラン] をクリックして、何も変更せずに検証します。
  • 診断リストに表示されたエラーを修正します。
  • 適用 をクリックしてライブボードへの変更をコミットします
  • ダウンロードを使用してローカル .md バックアップを保存します
💡

バージョン管理のヒント

ドキュメントはプレーン テキストであるため、Git リポジトリに貼り付けたり、バージョンの差分を取得したり、古いスナップショットを再適用して以前のボードの状態を復元したりできます。

Schema v1 · Updated September 2026