WP2 of the beads protocol conformance corpus (PROPOSAL-beads-protocol-v0 §11).
Seven §J clauses had no test; the keystone one had no test anywhere.
cmd/bd/protocol/interchange_test.go pins:
J6.6 export -> import into an EMPTY store -> export reproduces the stream.
bd-go had same-DB byte-stability and per-field round-trip tests, but
nothing asserted CROSS-store equivalence — the exact blind spot where an
import that drops, defaults, or rewrites a field hides. The fixture
spans P0 (the zero-value priority), every core issue_type, a closed
issue with close_reason, labels, inline comments, both dep orientations,
metadata, assignee, and memories.
J1.2 unknown fields ignored — a record carrying future fields at the top
level, inside a dependency, and inside a comment still imports cleanly.
J1.3 `_schema` header records skipped, on both the file and stdin readers.
J6.1 import never deletes: a partial stream does not remove the ids it omits.
J6.3 a dependency whose target id is absent is skipped AND reported
(skipped_dependencies in `bd import --json`).
J6.5 `bd import -` reads a stream from stdin.
J2.4 zero/unknown timestamps export as the Unix epoch, never year-0001
(which json.Marshal refuses outright, failing the whole export).
J1.3 needed a code fix, not just a test. parseJSONLFile (the bootstrap reader)
skipped the header record, but the `bd import` reader loop — the one `bd import`
and `bd import -` both run through — did not: the header line fell through to
the issue path, unmarshaled into an empty Issue, and aborted the WHOLE import
with "validation failed for issue : title is required". So a canonical export
carrying a provenance header could not be imported at all. Verified against the
new test: it fails with exactly that error without the guard.
Two stale artifacts found during the extraction, fixed here:
- TestCLI_Import_PrefixValidation_E2E asserted that import REJECTS a foreign
id prefix without --skip-prefix-validation, a flag that no longer exists
(every import path now passes SkipPrefixValidation). Being build-tagged out
of CI (cgo && integration), it rotted unnoticed. Rewritten as
TestCLI_Import_ForeignPrefix_E2E, pinning the behavior bd actually has —
which the protocol requires anyway: §J6.6 round-trips through a store with
its own prefix, and §J7.1 makes ids opaque.
- docs/reference/json-schema.md claimed export emits schema_version per line.
It does not (and must not): schema_version belongs to the --json command
envelope; the interchange's version marker is the optional _schema header.
The import --json summary field list was also missing five fields.
Gates: gofmt + go vet clean, go build ./... ok, full cmd/bd/protocol package
green (280s, -count=1).
6 KiB
| title | description |
|---|---|
| JSON Output Schema Contract | 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
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 createdupdated(number): Existing issues updatedskipped(number): Issues skipped (stale rows + dedup)dedup_skipped(number): Issues skipped by--deduptitle matchmemories(number): Memory records importedids(string[]): IDs of created issuesupdated_issues(object[]): Per-issue summary of what an update changedtie_kept_local_ids(string[]): Equal-updated_atrows where local state wonstale_skipped_ids(string[]): Rows older than the local issue, skippedskipped_dependencies(string[]): Dependency edges whose target id was absentdry_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, 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
-
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.