beads/docs/reference/json-schema.md
Athos Bernardes 3102cbd4d4
fix(show): flag comment_count as omitted when comments are not streamed (#4865)
* fix(show): flag comment_count as omitted when comments are not streamed

bd show --json's count-only default (be-ijck6q, pinned by
TestJSONContract_ShowOmitsOptInPayloadsByDefault) returns comment_count
with no comments key unless --include-comments is passed. A caller that
checks only `.comments` reads absence as "no comments" — wrong whenever
comment_count > 0. A caller that reads comment_count has no signal that
the array was left out on purpose rather than omitted by a client bug.

Add comments_omitted (bool, omitempty) to IssueDetails, set true only
when CommentCount > 0 and Comments was not populated. Leaves the
count-only default and its perf rationale untouched — this does not
revert cfcc95799/e538f2881, it makes the partial representation
self-announcing. Symmetric dependent_count/dependents case is a known,
separate gap left for a follow-up (not reported by ga-clgh, out of
scope here).

Did not bump JSONSchemaVersion / regen the golden corpus: this adds an
optional field via omitempty (no existing consumer's parse breaks,
no existing corpus fixture has comment_count > 0 for `show`), and
corpus-regen needs a live Dolt+Docker this sandbox doesn't have to
verify. Deferring that call to whoever can run `make corpus-regen` and
review the diff.

Fixes ga-clgh.

* fix(show): set comments_omitted on the proxied path too

The direct path flags comment_count as omitted when comments are not
streamed (ga-clgh); the proxied path silently left the flag unset. Mirror
the else-branch in proxiedBuildDetails, add proxied-path coverage for
present/included/zero cases, and document comments_omitted in the JSON
schema reference. No schema version bump: additive optional field already
emitted by the direct path.

Addresses the 2026-07-23 review on gastownhall/beads#4865.

Agent-Signature: claude-sonnet-5-medium on behalf of maphew

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
2026-07-25 16:16:41 -07:00

221 lines
6.3 KiB
Markdown

---
title: JSON Output Schema Contract
description: The stable JSON output contract for bd --json commands, covering the schema_version envelope, per-command fields, and consumer guidelines.
---
Last reviewed: 2026-05-08
Freshness source: `cmd/bd/output.go`, `cmd/bd/errors.go`, and
`cmd/bd/protocol/json_contract_test.go`.
All `bd` commands that support `--json` output can wrap their response in
a uniform envelope by setting `BD_JSON_ENVELOPE=1`. This will become the
default format in v2.0.
## Migration Guide
### Opt in to the envelope format
```bash
export BD_JSON_ENVELOPE=1
```
### Envelope format (BD_JSON_ENVELOPE=1, default in v2.0)
Every `--json` command wraps output as:
```json
{"schema_version": 1, "data": <original-payload>}
```
The original payload is untouched inside `.data` — no type corruption,
no field injection. Works identically for objects, arrays, and maps.
### Updating consumers
```bash
# Before (legacy):
bd list --json | jq '.[0].id'
bd show beads-abc --json | jq '.title'
# After (envelope):
bd list --json | jq '.data[0].id'
bd show beads-abc --json | jq '.data.title'
# Version check:
bd show beads-abc --json | jq '.schema_version'
```
### Timeline
- **Current release**: Legacy format is default. Set `BD_JSON_ENVELOPE=1` to opt in.
A deprecation notice is printed to stderr when `--json` is used without the env var.
- **v2.0**: Envelope becomes the default. `BD_JSON_ENVELOPE=0` available as
temporary escape hatch for one release cycle.
## Schema Version
Current version: **1**
The `schema_version` field is an integer that increments when:
- Fields are added, renamed, or removed
- Output structure changes (e.g., nesting depth)
- Field types change (e.g., string to integer)
Additive changes (new optional fields) do NOT bump the version.
## Output Formats
### Envelope mode (BD_JSON_ENVELOPE=1)
All commands emit a uniform envelope:
```json
{
"schema_version": 1,
"data": {
"id": "beads-abc",
"title": "Example issue",
"status": "open"
}
}
```
Arrays are wrapped the same way:
```json
{
"schema_version": 1,
"data": [
{"id": "beads-abc", "title": "First"},
{"id": "beads-def", "title": "Second"}
]
}
```
### Legacy mode (default, until v2.0)
### Object commands (show, create, close, update, etc.)
Commands that return a single issue or result emit a JSON object with
`schema_version` as a top-level field alongside the data:
```json
{
"schema_version": 1,
"id": "beads-abc",
"title": "Example issue",
"status": "open",
"priority": 1,
"issue_type": "task",
"created_at": "2026-04-20T12:00:00Z"
}
```
### List commands (list, ready, search, stale, etc.)
Commands that return multiple items emit a raw JSON array:
```json
[
{"id": "beads-abc", "title": "First", ...},
{"id": "beads-def", "title": "Second", ...}
]
```
### Error output (stderr)
Errors with `--json` active emit JSON to stderr:
```json
{
"schema_version": 1,
"error": "issue not found: beads-xyz",
"code": "not_found"
}
```
## Field Contracts by Command
### bd list --json
Required fields per item:
- `id` (string): Issue ID (e.g., "beads-abc")
- `title` (string): Issue title
- `status` (string): open, in_progress, closed, deferred
- `priority` (number): 0-4
- `issue_type` (string): bug, feature, task, epic, chore
- `created_at` (string): RFC3339 timestamp
Optional fields:
- `description`, `owner`, `updated_at`, `closed_at`
- `labels` (string[]): Attached labels
- `dependencies` (object[]): Dependency records
- `dependency_count`, `dependent_count`, `comment_count` (number)
- `parent` (string|null): Parent issue ID
### bd ready --json
Same schema as `bd list --json`. Items are filtered to unblocked issues only.
Each item includes `dependency_count`, `dependent_count`, `comment_count`,
and optional `parent` fields.
### bd blocked --json
Returns issues that are blocked by unresolved dependencies.
Each item includes all standard issue fields plus:
- `blocked_by_count` (number): Number of blocking dependencies
- `blocked_by` (string[]): IDs of blocking issues
### bd show --json
Returns a single object (not wrapped in `items`). Same required fields as list
items, plus:
- `description` (string)
- `acceptance_criteria` (string)
- `dependencies` (object[]): Full dependency records
- `comments` (object[]): Comment thread — present only with `--include-comments`;
the default response returns `comment_count` only (count-only, be-ijck6q)
- `comments_omitted` (boolean, optional): `true` only when `comment_count` is
nonzero and `comments` was left out of the response (no `--include-comments`).
Absent when comments were included or when there are none to omit (ga-clgh)
### `import --json`
Returns a summary object when `--json` is active:
- `source` (string): File path or "stdin"
- `created` (number): Issues created
- `updated` (number): Existing issues updated
- `skipped` (number): Issues skipped (stale rows + dedup)
- `dedup_skipped` (number): Issues skipped by `--dedup` title match
- `memories` (number): Memory records imported
- `ids` (string[]): IDs of created issues
- `updated_issues` (object[]): Per-issue summary of what an update changed
- `tie_kept_local_ids` (string[]): Equal-`updated_at` rows where local state won
- `stale_skipped_ids` (string[]): Rows older than the local issue, skipped
- `skipped_dependencies` (string[]): Dependency edges whose target id was absent
- `dry_run` (boolean): Whether `--dry-run` was active
### bd export --json
Outputs JSONL (one JSON object per line), not wrapped in an envelope.
Each line is a self-contained issue or memory record, discriminated by
`_type` (`"issue"` / `"memory"`). Export lines do **not** carry
`schema_version` — that field belongs to the `--json` command envelope,
not to the interchange stream. The interchange's own version marker is the
optional `_schema` header record (`{"_schema":"beads-jsonl/1"}`), which
readers skip.
## Consumer Guidelines
1. **Check `schema_version`** on object output. If the version is
higher than expected, log a warning but attempt to parse anyway
(additive changes are backward-compatible).
2. **For list commands**, parse the output as a JSON array directly.
3. **Ignore unknown fields**. New fields may be added without bumping
the schema version.
4. **Use `--json` flag**, not `--format json`. The `--json` flag is
the stable contract; `--format` is for human-readable variants.