Lifecycle: HISTORICAL (published KEEP). For the promoted reader route, see Kanboard unified schema.

🗃️ Kanboard Unified JSON Data Schema

This cheat sheet outlines the exact structure, data merging logic, and best practices for dealing with the unified Kanboard & Feedback JSON export/import format.

🏗️ Core Architecture

The structure is a hybrid payload enabling the single-source-of-truth (SSOT) fusion of both the project management Kanban board and the per-game feedback item boards.

1️⃣ Root Object

{
  "exportedAt": "2026-03-20T02:05:37.129Z",
  "source": "kanboard-unified",
  "board": { ... },    // The global developer kanboard
  "feedback": { ... } // The multi-game feedback system
}

🎯 Tip: Always check source === “kanboard-unified” to validate file integrity before running deep merge operations.

2️⃣ Board Structure (`root.board`)

The primary kanboard uses a column-first relationship mapping combined with a normalized task dictionary.

board.columns: Array of columns determining structure and WIP limits.
board.columns[].taskIds: The exact ordered array of strings referencing tasks.
board.tasks: An object map (Record<string, Task>) containing the actual task metadata.

Task Metadata Schema:

id (string)
title (string)
description (string)
tags (string[])
assignee (string)
priority (High | Medium | Low)
estimate (number)
color (string - hex)
createdAt / dueDate (timestamps/strings)

3️⃣ Feedback Structure (`root.feedback`)

The feedback system nests items by their exact gameId directly mapping to the Nakama collections.

feedback.totalGames & totalTickets: Helpful metric scalars.
feedback.boards: Object map keyed by gameId (e.g., "bombergang": { ... }).
feedback.boards[gameId].board.items: Array of feedback objects.

Feedback Item Schema:

id (string - generated via prefix e.g., fb-1773491499934-389s)
title (string)
description (string)
status (open | closed | resolved)
category (Bug | Idea | UX | Visual | Balance)
priority (High | Medium | Low)
createdAt (timestamp number)

🧬 Data Fusion (SSOT) Rules

When importing this JSON, the engine applies specific Deep Merge logic:

Never Duplicate: Checks incoming items against existing items using exact id matching.
Preserve State: If a task or feedback item already exists, do not overwrite its current state (preventing loss of live progress).
Smart Append: Append missing taskIds to the Done or Backlog columns to avoid violating strict wipLimits in the active columns.
Reactivity: Svelte 5 $state arrays (e.g. feedbackItems) must trigger reassignment feedbackItems = [...newSet] to guarantee view updates.

🚀 Pro-Tips

Emojis & Readability: Always render feedback categories with their respective icons/emojis (🐛 Bug, 🎨 Visual, ⚖️ Balance) in the UI.
Inline Promotion: Feedback items are easily promoted to Kanboard tasks by porting their stringified properties into a new task-xxx object and inserting into board.tasks.
Nakama Storage: The entire object should be stored as JSON objects in the global backend config collection to enable real-time multiplayer syncing of dev boards.

Kanboard unified schema