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).
217 lines
6 KiB
Markdown
217 lines
6 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
|
|
|
|
### `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.
|