beads/docs/JSON_SCHEMA.md
Kevin Glynn 8518e71d66
feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393)
* 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.
2026-04-21 13:24:17 -07:00

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=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:

{
  "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 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

import --json

Returns a summary object when --json is active:

  • source (string): File path or "stdin"
  • created (number): Issues created
  • skipped (number): Issues skipped (dedup)
  • dedup_skipped (number): Issues skipped by --dedup title match
  • memories (number): Memory records imported
  • ids (string[]): IDs of created issues
  • 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. schema_version is included per line.

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.