Kanban Studio›Markdown & JSON Reference

📝

Markdown & JSON Reference

Full schema reference for board editing

Overview

Every Kanban board is backed by a plain-text Markdown document you can read, write, copy, and version-control. The document has two sections: a machine-readable Structured block holding the board data as JSON, and a free-form Custom block for your personal notes.

Schema v1JSON + MarkdownDry-run safe

💡

Always dry-run first

Before clicking Apply, use the Dry-run button to validate your edits. The backend will report errors and a diff summary without modifying your board.

Document Structure

A full Kanban Markdown document is composed of three parts:

A human-readable header (board title, generation note)
The Structured block — JSON data between HTML comment markers
The Custom block — free Markdown (notes, Mermaid diagrams, links)

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 -->

Complete board document with all sections annotated

⚠️

Do not remove the comment markers

The markers , , , and  are required. Removing them causes a parse error.

Columns

Columns define the workflow stages of your board. They are rendered left-to-right by their order value.

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 }
]

Example: four columns with distinct colors

Field	Type	Required	Default	Description
`id`	string	Yes	—	Unique column identifier (UUID or any stable slug)
`title`	string	Yes	—	Column heading shown on the board
`color`	string	Yes	`#64748b`	Column accent color (hex). Shown as left border on cards
`order`	integer	Yes	—	Zero-based display order (ascending, left-to-right)

ℹ️

Note

Column IDs must be unique within the board. Tasks reference columns by this `id`.

Tasks

Tasks are the core unit of work. Each task lives inside a column (via columnId) and is sorted by position within that column.

Minimal task

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": []
}

Only required fields filled — all optional fields are null / empty

Full task with all fields

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 }
  ]
}

Production example with priority, tags, assignees, checklist, time tracking

Field	Type	Required	Default	Description
`id`	string	Yes	—	Unique task identifier (UUID or stable slug)
`columnId`	string	Yes	—	ID of the column this task belongs to
`position`	integer	Yes	—	Zero-based sort order within the column
`title`	string	Yes	—	Task title (1–280 characters)
`description`	string	No	`""`	Markdown-compatible longer description
`priority`	enum "low""medium""high""critical"	No	`medium`	Task urgency level
`tags`	string[]	No	`[]`	Free-form label strings for filtering and grouping
`assigneeIds`	string[]	No	`[]`	Member IDs of people assigned to this task
`mentionMemberIds`	string[]	No	`[]`	Member IDs mentioned (notified) in this task
`estimatePoints`	integer\|null	No	`null`	Story-point estimate (Fibonacci: 1, 2, 3, 5, 8, 13…)
`dueDate`	string\|null	No	`null`	ISO 8601 date string: YYYY-MM-DD
`plannedStartAt`	string\|null	No	`null`	ISO 8601 datetime: planned start
`plannedEndAt`	string\|null	No	`null`	ISO 8601 datetime: planned end
`timeboxMinutes`	integer\|null	No	`null`	Focus-session length for time-boxing
`isCompleted`	boolean	No	`false`	Marks the task as done (adds strikethrough in UI)
`archivedAt`	string\|null	No	`null`	ISO 8601 datetime when task was archived. Archived tasks are hidden from the board
`checklist`	object[]	No	`[]`	Sub-task checklist items (see Checklist section)

Checklist Items

Each task supports a flat list of checklist items — lightweight sub-tasks that can be individually marked done without creating separate tasks.

JSON

"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]

Three checklist items: first one done, two remaining

Field	Type	Required	Default	Description
`title`	string	Yes	—	Checklist item label (1–255 characters)
`isDone`	boolean	Yes	—	Whether this item is checked off

Custom Notes Section

Everything between  and  is your scratchpad. It supports full Markdown and Mermaid diagrams. The content is never parsed by the board engine — it is only shown in the Preview tab.

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 -->

Notes with a Mermaid Gantt chart

💡

Tip

Use the Custom section for sprint notes, team links, Gantt charts, architecture diagrams — anything you want visible alongside your board data.

Priority Values

The priority field accepts exactly one of four values. Each maps to a distinct badge color in the UI:

Field	Type	Required	Default	Description
`low`	enum value	No	—	Low urgency. Shown in slate/grey.
`medium`	enum value	No	—	Default. Shown in amber/yellow. Omitting priority defaults to this.
`high`	enum value	No	—	Important. Shown in orange.
`critical`	enum value	No	—	Blocking. Shown in red/rose.

Archiving Tasks

To archive a task, set its archivedAt field to an ISO datetime string. Archived tasks are excluded from the active board view but preserved in history.

JSON

{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}

Archived task — hidden from board, preserved in snapshot

ℹ️

Note

Setting archivedAt to null un-archives the task. The diff summary will show tasksToArchive when applying a markdown snapshot that archives tasks currently active on the board.

Dry-run & Diagnostics

The Dry-run feature validates your markdown without applying changes. The backend returns a diffSummary (what would change) and a diagnostics array listing any errors or warnings.

Successful dry-run response

JSON

{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}

ok: true means the markdown is valid and safe to apply

Dry-run with errors

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 — fix errors before applying

Field	Type	Required	Default	Description
`code`	string	Yes	—	Machine-readable error code (e.g. unknown_column_id)
`message`	string	Yes	—	Human-readable description of the issue
`line`	integer	Yes	—	Approximate line number in the markdown document
`severity`	enum "error""warning"	Yes	—	Either 'error' (blocks apply) or 'warning' (apply proceeds)

🚫

Errors block Apply

If diagnostics contains any item with severity: 'error', the Apply operation will refuse to proceed. Warnings are advisory and do not block.

Recommended Workflow

Follow this flow when editing the board via Markdown:

Open the Markdown panel on your board
Edit the JSON in the Structured block — add/modify columns or tasks
Click Dry-run to validate without changing anything
Fix any errors shown in the diagnostics list
Click Apply to commit changes to the live board
Use Download to save a local .md backup

💡

Version control tip

Because the document is plain text, you can paste it into a Git repository, diff versions, and restore previous board states by re-applying an older snapshot.