Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

Visão geral

Cada quadro Kanban é apoiado por um documento Markdown de texto simples que você pode ler, escrever, copiar e controlar a versão. O documento tem duas seções: um bloco Estruturado legível por máquina que contém os dados do quadro como JSON e um bloco Personalizado de formato livre para suas anotações pessoais.

Esquema v1JSON + reduçãoSeguro contra funcionamento a seco
💡

Sempre faça o teste primeiro

Antes de clicar em Aplicar, use o botão Teste para validar suas edições. O back-end reportará erros e um resumo das diferenças sem modificar seu quadro.

Estrutura do Documento

Um documento Kanban Markdown completo é composto de três partes:

  • Um cabeçalho legível (título do quadro, nota de geração)
  • O bloco estruturado — dados JSON entre marcadores de comentários HTML
  • O Bloco personalizado — Markdown gratuito (notas, diagramas de sereia, 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 -->
Documento completo do conselho com todas as seções anotadas
⚠️

Não remova os marcadores de comentários

Os marcadores <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> são obrigatórios. Removê-los causa um erro de análise.

Colunas

As colunas definem os estágios do fluxo de trabalho do seu quadro. Eles são renderizados da esquerda para a direita por seu valor 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 }
]
Exemplo: quatro colunas com cores distintas
FieldTypeRequiredDescription
idstringYesIdentificador de coluna exclusivo (UUID ou qualquer slug estável)
titlestringYesTítulo da coluna mostrado no quadro
colorstringYesCor de destaque da coluna (hex). Mostrado como borda esquerda nos cartões
orderintegerYesOrdem de exibição baseada em zero (crescente, da esquerda para a direita)
ℹ️

Note

Os IDs das colunas devem ser exclusivos no quadro. Colunas de referência de tarefas por este id.

Tarefas

As tarefas são a unidade central do trabalho. Cada tarefa reside dentro de uma coluna (via columnId) e é classificada por position dentro dessa coluna.

Tarefa mínima

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": []
}
Somente campos obrigatórios preenchidos — todos os campos opcionais são nulos/vazios

Tarefa completa com todos os campos

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 }
  ]
}
Exemplo de produção com prioridade, tags, responsáveis, checklist, controle de tempo
FieldTypeRequiredDescription
idstringYesIdentificador exclusivo de tarefa (UUID ou slug estável)
columnIdstringYesID da coluna à qual esta tarefa pertence
positionintegerYesOrdem de classificação baseada em zero na coluna
titlestringYesTítulo da tarefa (1–280 caracteres)
descriptionstringNoDescrição mais longa compatível com Markdown
priorityenum
"low""medium""high""critical"
NoNível de urgência da tarefa
tagsstring[]NoStrings de rótulos de formato livre para filtragem e agrupamento
assigneeIdsstring[]NoIDs de membros de pessoas atribuídas a esta tarefa
mentionMemberIdsstring[]NoIDs de membros mencionados (notificados) nesta tarefa
estimatePointsinteger|nullNoEstimativa de pontos da história (Fibonacci: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoSequência de data ISO 8601: AAAA-MM-DD
plannedStartAtstring|nullNoData e hora ISO 8601: início planejado
plannedEndAtstring|nullNoData e hora ISO 8601: fim planejado
timeboxMinutesinteger|nullNoDuração da sessão de foco para time-boxing
isCompletedbooleanNoMarca a tarefa como concluída (adiciona tachado na interface do usuário)
archivedAtstring|nullNoData e hora ISO 8601 quando a tarefa foi arquivada. As tarefas arquivadas ficam ocultas no quadro
checklistobject[]NoItens da lista de verificação de subtarefas (consulte a seção Lista de verificação)

Itens da lista de verificação

Cada tarefa suporta uma lista simples de itens da lista de verificação – subtarefas leves que podem ser marcadas individualmente como concluídas sem criar tarefas separadas.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
Três itens da lista de verificação: o primeiro concluído, dois restantes
FieldTypeRequiredDescription
titlestringYesEtiqueta do item da lista de verificação (1–255 caracteres)
isDonebooleanYesSe este item está marcado

Seção de notas personalizadas

Tudo entre <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> é o seu bloco de notas. Ele suporta diagramas Markdown e Mermaid completos. O conteúdo nunca é analisado pelo mecanismo da placa — ele é mostrado apenas na guia Visualização.

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 -->
Notas com um gráfico Mermaid Gantt
💡

Tip

Use a seção Personalizada para notas de sprint, links de equipe, gráficos de Gantt, diagramas de arquitetura – tudo o que você deseja que fique visível junto com os dados do quadro.

Valores prioritários

O campo priority aceita exatamente um dos quatro valores. Cada um mapeia para uma cor de emblema distinta na IU:

FieldTypeRequiredDescription
lowenum valueNoBaixa urgência. Mostrado em ardósia/cinza.
mediumenum valueNoPadrão. Mostrado em âmbar/amarelo. Omitir o padrão de prioridade para isso.
highenum valueNoImportante. Mostrado em laranja.
criticalenum valueNoBloqueio. Mostrado em vermelho/rosa.

Arquivando Tarefas

Para arquivar uma tarefa, defina seu campo archivedAt como uma string de data e hora ISO. As tarefas arquivadas são excluídas da visualização ativa do quadro, mas preservadas no histórico.

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
Tarefa arquivada – oculta do quadro, preservada no instantâneo
ℹ️

Note

Definir archivedAt como null desarquiva a tarefa. O resumo de diferenças mostrará tasksToArchive ao aplicar um instantâneo de redução que arquiva as tarefas atualmente ativas no quadro.

Teste e diagnóstico

O recurso Dry-run valida sua redução sem aplicar alterações. O backend retorna um array diffSummary (o que mudaria) e um array diagnostics listando quaisquer erros ou avisos.

Resposta de simulação bem-sucedida

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: verdadeiro significa que a redução é válida e segura para ser aplicada

Teste com erros

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 – corrija os erros antes de aplicar
FieldTypeRequiredDescription
codestringYesCódigo de erro legível por máquina (por exemplo, desconhecido_column_id)
messagestringYesDescrição legível do problema
lineintegerYesNúmero aproximado da linha no documento de redução
severityenum
"error""warning"
YesOu 'erro' (aplicam-se bloqueios) ou 'aviso' (aplicam-se procedimentos)
🚫

Bloco de erros Aplicar

Se o diagnóstico contiver algum item com gravidade: 'erro', a operação Aplicar se recusará a prosseguir. Os avisos são consultivos e não bloqueiam.

Fluxo de trabalho recomendado

Siga este fluxo ao editar o quadro via Markdown:

  • Abra o painel Markdown em seu quadro
  • Edite o JSON no Bloco estruturado — adicione/modifique colunas ou tarefas
  • Clique em Teste para validar sem alterar nada
  • Corrija quaisquer erros mostrados na lista de diagnósticos
  • Clique em Aplicar para confirmar as alterações no quadro ativo
  • Use Download para salvar um backup local .md
💡

Dica de controle de versão

Como o documento é um texto simples, você pode colá-lo em um repositório Git, comparar versões e restaurar estados anteriores do quadro reaplicando um instantâneo mais antigo.

Schema v1 · Updated September 2026