* feat: add BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping Follow-up to #3368 as discussed with @maphew. Adds the envelope format that wraps all --json output as {"schema_version": N, "data": <payload>}, gated behind BD_JSON_ENVELOPE=1 to avoid breaking existing consumers. Legacy mode (default): unchanged behavior from #3368 — objects get schema_version injected inline, arrays pass through raw. Envelope mode (BD_JSON_ENVELOPE=1): uniform wrapping for all types. The original payload is untouched inside .data — no type corruption, no field injection. A one-time deprecation notice is emitted to stderr when --json is used without the env var. Timeline: envelope becomes default in v2.0, with BD_JSON_ENVELOPE=0 as a temporary escape hatch for one release cycle. Includes: - wrapWithSchemaVersion dual-mode logic - outputJSONError and buildJSONError envelope support - Deprecation notice on stderr (once per process) - Tests for both legacy and envelope modes - Migration guide in docs/JSON_SCHEMA.md * fix: suppress deprecation notice when stderr is not a TTY Gate emitEnvelopeDeprecation() on ui.IsStderrTerminal() so the "NOTE: bd --json output format will change in v2.0" message only appears in interactive terminals. Test harnesses and pipelines capture stderr via CombinedOutput(), and the trailing notice after the JSON closing brace caused json.Unmarshal to fail with "invalid character 'N' after top-level value" in 15 CI tests. Follows the same TTY-gating pattern used by ShouldUseColor and ShouldUseEmoji. * fix: suppress gosec G304 false positive in hookWorkTreeRoot The path is filepath.Join(os.Getenv("GIT_DIR"), "gitdir") — reading a well-known git internal file from a trusted environment variable set by git itself during hook execution. Not a user-controlled file inclusion. This false positive causes the Lint CI check to fail on every PR in the repo, masking real lint issues.
5 KiB
JSON Output Schema Contract
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
export BD_JSON_ENVELOPE=1
Envelope format (BD_JSON_ENVELOPE=1, default in v2.0)
Every --json command wraps output as:
{"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
# 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=1to opt in. A deprecation notice is printed to stderr when--jsonis used without the env var. - v2.0: Envelope becomes the default.
BD_JSON_ENVELOPE=0available 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:
{
"schema_version": 1,
"data": {
"id": "beads-abc",
"title": "Example issue",
"status": "open"
}
}
Arrays are wrapped the same way:
{
"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:
{
"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:
[
{"id": "beads-abc", "title": "First", ...},
{"id": "beads-def", "title": "Second", ...}
]
Error output (stderr)
Errors with --json active emit JSON to stderr:
{
"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 titlestatus(string): open, in_progress, closed, deferredpriority(number): 0-4issue_type(string): bug, feature, task, epic, chorecreated_at(string): RFC3339 timestamp
Optional fields:
description,owner,updated_at,closed_atlabels(string[]): Attached labelsdependencies(object[]): Dependency recordsdependency_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 dependenciesblocked_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 recordscomments(object[]): Comment thread
import --json
Returns a summary object when --json is active:
source(string): File path or "stdin"created(number): Issues createdskipped(number): Issues skipped (dedup)dedup_skipped(number): Issues skipped by--deduptitle matchmemories(number): Memory records importedids(string[]): IDs of created issuesdry_run(boolean): Whether--dry-runwas 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. schema_version
is included per line.
Consumer Guidelines
-
Check
schema_versionon object output. If the version is higher than expected, log a warning but attempt to parse anyway (additive changes are backward-compatible). -
For list commands, parse the output as a JSON array directly.
-
Ignore unknown fields. New fields may be added without bumping the schema version.
-
Use
--jsonflag, not--format json. The--jsonflag is the stable contract;--formatis for human-readable variants.