Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

Descripción general

Cada tablero Kanban está respaldado por un documento Markdown de texto sin formato que puede leer, escribir, copiar y controlar las versiones. El documento tiene dos secciones: un bloque Estructurado legible por máquina que contiene los datos del tablero como JSON y un bloque Personalizado de formato libre para sus notas personales.

Esquema v1JSON + RebajaSeguro para funcionamiento en seco
💡

Siempre haga primero el funcionamiento en seco

Antes de hacer clic en Aplicar, utilice el botón Ejecución en seco para validar sus ediciones. El backend informará errores y un resumen de diferencias sin modificar su tablero.

Estructura del documento

Un documento Kanban Markdown completo se compone de tres partes:

  • Un encabezado legible por humanos (título del tablero, nota de generación)
  • El bloque estructurado: datos JSON entre marcadores de comentarios HTML
  • El bloque personalizado: Markdown gratuito (notas, diagramas de sirena, enlaces)
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 del tablero con todas las secciones anotadas.
⚠️

No eliminar los marcadores de comentarios.

Los marcadores <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> y <!-- KANBAN:CUSTOM:END --> son obligatorios. Eliminarlos provoca un error de análisis.

columnas

Las columnas definen las etapas del flujo de trabajo de su tablero. Se representan de izquierda a derecha según su 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 }
]
Ejemplo: cuatro columnas con colores distintos
FieldTypeRequiredDescription
idstringYesIdentificador de columna único (UUID o cualquier slug estable)
titlestringYesEncabezado de columna mostrado en el tablero
colorstringYesColor de acento de columna (hexadecimal). Se muestra como borde izquierdo en las tarjetas.
orderintegerYesOrden de visualización de base cero (ascendente, de izquierda a derecha)
ℹ️

Note

Los ID de las columnas deben ser únicos dentro del tablero. Columnas de referencia de tareas de este id.

Tareas

Las tareas son la unidad central de trabajo. Cada tarea se encuentra dentro de una columna (a través de columnId) y está ordenada por position dentro de esa columna.

Tarea 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": []
}
Solo se llenan los campos obligatorios: todos los campos opcionales son nulos/vacíos

Tarea completa con todos los 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 }
  ]
}
Ejemplo de producción con prioridad, etiquetas, asignados, lista de verificación, seguimiento del tiempo
FieldTypeRequiredDescription
idstringYesIdentificador de tarea único (UUID o slug estable)
columnIdstringYesID de la columna a la que pertenece esta tarea
positionintegerYesOrden de clasificación de base cero dentro de la columna
titlestringYesTítulo de la tarea (1–280 caracteres)
descriptionstringNoDescripción más larga compatible con Markdown
priorityenum
"low""medium""high""critical"
NoNivel de urgencia de la tarea
tagsstring[]NoCadenas de etiquetas de forma libre para filtrar y agrupar
assigneeIdsstring[]NoID de miembro de las personas asignadas a esta tarea
mentionMemberIdsstring[]NoID de miembros mencionados (notificados) en esta tarea
estimatePointsinteger|nullNoEstimación del punto de la historia (Fibonacci: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoCadena de fecha ISO 8601: AAAA-MM-DD
plannedStartAtstring|nullNoFecha y hora ISO 8601: inicio previsto
plannedEndAtstring|nullNoFecha y hora ISO 8601: finalización prevista
timeboxMinutesinteger|nullNoDuración de la sesión de enfoque para el timeboxing
isCompletedbooleanNoMarca la tarea como realizada (agrega tachado en la interfaz de usuario)
archivedAtstring|nullNoFecha y hora ISO 8601 en la que se archivó la tarea. Las tareas archivadas están ocultas del tablero.
checklistobject[]NoElementos de la lista de verificación de subtareas (consulte la sección Lista de verificación)

Elementos de la lista de verificación

Cada tarea admite una lista plana de elementos de la lista de verificación: subtareas livianas que se pueden marcar individualmente sin crear tareas separadas.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
Tres elementos de la lista de verificación: el primero hecho, quedan dos
FieldTypeRequiredDescription
titlestringYesEtiqueta del elemento de la lista de verificación (de 1 a 255 caracteres)
isDonebooleanYesSi este elemento está marcado

Sección de notas personalizadas

Todo lo que esté entre <!-- KANBAN:CUSTOM:START --> y <!-- KANBAN:CUSTOM:END --> es tu bloc de notas. Admite diagramas completos de Markdown y Mermaid. El contenido nunca es analizado por el motor de la placa; solo se muestra en la pestaña Vista previa.

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 con un diagrama de Gantt de sirena
💡

Tip

Utilice la sección Personalizada para notas de sprint, enlaces de equipo, diagramas de Gantt, diagramas de arquitectura: cualquier cosa que desee que esté visible junto con los datos de su tablero.

Valores de prioridad

El campo priority acepta exactamente uno de cuatro valores. Cada uno se asigna a un color de insignia distinto en la interfaz de usuario:

FieldTypeRequiredDescription
lowenum valueNoUrgencia baja. Se muestra en pizarra/gris.
mediumenum valueNoPredeterminado. Se muestra en ámbar/amarillo. Omitir la prioridad por defecto es esto.
highenum valueNoImportante. Se muestra en naranja.
criticalenum valueNoBloqueo. Se muestra en rojo/rosa.

Tareas de archivo

Para archivar una tarea, configure su campo archivedAt en una cadena de fecha y hora ISO. Las tareas archivadas se excluyen de la vista del tablero activo, pero se conservan en el historial.

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
Tarea archivada: oculta del tablero, conservada en una instantánea
ℹ️

Note

Establecer archivedAt en nulo desarchiva la tarea. El resumen de diferencias mostrará tareas para archivar al aplicar una instantánea de rebajas que archiva las tareas actualmente activas en el tablero.

Ejecución en seco y diagnóstico

La función de ejecución en seco valida su descuento sin aplicar cambios. El backend devuelve un diffSummary (lo que cambiaría) y una matriz diagnostics que enumera los errores o advertencias.

Respuesta exitosa al ensayo

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: verdadero significa que la rebaja es válida y segura de aplicar

Ejecución en seco con errores

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: corrige los errores antes de aplicar
FieldTypeRequiredDescription
codestringYesCódigo de error legible por máquina (por ejemplo, desconocido_columna_id)
messagestringYesDescripción legible por humanos del problema
lineintegerYesNúmero de línea aproximado en el documento de rebajas.
severityenum
"error""warning"
YesYa sea 'error' (se aplican bloqueos) o 'advertencia' (se aplican ingresos)
🚫

Bloque de errores Aplicar

Si el diagnóstico contiene algún elemento con gravedad: "error", la operación Aplicar se negará a continuar. Las advertencias son de asesoramiento y no bloquean.

Flujo de trabajo recomendado

Siga este flujo al editar el tablero a través de Markdown:

  • Abre el panel Markdown en tu tablero
  • Edite el JSON en el bloque estructurado: agregue/modifique columnas o tareas
  • Haga clic en Ejecución en seco para validar sin cambiar nada.
  • Corrija los errores que se muestran en la lista de diagnósticos.
  • Haga clic en Aplicar para confirmar los cambios en el tablero en vivo.
  • Utilice Descargar para guardar una copia de seguridad local .md
💡

Consejo de control de versiones

Debido a que el documento es texto sin formato, puede pegarlo en un repositorio de Git, comparar versiones y restaurar estados anteriores del tablero volviendo a aplicar una instantánea anterior.

Schema v1 · Updated September 2026