---
# nbd-s16w
title: Multiple file format support (md, toml, jsonb)
status: completed
type: feature
priority: normal
created_at: 2026-03-10T23:30:30Z
updated_at: 2026-03-10T23:30:30Z
---

Add `--ftype` flag to `create` and `update` to write tickets in markdown, TOML, or binary JSON (CBOR) in addition to the existing JSON format. Format is detected from file extension on read.

## Motivation

Markdown format lets agents write long-form ticket bodies with full markdown syntax, and makes tickets human-readable in a file browser. TOML is a natural config format. CBOR offers compact binary storage.

## Approach

### New crate dependencies (Cargo.toml)
Evaluate and add:
- `toml` — TOML serialisation (likely `toml = "0.8"`)
- `serde_yml` or `serde_yaml` — YAML frontmatter (for `.md` files)
- `ciborium` — CBOR binary JSON (`.jsonb`)

### ticket.rs
No changes needed — `Ticket` already derives `Serialize`/`Deserialize`.

### store.rs
New enum `FileFormat { Json, Markdown, Toml, Jsonb }`.

New function `detect_format(path: &Path) -> FileFormat`:
- `.json` → `Json`
- `.md` → `Markdown`
- `.toml` → `Toml`
- `.jsonb` → `Jsonb`
- Unknown → `Json` (fallback)

Update `ticket_path(root, id, format)` to use the format-appropriate extension. This is a breaking change to the function signature — update all callers.

Update `read_ticket(root, id)`:
1. Try each known extension in order until a file is found.
2. Read the file and dispatch to the format-appropriate deserialiser.

Serialisation helpers (private):
- `serialize_json(ticket) -> String`
- `serialize_toml(ticket) -> String`
- `serialize_markdown(ticket) -> String` — TOML frontmatter (`+++` delimiters) with body as file content
- `serialize_jsonb(ticket) -> Vec<u8>`

Deserialization helpers (private):
- `deserialize_markdown(bytes) -> Result<Ticket>` — parse frontmatter + body

Update `list_tickets` to scan for `*.json`, `*.md`, `*.toml`, `*.jsonb` files.

Update `write_ticket` to accept `format: FileFormat` and write in the appropriate format.

### main.rs
Add `--ftype [json|md|toml|jsonb]` option (default `json`) to `create` and `update`.
Conversion on `update --ftype`: read old file, write new format, delete old file (if extension changed).

## Markdown format (TOML frontmatter)
```
+++
id = "a3f9c2"
title = "Fix login bug"
priority = 8
status = "in_progress"
ticket_type = "bug"
dependencies = ["b7d41e"]
+++

Long-form body text goes here. Supports full markdown.
```

## Tests
- Unit tests: roundtrip each format (JSON already tested).
- Integration tests: `nbd create --ftype md` creates a `.md` file; `nbd read` finds and parses it.
- Integration test: `nbd update <id> --ftype toml` converts format and removes old file.

## Files touched
- `Cargo.toml` — new dependencies
- `src/store.rs` — format detection, multi-format read/write, updated `list_tickets`
- `src/main.rs` — `--ftype` flags
- `src/tests.rs` — format roundtrip tests
- `tests/integration.rs` — format integration tests
- `README.md` — document `--ftype`
- `docs/ARCHITECTURE.md` — update storage layout section