Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

Обзор

Каждая доска Канбан поддерживается обычным текстовым документом Markdown, который вы можете читать, писать, копировать и контролировать версии. Документ состоит из двух разделов: машиночитаемого блока Структурированный, содержащего данные доски в формате JSON, и блока Пользовательский произвольной формы для ваших личных заметок.

Схема v1JSON + МаркдаунБезопасный сухой ход
💡

Всегда сначала проводите сухой прогон

Прежде чем нажать «Применить», используйте кнопку «Пробный прогон», чтобы подтвердить внесенные изменения. Серверная часть сообщит об ошибках и предоставит сводную информацию о различиях без внесения изменений в вашу плату.

Структура документа

Полный документ Kanban Markdown состоит из трех частей:

  • Удобочитаемый заголовок (заголовок доски, примечание о поколении)
  • Структурированный блок — данные JSON между маркерами комментариев HTML.
  • Пользовательский блок — бесплатный Markdown (заметки, диаграммы Русалок, ссылки)
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 }
]
Пример: четыре столбца разных цветов.
FieldTypeRequiredDescription
idstringYesУникальный идентификатор столбца (UUID или любой стабильный фрагмент)
titlestringYesЗаголовок столбца отображается на доске
colorstringYesЦвет акцента столбца (шестнадцатеричный). Отображается как левая граница на карточках
orderintegerYesПорядок отображения с отсчетом от нуля (по возрастанию, слева направо)
ℹ️

Note

Идентификаторы столбцов должны быть уникальными внутри доски. Задачи ссылаются на столбцы по этому 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": []
}
Заполнены только обязательные поля — все необязательные поля пусты.

Полное задание со всеми полями

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Идентификатор столбца, к которому принадлежит эта задача
positionintegerYesПорядок сортировки с отсчетом от нуля внутри столбца
titlestringYesНазвание задачи (1–280 символов)
descriptionstringNoПодробное описание, совместимое с Markdown
priorityenum
"low""medium""high""critical"
NoУровень срочности задачи
tagsstring[]NoСтроки меток произвольной формы для фильтрации и группировки.
assigneeIdsstring[]NoИдентификаторы участников людей, которым назначена эта задача
mentionMemberIdsstring[]NoИдентификаторы участников, упомянутые (уведомленные) в этой задаче
estimatePointsinteger|nullNoОценка сюжетных точек (Фибоначчи: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoСтрока даты ISO 8601: ГГГГ-ММ-ДД.
plannedStartAtstring|nullNoДата и время ISO 8601: запланированное начало
plannedEndAtstring|nullNoДата и время ISO 8601: запланированное завершение
timeboxMinutesinteger|nullNoПродолжительность фокус-сессии для тайм-бокса
isCompletedbooleanNoОтмечает задачу как выполненную (добавляет зачеркивание в пользовательском интерфейсе)
archivedAtstring|nullNoДата и время ISO 8601, когда задача была заархивирована. Архивированные задачи скрыты с доски
checklistobject[]NoПункты контрольного списка подзадач (см. раздел Контрольный список)

Пункты контрольного списка

Каждая задача поддерживает плоский список элементов контрольного списка — легкие подзадачи, которые можно индивидуально пометить как выполненные, не создавая отдельные задачи.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
Три пункта контрольного списка: первый выполнен, осталось два.
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 принимает ровно одно из четырех значений. Каждому соответствует отдельный цвет значка в пользовательском интерфейсе:

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
  }
}
ок: 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Машиночитаемый код ошибки (например,known_column_id)
messagestringYesПонятное описание проблемы
lineintegerYesПриблизительный номер строки в документе уценки
severityenum
"error""warning"
YesЛибо «ошибка» (блокировка применяется), либо «предупреждение» (применяется выручка)
🚫

Блок ошибок Применить

Если диагностика содержит какой-либо элемент с уровнем серьезности: «ошибка», операция «Применить» не будет продолжена. Предупреждения носят рекомендательный характер и не блокируют.

Рекомендуемый рабочий процесс

Следуйте этому алгоритму при редактировании доски через Markdown:

  • Откройте панель Markdown на своей доске.
  • Отредактируйте JSON в Структурированном блоке — добавьте/измените столбцы или задачи.
  • Нажмите Пробный запуск, чтобы подтвердить ничего не меняя.
  • Исправьте все ошибки, показанные в списке диагностики.
  • Нажмите Применить, чтобы внести изменения в живую доску.
  • Используйте Загрузить, чтобы сохранить локальную резервную копию .md
💡

Совет по контролю версий

Поскольку документ представляет собой обычный текст, вы можете вставить его в репозиторий Git, сравнить версии и восстановить предыдущие состояния платы, повторно применив старый снимок.

Schema v1 · Updated September 2026