Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

Panoramica

Ogni lavagna Kanban è supportata da un documento Markdown in testo semplice che puoi leggere, scrivere, copiare e controllare la versione. Il documento ha due sezioni: un blocco Strutturato leggibile dalla macchina che contiene i dati della scheda come JSON e un blocco Personalizzato in formato libero per le tue note personali.

Schema v1JSON + RibassoSicuro per il funzionamento a secco
💡

Prima eseguire sempre un test a secco

Prima di fare clic su Applica, utilizzare il pulsante Prova per convalidare le modifiche. Il backend riporterà gli errori e un riepilogo delle differenze senza modificare la scheda.

Struttura del documento

Un documento Kanban Markdown completo è composto da tre parti:

  • Un'intestazione leggibile dall'uomo (titolo della scheda, nota di generazione)
  • Il blocco strutturato: dati JSON tra marcatori di commenti HTML
  • Il Blocco personalizzato: Markdown gratuito (note, diagrammi delle sirene, collegamenti)
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 di bordo completo con tutte le sezioni annotate
⚠️

Non rimuovere i marcatori di commento

I marcatori <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> sono obbligatori. La loro rimozione provoca un errore di analisi.

Colonne

Le colonne definiscono le fasi del flusso di lavoro della tua scheda. Sono visualizzati da sinistra a destra in base al loro valore 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 }
]
Esempio: quattro colonne con colori distinti
FieldTypeRequiredDescription
idstringYesIdentificatore univoco della colonna (UUID o qualsiasi slug stabile)
titlestringYesIntestazione della colonna mostrata sulla lavagna
colorstringYesColore in risalto della colonna (esadecimale). Mostrato come bordo sinistro sulle carte
orderintegerYesOrdine di visualizzazione in base zero (ascendente, da sinistra a destra)
ℹ️

Note

Gli ID delle colonne devono essere univoci all'interno della scheda. Le attività fanno riferimento alle colonne tramite questo id.

Compiti

I compiti sono l’unità centrale del lavoro. Ogni attività si trova all'interno di una colonna (tramite columnId) ed è ordinata per position all'interno di quella colonna.

Compito minimo

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": []
}
Compilati solo i campi obbligatori: tutti i campi facoltativi sono nulli/vuoti

Attività completa con tutti i campi

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 }
  ]
}
Esempio di produzione con priorità, tag, assegnatari, lista di controllo, monitoraggio del tempo
FieldTypeRequiredDescription
idstringYesIdentificatore univoco dell'attività (UUID o slug stabile)
columnIdstringYesID della colonna a cui appartiene questa attività
positionintegerYesOrdinamento in base zero all'interno della colonna
titlestringYesTitolo dell'attività (1–280 caratteri)
descriptionstringNoDescrizione più lunga compatibile con Markdown
priorityenum
"low""medium""high""critical"
NoLivello di urgenza dell'attività
tagsstring[]NoStringhe di etichette in formato libero per filtrare e raggruppare
assigneeIdsstring[]NoID membro delle persone assegnate a questa attività
mentionMemberIdsstring[]NoID membro menzionati (notificati) in questa attività
estimatePointsinteger|nullNoStima del punto della storia (Fibonacci: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoStringa della data ISO 8601: AAAA-MM-GG
plannedStartAtstring|nullNoData e ora ISO 8601: inizio pianificato
plannedEndAtstring|nullNoData e ora ISO 8601: fine pianificata
timeboxMinutesinteger|nullNoDurata della sessione focus per il timeboxing
isCompletedbooleanNoContrassegna l'attività come completata (aggiunge barrato nell'interfaccia utente)
archivedAtstring|nullNoData e ora ISO 8601 in cui l'attività è stata archiviata. Le attività archiviate sono nascoste dalla bacheca
checklistobject[]NoElementi dell'elenco di controllo delle attività secondarie (vedere la sezione Elenco di controllo)

Elementi della lista di controllo

Ogni attività supporta un elenco semplice di elementi della lista di controllo: attività secondarie leggere che possono essere contrassegnate individualmente come completate senza creare attività separate.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
Tre elementi della lista di controllo: il primo fatto, due rimanenti
FieldTypeRequiredDescription
titlestringYesEtichetta dell'elemento dell'elenco di controllo (1–255 caratteri)
isDonebooleanYesSe questo elemento è selezionato

Sezione note personalizzate

Tutto tra <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> è il tuo blocco appunti. Supporta i diagrammi Markdown e Sirena completi. Il contenuto non viene mai analizzato dal motore della scheda: viene mostrato solo nella scheda Anteprima.

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 -->
Appunti con un diagramma di Gantt a sirena
💡

Tip

Utilizza la sezione Personalizzata per note sullo sprint, collegamenti al team, diagrammi di Gantt, diagrammi di architettura: tutto ciò che desideri sia visibile insieme ai dati della scheda.

Valori prioritari

Il campo priority accetta esattamente uno dei quattro valori. Ciascuno è associato a un colore distintivo distinto nell'interfaccia utente:

FieldTypeRequiredDescription
lowenum valueNoBassa urgenza. Mostrato in ardesia/grigio.
mediumenum valueNoPredefinito. Mostrato in ambra/giallo. Per impostazione predefinita, l'omissione della priorità è questa.
highenum valueNoImportante. Mostrato in arancione.
criticalenum valueNoBlocco. Mostrato in rosso/rosa.

Attività di archiviazione

Per archiviare un'attività, imposta il suo campo archivedAt su una stringa data/ora ISO. Le attività archiviate vengono escluse dalla visualizzazione attiva della bacheca ma conservate nella cronologia.

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
Attività archiviata: nascosta dalla bacheca, conservata nell'istantanea
ℹ️

Note

L'impostazione di archivedAt su null annulla l'archiviazione dell'attività. Il riepilogo delle differenze mostrerà taskToArchive quando si applica un'istantanea markdown che archivia le attività attualmente attive sulla scheda.

Prova di funzionamento e diagnostica

La funzione di prova convalida il ribasso senza applicare modifiche. Il backend restituisce un diffSummary (cosa cambierebbe) e un array diagnostics che elenca eventuali errori o avvisi.

Risposta di prova riuscita

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: vero significa che il ribasso è valido e sicuro da applicare

Prova con errori

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: falso: correggi gli errori prima dell'applicazione
FieldTypeRequiredDescription
codestringYesCodice di errore leggibile dalla macchina (ad es. Unknown_column_id)
messagestringYesDescrizione leggibile del problema
lineintegerYesNumero di riga approssimativo nel documento di ribasso
severityenum
"error""warning"
YesO "errore" (si applicano i blocchi) o "avviso" (si applicano i proventi)
🚫

Blocco errori Applica

Se la diagnostica contiene elementi con gravità: "errore", l'operazione di applicazione rifiuterà di procedere. Gli avvisi sono consultivi e non bloccano.

Flusso di lavoro consigliato

Segui questo flusso quando modifichi la scheda tramite Markdown:

  • Apri il pannello Markdown sulla tua scheda
  • Modifica il JSON nel Blocco strutturato: aggiungi/modifica colonne o attività
  • Fare clic su Esecuzione di prova per convalidare senza modificare nulla
  • Correggere eventuali errori visualizzati nell'elenco di diagnostica
  • Fai clic su Applica per applicare le modifiche alla bacheca live
  • Utilizza Download per salvare un backup locale .md.
💡

Suggerimento per il controllo della versione

Poiché il documento è di testo semplice, puoi incollarlo in un repository Git, versioni diff e ripristinare gli stati precedenti della scheda riapplicando uno snapshot precedente.

Schema v1 · Updated September 2026