* 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>
221 lines
6.3 KiB
Markdown
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.
|